13.5 spld — SICStus Prolog Application Builder

Synopsis

% spld [ Option | InputFile ] …

Description

The application builder, spld, is used for creating stand-alone executables. See The Application Builder for an overview.

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.

Options

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. This may document more options than those described in this manual.

-v

--verbose

Print detailed information about each step in the compilation/linking sequence. Multiple occurrences increase verbosity.

-vv

Same as -v -v.

--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. Extended runtime systems need access to license information; see Extended Runtime 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

Specify what the executable should do upon startup. The possible values are:

prolog

Implies -D. The executable will start the Prolog top level. This is the default if -D is specified and no ‘.sav’, ‘.pl’, or ‘.po’ 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, then 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 termination 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’ or ‘.po’. This is the default if there are ‘.pl’ or ‘.po’ but no ‘.sav’ files among Files. Finally, the goal user:runtime_entry(start) is run. The executable exits with 0 upon normal termination 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, then 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

--no-moveable

Controls whether to hard-code certain paths into the executable in order for it to find the SICStus libraries and bootfiles etc.

Under UNIX, if --no-moveable is specified, then paths are hard-coded into executables in order for them to find the SICStus libraries and bootfiles. Two paths are normally hard-coded; 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), then 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 most 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, --moveable is in effect, the executable will rely on the system properties and environment variables (SP_PATH (see System Properties and Environment Variables) and LD_LIBRARY_PATH etc.) to find all relevant files.

Under Windows, --moveable is always on, since Windows applications do not need to hard-code paths in order for them to find out where they are installed. On UNIX platforms, --moveable is the default (as of release 4.2) but can be turned off with --no-moveable. See Runtime Systems on Target Machines for more information on how SICStus locates its libraries and bootfiles.

-S

--static

Link statically with SICStus runtime and foreign resources. When --static is specified, a static version of the SICStus runtime 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, then 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 runtime 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. Implies --main=none.

Can be combined with --static to create a all-in-one shared library runtime system.

--resources=ResourceList

ResourceList is a comma-separated list of resource names, describing which resources should be prelinked 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 prelinked 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 runtime.

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

--conf VAR=VALUE   since release 4.0.3

Override values from the configuration file. Can occur multiple times. For instance, ‘--conf CC=/usr/bin/gcc’ would override the default C compiler.

--cflag=CFlag

CFlag is an option to pass to the C-compiler. This option can occur multiple times.

The current behavior is that if CFlag contains commas, then each comma-separated part is treated as a separate compiler option. This may change in the future, so instead you should use multiple occurrences of --cflag. To turn off splitting at commas and treat CFlag as a single option even it contains a comma, you can pass the option --conf SPLIT_OPT_CFLAG=0. This can be useful with certain options to the gcc compiler.

--cxx   since release 4.7.0

This enables improved handling of C++ code. It is automatically enabled if any C++ source code is detected.

On some platforms the C++ compiler will be used for linking instead of the C compiler. On some platforms you may need to pass extra options to ensure the C++ library is available.

It can be disabled with --nocxx, e.g. if the C++ support causes some backward compatibility problem.

--   since release 4.0.3

--LD   since release 4.0.3

-LD

Do not process the rest of the command line, but send it directly to the linker step. Note that linking is often performed by the compiler.

--sicstus=Executable

spld relies on using SICStus during some stages of its execution. The default is the development system installed with the distribution. Executable can be used to override this, in case the user wants to use another development system.

--interactive

-i

Only applicable with --main=load or --main=restore. Calls SP_force_interactive() (see Initializing the Prolog Engine) before initializing SICStus.

--userhook

This option allows 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 that must be called before SP_initialize(), such as SP_set_user_stream_hook(). It is not meaningful to specify this option if --main=user or --main=none is given.

--locale=LOCALE   since release 4.3

--no-locale

By default, on UNIX platforms, the executable created by spld sets the process locale from the environment.

Setting the process locale from the environment can suppressed by passing the --no-locale option to spld. This corresponds to the behavior prior to release 4.3.

An explicit locale that the process should set on initialization, can be passed with the --locale option to spld.

The valid locale names depends on the operating system. Typically you can use the locale utility, with the -a option, to list all valid locale names.

--with_jdk=DIR

--with_tcltk=DIR

--with_tcl=DIR

--with_tk=DIR

--with_bdb=DIR

Specify the installation path for third-party software for foreign resources, such as jasper, that have special dependencies. 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 runtime ‘.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.

--license-file=LicenseFile

Specify the path to the license information needed by extended runtime systems. Only relevant with --extended-rt. See Extended Runtime Systems for details.

--embed-license

--no-embed-license

Controls whether to embed the license information in the executable. --no-embed-license is the default. Only relevant with --extended-rt. See Extended Runtime Systems for details.

--multi-sp-aware

Compile the application with support for using more than one SICStus runtime in the same process. Not compatible with --static or prelinked foreign resources. See Multiple SICStus Runtimes in C for details.

There may be additional, undocumented, options, some of which may be described with the --help option.

Files

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

‘*.pro’

‘*.pl’

‘*.po’

These are interpreted as names of files containing Prolog code and will be passed to SP_load() at runtime (if --main is load or restore). Please note: If the intention is to make an executable that works independently of the working directory at run time, then avoid relative file names, for they will be resolved at run time, not at spld time. 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 runtime 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’

‘*.C’

These files are assumed to be C source code and will be compiled by the C-compiler before being passed to the linker.

‘*.cc’

‘*.cpp’

‘*.c++’

These files are assumed to be C++ source code and will be compiled by the C++ compiler before being passed to the linker.

Prior to release 4.7, these files would be compiled with the C compiler. The --nocxx option can be used if the legacy behavior is desired.

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

See Also

See The Application Builder.