/usr/lib/swi-prolog/doc/Manual/autoload.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
<head>
<title>SWI-Prolog 7.1.16 Reference Manual: Section 2.13</title><link rel="home" href="index.html">
<link rel="contents" href="Contents.html">
<link rel="index" href="DocIndex.html">
<link rel="summary" href="summary.html">
<link rel="previous" href="hooks.html">
<link rel="next" href="gc.html">

<style type="text/css">

/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef, dt.multidef
{ color: #fff;
padding: 2px 10px 0px 10px;
margin-bottom: 5px;
font-size: 18px;
vertical-align: middle;
overflow: hidden;
}

dt.pubdef { background-color: #0c3d6e; }
dt.multidef { background-color: #ef9439; }

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #fff;
}

div.caption
{ width: 80%;
margin: auto;
text-align:center;
}

/* Footnotes */
.fn {
color: red;
font-size: 70%;
}

.fn-text, .fnp {
position: absolute;
top: auto;
left: 10%;
border: 1px solid #000;
box-shadow: 5px 5px 5px #888;
display: none;
background: #fff;
color: #000;
margin-top: 25px;
padding: 8px 12px;
font-size: larger;
}

sup:hover span.fn-text
{ display: block;
}

/* Lists */

dl.latex
{ margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.latex dl.latex dd.defbody
{ margin-bottom: 0.5ex;
}

/* PlDoc Tags */

dl.tags
{ font-size: 90%;
margin-left: 5ex;
margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.tags dt
{ margin-left: 0pt;
font-weight: bold;
}

dl.tags dd
{ margin-left: 3ex;
}

td.param
{ font-style: italic;
font-weight: bold;
}

/* Index */

dt.index-sep
{ font-weight: bold;
font-size: +1;
margin-top: 1ex;
}

/* Tables */

table.center
{ margin: auto;
}

table.latex
{ border-collapse:collapse;
}

table.latex tr
{ vertical-align: text-top;
}

table.latex td,th
{ padding: 2px 1em;
}

table.latex tr.hline td,th
{ border-top: 1px solid black;
}

table.frame-box
{ border: 2px solid black;
}

</style>
</head>
<body style="background:white">
<div class="navigate"><a class="nav" href="index.html"><img src="home.gif" alt="Home"></a>
<a class="nav" href="Contents.html"><img src="index.gif" alt="Contents"></a>
<a class="nav" href="DocIndex.html"><img src="yellow_pages.gif" alt="Index"></a>
<a class="nav" href="summary.html"><img src="info.gif" alt="Summary"></a>
<a class="nav" href="hooks.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="gc.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:autoload"><a id="sec:2.13"><span class="sec-nr">2.13</span> <span class="sec-title">Automatic 
loading of libraries</span></a></h2>

<a id="sec:autoload"></a>

<p>If ---at runtime--- an undefined predicate is trapped, the system 
will first try to import the predicate from the module's default module 
(see
<a class="sec" href="importmodule.html">section 5.9</a>. If this fails 
the <em>auto loader</em> is activated.<sup class="fn">17<span class="fn-text">Actually, 
the hook user:exception/3 is called; only if this hook fails does it 
call the autoloader.</span></sup> On first activation an index to all 
library files in all library directories is loaded in core (see <a id="idx:librarydirectory1:159"></a><a class="pred" href="consulting.html#library_directory/1">library_directory/1</a>, <a id="idx:filesearchpath2:160"></a><a class="pred" href="consulting.html#file_search_path/2">file_search_path/2</a> 
and
<a id="idx:reloadlibraryindex0:161"></a><a class="pred" href="autoload.html#reload_library_index/0">reload_library_index/0</a>). 
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 <a id="idx:currentprologflag2:162"></a><a class="pred" href="flags.html#current_prolog_flag/2">current_prolog_flag/2</a> 
key <a class="flag" href="flags.html#flag:verbose_autoload">verbose_autoload</a> 
is provided to get verbose loading. The Prolog flag <a class="flag" href="flags.html#flag:autoload">autoload</a> 
can be used to enable/disable the autoload system.

<p>Autoloading only handles (library) source files that use the module 
mechanism described in <a class="sec" href="modules.html">chapter 5</a>. 
The files are loaded with <a id="idx:usemodule2:163"></a><a class="pred" href="import.html#use_module/2">use_module/2</a> 
and only the trapped undefined predicate is imported into the module 
where the undefined predicate was called. Each library directory must 
hold a file <code>INDEX.pl</code> that contains an index to all library 
files in the directory. This file consists of lines of the following 
format:

<pre class="code">
index(Name, Arity, Module, File).
</pre>

<p>The predicate <a id="idx:make0:164"></a><a class="pred" href="consulting.html#make/0">make/0</a> 
updates the autoload index. It searches for all library directories (see <a id="idx:librarydirectory1:165"></a><a class="pred" href="consulting.html#library_directory/1">library_directory/1</a> 
and <a id="idx:filesearchpath2:166"></a><a class="pred" href="consulting.html#file_search_path/2">file_search_path/2</a>) 
holding the file <code>MKINDEX.pl</code> or <code>INDEX.pl</code>. If 
the current user can write or create the file <code>INDEX.pl</code> 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 <code>MKINDEX.pl</code> 
exists, updating is achieved by loading this file, normally containing a 
directive calling
<a id="idx:makelibraryindex2:167"></a><a class="pred" href="autoload.html#make_library_index/2">make_library_index/2</a>. 
Otherwise <a id="idx:makelibraryindex1:168"></a><a class="pred" href="autoload.html#make_library_index/1">make_library_index/1</a> 
is called, creating an index for all <code>*.pl</code> files containing 
a module.

<p>Below is an example creating an indexed library directory.

<pre class="code">
% mkdir ~/lib/prolog
% cd ~/lib/prolog
% swipl -g true -t 'make_library_index(.)'
</pre>

<p>If there is more than one library file containing the desired 
predicate, the following search schema is followed:

<p>
<ol class="latex">
<li>If there is a library file that defines the module in which the 
undefined predicate is trapped, this file is used.
<li>Otherwise library files are considered in the order they appear in 
the <a id="idx:librarydirectory1:169"></a><a class="pred" href="consulting.html#library_directory/1">library_directory/1</a> 
predicate and within the directory alphabetically.
</ol>

<dl class="latex">
<dt class="pubdef"><a id="autoload_path/1"><strong>autoload_path</strong>(<var>+DirAlias</var>)</a></dt>
<dd class="defbody">
Add <var>DirAlias</var> to the libraries that are used by the 
autoloader. This extends the search path <code>autoload</code> and 
reloads the library index. For example:

<pre class="code">
:- autoload_path(library(http)).
</pre>

<p>If this call appears as a directive, it is term-expanded into a 
clause for user:file_search_path/2 and a directive calling
<a id="idx:reloadlibraryindex0:170"></a><a class="pred" href="autoload.html#reload_library_index/0">reload_library_index/0</a>. 
This keeps source information and allows for removing this directive.</dd>
<dt class="pubdef"><a id="make_library_index/1"><strong>make_library_index</strong>(<var>+Directory</var>)</a></dt>
<dd class="defbody">
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.</dd>
<dt class="pubdef"><a id="make_library_index/2"><strong>make_library_index</strong>(<var>+Directory, 
+ListOfPatterns</var>)</a></dt>
<dd class="defbody">
Normally used in <code>MKINDEX.pl</code>, this predicate creates <code>INDEX.pl</code> 
for <var>Directory</var>, indexing all files that match one of the file 
patterns in <var>ListOfPatterns</var>.

<p>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 <code>MKINDEX.pl</code>, including the public 
functionality of <code>trace/browse.pl</code> to the autoloadable 
predicates for the XPCE package.

<pre class="code">
:- make_library_index('.',
                      [ '*.pl',
                        'trace/browse.pl'
                      ]).
</pre>

</dd>
<dt class="pubdef"><a id="reload_library_index/0"><strong>reload_library_index</strong></a></dt>
<dd class="defbody">
Force reloading the index after modifying the set of library directories 
by changing the rules for <a id="idx:librarydirectory1:171"></a><a class="pred" href="consulting.html#library_directory/1">library_directory/1</a>, <a id="idx:filesearchpath2:172"></a><a class="pred" href="consulting.html#file_search_path/2">file_search_path/2</a>, 
adding or deleting <code>INDEX.pl</code> files. This predicate does <em>not</em> 
update the <code>INDEX.pl</code> files. Check <a id="idx:makelibraryindex12:173"></a><span class="pred-ext">make_library_index/[1,2]</span> 
and
<a id="idx:make0:174"></a><a class="pred" href="consulting.html#make/0">make/0</a> 
for updating the index files.

<p>Normally, the index is reloaded automatically if a predicate cannot 
be found in the index and the set of library directories has changed. 
Using
<a id="idx:reloadlibraryindex0:175"></a><a class="pred" href="autoload.html#reload_library_index/0">reload_library_index/0</a> 
is necessary if directories are removed or the order of the library 
directories is changed.
</dd>
</dl>

<p>When creating an executable using either <a id="idx:qsaveprogram2:176"></a><a class="pred" href="runtime.html#qsave_program/2">qsave_program/2</a> 
or the
<strong>-c</strong> command line options, it is necessarry to load all 
predicates that would normally be autoloaded explicitly. This is 
discussed in <a class="sec" href="runtime.html">section 10</a>. See <a id="idx:autoload0:177"></a><a class="pred" href="runtime.html#autoload/0">autoload/0</a>.

<p></body></html>
swi-prolog-nox 6.6.6-5 / usr / lib / swi-prolog / doc / Manual / autoload.html
