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.

local-LK-bytesSize (Limit) of local stack
global-GK-bytesSize (Limit) of global stack
trail-TK-bytesSize (Limit) of trail stack
argument-AK-bytesSize (Limit) of argument stack
goal-gatomInitialisation goal
toplevel-tatomProlog top-level goal
init_file-fatomPersonal initialisation file
classatomIf 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.
autoloadboolIf true, run autoload/0 first
mapfileFile to write info on dump
opsave/standardSave operator declarations?
stand_aloneboolInclude the emulator in the state
emulatorfileEmulator 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

Equivalent to qsave_program(File, []).
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.

Section Index

10.1 Limitations of qsave_program
10.2 Runtimes and Foreign Code
10.3 Using program resources
10.3.1 Predicates Definitions
10.3.2 The plrc program
10.4 Finding Application files
10.4.1 Passing a path to the application
10.5 The Runtime Environment
10.5.1 The Runtime Emulator