2.10 Compilation

2.10.1 During program development

During program development, programs are normally loaded using consult/1, or the list abbreviation. It is common practice to organise a project as a collection of source files and a load-file, a Prolog file containing only use_module/[1,2] or ensure_loaded/1 directives, possibly with a definition of the entry-point of the program, the predicate that is normally used to start the program. This file is often called load.pl. If the entry-point is called go, a typical session starts as:

% pl
<banner>

1 ?- [load].
<compilation messages>

Yes
2 ?- go.
<program interaction>

When using Windows, the user may open load.pl from the Windows explorer, which will cause plwin.exe to be started in the directory holding load.pl. Prolog loads load.pl before entering the top-level.

2.10.2 For running the result

There are various options if you want to make your program ready for real usage. The best choice depends on whether the program is to be used only on machines holding the SWI-Prolog development system, the size of the program and the operating system (Unix vs. Windows).

2.10.2.1 Using PrologScript

New in version 4.0.5 is the possibility to use a Prolog source file directly as a Unix script-file. The same mechanism is useful to specify additional parameters for running a Prolog file on Windows.

If the first letter of a Prolog file is #, the first line is treated as comment.6The #-sign can be the legal start of a normal Prolog clause. In the unlikely case this is required, leave the first line blank or add a header-comment. To create a Prolog script, make the first line start like this:

#!/path/to/pl <options> -s

Prolog recognises this starting sequence and causes the interpreter to receive the following argument-list:

/path/to/pl <options> -s <script> -- <ScriptArguments>

Instead of -s, the user may use -f to stop Prolog from looking for a personal initialisation file.

Here is a simple script doing expression evaluation:

#!/usr/bin/pl -q -t main -f

eval :-
        current_prolog_flag(argv, Argv),
        append(_, [--|Args], Argv),
        concat_atom(Args, ' ', SingleArg),
        term_to_atom(Term, SingleArg),
        Val is Term,
        format('~w~n', [Val]).

main :-
        catch(eval, E, (print_message(error, E), fail)),
        halt.
main :-
        halt(1).

And here are two example runs:

% eval 1+2
3
% eval foo
ERROR: Arithmetic: `foo/0' is not a function
%

The Windows version supports the #! construct too, but here it serves a rather different role. The Windows shell already allows the user to start Prolog source files directly through the Windows file-type association. Windows however makes it rather complicated to provide additional parameters, such as the required stack-size for an individual Prolog file. The #! line provides for this, providing a more flexible approach than changing the global defaults. The following starts Prolog with unlimited stack-size on the given source file:

#!/usr/bin/pl -L0 -T0 -G0 -s

....

Note the use of /usr/bin/pl, which specifies the interpreter. This argument is ignored in the Windows version, but required to ensure best cross-platform compatibility.

2.10.2.2 Creating a shell-script

With the introduction of PrologScript (see section 2.10.2.1), using shell-scripts as explained in this section has become redundant for most applications.

Especially on Unix systems and not-too-large applications, writing a shell-script that simply loads your application and calls the entry-point is often a good choice. A skeleton for the script is given below, followed by the Prolog code to obtain the program arguments.

#!/bin/sh

base=<absolute-path-to-source>
PL=pl

exec $PL -f none -g "load_files(['$base/load'],[silent(true)])" \
         -t go -- $*
go :-
        current_prolog_flag(argv, Arguments),
        append(_SytemArgs, [--|Args], Arguments), !,
        go(Args).

go(Args) :-
        ...

On Windows systems, similar behaviour can be achieved by creating a shortcut to Prolog, passing the proper options or writing a .bat file.

2.10.2.3 Creating a saved-state

For larger programs, as well as for programs that are required to run on systems that do not have the SWI-Prolog development system installed, creating a saved state is the best solution. A saved state is created using qsave_program/[1,2] or using the linker plld(1). A saved state is a file containing machine-independent intermediate code in a format dedicated for fast loading. Optionally, the emulator may be integrated in the saved state, creating a single-file, but machine-dependent, executable. This process is described in chapter 10.

2.10.2.4 Compilation using the -c command-line option

This mechanism loads a series of Prolog source files and then creates a saved-state as qsave_program/2 does. The command syntax is:

% pl [option ...] [-o output] -c file ...

The options argument are options to qsave_program/2 written in the format below. The option-names and their values are described with qsave_program/2.

--option-name=option-value

For example, to create a stand-alone executable that starts by executing main/0 and for which the source is loaded through load.pl, use the command

% pl --goal=main --stand_alone=true -o myprog -c load.pl

This performs exactly the same as executing

% pl
<banner>
?- [load].
?- qsave_program(myprog,
                 [ goal(main),
                   stand_alone(true)
                 ]).
?- halt.