10 Generating Runtime Applications

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 emulator, which is machine dependent. The second part is the resource archive, which contains the compiled program in a machine-independent format, startup options and possibly user-defined 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 concatenate the two parts. This can be achieved using external commands (Unix: cat, Windows: copy), or using the 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 -x command-line switch.

qsave_program(+File, +ListOfOptions)

Saves the current state of the program to the file 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 stand_alone option, the resource is headed by the emulator, a Unix shell-script or nothing.

ListOfOptions is a list of <Key> = <Value> or <Key>(<Value>) pairs. The available keys are described in table 8.

Key	Option	Type	Description
local	-L	K-bytes	Size (Limit) of local stack
global	-G	K-bytes	Size (Limit) of global stack
trail	-T	K-bytes	Size (Limit) of trail stack
argument	-A	K-bytes	Size (Limit) of argument stack
goal	-g	atom	Initialisation goal
toplevel	-t	atom	Prolog top-level goal
init_file	-f	atom	Personal initialisation file
class		atom	If runtime, only read resources from the state (default). If kernel, lock all predicates as system predicates If 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		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.

Table 8 : <Key> = <Value> pairs for qsave_program/2

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 development emulator. The runtime emulator is similar, but lacks the tracer.

If the option stand_alone(true) 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 section 2.10.2.4.

qsave_program(+File)

Equivalent to qsave_program(File, []).

autoload

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 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:

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).

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 library(quintus) explicitly or use require/1 to tell the system that the predicate log/2 is required by this module.

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).

volatile +Name/Arity, \ldots

Declare that the clauses of specified predicates should 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.