All-in-one Executables

It is possible to embed saved states into an executable. Together with static linking, this gives an all-in-one executable, an executable which does not depend on external SICStus files.

The keys to this feature are:

• Static linking. By linking an application with a static version of the SICStus run-time, you avoid any dependency on, e.g., sprt39.dll (Windows) or libsprt39.so (Unix). Note that, as of SICStus 3.9, static linking is supported on Windows.

  If the application needs foreign resources (predicates written in C code), as used for example by library(system) and library(clpfd), then these foreign resources can be linked statically with the application as well.

  The remaining component is the Prolog code itself; see the next item.

• Data Resources (in-memory files). It is possible to link an application with data resources that can be read directly from memory. In particular, saved states can be embedded in an application and used when restoring the saved state of the application.

  An application needs two saved states:

  1. The SICStus run-time system (sprt.sav).

     This is added automatically when spld is invoked with the --static (or -S) flag unless the spld-flag --no-embed-rt-sav is specified. It can also be added explicitly with the flag --embed-rt-sav.

  2. The user written code of the application as well as any SICStus libraries.

     This saved state is typically created by loading all application code using compile/1 and then creating the saved state with save_program/2.

Data resources are added by specifying their internal name and their location as part of the comma separated list of resources passed with the spld option --resources. Each data resource is specified as file=name where file is the name of the file containing the data (it must exist during the call to spld) and name is the name used to access the content of file during run-time. name should begin with a slash (/) and look like an ordinary lowercase file path made up of /-separated names consisting of a to z, underscore (_, period (.), and digits.

Typically, you would use spld --main=restore which will automatically restore the first .sav argument. To manually restore an embedded saved state you should use the syntax URL:x-sicstus-resource:name, e.g., SP_restore("URL:x-sicstus-resource:name").

An example will make this clearer. Suppose we create a run-time system that consists of a single file main.pl that looks like:

     :- use_module(library(system)).
     :- use_module(library(clpfd)).
     
     % This will be called when the application starts:
     runtime_entry(start) :-
        %% You may consider putting some other code here...
        write('hello world'),nl,
        write('Getting host name:'),nl,
        host_name(HostName),             % from system
        write(HostName),nl,
        ( all_different([3,9]) ->        % from clpfd
            write('3 != 9'),nl
        ; otherwise ->
            write('3 = 9!?'),nl
        ).
     

Then create the saved state main.sav which will contain the compiled code of main.pl as well as the Prolog code of library(system) and library(clpfd) and other Prolog libraries needed by library(clpfd).

     sicstus -i -f
     
     SICStus 3.9 ...
     Licensed to SICS
     | ?- compile(main).
     % compiling .../main.pl...
     % ... loading several library modules
     | ?- save_program('main.sav').
     % .../main.sav created in 201 msec
     yes
     | ?- halt.
     
     

Finally, tell spld to build an executable statically linked with the SICStus run-time and the foreign resources needed by library(system) and library(clpfd). Also, embed the Prolog run-time saved state and the application specific saved state just created.

(The example is using Cygwin bash (<http://www.cygwin.com>) on Windows but would look much the same on other platforms. The command should be given on a single line; it is broken up here for better layout.)

     spld --static
       --main=restore
       --resources=main.sav=/mystuff/main.sav,clpfd,system
       --output=main.exe
     

The arguments are as follows:

--static

Link statically with the SICStus run-time and foreign resources (system and clpfd in this case). This option also adds --embed-rt-sav ensuring that the SICStus run-time .sav file is embedded.

--main=restore

Start the application by restoring the saved state and calling runtime_entry(start). This is not strictly needed in the above example since it is the default if any file with extension .sav or a data resource with a name with extension .sav is specified.

--resources=...

This is followed by three comma separated resource specifications:

main.sav=/mystuff/main.sav

This tells spld to make the content (at the time spld is invoked) of the file main.sav available at run-time in a data resource named /mystuff/main.sav. That is, the data resource name corresponding to "URL:x-sicstus-resource:/mystuff/main.sav".

clpfd

system

These tell spld to link with the foreign resources (that is, C-code) associated with library(system) and library(clpfd). Since --static was specified the static versions of these foreign resources will be used.

Alternatively, spld can extract the information about the required foreign resources from the saved state (main.sav). This feature is enabled by adding the option --resources-from-sav. By adding this option the example above would be

               spld --static
                 --main=restore
                 --resources-from-sav
                 --resources=main.sav=/mystuff/main.sav
                 --output=main.exe
               

this option was introduced in SICStus 3.10.0 and may become the default in a future release.

--output=main.exe

This tells spld where to put the resulting executable.

Finally, we may run this executable on any machine, even if SICStus is not installed:

     bash-2.04$ ./main.exe
     hello world
     Getting host name:
     EOWYN
     3 != 9
     bash-2.04$
     

Note that no pathnames passed to spld should contain spaces. On MS Windows, this can be avoided by using the short version of pathnames as necessary.