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

## Section Index