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

The Application Builder

• Customizing spld: Customizing spld under UNIX
• All-in-one Executables: All-in-one Executables
• spld Examples: Examples

The application builder, spld, is used for creating stand-alone executables. This tool replaces the tools spmkrs and spmkds of 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.

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

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. Under Windows you can use the short file name 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 file name. The default depends on the linker (e.g. a.out on UNIX systems).

-E

--extended-rt

Create an extended runtime system. In addition to the normal set of built-in runtime system predicates, extended runtime systems include the compiler. Extended runtime systems require the extended runtime library, available from SICS as an add-on product.

-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 option (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 option 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 not need to hardcode paths in order for them to find out where they're installed. See Runtime Systems on Windows Target Machines, for more information on how SICStus locates its libraries and bootfiles.

-S

--static

Link statically with SICStus run-time and foreign resources. When --static is specified, 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, --embed-sav-file and --resources-from-sav.

Even with --static, 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 [...]

The SICStus run-time depends on certain OS support that is only available in dynamically linked executables. For this reason it will probably not work to try to tell the linker to build a completely static executable, i.e. an executable that links statically also with the C library and that cannot load shared objects.

--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 data, 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.

--resources-from-sav

--no-resources-from-sav

When embedding a saved-state as a data resource (with --resources or --embed-sav-file), this option extracts information from the embedded saved-state about the names of the foreign resources that were loaded when the saved-state was created. This is the default for static executables when no other resource is specified except the embedded saved-state. This option is only supported when a saved-state is embedded as a data resource. See All-in-one Executables, for more information.

Use --no-resources-from-sav to ensure that this feature is not enabled.

--respath=Path

Specify additional paths used for searching for resources. Path is a list of search-paths, colon separated under UNIX, semicolon separated under 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 file name 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 obsolescent

For compatibility with previous versions. Ignored.

--more-memory

--no-more-memory

Applies platform specific tricks to ensure that the Prolog stacks can use close to 256MB (on 32bit architectures). Currently only affects x86 Linux where it circumvents the default 128MB limit. Ignored on other platforms. Not compatible with --shared. Somewhat experimental since the required linker options are not well documented. This is the default on Linux. It can be forced on (off) by specifying --more-memory (--no-more-memory).

--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 third-party software. This is mostly useful under 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).

--embed-sav-file

--no-embed-sav-file

--embed-sav-file will embed any .sav file passed to spld into the executable. This is just a shorthand for avoiding the ugly data resource syntax of the --resources option. This is the default when --static is specified. It can be forced on (off) by specifying --embed-sav-file (--no-embed-sav-file). A file ./foo/bar.sav will be added with the data resource name /bar.sav, i.e. as if --resources=./foo/bar.sav=/bar.sav had been specified.

--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-linked foreign resources. See Multiple SICStus Run-Times in C, for details.

Arguments to spld 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 file names. Use absolute file names instead, SP_APP_DIR, SP_LIBRARY_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 file names.

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.