Node:The Application Builder, Next:, Previous:Runtime Systems on Target Machines, Up:Stand-alone Executables


The Application Builder

The application builder, spld, is used for creating stand-alone executables. This tool replaces the scripts spmkrs and spmkds in previous versions of SICStus. It is invoked as: 

% spld [ Option | InputFile ] ...

spld takes the files specified on the command line and combines them into an executable file, much like the UNIX ld or the Windows link commands.

The input to spld can be divided into Options and Files which can be arbitrarily mixed on the command line. Anything not interpreted as an option will be interpreted as an input file. Do not use spaces in any file or option passed to spld. On Windows you can use the short filename for files with space in their name. The following options are available:

--help
Prints out a summary of all options.
-v
--verbose
Print detailed information about each step in the compilation/linking sequence.
-vv
Be very verbose. Prints everything printed by --verbose, and switches on verbose flags (if possible) to the compiler and linker.
--version
Prints out the version number of spld and exits successfully.
-o
--output=filename
Specify output filename. The default depends on the linker (e.g. a.out on UNIX systems).
-D
--development
Create a development system (with top-level, debugger, compiler, etc.). The default is to create a runtime system. Implies --main=prolog.
--main=type
runtime_entry(+Message) [Hook]
user:runtime_entry(+Message)
Specify what the executable should do upon startup. The possible values are prolog, user, restore and load.

prolog
Implies -D. The executable will start the Prolog top-level. This is the default if -D is specified and no .sav, .pl, .po, or .ql files are specified.
user
The user supplies his/her own main-program by including C-code (object file or source) which defines a function user_main(). This option is not compatible with -D. See User-defined Main Programs.
restore
The executable will restore a saved-state created by save_program/[1,2]. This is the default if a .sav file is found among Files. It is only meaningful to specify one .sav file. If it was created by save_program/2, the given startup goal is run. Then the executable will any Prolog code specified on the command line. Finally, the goal user:runtime_entry(start) is run. The executable exits with 0 upon normal temination and with 1 on failure or exception. Not compatible with -D.
load
The executable will load any Prolog code specified on the command line, i.e. files with extension .pl, .po or .ql. This is the default if there are .pl, .po or .ql but no .sav files among Files. Finally, the goal user:runtime_entry(start) is run. The executable exits with 0 upon normal temination and with 1 on failure or exception. Not compatible with -D. Note that this is almost like --main==restore except that no saved state will be restored before loading the other files.
none
No main function is generated. The main function must be supplied in one of the user supplied files. Not compatible with -D.

--window
Win32 only. Create a windowed executable. A console window will be opened and connected to the Prolog standard streams. If --main=user is specified, user_main() should not set the user-stream hooks. C/C++ source code files specified on the command-line will be compiled with -DSP_WIN=1 if this option is given.
--moveable

Under UNIX, paths are normally hardcoded into executables in order for them to find the SICStus libraries and bootfiles. Two paths are normally hardcoded; the value of SP_PATH and, where possible, the runtime library search path using the -R linker option (or equivalent). If the linker does not support the -R flag (or an equivalent), a wrapper script is generated instead which sets LD_LIBRARY_PATH (or equivalent).

The --moveable option turns off this behavior, so the executable is not dependent on SICStus being installed in a specific place. On some platforms the executable can figure out where it is located and so can locate any files it need, e.g. using SP_APP_DIR and SP_RT_DIR. On some UNIX platforms, however, this is not possible. In these cases, if this flag is given, the executable will rely on environment variables (SP_PATH (see Environment Variables) and LD_LIBRARY_PATH, etc.) to find all relevant files.

Under Windows, this option is always on, since Windows applications do no need to hardcode paths in order for them to find out where they're installed. See Launching Runtime Systems on Target Machines, for more information on how SICStus locates its libraries and bootfiles.

-S
--static
Prefer static linking over dynamic. When --static is specified, spld will try to use static (not shared) versions of libraries and object-files. This option can be used to minimize runtime dependencies on shared libraries/object-files. In particular, a static version of the SICStus run-time will be used and any SICStus foreign resources specified with --resources will be statically linked with the executable. In addition, --static implies --embed-rt-sav.

