.\" -*- nroff -*-
.TH swipl 1 "Oct 10, 2020" "SWI-Prolog 8"
.SH NAME
swipl \- SWI-Prolog 9.0.4
.SH SYNOPSIS
.B swipl
.RB [ \-\-help | \-\-version | \-\-arch | \-\-dump\-runtime\-variables ]
.br
.B swipl
[options]
.IR prolog-file " ... [--] [" arg " ...]"
.br
.B swipl
[options]
.RB [ "\-o \fIoutput" ]
.BI \-c " file ..."
.br
.B swipl
[options]
.RB [ "\-o \fIoutput" ]
.BI \-b " initfile ..."

The first version provides information about the system and exits
immediately. The second version is the primary way to call Prolog on one
or more Prolog source file(s) and provide arguments to the application that
can be requested using
.BR "current_prolog_flag" "(argv, Argv)."
The third version is used to create a
.I saved state
while the last version is used for boot-compilation of the Prolog parts of the
system.

.SH DESCRIPTION
SWI-Prolog is a comprehensive and stable implementation of
the Prolog language with a large set of libraries. Among its
distinguishing features are mature support for multi-threading, a mature
embedded web-server library, graphical development tools (debugger,
profiler, cross-referencer, editor), an embedded efficient RDF store,
support for XML/SGML/HTML and Unicode.  More widely supported features
are support for constraint programming, atom garbage collection, interfaces
to databases (ODBC), C, C++ and Java (JPL).

SWI-Prolog implements the ISO core standard. Many of its extensions are
largely compatible to YAP and SICStus Prolog.

This manual page only lists the commandline options.  Full documentation
is available on-line as well as in
.BR HTML " and " PDF
format from the WWW home page at
.B http://www.swi-prolog.org

