qsave_program/2

Documentation
- Reference manual
  - Deploying applications
    - Understanding saved states
      - Creating a saved state
        
        qsave_program/2
        
        qsave_program/1
        
        autoload_all/0
        
        volatile/1
- Packages

Availability::- use_module(library(qsave)).(can be autoloaded)

qsave_program(+File, +Options)

Saves the current state of the program to the file File. The result is a resource archive File containing expresses all Prolog data from the running program, all user-defined resources (see resource/2 and open_resource/2) and optionally all shared objects/DLLs required by the program for the current architecture. 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:

stack_limit(+Bytes)

Sets default stack limit for the new process. See the command line option --stack-limit and the Prolog flag stack_limit.

goal(:Callable)

Initialization goal for the new executable (see -g). Two values have special meaning: prolog starts the Prolog toplevel and default runs halt/0 if there are initialization goals and the prolog/0 toplevel otherwise.

toplevel(:Callable)

Top-level goal for the new executable (see -t). Similar to initialization/2 using main, the default toplevel is to enter the Prolog interactive shell unless a goal has been specified using goal(Callable).

init_file(+Atom)

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

class(+Class)

If runtime (default), read resources from the state and disconnect the code loaded into the state from the original source. If development, save the predicates in their current state and keep reading resources from their source (if present). See also open_resource/3.

autoload(+Boolean)

If true (default), run autoload/0 first. If the class is runtime and autoload is true, the state is supposed to be self contained and autoloading is disabled in the restored state.

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 tests whether a saved state is attached to itself and load this state. Provided the application has all libraries loaded, the resulting executable is completely independent from the runtime environment or location where it was built. See also section 2.11.2.4.

emulator(+File)

File to use for the emulator or executable used by the startup script. Default is the running Prolog image after following symbolic links, e.g., /usr/lib/swipl/lib/x86_64-linux/swipl. To create a saved state based on the public executable such that it can run on multiple archirectures one can use e.g.

$ swipl -o myexe --emulator=$(which swipl) -c myload.pl

foreign(+Action)

If save, include shared objects (DLLs) for the current architecture into the saved state. See current_foreign_library/2, and current_prolog_flag(arch, Arch). 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 resource database. 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.^{229This
option is experimental and currently disabled by default. It will become
the default if it proves robust.}^{230Creating
a temporary file is the most portable way to load a shared object from a
zip file but requires write access to the file system. Future versions
may provide shortcuts for specific platforms that bypass the file
system.}

If Action is of the form arch(ListOfArches) then the shared objects for the specified architectures are stored in the saved state. On the command line, the list of architectures can be passed as --foreign=<CommaSepArchesList>. In order to obtain the shared object file for the specified architectures, qsave_program/2 calls a user defined hook: qsave:arch_shlib(+Arch, +FileSpec, -SoPath). This hook needs to unify SoPath with the absolute path to the shared object for the specified architecture. FileSpec is of the form foreign(Name).

At runtime, SWI-Prolog will try to load the shared library which is compatible with the current architecture, obtained by calling current_prolog_flag(arch, Arch). An architecture is compatible if one of the two following conditions is true (tried in order):

There is a shared object in the saved state file which matches the current architecture name (from current_prolog_flag/2) exactly.
The user definable qsave:compat_arch(Arch1, Arch2) hook succeeds.

This last one is useful when one wants to produce one shared object file that works for multiple architectures, usually compiling for the lowest common denominator of a certain CPU type. For example, it is common to compile for armv7 if even if the code will be running on newer arm CPUs. It is also useful to provide highly-optimized shared objects for particular architectures.

undefined(+Value)

Defines what happens if an undefined predicate is found during the code analysis. Values are ignore (default) or error. In the latter case creating the state is aborted with a message that indicates the undefines predicates and from where they are called.

obfuscate(+Boolean)

If true (default false), replace predicate names with generated symbols to make the code harder to assess for reverse engineering. See section 14.6.1.

verbose(+Boolean)

If true (default false), report progress and status, notably regarding auto loading.