/usr/lib/swi-prolog/doc/Manual/runtime.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.10 Reference Manual</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="foreignnotes.html">
<link rel="next" href="qsavelimits.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="foreignnotes.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="qsavelimits.html"><img src="next.gif" alt="Next"></a>
</div>
<h1 id="sec:runtime"><a id="sec:10"><span class="sec-nr">10</span> <span class="sec-title">Generating 
Runtime Applications</span></a></h1>

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

<p>This chapter describes the features of SWI-Prolog for delivering 
applications that can run without the development version of the system 
installed.

<p>A SWI-Prolog runtime executable is a file consisting of two parts. 
The first part is the <em>emulator</em>, which is machine-dependent. The 
second part is the <em>resource archive</em>, which contains the 
compiled program in a machine-independent format, startup options and 
possibly user-defined <em>resources</em>; see <a id="idx:resource3:1750"></a><a class="pred" href="useresource.html#resource/3">resource/3</a> 
and
<a id="idx:openresource3:1751"></a><a class="pred" href="useresource.html#open_resource/3">open_resource/3</a>.

<p>These two parts can be connected in various ways. The most common way 
for distributed runtime applications is to <em>concatenate</em> the two 
parts. This can be achieved using external commands (Unix:
<b>cat</b>, Windows: <b>copy</b>), or using the
<code>stand_alone</code> option to <a id="idx:qsaveprogram2:1752"></a><a class="pred" href="runtime.html#qsave_program/2">qsave_program/2</a>. 
The second option is to attach a startup script in front of the resource 
that starts the emulator with the proper options. This is the default 
under Unix. Finally, an emulator can be told to use a specified resource 
file using the <strong>-x</strong> command line switch.

<dl class="latex">
<dt class="pubdef"><a id="qsave_program/2"><strong>qsave_program</strong>(<var>+File, 
+Options</var>)</a></dt>
<dd class="defbody">
Saves the current state of the program to the file <var>File</var>. The 
result is a resource archive containing a saved state that expresses all 
Prolog data from the running program and all user-defined resources. 
Depending on the <code>stand_alone</code> option, the resource is headed 
by the emulator, a Unix shell script or nothing. <var>Options</var> is a 
list of additional options:

<dl class="latex">
<dt><strong>local</strong>(<var>+KBytes</var>)</dt>
<dd class="defbody">
Limit for the local stack. See <a class="sec" href="cmdline.html">section 
2.4.3</a>.
</dd>
<dt><strong>global</strong>(<var>+KBytes</var>)</dt>
<dd class="defbody">
Limit for the global stack. See <a class="sec" href="cmdline.html">section 
2.4.3</a>.
</dd>
<dt><strong>trail</strong>(<var>+KBytes</var>)</dt>
<dd class="defbody">
Limit for the trail stack. See <a class="sec" href="cmdline.html">section 
2.4.3</a>.
</dd>
<dt><strong>goal</strong>(<var>:Callable</var>)</dt>
<dd class="defbody">
Initialization goal for the new executable (see <strong>-g</strong>).
</dd>
<dt><strong>toplevel</strong>(<var>:Callable</var>)</dt>
<dd class="defbody">
Top-level goal for the new executable (see <strong>-t</strong>).
</dd>
<dt><strong>init_file</strong>(<var>+Atom</var>)</dt>
<dd class="defbody">
Default initialization file for the new executable. See
<strong>-f</strong>.
</dd>
<dt><strong>class</strong>(<var>+Class</var>)</dt>
<dd class="defbody">
If <code>runtime</code>, only read resources from the state (default). 
If
<code>kernel</code>, lock all predicates as system predicates. If
<code>development</code>, save the predicates in their current state and 
keep reading resources from their source (if present). See also <a id="idx:resource3:1753"></a><a class="pred" href="useresource.html#resource/3">resource/3</a>.
</dd>
<dt><strong>autoload</strong>(<var>+Boolean</var>)</dt>
<dd class="defbody">
If <code>true</code> (default), run <a id="idx:autoload0:1754"></a><a class="pred" href="runtime.html#autoload/0">autoload/0</a> 
first.
</dd>
<dt><strong>map</strong>(<var>+File</var>)</dt>
<dd class="defbody">
Dump a human-readable trace of what has been saved in <var>File</var>.
</dd>
<dt><strong>op</strong>(<var>+Action</var>)</dt>
<dd class="defbody">
One of <code>save</code> (default) to save the current operator table or <code>standard</code> 
to use the initial table of the emulator.
</dd>
<dt><strong>stand_alone</strong>(<var>+Boolean</var>)</dt>
<dd class="defbody">
If <code>true</code>, the emulator is the first part of the state. If 
the emulator is started it will test whether a boot file (state) is 
attached to the emulator itself and load this state. Provided the 
application has all libraries loaded, the resulting executable is 
completely independent of the runtime environment or location where it 
was built. See also
<a class="sec" href="compilation.html">section 2.10.2.4</a>.
</dd>
<dt><strong>emulator</strong>(<var>+File</var>)</dt>
<dd class="defbody">
File to use for the emulator. Default is the running Prolog image.
</dd>
<dt><strong>foreign</strong>(<var>+Action</var>)</dt>
<dd class="defbody">
If <code>save</code>, include shared objects (DLLs) into the saved 
state. See
<a id="idx:currentforeignlibrary2:1755"></a><a class="pred" href="foreignlink.html#current_foreign_library/2">current_foreign_library/2</a>. 
If the program <b>strip</b> is available, this is first used to reduce 
the size of the shared object. If a state is started, <a id="idx:useforeignlibrary1:1756"></a><a class="pred" href="foreignlink.html#use_foreign_library/1">use_foreign_library/1</a> 
first tries to locate the foreign resource in the executable. When found 
it copies the content of the resource to a temporary file and loads it. 
If possible (Unix), the temporary object is deleted immediately after 
opening.<sup class="fn">122<span class="fn-text">This option is 
experimental and currently disabled by default. It will become the 
default if it proves robust.</span></sup>
</dd>
</dl>