Under UNIX, even if there is a static version of a library (such as for example Tcl/Tk (libtcl8.0.a), spld may still use the dynamic version (libtcl8.0.so). This is because there is no portable way of telling the linker to prefer static libraries over shared, it is usually only possible to link statically or dynamically; the modes are usually exclusive. In this case, spld will go with the linker's default, which is usually dynamic. If you are in a situation where you would want spld to use a static library instead of a dynamic one, you will have to hack into spld's configuration file spconfig-version (normally located in <installdir>/bin). We recommend that you make a copy of the configuration file and specify the new configuration file using --config=<file>. A typical modification of the configuration file for this purpose may look like: 

[...]
TCLLIB=-Bstatic -L/usr/local/lib -ltk8.0 -ltcl8.0 -Bdynamic
[...]
Use the new configuration file by typing 
% spld [...] -S --config=/home/joe/hacked_spldconfig [...]

--shared
Create a shared library runtime system instead of an ordinary executable. Not compatible with --static. Implies --main=none.

Not supported on all platforms.

--resources=ResourceList
ResourceList is a comma-separated list of resource names, describing which resources should be pre-linked with the executable. Names can be either simple resource names, for example tcltk, or they can be complete paths to a foreign resource (with or without extensions). Example 
% spld [...] --resources=tcltk,clpfd,/home/joe/foobar.so
This will cause library(tcltk), library(clpfd), and /home/joe/foobar.so to be pre-linked with the executable. See also the option --respath below.

It is also possible to embed a data resource, that is, the contents of an arbitrary data file that can be accessed at run-time.

It is possible to embed any kind of dat, but, currently, only restore/1 knows about data resources. For this reason it only makes sense to embed .sav files.

The primary reason to embed files within the executable is to create an all-in-one executable, that is, an executable file that does not depend on any other files and that therefore is easy to run on machines without SICStus installed. See All-in-one Executables, for more information.

--respath=Path
Specify additional paths used for searching for resources. Path is a list of search-paths, colon separated on Unix, semicolon separated on Windows. spld will always search the default library directory as a last resort, so if this option is not specified, only the default resources will be found. See also the --resources option above.
--config=ConfigFile
Specify another configuration file. This option is not intended for normal use. The filename may not contain spaces.
--cflag=CFlag
CFlag is a comma-separated list of options to send to the C-compiler. Any commas in the list will be replaced by spaces. This option can occur multiple times.
-LD
Do not process the rest of the command-line, but send it directly to the compiler/linker. Syntactic sugar for --cflag.
--sicstus=Executable
spld relies on using SICStus during some stages of its execution. The default is the SICStus-executable installed with the distribution. Executable can be used to override this, in case the user wants to use another SICStus executable.
--interactive
-i
Only applicable with --main=load or --main=restore. Calls SP_force_interactive() (see Initializing the Prolog Engine) before initializing SICStus.
--memhook=hook
Corresponds to SP_set_memalloc_hooks(MM_USE_hook,...). hook can be one of default, sbrk, malloc or sparse, corresponding respectively to MM_USE_DEFAULT, MM_USE_SBRK, MM_USE_MALLOC and MM_USE_SPARSE. This option can only be used with --main=load and --main=restore.
--lang=Dialect
Corresponds to prolog_flag(language,_,Dialect). Dialect can be one of iso or sicstus. The language mode is set before restoring or loading any argument files. This option can only be used with --main=load and --main=restore.
--userhook
This option enables you to define your own version of the SU_initialize() function. SU_initialize() is called by the main program before SP_initialize(). Its purpose is to call interface functions which must be called before SP_initialize(), such as SP_set_memalloc_hooks(). It is not meaningful to specify this option if --main=user or --main=none is given.

SU_initialize() should be defined as: 

int SU_initialize(int argc, char *argv[])
The contents of argv should not be modified. SU_initialize() should return 0 for success and non-zero for failure. If a non-zero value is returned, the development system exits with the return value as error code.
--with_jdk=DIR
--with_tcltk=DIR
--with_tcl=DIR
--with_tk=DIR
--with_bdb=DIR
Specify the installation path for external (third-party) software. This is mostly useful on Windows. Under UNIX, the installation script manages this automatically.
--keep
Keep temporary files and interface code and rename them to human-readable names. Not intended for the casual user, but useful if you want to know exactly what code is generated.
--nocompile
Do not compile, just generate code. This may be useful in Makefiles, for example to generate the header file in a separate step. Implies --keep.
--namebase=namebase
Use namebase to construct the name of generated files. This defaults to spldgen_ or, if --static is specified, spldgen_s_.
--embed-rt-sav
--no-embed-rt-sav
--embed-rt-sav will embed the SICStus run-time .sav file into the executable. This is off by default unless --static is specified. It can be forced on (off) by specifying --embed-rt-sav (--no-embed-rt-sav).
--multi-sp-aware
Compile the application with support for using more than one SICStus run-time in the same process. Not compatible with --static or pre-liked foreign resources. See Multiple SICStus Run-Times in C, for details.

Arguments to spld which are not recognized as options are assumed to be input-files and are handled as follows:

*.pl
*.po
*.ql
These are interpreted as names of files containing Prolog code and will be passed to SP_load() at run-time (if --main is load or restore. If the intention is to make an executable that works independently of the run-time working directory, avoid relative filenames. Instead use absolute filenames, SP_APP_DIR or embed a .sav file as a data resource, using --resource.
*.sav
These are interpreted as names of files containing saved states and will be passed to SP_restore() at run-time if --main=restore is specified, subject to the above caveat about relative filenames.

It is not meaningful to give more than one .sav argument.

*.so
*.sl
*.s.o
*.o
*.obj
*.dll
*.lib
*.dylib
These files are assumed to be input-files to the linker and will be passed on unmodified.
*.c
*.cc
*.C
*.cpp
*.c++
These files are assumed to be C/C++ source code and will be compiled by the C/C++-compiler before being passed to the linker.

If an argument is still not recognized, it will be passed unmodified to the linker.