\chapter{Generating Runtime Applications}	\label{sec:runtime}

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

A SWI-Prolog runtime executable is a file consisting of two parts.  The
first part is the \jargon{emulator}, which is machine-dependent. The
second part is the \jargon{resource archive}, which contains the
compiled program in a machine-independent format, startup options
and possibly user-defined \jargon{resources}; see resource/3 and
open_resource/3.

These two parts can be connected in various ways. The most
common way for distributed runtime applications is to \emph{concatenate}
the two parts. This can be achieved using external commands (Unix:
\program{cat}, Windows: \program{copy}), or using the
\const{stand_alone} option to qsave_program/2. 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 \cmdlineoption{-x}{} command line switch.


\begin{description}
    \predicate{qsave_program}{2}{+File, +Options}
Saves the current state of the program to the file \arg{File}.  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 \const{stand_alone} option, the resource is headed by
the emulator, a Unix shell script or nothing.  \arg{Options} is a list
of additional options:

    \begin{description}
	\termitem{local}{+KBytes}
Limit for the local stack.  See \secref{stacksizes}.
	\termitem{global}{+KBytes}
Limit for the global stack.  See \secref{stacksizes}.
	\termitem{trail}{+KBytes}
Limit for the trail stack.  See \secref{stacksizes}.
	\termitem{goal}{:Callable}
Initialization goal for the new executable (see \cmdlineoption{-g}).
	\termitem{toplevel}{:Callable}
Top-level goal for the new executable (see \cmdlineoption{-t}).
	\termitem{init_file}{+Atom}
Default initialization file for the new executable. See
\cmdlineoption{-f}.
	\termitem{class}{+Class}
If \const{runtime}, only read resources from the state (default). If
\const{kernel}, lock all predicates as system predicates. If
\const{development}, save the predicates in their current state and keep
reading resources from their source (if present). See also resource/3.
	\termitem{autoload}{+Boolean}
If \const{true} (default), run autoload/0 first.
	\termitem{map}{+File}
Dump a human-readable trace of what has been saved in \arg{File}.
	\termitem{op}{+Action}
One of \const{save} (default) to save the current operator table
or \const{standard} to use the initial table of the emulator.
	\termitem{stand_alone}{+Boolean}
If \const{true}, 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
\secref{cmdlinecomp}.
	\termitem{emulator}{+File}
File to use for the emulator.  Default is the running Prolog image.
	\termitem{foreign}{+Action}
If \const{save}, include shared objects (DLLs) into the saved state. See
current_foreign_library/2. If the program \program{strip} is available,
this is first used to reduce the size of the shared object. If a state
is started, use_foreign_library/1 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.\footnote{This
option is experimental and currently disabled by default.  It will
become the default if it proves robust.}
    \end{description}

    \predicate{qsave_program}{1}{+File}
Equivalent to \exam{qsave_program(File, [])}.

    \predicate{autoload}{0}{}
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.

This predicate is used by qsave_program/[1,2] to ensure the saved state
does not depend on availability of the libraries. The predicate
autoload/0 examines all clauses of the loaded program (obtained with
clause/2) 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:

    \begin{itemize}
        \item Direct goals appearing in the body
	\item Arguments of declared meta-predicates that are marked
	      with an integer (0..9).  See meta_predicate/1.
    \end{itemize}

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:

\begin{code}
	...,
	Goal = prove(Theory),
	forall(current_theory(Theory),
	       Goal)),
\end{code}

But, the calls to \nopredref{prove_simple}{1} and
\nopredref{prove_complex}{1} in the example below are \emph{not}
discovered by the analysis and therefore the modules that define these
predicates must be loaded explicitly using use_module/1,2.

\begin{code}
	...,
	member(Goal, [ prove_simple(Theory),
		       prove_complex(Theory)
		     ]),
	forall(current_theory(Theory),
	       Goal)),
\end{code}

It is good practice to use gxref/0 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 meta_predicate/1, dynamic/1, public/1 and prolog:called_by/2.

    \prefixop{volatile}{+Name/Arity, \ldots}
Declare that the clauses of specified predicates should \strong{not} 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.
\end{description}


\section{Limitations of qsave_program}	\label{sec:qsavelimits}

There are three areas that require special attention when using
qsave_program/[1,2].

\begin{itemize}
    \item
If the program is an embedded Prolog application or uses the foreign
language interface, care has to be taken to restore the appropriate
foreign context. See \secref{qforeign} for details.

    \item