</dd>
<dt class="pubdef"><a id="qsave_program/1"><strong>qsave_program</strong>(<var>+File</var>)</a></dt>
<dd class="defbody">
Equivalent to <code>qsave_program(File, [])</code>.</dd>
<dt class="pubdef"><a id="autoload/0"><strong>autoload</strong></a></dt>
<dd class="defbody">
Check the current Prolog program for predicates that are referred to, 
are undefined and have a definition in the Prolog library. Load the 
appropriate libraries.

<p>This predicate is used by <a id="idx:qsaveprogram12:1757"></a><span class="pred-ext">qsave_program/[1,2]</span> 
to ensure the saved state does not depend on availability of the 
libraries. The predicate
<a id="idx:autoload0:1758"></a><a class="pred" href="runtime.html#autoload/0">autoload/0</a> 
examines all clauses of the loaded program (obtained with
<a id="idx:clause2:1759"></a><a class="pred" href="examineprog.html#clause/2">clause/2</a>) 
and analyzes the body for referenced goals. Such an analysis cannot be 
complete in Prolog, which allows for the creation of arbitrary terms at 
runtime and the use of them as a goal. The current analysis is limited 
to the following:

<p>
<ul class="latex">
<li>Direct goals appearing in the body
<li>Arguments of declared meta-predicates that are marked with an 
integer (0..9). See <a id="idx:metapredicate1:1760"></a><a class="pred" href="metapred.html#meta_predicate/1">meta_predicate/1</a>.
</ul>

<p>The analysis of meta-predicate arguments is limited to cases where 
the argument appears literally in the clause or is assigned using =/2 
before the meta-call. That is, the following fragment is processed 
correctly:

<pre class="code">
        ...,
        Goal = prove(Theory),
        forall(current_theory(Theory),
               Goal)),
</pre>

<p>But, the calls to prove_simple/1 and prove_complex/1 in the example 
below are <em>not</em> discovered by the analysis and therefore the 
modules that define these predicates must be loaded explicitly using <a id="idx:usemodule1:1761"></a><a class="pred" href="import.html#use_module/1">use_module/1</a>,2.

<pre class="code">
        ...,
        member(Goal, [ prove_simple(Theory),
                       prove_complex(Theory)
                     ]),
        forall(current_theory(Theory),
               Goal)),
</pre>

<p>It is good practice to use <a id="idx:gxref0:1762"></a><a class="pred" href="xref.html#gxref/0">gxref/0</a> 
to make sure that the program has sufficient declarations such that the 
analaysis tools can verify that all required predicates can be resolved 
and that all code is called. See <a id="idx:metapredicate1:1763"></a><a class="pred" href="metapred.html#meta_predicate/1">meta_predicate/1</a>, <a id="idx:dynamic1:1764"></a><a class="pred" href="dynamic.html#dynamic/1">dynamic/1</a>, <a id="idx:public1:1765"></a><a class="pred" href="dynamic.html#public/1">public/1</a> 
and prolog:called_by/2.</dd>
<dt class="pubdef"><a id="volatile/1"><strong>volatile</strong> <var>+Name/Arity, 
...</var></a></dt>
<dd class="defbody">
Declare that the clauses of specified predicates should <strong>not</strong> 
be saved to the program. The volatile declaration is normally used to 
prevent the clauses of dynamic predicates that represent data for the 
current session from being saved in the state file.
</dd>
</dl>

<p>
<hr>
<div style="text-align:center">

<h2>Section Index</h2>

</div>
<hr>
<div class="toc">
<div class="toc-h2"><a class="sec" href="qsavelimits.html"><span class="sec-nr">10.1</span> <span class="sec-title">Limitations 
of qsave_program</span></a></div>
<div class="toc-h2"><a class="sec" href="qsaveforeign.html"><span class="sec-nr">10.2</span> <span class="sec-title">Runtimes 
and Foreign Code</span></a></div>
<div class="toc-h2"><a class="sec" href="useresource.html"><span class="sec-nr">10.3</span> <span class="sec-title">Using 
program resources</span></a></div>
<div class="toc-h3"><a class="sec" href="useresource.html#sec:10.3.1"><span class="sec-nr">10.3.1</span> <span class="sec-title">Resource 
manipulation predicates</span></a></div>
<div class="toc-h3"><a class="sec" href="useresource.html#sec:10.3.2"><span class="sec-nr">10.3.2</span> <span class="sec-title">The <b>swipl-rc</b> 
program</span></a></div>
<div class="toc-h2"><a class="sec" href="findappfile.html"><span class="sec-nr">10.4</span> <span class="sec-title">Finding 
Application files</span></a></div>
<div class="toc-h3"><a class="sec" href="findappfile.html#sec:10.4.1"><span class="sec-nr">10.4.1</span> <span class="sec-title">Specifying 
a file search path from the command line</span></a></div>
</div>
</body></html>
swi-prolog-nox 6.6.4-2ubuntu1 / usr / lib / swi-prolog / doc / Manual / runtime.html
