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

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

\renewcommand{\runningtitle}{SWI-Prolog for MacOS X (Darwin)}

\begin{document}

\title{SWI-Prolog for MacOS X}
\author{Jan Wielemaker \\
	Paulo Moura
       }

\maketitle

\begin{abstract}
This document briefly explains the MacOS X specific issues for
SWI-Prolog. This 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 \href{http://www.swi-prolog.org/}{SWI-Prolog
website}, which also provides links to books, online tutorials and other
Prolog related material.
\end{abstract}


\tableofcontents

\section{Introduction -- MacPorts}
\label{sec:macosx-intro}

SWI-Prolog is by origin an Unix application, and not a native Macintosh
application.  It has been brought to the Mac using the
\href{http://www.macports.org/}{MacPorts} project, using
\href{http://xquartz.macosforge.org/}{XQuartz} (Macintosh X11)
for its graphical capabilities.

\section{Installation}
\label{sec:macosx-install}

XQuartz should be installed prior to SWI-Prolog installation. The
installer can be downloaded from the XQuartz web site.

\subsection{Using MacPorts}
\label{sec:macosx-using}

Users of the MacPorts system can install the system just like any port
using the command below. In addition to the port named
\const{swi-prolog} providing the stable version, there is a port called
\const{swi-prolog-devel} providing the development version.

\begin{code}
% sudo port -v selfupdate       # make sure we have the latest portfiles
% sudo port install swi-prolog
\end{code}

The swi-prolog port depends on \const{readline}, \const{ncurses},
\const{ncursesw}, \const{gmp} \const{libmcrypt}, \const{zlib},
\const{expat}, and \const{jpeg}.

\subsection{From the installer}
\label{sec:macosx-installer}

Opening and installing the meta installer installs the required ports
from the MacPorts system.  The programs are installed in the directory
\file{/opt/local/bin}.  The main executable is named \file{swipl}.

\section{Running SWI-Prolog}
\label{sec:macosx-running}

Not being a Macintosh Application, SWI-Prolog must be started from a
terminal window. This can either be an X11 \program{xterm} or
\textsf{Terminal.app} from Utilities.  For comfortable usage it is
necessary to setup some environment variables.  The procedure depends
on your shell of choice.  On Tiger the default is \program{bash}.  Add
the following lines to the file \verb$~/.bashrc$ (or create this
file if it does not yet exist).

\begin{code}
# This allows using Prolog graphics if you use Terminal.app
if [ -z "$DISPLAY" ]; then export DISPLAY=:0; fi

# This sets up the path
PATH=$PATH:/opt/local/bin
\end{code}

Now start \textsf{X11.App} and configure it to autostart at login.  Open
\textsf{Terminal.app} or \program{xterm} and type

\begin{code}
% swipl
Welcome to SWI-Prolog (threaded, 64 bits, version 7.3.33)
SWI-Prolog comes with ABSOLUTELY NO WARRANTY. This is free software.
Please run ?- license. for legal details.

For online help and background, visit http://www.swi-prolog.org
For built-in help, use ?- help(Topic). or ?- apropos(Word).

?-
\end{code}

If X11 is properly configured, the help system of the graphics subsystem
XPCE can now be started using the command below.

\begin{code}
?- manpce.
\end{code}


\subsection{Loading a program}
\label{sec:macosx-loading}

Prolog source files can be loaded by specifying their filename between
\verb$[]$.  In addition to a plain filename, files may be searched on
a named search-path%
	\footnote{See file_search_path/2 in the manual for details.}
using the notation \term{SearchPath}{File}. Two defined paths are
\const{library} for the Prolog library and \const{swi} for the Prolog
installation directory. Below we load the file \file{likes.pl} from the
\file{demo} directory in the installation directory, Be sure to get the
quotes right and terminate the command with a full-stop (\chr{.}).

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

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

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 (;)%
	\footnote{On most installations, single-character commands are
		  executed without waiting for the {\sc return} key.}
if (s)he wants another solution, or {\sc return} if (s)he is satisfied,
after which Prolog will say {\bf Yes}. If Prolog answers {\bf No}, it
indicates it cannot find any (more) answers to the query. 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 ;

No
?-
\end{code}


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

There are three options for editing. One is to run an editor of choice
in a separate window and use the below described make/0 command 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 \file{~/config/swi-prolog/init.pl}.
A commented template is in the directory \file{customize} of the
SWI-Prolog installation directory.

Finally, you may wish to use the built-in editor called \emph{PceEmacs}.
This editor provides colourisation support based on real-time parsing
and cross-reference analysis of the program. It is started using the
command \verb$?- emacs.$ or can be set as default editor in the
personalisation file.


\subsection{Some useful commands}
\label{sec:macosx-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. A Prolog list ([\ldots]) can be used to abbreviate
the consult command. The file-extension (\fileext{pl} 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 ?- ['/opt/local/lib/swipl-5.6.0/demo/likes'] & Load \file{likes.pl} using
			absolute path. \\
\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 where last loaded.
Normally used after editing one or more files.

    \predicate{trace}{0}{}
Start the interactive 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{?- trace, 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) -> trace ; true),
	...,
\end{code}

    \predicate{gtrace}{0}{}
Same as trace, but forces the use of the graphical (source-level)
debugger.

    \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++}
\label{sec:macosx-cpp}

To use SWI-Prolog with C or C++ code you must install Apples Xcode
environment, providing \program{gcc}. If all paths are properly
installed, programs can be linked using the \program{plld} command
described in the manual.


\section{Known problems}
\label{sec:macosx-issues}

\begin{itemlist}
    \item [XPCE and the meta-key]
By default, the `Meta' key is bound to X11 \jargon{modifier 1} which
is set by the `Alt' key.  This doesn't work very well for the Mac as
the Alt key is commonly used to create alternative characters, while
the Command key, which is used for composing commands, is bound to the
X11 \jargon{modifier 2}.  For the Apple we therefore bind the XPCE
meta modifier to the X11 modifier 2.  Wherever the documentation
mentions Alt-X or Meta-X this must be read as \emph{Command-X}.

    \item [Threaded XPCE programs]
XPCE normally initializes Xlib for multi-threaded access using
XInitThreads().  It turns out the MacOS X X11 version (tested
on Tiger) causes a deadlock on certain keys.  We now do not call
XInitThreads().  As Xlib access is synchronised using the currently
global XPCE lock and XPCE/Prolog interfacing is designed to have only
a single Prolog thread talking to XPCE this should not be a serious
problem.

    \item [XPCE programs do not open]
A problem has been reported where starting XPCE programs, including the
IDE components such as help, PceEmacs, etc. causes the program to hang.
In the end, it turned out the fontconfig/freetype library used by XPCE
to render Unicode fonts builds a database on first invocation. This
process can take several minutes. Ones created, XPCE applications start
quickly.

    \item [Font display issues]
If fonts do not display correctly (e.g. manpce pages not showing
bold styles or editor text in `screen' font looking mis-spaced and
misaligned) you may try to rebuild the X11 font cache by using the
command \program{sudo /usr/x11r6/bin/ fc-cache}.
\end{itemlist}


\section{The SWI-Prolog community and foundation}
\label{sec:macosx-intro}

\subsection{Web-site and mailing lists}
\label{sec:macosx-mailinglist}

The SWI-Prolog web-site is located at \url{http://www.swi-prolog.org/}.
Part of the web is powered by \href{http://twiki.org/}{TWiki}, a
\emph{wiki} web that can be edited by any registered user and used to
exchange ideas, problems and solutions.  The web also provides access
to the archive of the mailing list and allows to (de)register the
mailing list.  Finally, it incorporates Bugzilla, the Mozilla project
bugtracking system, for reporting bugs and tracking issues.


\subsection{About license conditions}
\label{sec:macosx-license}

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}
\label{sec:macosx-support}

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 Ask for commercial development or support at
          \url{http://www.cognitivetools.com/}
    \item Support development financially at
          \url{http://www.swi-prolog.org/donate.html}.
\end{itemize}

\end{document}