Embedding SWI-Prolog in a C-program

As of version 2.1.0, SWI-Prolog may be embedded in a C-program. To reach at a compiled C-program with SWI-Prolog as an embedded application is very similar to creating a statically linked SWI-Prolog executable as described in staticl.

The file .../pl/include/stub.c defines SWI-Prologs default main program:

This may be replaced with your own main C-program. The interface function PL_initialise must be called before any of the other SWI-Prolog foreign language functions described in this chapter. PL_initialise interprets all the command-line arguments, except for the -ttoplevel flag that is interpreted by PL_toplevel.

intPL_initialiseint argc, char **argv Initialises the SWI-Prolog heap and stacks, restores the boot QLF file, loads the system and personal initialisation files, runs the at_initialization1 hooks and finally runs the -ggoal hook.

Special consideration is required for argv[0]. On Unix, this argument passes the part of the commandline that is used to locate the executable. Prolog uses this to find the file holding the running executable. The Windows version uses this to find a module of the running executable. If the specified module cannot be found, it tries the module libpl.dll, containing the Prolog runtime kernel. In all these cases, the resulting file is used for two purposes

• See whether a Prolog saved-state is appended to the file. If this is the case, this state will be loaded instead of the default boot.prc file from the SWI-Prolog home directory. See also qsave_program[1,2] and plld.
• Find the Prolog home directory. This process is described in detail in findhome.

PL_initialise returns 1 if all initialisation succeeded and 0 otherwise.Various fatal errors may cause PL_initialise to call PL_halt1, preventing it from returning at all.

In most cases, argc and argv will be passed from the main program. It is allowed to create your own argument vector, provided argv[0] is constructed according to the rules above. For example:

Please note that the passed argument vector may be referred from Prolog at any time and should therefore be valid as long as the Prolog engine is used.

A good setup in Windows is to add SWI-Prolog's bin directory to your PATH and either pass a module holding a saved-state, or "libpl.dll" as argv[0].

intPL_is_initialisedint *argc, char ***argv Test whether the Prolog engine is already initialised. Returns FALSE if Prolog is not initialised and TRUE otherwise. If the engine is initialised and argc is not NULL, the argument count used with PL_initialise is stored in argc. Same for the argument vector argv.

voidPL_install_readline Installs the GNU-readline line-editor. Embedded applications that do not use the Prolog toplevel should normally delete this line, shrinking the Prolog kernel significantly. intPL_toplevel Runs the goal of the -ttoplevel switch (default prolog0) and returns 1 if successful, 0 otherwise. voidPL_haltint status Cleanup the Prolog environment and calls exit() with the status argument.