\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 different 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}{} commandline switch.


\begin{description}
    \predicate{qsave_program}{2}{+File, +ListOfOptions}
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{ListOfOptions} is a list of $<Key> = <Value>$ or $<Key>(<Value>)$
pairs. The available keys are described in \tabref{qsave-options}.

\begin{table}
\begin{center}
\begin{tabular}{|l|c|c|p{3in}|}
\hline
\bf Key & \bf Option    & \bf Type      & \bf Description \\
\hline
local    & \bf -L       & K-bytes       & Size (Limit) of local stack \\
global   & \bf -G       & K-bytes       & Size (Limit) of global stack \\
trail    & \bf -T       & K-bytes       & Size (Limit) of trail stack \\
argument & \bf -A       & K-bytes       & Size (Limit) of argument stack \\
goal     & \bf -g       & atom          & Initialisation goal \\
toplevel & \bf -t       & atom          & Prolog toplevel goal \\
init_file& \bf -f       & atom          & Personal initialisation file \\
\hline
class	 &		& atom		& 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. \\
autoload &              & bool          & If true, run autoload/0 first \\
map      &              & file          & File to write info on dump \\
op       &              & \tt save/standard & Save operator declarations? \\
stand_alone &           & bool          & Include the emulator in the state \\
emulator &		& file		& Emulator attached to the
					  (stand-alone) executable.  Default
					  is the running emulator. \\
\hline
\end{tabular}
\end{center}

    \caption{<Key> = <Value> pairs for qsave_program/2}
    \label{tab:qsave-options}
\end{table}

Before writing the data to file, qsave_program/2 will run autoload/0 to
all required autoloading the system can discover.  See autoload/0.

Provided the application does not require any of the Prolog libraries to
be loaded at runtime, the only file from the SWI-Prolog development
environment required is the emulator itself.  The emulator may be built
in two flavours.  The default is the \jargon{development emulator}.  The 
\jargon{runtime emulator} is similar, but lacks the tracer.

If the option \exam{stand_alone(on)} is present, 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 build.

See also \secref{cmdlinecomp}.

    \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
will not depend on one of the libraries. The predicate autoload/0 will
find all \strong{direct} references to predicates. It does not find
predicates referenced via meta-predicates. The predicate {log}/2 is
defined in the library(quintus) to provide a quintus compatible means to
compute the natural logarithm of a number. The following program will
behave correctly if its state is executed in an environment where the
library(quintus) is not available:

\begin{code}
logtable(From, To) :-
        From > To, !.
logtable(From, To) :-
        log(From, Value),
        format('~d~t~8|~2f~n', [From, Value]),
        F is From + 1,
        logtable(F, To).
\end{code}

However, the following implementation refers to {log}/2 through the
meta-predicate maplist/3.  Autoload will not be able to find the
reference.  This problem may be fixed either by loading the
module libtary(quintus) explicitly or use require/1 to tell the
system that the predicate {log}/2 is required by this module.

\begin{code}
logtable(From, To) :-
        findall(X, between(From, To, X), Xlist),
        maplist(log, Xlist, SineList),
        write_table(Xlist, SineList).

write_table([], []).
write_table([I|IT], [V|VT]) :-
        format('~d~t~8|~2f~n', [I, V]),
        write_table(IT, VT).
\end{code}
    \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
avoid that the clauses of dynamic predicates that represent data for
the current session is 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 then 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 {\tt myextension} defining the installation
function \funcref{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
\funcref{install}{} as the predicate 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 sourcecode, 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 help.txt is incorperated into the runtime
executable.

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

help :-
	open_resource(help, text, In),
	copy_stream(In, user_output),
	close(In).

copy_stream(In, Out) :-
	get0(In, C),
	copy_stream(C, In, Out).

copy_stream(-1, _, _) :- !.
copy_stream(C, In, Out) :-
	put(Out, C),
	get0(In, C2),
	copy_stream(C2, In, Out).
\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{gelp.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{Predicates Definitions}

\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 what kind of object is 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 resources 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 succesful
it will open the returned resource source-file.  Otherwise it will look
in the programs 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 affect the running environment, while the runtime
system quickly accesses the system resources.
\end{description}

			    
\subsection{The \program{plrc} program}			\label{sec:plrc}

The utility program \program{plrc} 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}
% plrc 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 is 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 toplevel 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 gnatdir contains a file {\tt config.pl} to define 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{Passing a path to the application}

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 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 gnat runtime files in
\file{/users/bob/lib/gnat}.  For one-time usage, the user may decide
to start gnat using the command:

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

\section{The Runtime Environment}	\label{sec:runenv}

\subsection{The Runtime Emulator}

The sources may be used to built two versions of the emulator. By
default, the \jargon{development emulator} is built. This emulator
contains all features for interactive development of Prolog
applications. If the system is configured using
\cmdlineoption{--enable-runtime}{}, \manref{make}{1} will create a
\jargon{runtime version} of the emulator. This emulator is equivalent to
the development version, except for the following features:

\begin{itemlist}
\item [No input editing]
The GNU library \clib{-lreadline} that provides EMACS compatible editing
of input lines will not be linked to the system.
\item [No tracer]
The tracer and all its options are removed, making the system a little
faster too.
\item [No profiler]
profile/3 and friends are not supported.  This saves some space and
provides better performance.
\item [No interrupt]
Keyboard interrupt (Control-C normally) is not rebound and will normally
terminate the application.
\item [current_prolog_flag(runtime, true) succeeds]
This may be used to verify your application is running in the runtime
environment rather than the development environment.
\item [clause/[2,3] do not work on static predicates]
This prolog-flag inhibits listing your program.  It is only a very limited
protection however.
\end{itemlist}

The following fragment is an example for building the runtime
environment in \file{\env{HOME}/lib/rt-pl-3.2.0}. If possible, the
shared-library interface should be configured to ensure it can serve a
large number of applications.

\begin{code}
% cd pl-3.2.0
% mkdir runtime
% cd runtime
% ../src/configure --enable-runtime --prefix=$HOME
% make
% make rt-install
\end{code}

The runtime directory contains the components listed below. This
directory may be tar'ed and shipped with your application.
			    
\begin{center}
\begin{tabular}{|l|l|}
\hline
\file{README.RT}        & Info on the runtime environment \\
\hline
\file{bin/<arch>/pl}    & The emulator itself \\
\hline
\file{man/pl.1}         & Manual page for pl \\
\hline
\file{swipl}            & pointer to the home directory (.) \\
\hline
\file{lib/}             & directory for shared libraries \\
\file{lib/<arch>/}      & machine-specific shared libraries \\
\hline
\end{tabular}
\end{center}