2.13 Automatic loading of libraries

If ---at runtime--- an undefined predicate is trapped the system will first try to import the predicate from the module's default module. If this fails the auto loader is activated. On first activation an index to all library files in all library directories is loaded in core (see library_directory/1 and file_search_path/2). If the undefined predicate can be located in one of the libraries that library file is automatically loaded and the call to the (previously undefined) predicate is restarted. By default this mechanism loads the file silently. The current_prolog_flag/2 verbose_autoload is provided to get verbose loading. The Prolog flag autoload can be used to enable/disable the entire auto load system.

The auto-loader only works if the unknown flag (see unknown/2) is set to trace (default). A more appropriate interaction with this flag should be considered.

Autoloading only handles (library) source files that use the module mechanism described in chapter 5. The files are loaded with use_module/2 and only the trapped undefined predicate will be imported to the module where the undefined predicate was called. Each library directory must hold a file INDEX.pl that contains an index to all library files in the directory. This file consists of lines of the following format:

index(Name, Arity, Module, File).

The predicate make/0 updates the autoload index. It searches for all library directories (see library_directory/1 and file_search_path/2) holding the file MKINDEX.pl or INDEX.pl. If the current user can write or create the file INDEX.pl and it does not exist or is older than the directory or one of its files, the index for this directory is updated. If the file MKINDEX.pl exists updating is achieved by loading this file, normally containing a directive calling make_library_index/2. Otherwise make_library_index/1 is called, creating an index for all *.pl files containing a module.

Below is an example creating a completely indexed library directory.

% mkdir ~/lib/prolog
% cd !$
% pl -g true -t 'make_library_index(.)'

If there are more than one library files containing the desired predicate the following search schema is followed:

1. If there is a library file that defines the module in which the undefined predicate is trapped, this file is used.
2. Otherwise library files are considered in the order they appear in the library_directory/1 predicate and within the directory alphabetically.

make_library_index(+Directory)

Create an index for this directory. The index is written to the file 'INDEX.pl' in the specified directory. Fails with a warning if the directory does not exist or is write protected.

make_library_index(+Directory, +ListOfPatterns)

Normally used in MKINDEX.pl, this predicate creates INDEX.pl for Directory, indexing all files that match one of the file-patterns in ListOfPatterns.

Sometimes library packages consist of one public load file and a number of files used by this load-file, exporting predicates that should not be used directly by the end-user. Such a library can be placed in a sub-directory of the library and the files containing public functionality can be added to the index of the library. As an example we give the XPCE library's MKINDEX.pl, including the public functionality of trace/browse.pl to the autoloadable predicates for the XPCE package.

:- make_library_index('.',
                      [ '*.pl',
                        'trace/browse.pl'
                      ]).

reload_library_index

Force reloading the index after modifying the set of library directories by changing the rules for library_directory/1, file_search_path/2, adding or deleting INDEX.pl files. This predicate does not update the INDEX.pl files. Check make_library_index/[1,2] and make/0 for updating the index files.

Normally, the index is reloaded automatically if a predicate cannot be found in the index and the set of library directories has changed. Using reload_library_index/0 is necessary if directories are removed or the order of the library directories is changed.