13.3 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.

-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, 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’ 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 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 the system properties and enviroment variables (SP_PATH (see System Properties and 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.

--conf VAR=VALUE

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 occurences 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.

--

--LD

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

--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_memalloc_hooks(). It is not meaningful to specify this option if --main=user or --main=none is given.

--memhook

This option allows you to specify which memory manager to use. One of default or malloc. If specified as malloc, SP_set_memalloc_hooks() will be called with SP_SET_MEMALLOC_HOOKS_HINT_USE_MALLOC and the C library malloc() will be used for all allocations instead of SICStus default allocator. See cpg-ref-SP_set_memalloc_hooks for more information.

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

--license-file=LicenseFile

Specify the 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

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

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 run-time (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, 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 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.

See Also

See The Application Builder.