If the program uses directives (\exam{:- goal.} lines) that perform
other actions than setting predicate attributes (dynamic, volatile,
etc.) or loading files (consult, etc.), the directive may need to be
prefixed with initialization/1.

    \item
Database references as returned by clause/3, recorded/3, etc.,
are not preserved and may thus not be part of the database when saved.
\end{itemize}


\section{Runtimes and Foreign Code}	\label{sec:qsaveforeign}

\label{sec:qforeign}
Some applications may need to use the foreign language interface.
Object code is by definition machine-dependent and thus cannot be
part of the saved program file.

To complicate the matter even further there are various ways of
loading foreign code:

\begin{itemlist}
    \item [Using the library(shlib) predicates]
This is the preferred way of dealing with foreign code. It loads quickly
and ensures an acceptable level of independence between the versions of
the emulator and the foreign code loaded.  It works on Unix machines
supporting shared libraries and library functions to load them.  Most
modern Unixes, as well as Win32 (Windows 95/NT), satisfy this constraint.
    \item [Static linking]
This mechanism works on all machines, but generally requires the same
C compiler and linker to be used for the external code as is used to
build SWI-Prolog itself.
\end{itemlist}

To make a runtime executable that can run on multiple platforms one
must make runtime checks to find the correct way of linking.  Suppose
we have a source file \file{myextension.c} defining the installation
function install().

If this file is compiled into a shared library, load_foreign_library/1
will load this library and call the installation function to initialise
the foreign code. If it is loaded as a static extension, define
install() as the predicate \nopredref{install}{0}:

\begin{code}
static foreign_t
pl_install()
{ install();

  PL_succeed;
}

PL_extension PL_extensions [] =
{
/*{ "name",     arity,  function,       PL_FA_<flags> },*/

  { "install",  0,      pl_install,     0 },
  { NULL,       0,      NULL,           0 } /* terminating line */
};
\end{code}

Now, use the following Prolog code to load the foreign library:

\begin{code}
load_foreign_extensions :-
        current_predicate(install, install), !, % static loaded
        install.
load_foreign_extensions :-                      % shared library
        load_foreign_library(foreign(myextension)).

:- initialization load_foreign_extensions.
\end{code}

The path alias \const{foreign} is defined by file_search_path/2.  By
default it searches the directories \file{<home>/lib/<arch>} and
\file{<home>/lib}.  The application can specify additional rules for
file_search_path/2.


\section{Using program resources}	\label{sec:useresource}

A \jargon{resource} is very similar to a file.  Resources, however, can
be represented in two different formats: on files, as well as part of
the resource \jargon{archive} of a saved state (see qsave_program/2).

A resource has a \jargon{name} and a \jargon{class}. The \jargon{source}
data of the resource is a file. Resources are declared by declaring the
predicate resource/3. They are accessed using the predicate
open_resource/3.

