[Contents] [Index] [Summary]

6 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 built application consists of at least two parts: the emulator and the compiled application. The latter is in the same format as a SWI-Prolog boot-file and SWI-Prolog pre-compiled (QLF) file. This format is fast loadable and abstracted just far enough to be machine independent. This implies an application delivered in binary format can run on any computer for which an emulator is available without modification.

qsave_program(+File, +ListOfOptions)
Saves the current state of the program to the file File. The result is an executable shell-script, that will start the emulator. ListOfOptions is a list of <Key> = <Value> pairs. The available keys are described in table 8.

KeyOptionTypeDescription
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 toplevel goal
init_file-fatomPersonal initialisation file
autoloadboolIf true, runautoload/0first
mapatomFile containing info on dump
opsave/standardSave operator declarations?
stand_aloneboolInclude the emulator in the state

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

The /bin/sh script contains the following data:

  1. The shell script header starts as: #!/bin/sh #SAVE-VERSION=<num> #PROLOG-VERSION=<num> exec ${SWIPL-/path-to-emulator} -x $0 "$@"

  2. The settings section contains the default values for the various command line options.
  3. The predicates section contains all predicates from the currently running system. Clauses of predicates defined as volatile (see volatile/1) are not saved. Neither are foreign predicates (see also below).
  4. The record section contains the database records saved with recorda/3 and friends. The current version saves records using directives.
  5. The flag section contains the global flags saved using the flag/3 predicate. Flags are saved as directives.
  6. The feature section contains all features that do not originate from the emulator itself. See set_feature/2.
  7. The import section contains the imports as far as they are not handled by the auto-import system. That is, an import is stored if the module is user or the module user contains a different definition as the one imported in the target module.'

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. The stand-alone program chpl(1) may be used to change the default path to the emulator.

If the option stand_alone(on) is present, the emulator is prepended for the state. If the emulator is started and no state is specified using the -x flag, 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 file may be started anywhere.

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 libtary(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