11 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 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, +Options)

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. Options is a list of additional options:

local(+KBytes)

Limit for the local stack. See section 2.4.3.

global(+KBytes)

Limit for the global stack. See section 2.4.3.

trail(+KBytes)

Limit for the trail stack. See section 2.4.3.

goal(:Callable)

Initialization goal for the new executable (see -g).

toplevel(:Callable)

Top-level goal for the new executable (see -t).

init_file(+Atom)

Default initialization file for the new executable. See -f.

class(+Class)

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(+Boolean)

If true (default), run autoload/0 first.

map(+File)

Dump a human-readable trace of what has been saved in File.

op(+Action)

One of save (default) to save the current operator table or standard to use the initial table of the emulator.

stand_alone(+Boolean)

If 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 section 2.10.2.4.

emulator(+File)

File to use for the emulator. Default is the running Prolog image.

foreign(+Action)

If save, include shared objects (DLLs) into the saved state. See current_foreign_library/2. If the 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.^{158This option is experimental and currently disabled by default. It will become the default if it proves robust.}

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

• Direct goals appearing in the body
• Arguments of declared meta-predicates that are marked with an integer (0..9). See meta_predicate/1.

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:

        ...,
        Goal = prove(Theory),
        forall(current_theory(Theory),
               Goal)),

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

        ...,
        member(Goal, [ prove_simple(Theory),
                       prove_complex(Theory)
                     ]),
        forall(current_theory(Theory),
               Goal)),

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.

volatile +Name/Arity, ...

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