\documentclass[11pt]{article}
\usepackage{pl}
\usepackage{html}
%\onefile
\sloppy
\makeindex

\onefile
\htmloutput{.}				% Output directory
\htmlmainfile{windows}			% Main document file
\bodycolor{white}			% Page colour

\renewcommand{\runningtitle}{SWI-Prolog for MS-Windows}

\begin{document}

\title{SWI-Prolog for MS-Windows}
\author{Jan Wielemaker \\
	VU University Amsterdam \\
	University of Amsterdam \\
	The Netherlands \\
	E-mail: \email{jan@swi-prolog.org}}

\maketitle

\begin{abstract}
This document gets you started using SWI-Prolog on MS-Windows. It
also describes the components and issues that are specific to
MS-Windows. It is by no means a manual or Prolog tutorial. The reference
manual is available online or can be downloaded in HTML and PDF format
from the \url[SWI-Prolog website]{http://www.swi-prolog.org/}, which
also provides links to books, online tutorials and other Prolog-related
material.
\end{abstract}


\tableofcontents

\section{Using SWI-Prolog}

\subsection{Starting Prolog and loading a program}

The SWI-Prolog executable \program{swipl-win.exe} can be started from the
\emph{StartMenu} or by opening a \fileext{pl} file holding Prolog
program text from the Windows explorer.%
	\footnote{The .PL file extension can be changed
		  during installation. See \secref{ext}.}
The installation folder (by default
\file{C:\bsl{}Program~Files\bsl{}swipl}) contains a subfolder
\file{demo} with the file \file{likes.pl}. This file can be opened in
Prolog from the StartMenu, by opening \file{likes.pl} in the Windows
explorer or by using the following command in the Prolog application. Be
sure to get the quotes right and terminate the command with a full stop
(\chr{.}).

\begin{code}
?- [swi('demo/likes')].
\end{code}

If Prolog is started from the start menu it is passed the option
\texttt{--win_app}, which causes it to start in the local equivalent of
\file{My Documents\bsl{}Prolog}.  This folder is created if it does not
exist.


\subsection{Executing a query}			\label{sec:execquery}

After loading a program, one can ask Prolog queries about the program.
The query below asks Prolog what food `sam' likes. The system responds
with \mbox{\tt X = <value>} if it can prove the goal for a certain
\arg{X}. The user can type the semi-colon (;) or spacebar. If you want
another solution. Use the \textsc{return} key if you do not want to see
the more answers. Prolog completes the output a full stop (.) if the
user uses the \textsc{return} key or Prolog \emph{knowns} there are no
more answers. If Prolog cannot find (more) answers, it writes
\textbf{false.} Finally, Prolog can answer using an error message to
indicate the query or program contains an error.

\begin{code}
?- likes(sam, X).
X = dahl ;
X = tandoori ;
...
X = chips.

?-
\end{code}

Note that the answer written by Prolog is a valid Prolog program that,
when executed, produces the same set of answers as the original
program.


\subsection{Menu commands}		\label{sec:menu}

The SWI-Prolog console provided by \program{swipl-win.exe} has a menu for
accessing the most commonly used commands. We assume not all menu
entries need to be explained in detail.  We make some exceptions:

\begin{description}
    \definition{File/Reload modified files}
This menu reloads all loaded source files that have been modified
using the make/0 command described in \secref{commands}.

    \definition{File/Navigator ...}
Opens an explorer-like view on Prolog files and the predicates they
contain.

    \definition{Settings/Font ...}
Allows for changing the font of the console.  On some installations the
default font gives redraw and cursor dislocation problems.  In this case
you may wish to select an alternative.  Some built-in commands assume
non-proportional fonts.

    \definition{Settings/User init file ...}
Edits the user personalisation file.  If no such file exists, it first
installs a default file as \file{swipl.ini} that contains commonly used
settings in comments.

    \definition{Settings/Stack sizes ...}
Allows for defining the maximum size to which the various Prolog stacks are
allowed to grow. The system defaults are chosen to make erroneous
programs fail quickly on modest hardware.  Programs with large data
structures or many choice points often need larger stacks.  Note that
an active Prolog process growing over the size of the physical memory of
your computer can make the system extremely slow.

    \definition{Run/Interrupt}
Try to interrupt the running Prolog process.  This is the same as
using \emph{Control-C}.  Sometimes interrupts are not honoured or
take very long to process.  Closing the window twice provides a
way to force Prolog to stop.

    \definition{Run/New thread}
Creates a new interactor window running in a separate thread of
execution.  This may be used to inspect the database or program
while the main task continues.

    \definition{Debug/Edit spy points ...}
Edit break points on predicates. From the PceEmacs editor (see
\secref{edit}) break points can also be set on specific calls from
specific clauses.

    \definition{Debug/Graphical debugger ...}
Use the source-level debugger on the next spy or break point or
other call that enables the debugger.

    \definition{Help}
The help menu provides various starting points to related documents.
Items flagged with {\sf (on www)} open your default internet
browser on a page of the SWI-Prolog website.
\end{description}


\subsection{Editing Prolog programs}		\label{sec:edit}

There are three options for editing.  One is to run an editor of choice
in a separate window and use the make/0 command described below to
reload modified files.  In addition to this option Prolog can be used
to locate predicates, modules and loaded files by specifying the editor
of choice for use with the edit/1 command, described below.  This is
achieved by editing the personalisation file (see \secref{menu}) and
following the instructions in the comments.

The default editor is the built-in editor called \emph{PceEmacs}. This
editor provides colourisation support based on real-time parsing and
cross-reference analysis of the program.

Other options for editing include GNU-Emacs, SWI-Prolog-Editor and the
Eclipse-based PDT environment. See
\url{http://www.swi-prolog.org/IDE.html} for an up-to-date overview.


\subsection{Some useful commands}
\label{sec:commands}

This section provides a very brief overview of important or
commonly used SWI-Prolog predicates to control the environment.

\begin{description}
    \predicate{consult}{1}{:File}
Load a source file. On Windows, folders may be specified with the
DOS/Windows \chr{\}, which must be escaped, or by using the POSIX standard
\chr{/}.  Especially when used in source code, \chr{/} is to be preferred
as it is portable.  A Prolog list ([\ldots]) can be used to abbreviate
the consult command.  The file extension (\fileext{pl} as well as the
selected alternative) can be omitted.  Here are some examples:

\begin{center}
\begin{tabular}{ll}
\tt ?- consult(likes). & Load \file{likes.pl} from the current folder
			 (see pwd/0). \\
\tt ?- ['C:/Program Files/pl/demo/likes'] & Load \file{likes.pl} using
			absolute path. \\
\tt ?-
['C:\bsl{}\bsl{}Program~Files\bsl{}\bsl{}pl\bsl{}\bsl{}demo\bsl{}\bsl{}likes']
& Same using Windows-style path name \\
\end{tabular}
\end{center}

    \predicate{pwd}{0}{}
Print working directory (folder).

    \predicate{ls}{0}{}
List files in current directory.

    \predicate{edit}{0}{}
If Prolog is started by opening a \fileext{pl} file in the explorer,
edit this file.  Also available from the menu.

    \predicate{edit}{1}{+Spec}
Edit file, predicate, module, etc., with the given name.  If multiple
items are named \arg{Spec} it prompts for the desired alternative.

    \predicate{make}{0}{}
Reload all files that have been changed since they were last loaded.
Normally used after editing one or more files.

    \predicate{gtrace}{0}{}
Start the graphical debugger. There are three ways to use
this. Entered as a single goal at the top level, the next query will be
traced. Alternatively it can be used in conjunction with the goal to be
debugged: \exam{?- gtrace, run.} and finally you can include it in your
program to start tracing at a particular point or under a particular
condition:

\begin{code}
	...,
	(var(X) -> gtrace ; true),
	...,
\end{code}

    \predicate{trace}{0}{}
Same as gtrace, but text-based on the console.

    \predicate{apropos}{1}{+Keyword}
Search for all predicates that contain \arg{Keyword} in their name
or short description.  If a GUI environment is available the results
are hyperlinks.  Otherwise use help/1 to get details on selected
hits.

    \predicate{help}{1}{+Spec}
Give help on \arg{Spec}, which is normally the name of a predicate or
C interface function.
\end{description}


\section{Using SWI-Prolog with C/C++}

Using \url[MinGW]{http://www.mingw.org} or a compiler with a compatible
calling format you can write C or C++ code that can be loaded into
SWI-Prolog and called as a predicate. You can also embed SWI-Prolog in
C/C++ applications.

Details on how to interact with Prolog are in the \url[SWI-Prolog
reference manual]{http://www.swi-prolog.org/pldoc/refman/}. The mailing
list archives and TWiki web provide problems and solutions to the many
problems that may occur. Documentation of the \file{SWI-cpp.h} C++
include file is available from the \url[package
documentation]{http://www.swi-prolog.org/pldoc/package/pl2cpp.html}.
This section only discusses some Windows-specific issues.

\subsection{Using MSVC}

\begin{quote}
Because the current versions of SWI-Prolog are compiled and linked with
MinGW, we are unsure about the status with regard to compiling
extensions using MSVC and embedding SWI-Prolog into MSVC projects.

Please send your comments to the SWI-Prolog mailinglist, and/or
\url{mailto:bugs@swi-prolog.org}.
\end{quote}

First of all, add the \file{include} folder of the installation to the
search path for headers and the \file{lib} folder to the search path for
libraries. Both DLLs (extensions) or embedded executables should link to
\file{libswipl.dll.a} and, if appropriate, to the multithreaded DLL
version of the MSVC runtime library.

To create extensions, create a Win32 DLL. To embed Prolog, care should
be taken that Prolog can find the Prolog installation. For
\emph{development}, the simplest way to ensure this is by adding the
installation \file{bin} folder to the \verb|%PATH%| environment and
calling PL_initialise() as illustrated below. PL_initialise() uses the
path of the loaded \file{libswipl.dll} module to find the Prolog
installation folder.\footnote{When using the C++ interface from
\file{SWI-cpp.h}, these comments apply to the arguments for PlEngine().}

\begin{code}
  { static char *av[] = { "libswipl.dll", NULL };

    if ( !PL_initialise(1, av) )
    { <error>
    }
  }
\end{code}

To create an executable that does not rely on Prolog one must create
a saved state of the required Prolog code and attach this to the
executable.  Creating saved states is described with qsave_program/2
in the reference manual.  This can be attached to a state using the
DOS command below to create \file{final.exe} from the executable
produced by MSVC and the generated saved state.

\begin{code}
> copy /b file.exe+file.state final.exe
\end{code}


\subsection{Using swipl-ld.exe}

The \program{swipl-ld.exe} automates most of the above complications and
provides compatibility for common tasks on many platforms supported by
SWI-Prolog. To use it with MinGW, set the \verb+PATH+ environment
variables to include the SWI-Prolog binary folder as well as the MinGW
binary folders (typically \file{C:\bsl{}MinGW\bsl{}bin}) to find
\program{gcc}. An extension \file{myext.dll} can be created from the
source \file{myext.c} using the command below.  Add \const{-v} to
see what commands are executed by \program{swipl-ld.exe}.

\begin{code}
> swipl-ld.exe -shared -o myext myext.c
\end{code}

An embedded executable is created from C, C++ and Prolog files using

\begin{code}
> swipl-ld.exe -o myexe file.c ... file.pl ...
\end{code}


\section{The installation}


\subsection{Supported Windows versions}			\label{sec:winver}

SWI-Prolog requiring Windows XP or later (XP, Vista, Windows-7). The
download site of SWI-Prolog contains older binaries that run on older
versions of Windows. We provide both 32-bit and 64-bit installers.


\subsection{Choosing the file extension}		\label{sec:ext}

By default, Prolog uses the \fileext{pl} extension to indicate Prolog
source files. Unfortunately this extension conflicts with the Perl
language. If you want to use both on the same Windows machine SWI-Prolog
allows you to choose a different extension during the installation. The
extension \fileext{pro} is a commonly used alternative. If portability
is an issue, it is advised to use the alternative extension only for the
\emph{load file}, the source file that loads the entire program, and use
the normal \fileext{pl} extension for libraries and files loaded from
other files.


\subsection{Installed programs}

The table below lists the installed components. Some components are
marked (32-bits) or (64-bits). Most of this is because the 64-bit
version is built using more recent tools and from more recent versions
of required libraries using different naming conventions.  This will
probably be synchronised in the future.

\begin{center}
\begin{tabular}{|l|p{4in}|}
\hline
\multicolumn{2}{|c|}{Programs} \\
\hline
\verb$bin\swipl-win.exe$	& Default Windows application for interactive
			  use. \\
\verb$bin\swipl.exe$    & Console-based version for scripting purposes. \\
\hline
\multicolumn{2}{|c|}{Utilities} \\
\hline
\verb$bin\swipl-ld.exe$	& Linker front-end to make single-file mixed
			  Prolog/C/C++ executables. \\
\verb$bin\swipl-rc.exe$	& Manipulate Prolog resource files. \\
\hline
\multicolumn{2}{|c|}{Important directories} \\
\hline
\verb$bin$		& Executables and DLL files \\
\verb$library$		& Prolog library \\
\verb$boot$		& Sources for system predicates \\
\verb$include$		& C/C++ header files for embedding or to create
			  extensions \\
\verb$xpce$		& XPCE graphics system \\
\verb$xpce\prolog\lib$	& XPCE/Prolog library \\
\hline
\multicolumn{2}{|c|}{DLLs and other supporting files} \\
\hline
\verb$boot32.prc$       & Initial Prolog state (32-bits) \\
\verb$boot64.prc$       & Initial Prolog state (64-bits) \\
\verb$\bin\libswipl.dll$	& The Prolog kernel \\
\verb$\bin\plterm.dll$	& The window for \program{swipl-win.exe} \\
\verb$\bin\pthreadVC2.dll$& POSIX thread runtime library (64-bits) \\
\hline
\multicolumn{2}{|c|}{Extension DLLs (plugins)} \\
\hline
\verb$\bin\cgi.dll$		 & Gather CGI GET and POST arguments \\
\verb$\bin\double_metaphone.dll$ & Soundex (sounds similar) \\
\verb$\bin\memfile.dll$		 & In-memory temporary `files' \\
\verb$\bin\odbc4pl.dll$		 & ODBC interface \\
\verb$\bin\plregtry.dll$	 & Windows registry interface \\
\verb$\bin\porter_stem.dll$	 & Porter stemming implementation \\
\verb$\bin\random.dll$		 & Portable random number generator \\
\verb$\bin\rdf_db.dll$		 & RDF database \\
\verb$\bin\readutil.dll$	 & Fast reading utility \\
\verb$\bin\sgml2pl.dll$		 & SGML/XML parser \\
\verb$\bin\socket.dll$		 & Prolog socket interface \\
\verb$\bin\table.dll$		 & Access structured files as tables \\
\verb$\bin\time.dll$		 & Timing and alarm library \\
\verb$\bin\xpce2pl.dll$		 & The XPCE graphics system \\
\verb$\bin\zlib1.dll$		 & Compression library (32-bits) \\
\verb$\bin\zlibwapi.dll$	 & Compression library (64-bits) \\
\verb$\bin\zlib4pl.dll$		 & Compression library interface \\
\hline
\end{tabular}
\end{center}

\subsection{Installed Registry keys and menus}

The filetype \fileext{pl} or chosen alternative (see \secref{ext}) is
associated to \program{swipl-win.exe}. A chosen folder (default SWI-Prolog)
is added to the start menu holding shortcuts to Prolog and some related
utilities. The following registry keys are in use. The 64-bit version
uses \texttt{Prolog64} instead of \texttt{Prolog} as a key to accommodate
installation of both versions on the same machine. Note that opening a
\fileext{pl} file can be associated with one of the installed Prolog
versions only.

\begin{center}
\begin{tabular}{|l|p{4in}|}
\hline
\multicolumn{2}{|c|}{\tt HKEY_LOCAL_MACHINE\bsl{}Software\bsl{}SWI\bsl{}Prolog} \\
\hline
\verb$fileExtension$		& Extension used for Prolog files \\
\verb$group$			& Start menu group \\
\verb$home$			& Installation directory \\
\hline
\multicolumn{2}{|c|}{\tt HKEY_CURRENT_USER\bsl{}Software\bsl{}SWI\bsl{}Plwin\bsl{}Console} \\
\multicolumn{2}{|c|}{Note: thread-windows store the same info in sub-keys} \\
\hline
\verb$Height$			& Height of window in character units \\
\verb$Width$			& Width of window in character units \\
\verb$X$			& Left edge of window in pixel units \\
\verb$Y$			& Top edge of window in pixel units \\
\verb$SaveLines$		& Number of lines available for scrollback \\
\hline
\end{tabular}
\end{center}


\subsection{Execution level}

The installer asks for the \const{admin} execution level (Vista and
later) to be able to write shortcuts and registry keys.


\subsection{Creating a desktop menu item}

If you want a desktop entry for SWI-Prolog, right-drag
\program{swipl-win.exe} to the desktop and select `Create shortcut'. Then
edit the properties and add \const{--win_app} to the command line to make
the application start in \file{My Documents\bsl{}Prolog}.


\section{The SWI-Prolog community and foundation}


\subsection{Website and mailing lists}

The SWI-Prolog website is located at \url{http://www.swi-prolog.org/}.


\subsection{About license conditions}

The SWI-Prolog license allows it to be used in a wide variety of
environments, including closed-source commercial applications. In
practice, redistribution and embedding is allowed, as long as
\emph{modifications} to the SWI-Prolog source are published following
the Free Software rules.

The SWI-Prolog kernel and foreign libraries are licensed under the
\emph{Lesser General Public License} (LGPL).  The Prolog files are
licensed under the normal \emph{General Public License} GPL with
an additional statement that allows for embedding in proprietary
software:

\begin{quote}
    As a special exception, if you link this library with other files
    compiled with a Free Software compiler to produce an executable, this
    library does not by itself cause the resulting executable to be covered
    by the GNU General Public License. This exception does not, however,
    invalidate any other reasons why the executable file might be covered by
    the GNU General Public License.
\end{quote}

This exception is a proven construct used for \emph{libgcc}, the GNU
C-compiler runtime library.


\subsection{Supporting SWI-Prolog}

There are several ways to support SWI-Prolog:

\begin{itemize}
    \item Extend the system with contributions.
    \item Improve the system by submitting bug reports and patches.
    \item Link to \url{http://www.swi-prolog.org} and refer to SWI-Prolog
          in publications.
    \item For commercial users, it may be profitable to sponsor development
          projects that make SWI-Prolog more useful for you and others.
	  Example projects from the part include adding the initial
	  garbage collector, unbounded integer support, SSL interface,
	  (re-)introduction of the stack-shifter, avoid C-recursion on
	  Prolog data structures, the PlUnit test environment and the
	  PlDoc documentation environment.

	  Sponsoring development has several benefits: (1) it solves
	  your bottlenecks, (2) others help debugging it, and (3) it
	  strengthens SWI-Prolog's position, which gives you better
	  guarantees that the system remains actively developed and
	  makes it easier to find resources and programmers.
\end{itemize}

\end{document}