Before going into details, let us start with an example.  Short texts
can easily be expressed in Prolog source code, but long texts are
cumbersome.  Assume our application defines a command `help' that
prints a helptext to the screen.  We put the content of the helptext
into a file called \file{help.txt}.  The following code implements
our help command such that \file{help.txt} is incorporated into the
runtime executable.

\begin{code}
resource(help, text, 'help.txt').

help :-
	open_resource(help, text, In),
	call_cleanup(copy_stream_data(In, user_output),
		     close(In)).
\end{code}

The predicate help/0 opens the resource as a Prolog stream.  If we are
executing this from the development environment, this will actually
return a stream to the file \file{help.txt} itself. When executed from
the saved state, the stream will actually be a stream opened on the
program resource file, taking care of the offset and length of the
resource.

\subsection{Resource manipulation predicates}
\label{sec:runtime-predicates}

\begin{description}
    \predicate{resource}{3}{+Name, +Class, +FileSpec}
This predicate is defined as a dynamic predicate in the module
\const{user}. Clauses for it may be defined in any module, including the
user module. \arg{Name} is the name of the resource (an atom). A
resource name may contain any character, except for \$ and :, which are
reserved for internal usage by the resource library. \arg{Class}
describes the kind of object stored in the resource. In the
current implementation, it is just an atom. \arg{FileSpec} is a file
specification that may exploit file_search_path/2 (see
absolute_file_name/2).

Normally, resources are defined as unit clauses (facts), but the
definition of this predicate also allows for rules. For proper
generation of the saved state, it must be possible to enumerate the
available resources by calling this predicate with all its arguments
unbound.

Dynamic rules are useful to turn all files in a certain directory
into resources, without specifying a resource for each file.  For
example, assume the file_search_path/2 \const{icons} refers to the
resource directory containing icon files.  The following definition
makes all these images available as resources:

\begin{code}
resource(Name, image, icons(XpmName)) :-
	atom(Name), !,
	file_name_extension(Name, xpm, XpmName).
resource(Name, image, XpmFile) :-
	var(Name),
	absolute_file_name(icons(.), [type(directory)], Dir)
	concat(Dir, '/*.xpm', Pattern),
	expand_file_name(Pattern, XpmFiles),
	member(XpmFile, XpmFiles).
\end{code}

    \predicate{open_resource}{3}{+Name, ?Class, -Stream}
Opens the resource specified by \arg{Name} and \arg{Class}.  If the
latter is a variable, it will be unified to the class of the first
resource found that has the specified \arg{Name}.  If successful,
\arg{Stream} becomes a handle to a binary input stream, providing
access to the content of the resource.

The predicate open_resource/3 first checks resource/3.  When successful
it will open the returned resource source file.  Otherwise it will look
in the program's resource database.  When creating a saved state, the
system normally saves the resource contents into the resource archive,
but does not save the resource clauses.

This way, the development environment uses the files (and modifications)
to the resource/3 declarations and/or files containing resource info,
thus immediately affecting the running environment, while the runtime
system quickly accesses the system resources.
\end{description}


\subsection{The \program{swipl-rc} program}
\label{sec:swiplrc}

The utility program \program{swipl-rc} can be used to examine and manipulate
the contents of a SWI-Prolog resource file.  The options are inspired by
the Unix \program{ar} program.  The basic command is:

\begin{code}
% swipl-rc option resource-file member ...
\end{code}

The options are described below.

\begin{description}
    \cmdlineoptionitem{l}{}
List contents of the archive.
    \cmdlineoptionitem{x}{}
Extract named (or all) members of the archive into the current
directory.
    \cmdlineoptionitem{a}{}
Add files to the archive. If the archive already contains a member with
the same name, the contents are replaced. Anywhere in the sequence of
members, the options \longoption{class}{class} and
\longoption{encoding}{encoding} may appear. They affect the class and
encoding of subsequent files. The initial class is \const{data} and
encoding \const{none}.
    \cmdlineoptionitem{d}{}
Delete named members from the archive.
\end{description}

This command is also described in the \manref{pl}{1} Unix manual page.


\section{Finding Application files}	\label{sec:findappfile}

If your application uses files that are not part of the saved program
such as database files, configuration files, etc., the runtime version
has to be able to locate these files. The file_search_path/2 mechanism
in combination with the \cmdlineoption{-p}{alias} command line argument
is the preferred way to locate runtime files. The first step is to
define an alias for the top-level directory of your application. We will
call this directory \file{gnatdir} in our examples.

A good place for storing data associated with SWI-Prolog runtime systems
is below the emulator's home directory. \const{swi} is a predefined
alias for this directory. The following is a useful default definition
for the search path.

\begin{code}
user:file_search_path(gnatdir, swi(gnat)).
\end{code}

The application should locate all files using absolute_file_name.
Suppose \file{gnatdir} contains a file {\tt config.pl} to define the local
configuration.  Then use the code below to load this file:

\begin{code}
configure_gnat :-
   (   absolute_file_name(gnatdir('config.pl'), ConfigFile)
   ->  consult(ConfigFile)
   ;   format(user_error, 'gnat: Cannot locate config.pl~n'),
       halt(1)
   ).
\end{code}

\subsection{Specifying a file search path from the command line}
\label{sec:runtime-file-search-path}

Suppose the system administrator has installed the SWI-Prolog runtime
environment in \file{/usr/local/lib/rt-pl-3.2.0}. A user wants to
install \file{gnat}, but \file{gnat} will look for its configuration in
\file{/usr/local/lib/rt-pl-3.2.0/gnat} where the user cannot write.

The user decides to install the \file{gnat} runtime files in
\file{/users/bob/lib/gnat}.  For one-time usage, the user may decide
to start \file{gnat} using the command:

\begin{code}
% gnat -p gnatdir=/users/bob/lib/gnat
\end{code}

% do not remove