.SH OPTIONS
.TP
.B \-\-help
Give a summary of the most important options.
.TP
.B \-\-version
Display version and architecture information.
.TP
.B \-\-abi\-version
Display ABI version key.  This key indicates binary compatibility of
various interfaces.
.TP
.B \-\-arch
Print the architecture identifier.
.TP
.BR \-\-dump\-runtime\-variables [=format]
Dump information that is generally useful for installation scripts in
a form defined by
.IR format .
Defines formats are
.BR sh " (default, bourne shell) and " cmd " (Windows CMD)" .
This option is used by
.B swipl-ld (1)
to fetch necessary information about Prolog.  It is normally invoked as
.I eval `swipl --dump-runtime-variables`,
which assigns the following shell variables:
.RS
.TP
.B CC
The
.B C\-
compiler used to compile SWI-Prolog.
.TP
.B PLBASE
The home directory of SWI-Prolog.  This is the same value as returned
by the
.I current_prolog_flag home.
.TP
.B PLARCH
The architecture identifier used.  Together with
.B PLBASE
this defines the location of various components.  For example,
the library for embedding is in
.B $PLBASE/lib/$PLARCH/libswipl.a
.TP
.B PLBITS
Address bits for VM.  Either 32 or 64.
.TP
.B PLLIB
CC identifier to link to SWI-Prolog.  Typically
.B -lswipl
.TP
.B PLLIBSWIPL
Full path name to the shared object (DLL) that provides the Prolog core.
.TP
.B PLLIBS
Additional libraries needed for linking PLLIB
.TP
.B PLCFLAGS
Flags that need to be passed to the C-compiler to generate compatible
code.
.TP
.B PLLDFLAGS
Flags that need to be passed to the C-linker for linking embedded executables.
.TP
.B PLSOEXT
Extension used by the hosting operating system for shared objects. On most
Unix systems this is "so"; on MS-Windows it is "dll".  AIX uses "o", HPUX
"sl".
.TP
.B PLSOPATH
Environment variable used by the hosting operating system to extend the
search path for shared objects.  For example, on ELF systems this is
"LD_LIBRARY_PATH" and on MS-Windows it is "PATH".
.TP
.B PLVERSION
Numeric representation of the SWI-Prolog version.
.TP
.B PLVERSIONTAG
If present, a version tag such as "rc1".
.TP
.B PLSHARED
Has the value
.B yes
if Prolog supports linking shared libraries using
.B load_foreign_library/[1,2]
and
.B no
otherwise.
.TP
.B PLTHREADS
Has the value
.B yes
if Prolog was compiled for multi-threading and
.B no
otherwise.
.RE
.TP
.BI \-\-home= DIR
Use
.I DIR
as home directory.
.TP
.BI \-\-stack\-limit= size [bkmg]
Set the combined stack limit to
.IR size " bytes."
The suffix is case insensitive and defines the unit as
.IR b " (bytes),"
.IR k " (Kbytes),"
.IR m " (Mbytes) or "
.IR g " (Gbytes)."
.TP
.BI \-\-table\-space= size [bkmg]
Set the table space limit for SLG resolution (tabling) to
.IR size " bytes."
The suffixes are the same as for the
.B --stack-limit
option.
.TP
.BI \-\-shared\-table\-space= size [bkmg]
Set the table space limit for shared tabling to
.IR size " bytes."
The suffixes are the same as for the
.B --stack-limit
option.
.TP
.BI \-O
Optimised compilation. See
.B set_prolog_flag/2
in the SWI-Prolog Reference Manual.
.TP
.BI \-b " initfile ... " -c " file ..."
Boot compilation.
.I "initfile ..."
are compiled by the C written bootstrap compiler,
.I "file ..."
by the normal Prolog compiler into an intermediate code file. This
option is for system maintenance and is given for reference only.
.TP
.BI \-c " file ..."
Compile
.I "file ..."
into an intermediate code file.
.TP
.BI \-d " level"
Set debug level to
.IR level .
This option is for system maintenance and is given for reference only.
.TP
.BR \-\-packs [=bool]
Disable attaching extension packs (add-ons).
.TP
.BR \-\-pce [=bool]
Disable the XPCE GUI subsystem.
.TP
.BR \-\-pldoc [=port]
Start the PlDoc documentation system on a free network port and launch the user's browser on
.IR http://localhost:port .
If
.I port
is specified, the server is started at the given
.I port
but the browser is not launched.
.TP
.BI \-f " file"
Use
.I "file"
as initialisation file instead of
.RB "`" init.pl "'. `" "-f none" "'"
stops SWI-Prolog from searching for an initialisation file.
.TP
.BI \-F " file"
Select startup script from the SWI-Prolog home directory.
.I file
Specifies the base-name of the script.  The extension is
.I .rc.
The default script is deduced from the basename of the executable,
taking all leading alphanumerical (letters, digits and underscore)
from the program name.  Thus if the program is named
.I swi-2.0
it will try to load the file
.I swi.rc
from the SWI-Prolog home directory.  If the file does not exist, or
the user has no read-access to it, the script is silently not loaded.
.TP
.BI \-s " file"
Load
.I file
as a script.  This option may be used from the shell to make
Prolog load a file before entering the toplevel.  Deprecated
as file names with a Prolog extension
.RB "(" .pl " or " .qlf ")"
are used to load the program.
.TP
.BI \-l " file"
Load
.I file
as a script.  This is a synonym for
.I \-s
that is compatible with several other Prolog implementations.  If
multiple
.IR \-s " or " \-l
arguments are provided, all specified files are loaded in the order
in which they appear on the argument list.
.TP
.BR \-\-quiet "[=bool] " \-q
Operate silently.  This option suppresses all
.I informational
messages.
.TP
.BR \-\-debug [=bool]
Disable generating code that can be debugged using
.IR trace/0 ,
.IR spy/1 ,
etc.
.TP
.BR \-\-debug\-on\-interrupt [=bool]
Immediately start handling SIGINT (Control-C) to start the debugger.
By default this is enabled when the interactive toplevel is entered.
.TP
.BR \-\-on-error =style
How to handle on a (printed) error message.  Default is
.IR print
which causes errors to be printed while execution continues.  Using
.IR status
execution continues as with print, but
.I halt/0
causes the process to exit with status 1 and
.I halt
causes the process to exit with status 1 on the first error.
.TP
.BR \-\-on-warning =style
Similar to
.I \-\-on-error, but for warning messages.
.TP
.BI \-g " goal"
.I Goal
is executed just before entering the top level. This option may appear
multiple times.  Goals are executed in the order of appearance.  Possible
choice points are pruned.  If a goal
.I fails
an error is printed (depending on the
.B "\-q"
flag) and the process stops with exit code 1.  If a goal
.I "raises an exception"
the error is printed and the process stops with exit code 2.  In no
goal is present
.I "version/0"
is called to write the welcome message.  The welcome message
can thus be suppressed by giving
.BR "\-g true" .
.I goal
can be a complex term. In this case, quotes are normally needed
to protect it from being expanded by the Unix shell.
.TP
.BI \-o " output"
Used in combination with
.B \-b
or
.B \-c
to determine the output file for compilation.
.TP
.BI \-p " alias" = pathlist
Define a path alias for
.BR file_search_path/2 .
.I pathlist
is a ":" separated list of values for the alias. See
.B file_search_path/2
in the SWI-Prolog Reference Manual.
.TP
.BI \-t " goal"
Use
.I goal
as an interactive top level instead of the default goal
.BR prolog/0 .
.I goal
can be a complex term. If the top level goal succeeds, SWI-Prolog
exits with status 0. If it fails, the exit status is 1. This flag
also determines the goal started by
.B break/0
and
.BR abort/0 .
If you want to stop the user from entering interactive mode, start
the application with
.RB "`" \-g
.IR goal "'"
and give
.RB "`" halt "'"
as the top level.
.TP
.BI \-x " bootfile"
Start from an intermediate code file resulting from a Prolog compilation
using the
.B \-b
or
.B \-c
option, or created using
.BR qsave_program/[1,2] .
.TP
.BR \-\-tty [=bool]
Switches tty control (using
.BR ioctl (2)).
Normally tty control is switched on. This default depends on the
installation. You may wish to switch tty control off if SWI-Prolog is
used from an editor such as GNU Emacs. If switched off,
.B get_single_char/1
and the tracer will wait for a carriage return.
.TP
.B \-\-win\-app
This option is available only in
.IR swipl-win.exe .
The Start menu shortcut uses this option to change the working directory to
.IR ...\eDocuments\eProlog .
The
.I Prolog
subdirectory will be created if it does not exist.
.TP
.BR \-\-signals [=bool]
Disable handling of signals.  Often used if SWI-Prolog is embedded in
another application on Unix systems.
.TP
.BR \-\-sigalert= "NUM"
Use
.I NUM
for unblocking system calls.  Default is
.BR SIGUSR2 "."
Using 0 disables installing a signal handler, delaying the delivery
of thread signals until the blocking system call completes.
.TP
.BR \-\-threads [=bool]
Disable creating threads in the multi-threaded version.  This notably
prevents running global garbage collection on a separate thread and
may be used for situations where multiple threads are not desirable.
.TP
.B \-\-traditional
Disable SWI-Prolog version 7 extensions that are incompatible with earlier
versions.
.TP
.B \-\-
Stop scanning for more arguments.
.SH ENVIRONMENT VARIABLES
.TP
.I SWI_HOME_DIR
Location for finding the startup file  and the libraries.
Normally discovered from the executable or configured default location.
Providing the value through the environment may be needed if SWI-Prolog
is embedded into another executable.
.SH ON-LINE HELP
SWI-Prolog has on-line help. This provides a fast lookup and browsing
facility to the SWI-Prolog Reference manual. The on-line manual can
show predicate definitions as well as entire sections of the manual.
.TP
.B help
Equivalent to
.BR help(help/1) .
.TP
.BI help( \+What )
Show a specified part of the manual.
.I What
is one of:
.RS
.TP
Name/Arity
give help on the specified predicate
.TP
Name
give help on the named predicate with any arity or a C interface
function with that name.
.TP
Section
display the specified section of the SWI-Prolog Reference Manual.
Section numbers are dash separated numbers: e.g.
.B 2-3
refers to section 2.3 of the manual.
.PP
If Prolog is used together with the
.BR GUI
tool
.BR XPCE,
these predicates start a graphical interface, providing a coherent interface
to
.BR help/1,
.BR apropos/1
and
.BR explain/1.
.RE
.SH FILES
This installation of SWI-Prolog has been configured using the configure
option
.BI \-\-prefix= /usr.
If the files listed below are not at the indicated place, the installation
has probably been moved.  Use
.TP
?- current_prolog_flag(home, Home).
.P
to find the local installation directory of SWI-Prolog.
.TP
.I ~/.config/swi-prolog/init.pl
Personal initialisation files consulted by SWI-Prolog on startup.
The exact location depends on the OS.
.TP
.I /usr/lib/swipl-9.0.4/bin//
Location for the executables.
.TP
.I /usr/lib/swipl-9.0.4/include/
Location for the include files.  If writable, SWI-Prolog.h is also
copied to /usr/include/SWI-Prolog.h.
.TP
.I /usr/lib/swipl-9.0.4/library/
SWI-Prolog user libraries.
.TP
.I /usr/lib/swipl-9.0.4/boot/
SWI-Prolog kernel parts written in Prolog.  The startup file
/usr/lib/swipl-9.0.4/ may be recreated using
the command from the directory /usr/lib/swipl-9.0.4:
.RS
.TP
bin//swipl \-O \-o  \-b boot/init.pl
.RE
.TP
.I /usr/lib/swipl-9.0.4/doc/packages
HTML and/or PDF documentation on the installed add-ons.
.TP
.I /usr/lib/swipl-9.0.4/
Default startup file.  This is a `intermediate code' file containing
precompiled code from the boot directory.  The
.BI \-x bootfile
option may be used to select a different file.
.TP
.I /usr/lib/swipl-9.0.4/runtime//libpl.a
SWI-Prolog library for embedding.  See also
.I plld(1).
.SH SEE ALSO
.PP
The SWI-Prolog web-home at
.I http://www.swi-prolog.org
.PP
Jan\ Wielemaker
.IR "SWI-Prolog Reference Manual" " at"
.I http://www.swi-prolog.org/pldoc/index.html
.PP
Documentation on the add-on packages in
.I /usr/lib/swipl-9.0.4/boot/doc
.PP
William\ F.\ Clocksin & Christopher\ S.\ Mellish,
.IR "Programming in Prolog" ,
fourth edition, Springer Verlag, Berlin 1994.
.PP
.BR swipl-ld "(1)"
.SH WARRANTY
The software is provided
.B as is,
without warranty of any kind, express or implied, including but not
limited to the warranties of merchantability, fitness for a particular
purpose and non infringement. In no event shall the author or his
employer be liable for any claim, damages or other liability, whether in
an action of contract, tort or otherwise, arising from, out of or in
connection with the software or the use or other dealings in the
software.
.SH LICENSE INFORMATION
SWI-Prolog is distributed under the
.IR "Simplified BSD" " or " "BSD-2"
License.  A particular configuration may contain components that are
subject to other license conditions.  Use
.B license/0
to find components with less permissive license conditions.
See the SWI-Prolog license page at
.B http://www.swi-prolog.org/license.html
for details.
.SH COPYRIGHT
Copyright (c) 1986\-2020 University of Amsterdam, VU University Amsterdam
.SH AUTHOR
Jan Wielemaker