\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 = } 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}