<HTML>
<HEAD>
<!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 -->
<LINK rel="stylesheet" href="ciao.css" type="text/css">
<TITLE>The Ciao Prolog System - Installing Ciao from the source distribution</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_230.html">previous</A>, <A HREF="ciao_232.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC896" HREF="ciao_toc.html#TOC896">Installing Ciao from the source distribution</A></H1>
<P>
<STRONG>Author(s):</STRONG> Manuel Carro, Daniel Cabeza, Manuel Hermenegildo.
<P>
<STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST)
<P>
<STRONG>Version of last change:</STRONG> 1.10#2 (2004/8/2, 19:25:49 CEST)
<P>
This describes the installation procedure for the Ciao Prolog system, including libraries and manuals, from a <EM>source</EM> distribution. This applies primarily to Unix-type systems (Linux, Mac OS X, Solaris, SunOS, etc.). However, the sources can also be compiled if so desired on Windows systems -- see section <A HREF="ciao_231.html#SEC902">Installation and compilation under Windows</A> for details.
<P>
If you find any problems during installation, please refer to section <A HREF="ciao_231.html#SEC904">Troubleshooting (nasty messages and nifty workarounds)</A>.
<A NAME="IDX9820"></A>
<A NAME="IDX9821"></A>
See also section <A HREF="ciao_233.html#SEC915">Downloading new versions</A> and section <A HREF="ciao_233.html#SEC916">Reporting bugs</A>.
<UL>
<LI><A HREF="ciao_231.html#SEC897">Un*x installation summary</A>
<LI><A HREF="ciao_231.html#SEC898">Un*x full installation instructions</A>
<LI><A HREF="ciao_231.html#SEC899">Checking for correct installation on Un*x</A>
<LI><A HREF="ciao_231.html#SEC900">Cleaning up the source directory</A>
<LI><A HREF="ciao_231.html#SEC901">Multiarchitecture support</A>
<LI><A HREF="ciao_231.html#SEC902">Installation and compilation under Windows</A>
<LI><A HREF="ciao_231.html#SEC903">Porting to currently unsupported operating systems</A>
<LI><A HREF="ciao_231.html#SEC904">Troubleshooting (nasty messages and nifty workarounds)</A>
</UL>
<H2><A NAME="SEC897" HREF="ciao_toc.html#TOC897">Un*x installation summary</A></H2>
<P>
<A NAME="IDX9822"></A>
<A NAME="IDX9823"></A>
<A NAME="IDX9824"></A>
<A NAME="IDX9825"></A>
<P>
<STRONG>Note:</STRONG> it is recommended that you read the full installation instructions (specially if the installation will be shared by different architectures). However, in many cases it suffices to follow this summary:
<OL>
<LI>Uncompress and unpackage (using
<A NAME="IDX9826"></A>
<CODE>gunzip</CODE> and <CODE>tar -xpf</CODE>) the distribution. This will put everything in a new directory whose name reflects the Ciao version.
<LI>Enter the newly created directory (<CODE>SRC</CODE>). Edit
<A NAME="IDX9827"></A>
<CODE>SETTINGS</CODE> and check/set the variables <CODE>SRC</CODE>, <CODE>CIAOROOT</CODE> (this defines where the installation will hang from) and <CODE>DOCROOT</CODE> (where the documentation will go, preferably a directory <EM>accessible via</EM>
<A NAME="IDX9828"></A>
WWW). <CODE>CIAOROOT</CODE> is used to give values to <CODE>BINROOT</CODE>, <CODE>LIBROOT</CODE>, and <CODE>INCLUDEROOT</CODE>. You can give different values to these if you want.
<LI>Type <CODE>gmake install</CODE>. This will build executables, compile libraries, and install everything in a directory <CODE>LIBROOT/ciao</CODE> and in <CODE>BINROOT</CODE>.
Note that <CODE>gmake</CODE> refers to the
<A NAME="IDX9829"></A>
GNU implementation of the
<A NAME="IDX9830"></A>
make Un*x command, which is available in many systems (including all Linux systems and Mac OS X) simply as
<A NAME="IDX9831"></A>
<CODE>make</CODE>. I.e., you can try simply typing <CODE>make install</CODE> if <CODE>gmake install</CODE> does not work. If typing <CODE>make</CODE> stops right away with error messages it is probably an older version and you need to install <CODE>gmake</CODE>.
<LI>Make the following modifications in your startup scripts. This will make the documentation accessible, set the correct mode when opening Ciao source files in
<A NAME="IDX9832"></A>
<CODE>emacs</CODE>, etc. Note that <CODE><LIBROOT></CODE> must be replaced with the appropriate value:
<A NAME="IDX9833"></A>
<A NAME="IDX9834"></A>
<UL>
<LI>For users a
<A NAME="IDX9835"></A>
<A NAME="IDX9836"></A>
<EM>csh-compatible shell</EM> (
<A NAME="IDX9837"></A>
<CODE>csh</CODE>,
<A NAME="IDX9838"></A>
<CODE>tcsh</CODE>, ...), add to
<A NAME="IDX9839"></A>
<CODE>~/.cshrc</CODE>:
<PRE>
if ( -e <LIBROOT>/ciao/DOTcshrc ) then
source <LIBROOT>/ciao/DOTcshrc
endif
</PRE>
<A NAME="IDX9840"></A>
<CODE>Mac OS X</CODE> users should add (or modify) the
<A NAME="IDX9841"></A>
<CODE>path</CODE> file in the directory <CODE>~/Library/init/tcsh</CODE>, adding the lines shown above. <STRONG>Note:</STRONG> while this is recognized by the terminal shell, and therefore by the text-mode Emacs which comes with Mac OS X, the Aqua native Emacs 21 does not recognize that initialization. It is thus necessary, at this moment, to set manually the Ciao shell (ciaosh) and Ciao library location by hand. This can be done from the Ciao menu within Emacs after a Ciao Prolog file has been loaded. We suppose that the reason is that Mac OS X does not actually consult the per-user initialization files on startup. It should also be possible to put the right initializations in the .emacs file using the <CODE>setenv</CODE> function of Emacs-lisp, as in
<PRE>
(setenv "CIAOLIB" "<LIBROOT>/ciao")
</PRE>
The same can be done for the rest of the variables initialized in <CODE><LIBROOT>/ciao/DOTcshrc</CODE>
<LI>For users of an
<A NAME="IDX9842"></A>
<A NAME="IDX9843"></A>
<EM>sh-compatible shell</EM> (
<A NAME="IDX9844"></A>
<CODE>sh</CODE>,
<A NAME="IDX9845"></A>
<CODE>bash</CODE>, ...), add to
<A NAME="IDX9846"></A>
<CODE>~/.profile</CODE>:
<PRE>
if [ -f <LIBROOT>/ciao/DOTprofile ]; then
. <LIBROOT>/ciao/DOTprofile
fi
</PRE>
This will set up things so that the Ciao executables are found and you can access the Ciao system manuals using the
<A NAME="IDX9847"></A>
<CODE>info</CODE> command. Note that, depending on your shell, <EM>you may have to log out and back in</EM> for the changes to take effect.
<LI>Also, if you use
<A NAME="IDX9848"></A>
<CODE>emacs</CODE> (highly recommended) add this line to your
<A NAME="IDX9849"></A>
<CODE>~/.emacs</CODE> file:
<PRE>
(load-file "<LIBROOT>/ciao/DOTemacs.el")
</PRE>
</UL>
If you are installing Ciao globally in a multi-user machine, make sure that you instruct all users to do the same. If you are the system administrator, the previous steps can be done once and for all, and globally for all users by including the lines above in the central startup scripts (e.g., in Linux
<A NAME="IDX9850"></A>
<CODE>/etc/bashrc</CODE>,
<A NAME="IDX9851"></A>
<CODE>/etc/csh.login</CODE>,
<A NAME="IDX9852"></A>
<CODE>/etc/csh.cshrc</CODE>,
<A NAME="IDX9853"></A>
<CODE>/etc/skel</CODE>,
<A NAME="IDX9854"></A>
<CODE>/usr/share/emacs/.../lisp/site-init.pl</CODE>, etc.).
<LI>Finally, if the (freely available)
<A NAME="IDX9855"></A>
<CODE>emacs</CODE> editor/environment is not installed in your system, we <EM>highly recommend</EM> that you also install it at this point (see section <A HREF="ciao_231.html#SEC898">Un*x full installation instructions</A> for instructions). While it is easy to use Ciao with any editor of your choice, the Ciao distribution includes a very powerful
<A NAME="IDX9856"></A>
<A NAME="IDX9857"></A>
<EM>application development environment</EM> which is based on
<A NAME="IDX9858"></A>
<CODE>emacs</CODE> and which enables, e.g., source-level debugging, syntax coloring, context-sensitive on-line help, etc.
<LI>You may want now want to check your installation (see section <A HREF="ciao_231.html#SEC899">Checking for correct installation on Un*x</A>) and read the documentation, which is stored in <CODE>DOCROOT</CODE> (copied from <CODE>SRC/doc/reference</CODE>) and can be easily accessed as explained in that same section. There are special "getting started" sections at the beginning of the manual.
<LI>If you have any problems you may want to check the rest of the instructions. The system can be <EM>uninstalled</EM> by typing <CODE>gmake uninstall</CODE>.
<A NAME="IDX9859"></A>
<A NAME="IDX9860"></A>
</OL>
<P>
<H2><A NAME="SEC898" HREF="ciao_toc.html#TOC898">Un*x full installation instructions</A></H2>
<P>
<A NAME="IDX9861"></A>
<A NAME="IDX9862"></A>
<A NAME="IDX9863"></A>
<A NAME="IDX9864"></A>
<OL>
<LI><STRONG>Uncompress and unpackage:</STRONG> (using
<A NAME="IDX9865"></A>
<CODE>gunzip</CODE> and <CODE>tar -xpf</CODE>)
<A NAME="IDX9866"></A>
<A NAME="IDX9867"></A>
the distribution in a suitable directory. This will create a new directory called <CODE>ciao-X.Y</CODE>, where <CODE>X.Y</CODE> is the version number of the distribution. The <CODE>-p</CODE> option in the
<A NAME="IDX9868"></A>
<CODE>tar</CODE> command ensures that the relative dates of the files in the package are preserved, which is needed for correct operation of the Makefiles.
<LI><STRONG>Select installation options:</STRONG> Edit the file
<A NAME="IDX9869"></A>
<CODE>SETTINGS</CODE> and set the following variables:
<UL>
<LI><CODE>SRC</CODE>: directory where the sources are stored.
<A NAME="IDX9870"></A>
<A NAME="IDX9871"></A>
<LI><CODE>BINROOT</CODE>: directory where the Ciao executables will go. For example, if <CODE>BINROOT=/usr/local/bin</CODE>, then the Ciao
<A NAME="IDX9872"></A>
compiler (
<A NAME="IDX9873"></A>
<CODE>ciaoc</CODE>) will be stored at <CODE>/usr/local/bin/ciaoc</CODE>. Actually, it will be a link to <CODE>ciaoc-</CODE><EM>VersionNumber</EM>. This applies also to other executables below and is done so that several versions of Ciao can coexist on the same machine. Note that the <EM>version installed latest</EM> will be the one started by default when typing <CODE>ciao</CODE>, <CODE>ciaoc</CODE>, etc.
<A NAME="IDX9874"></A>
<A NAME="IDX9875"></A>
<LI><CODE>LIBROOT</CODE>: directory where the
<A NAME="IDX9876"></A>
run-time libraries will be installed.
<A NAME="IDX9877"></A>
<A NAME="IDX9878"></A>
The Ciao installation procedure will create a new subdirectory <CODE>ciao</CODE> below <CODE>LIBROOT</CODE> and a subdirectory below this one for each Ciao version installed. For example, if <CODE>LIBROOT=/usr/local/lib</CODE> and you have Ciao version <CODE>x.y</CODE>, then the libraries will be installed under <CODE>/usr/local/lib/ciao/ciao-x.y</CODE>. This allows you to install
<A NAME="IDX9879"></A>
site-specific programs under <CODE>/usr/local/lib/ciao</CODE> and they will not be overwritten if a new version of Ciao is installed. It also again allows having several Ciao versions installed simultaneously.
<LI><CODE>DOCROOT</CODE>: directory where the
<A NAME="IDX9880"></A>
manuals will be installed. It is often convenient if this directory is accessible via
<A NAME="IDX9881"></A>
WWW (<CODE>DOCROOT=/home/httpd/html/ciao</CODE>, or something like that).
</UL>
For network-based installations,
<A NAME="IDX9882"></A>
<A NAME="IDX9883"></A>
it is of <EM>utmost importance</EM> that the paths given be reachable in all the networked machines. Different machines with different architectures can share the same physical <CODE>SRC</CODE> directory during installation, since compilations for different architectures take place in dedicated subdirectories. Also, different machines/architectures can share the same <CODE>LIBROOT</CODE> directory. This saves space since the architecture-independent libraries will be shared. See section <A HREF="ciao_231.html#SEC901">Multiarchitecture support</A> below.
<LI><STRONG>Compile Ciao:</STRONG> At the ciao top level directory type <CODE>gmake all</CODE>.
<EM>Important:</EM> use
<A NAME="IDX9884"></A>
GNU make (
<A NAME="IDX9885"></A>
<CODE>gmake</CODE>), not the standard
<A NAME="IDX9886"></A>
UNIX make, as the latter does not support some features used during the compilation. It does not matter if the name of the executable is
<A NAME="IDX9887"></A>
<CODE>make</CODE> or
<A NAME="IDX9888"></A>
<CODE>gmake</CODE>: only make sure that it is GNU make.
This will:
<UL>
<LI>Build an
<A NAME="IDX9889"></A>
engine in <CODE>$(SRC)/bin/$(CIAOARCH)</CODE>, where <CODE>$(CIAOARCH)</CODE> depends on the architecture. The engine is the actual interpreter of the low level code into which Ciao Prolog programs are compiled.
<LI>Build a new Ciao
<A NAME="IDX9890"></A>
standalone compiler (
<A NAME="IDX9891"></A>
<CODE>ciaoc</CODE>), with the default paths set for your local configuration (nonetheless, these can be overridden by environment variables, as described below).
<LI>Precompile all the libraries under <CODE>$(SRC)/lib</CODE> and <CODE>$(SRC)/library</CODE> using this compiler.
<LI>Compile a toplevel
<A NAME="IDX9892"></A>
Prolog shell and a shell for
<A NAME="IDX9893"></A>
Prolog scripts,
<A NAME="IDX9894"></A>
<A NAME="IDX9895"></A>
under the <CODE>$(SRC)/shell</CODE> directory.
<LI>Compile some small, auxiliary applications (contained in the
<A NAME="IDX9896"></A>
<CODE>etc</CODE> directory, and documented in the part of the manual on 'Miscellaneous Standalone Utilities').
</UL>
This step can be repeated successively for several architectures in the same source directory. Only the engine and some small parts of the libraries (those written in
<A NAME="IDX9897"></A>
C) differ from one architecture to the other. Standard Ciao Prolog code compiles into
<A NAME="IDX9898"></A>
bytecode object files (<CODE>.po</CODE>) and/or
<A NAME="IDX9899"></A>
executables which are portable among machines of different architecture, provided there is an executable engine accessible in every such machine. See more details below under section <A HREF="ciao_231.html#SEC901">Multiarchitecture support</A>.
<LI><STRONG>Check compilation:</STRONG> If the above steps have been satisfactorily finished, the compiler has compiled itself and all the distribution modules, and very probably everything is fine.
<LI><STRONG>Install Ciao:</STRONG> To install Ciao in the directories selected in the file
<A NAME="IDX9900"></A>
<CODE>SETTINGS</CODE> during step 2 above, type <CODE>gmake justinstall</CODE>. This will:
<UL>
<LI>Install the executables of the Ciao
<A NAME="IDX9901"></A>
program development tools (i.e., the general driver/top-level
<A NAME="IDX9902"></A>
<CODE>ciao</CODE>, the standalone compiler
<A NAME="IDX9903"></A>
<CODE>ciaoc</CODE>, the script interpreter
<A NAME="IDX9904"></A>
<CODE>ciao-shell</CODE>, miscellaneous utilities, etc.) in <CODE>BINROOT</CODE> (see below). In order to use these tools, the <CODE>PATH</CODE>
<A NAME="IDX9905"></A>
<A NAME="IDX9906"></A>
<A NAME="IDX9907"></A>
environment variable of users needs to contain the path <CODE>BINROOT</CODE>.
<LI>Install the Ciao libraries under <CODE>LIBROOT/ciao</CODE> (these will be automatically found).
<LI>Install under <CODE>DOCROOT</CODE> the Ciao manuals in several formats (such as GNU <CODE>info</CODE>, <CODE>html</CODE>, <CODE>postscript</CODE>, etc.), depending on the distribution. In order for these manuals to be found when typing <CODE>M-x info</CODE> within
<A NAME="IDX9908"></A>
<CODE>emacs</CODE>, or by the standalone
<A NAME="IDX9909"></A>
<CODE>info</CODE> and
<A NAME="IDX9910"></A>
<CODE>man</CODE> commands, the <CODE>MANPATH</CODE>
<A NAME="IDX9911"></A>
<A NAME="IDX9912"></A>
and <CODE>INFOPATH</CODE>
<A NAME="IDX9913"></A>
<A NAME="IDX9914"></A>
<A NAME="IDX9915"></A>
environment variables of users both need to contain the path <CODE>DOCROOT</CODE>.
<LI>Install under <CODE>LIBROOT/ciao</CODE> the Ciao GNU
<A NAME="IDX9916"></A>
<CODE>emacs</CODE> interface (
<A NAME="IDX9917"></A>
<CODE>ciao.el</CODE>, which provides an interactive interface to the Ciao program development tools, as well as some other auxiliary files) and a file
<A NAME="IDX9918"></A>
<CODE>DOTemacs</CODE> containing the
<A NAME="IDX9919"></A>
<CODE>emacs</CODE> initialization commands which are needed in order to use the Ciao
<A NAME="IDX9920"></A>
<CODE>emacs</CODE> interface.
</UL>
<LI><STRONG>Set up user environments:</STRONG> In order to automate the process of setting the variables above, the installation process leaves the files <CODE>LIBROOT/ciao/DOTcshrc</CODE> (for
<A NAME="IDX9921"></A>
<CODE>csh</CODE>-like shells), <CODE>LIBROOT/ciao/DOTprofile</CODE> (for
<A NAME="IDX9922"></A>
<CODE>sh</CODE>-like shells), and <CODE>LIBROOT/ciao/DOTemacs</CODE> (for emacs) with appropriate definitions which will take care of all needed
<A NAME="IDX9923"></A>
environment variable definitions and
<A NAME="IDX9924"></A>
emacs mode setup. Make the following modifications in your startup scripts, so that these files are used (<CODE><LIBROOT></CODE> must be replaced with the appropriate value):
<UL>
<LI>For users a
<A NAME="IDX9925"></A>
<A NAME="IDX9926"></A>
<EM>csh-compatible shell</EM> (
<A NAME="IDX9927"></A>
<CODE>csh</CODE>,
<A NAME="IDX9928"></A>
<CODE>tcsh</CODE>, ...), add to
<A NAME="IDX9929"></A>
<CODE>~/.cshrc</CODE>:
<PRE>
if ( -e <LIBROOT>/ciao/DOTcshrc ) then
source <LIBROOT>/ciao/DOTcshrc
endif
</PRE>
<A NAME="IDX9930"></A>
<CODE>Mac OS X</CODE> users should add (or modify) the
<A NAME="IDX9931"></A>
<CODE>path</CODE> file in the directory <CODE>~/Library/init/tcsh</CODE>, adding the lines shown above. <STRONG>Note:</STRONG> while this is recognized by the terminal shell, and therefore by the text-mode Emacs which comes with Mac OS X, the Aqua native Emacs 21 does not recognize that initialization. It is thus necessary, at this moment, to set manually the Ciao shell (ciaosh) and Ciao library location by hand. This can be done from the Ciao menu within Emacs after a Ciao Prolog file has been loaded. We suppose that the reason is that Mac OS X does not actually consult the per-user initialization files on startup. It should also be possible to put the right initializations in the .emacs file using the <CODE>setenv</CODE> function of Emacs-lisp, as in
<PRE>
(setenv "CIAOLIB" "<LIBROOT>/ciao")
</PRE>
The same can be done for the rest of the variables initialized in <CODE><LIBROOT>/ciao/DOTcshrc</CODE>
<LI>For users of an
<A NAME="IDX9932"></A>
<A NAME="IDX9933"></A>
<EM>sh-compatible shell</EM> (
<A NAME="IDX9934"></A>
<CODE>sh</CODE>,
<A NAME="IDX9935"></A>
<CODE>bash</CODE>, ...), add to
<A NAME="IDX9936"></A>
<CODE>~/.profile</CODE>:
<PRE>
if [ -f <LIBROOT>/ciao/DOTprofile ]; then
. <LIBROOT>/ciao/DOTprofile
fi
</PRE>
This will set up things so that the Ciao executables are found and you can access the Ciao system manuals using the
<A NAME="IDX9937"></A>
<CODE>info</CODE> command. Note that, depending on your shell, <EM>you may have to log out and back in</EM> for the changes to take effect.
<LI>Also, if you use
<A NAME="IDX9938"></A>
<CODE>emacs</CODE> (highly recommended) add this line to your
<A NAME="IDX9939"></A>
<CODE>~/.emacs</CODE> file:
<PRE>
(load-file "<LIBROOT>/ciao/DOTemacs.el")
</PRE>
</UL>
If you are installing Ciao globally in a multi-user machine, make sure that you instruct all users to do the same. If you are the system administrator, the previous steps can be done once and for all, and globally for all users by including the lines above in the central startup scripts (e.g., in Linux
<A NAME="IDX9940"></A>
<CODE>/etc/bashrc</CODE>,
<A NAME="IDX9941"></A>
<CODE>/etc/csh.login</CODE>,
<A NAME="IDX9942"></A>
<CODE>/etc/csh.cshrc</CODE>,
<A NAME="IDX9943"></A>
<CODE>/etc/skel</CODE>,
<A NAME="IDX9944"></A>
<CODE>/usr/share/emacs/.../lisp/site-init.pl</CODE>, etc.).
<LI><STRONG>Download and install Emacs (highly recommended):</STRONG> If the (freely available)
<A NAME="IDX9945"></A>
<CODE>emacs</CODE> editor is not installed in your system, its installation is <EM>highly recommended</EM> (if you are installing in a multi-user machine, you may want to do it in a general area so that it is available for other users, even if you do not use it yourself). While it is easy to use Ciao with any editor of your choice, the Ciao distribution includes a very powerful
<A NAME="IDX9946"></A>
<A NAME="IDX9947"></A>
<EM>application development environment</EM> which is based on
<A NAME="IDX9948"></A>
<CODE>emacs</CODE> and which enables, e.g., source-level debugging, syntax coloring, context-sensitive on-line help, etc.
<A NAME="IDX9949"></A>
<A NAME="IDX9950"></A>
<A NAME="IDX9951"></A>
<A NAME="IDX9952"></A>
The emacs editor (in all its versions: Un*x, Windows, etc.) can be downloaded from, for example, <A HREF="http://www.emacs.org/">http://www.emacs.org/</A>, and also from the many GNU mirror sites worldwide (See <A HREF="http://www.gnu.org/">http://www.gnu.org/</A> for a list), in the <CODE>gnu/emacs</CODE> and <CODE>gnu/windows/emacs</CODE> directories. You can find answers to frequently asked questions (FAQ) about
<A NAME="IDX9953"></A>
<CODE>emacs</CODE> in general at <A HREF="http://www.gnu.org/software/emacs/emacs-faq.text">http://www.gnu.org/software/emacs/emacs-faq.text</A> and about the Windows version at <A HREF="http://www.gnu.org/software/emacs/windows/ntemacs.html">http://www.gnu.org/software/emacs/windows/ntemacs.html</A> (despite the
<A NAME="IDX9954"></A>
<CODE>ntemacs</CODE> name it runs fine also as is on Win9X and Win2000 machines).
<LI><STRONG>Check installation / read documentation:</STRONG> You may now want to check your installation (see section <A HREF="ciao_231.html#SEC899">Checking for correct installation on Un*x</A>) and read the documentation, which is stored in <CODE>DOCROOT</CODE> (copied from <CODE>SRC/doc/reference</CODE>) and can be easily accessed as explained that same section. There are special "getting started" sections at the beginning of the manual.
</OL>
<P>
Other useful <CODE>make</CODE> targets are listed at the beginning of <CODE>$(SRC)/Makefile</CODE>.
<P>
If you have any problems you may want to check section <A HREF="ciao_231.html#SEC904">Troubleshooting (nasty messages and nifty workarounds)</A>.
<P>
The system can be <EM>uninstalled</EM> by typing <CODE>gmake uninstall</CODE> in the top directory (the variables in
<A NAME="IDX9955"></A>
<CODE>SETTINGS</CODE> should have the same value as when the install was performed, so that the same directories are cleaned).
<A NAME="IDX9956"></A>
<A NAME="IDX9957"></A>
<H2><A NAME="SEC899" HREF="ciao_toc.html#TOC899">Checking for correct installation on Un*x</A></H2>
<P>
<A NAME="IDX9958"></A>
<A NAME="IDX9959"></A>
<P>
If everything has gone well, several applications and tools should be available to a normal user. Try the following while logged in as a <EM>normal user</EM> (important in order to check that permissions are set up correctly):
<P>
<UL>
<LI>Typing
<A NAME="IDX9960"></A>
<CODE>ciao</CODE> (or
<A NAME="IDX9961"></A>
<CODE>ciaosh</CODE>) should start the typical Prolog top-level shell.
<LI>In the top-level shell, Prolog library modules should load correctly. Type for example <CODE>use_module(library(dec10_io))</CODE> --you should get back a prompt with no errors reported.
<LI>To exit the top level shell, type <CODE>halt.</CODE> as usual, or <KBD>^D</KBD>.
<LI>Typing
<A NAME="IDX9962"></A>
<CODE>ciaoc</CODE> should produce the help message from the Ciao
<A NAME="IDX9963"></A>
standalone compiler.
<LI>Typing
<A NAME="IDX9964"></A>
<CODE>ciao-shell</CODE> should produce a message saying that no code was found. This is a Ciao application which can be used to write
<A NAME="IDX9965"></A>
scripts written in Prolog, i.e., files which do not need any explicit compilation to be run.
</UL>
<P>
Also, the following documentation-related actions should work:
<UL>
<LI>If the
<A NAME="IDX9966"></A>
<CODE>info</CODE> program is installed, typing <CODE>info</CODE> should produce a list of manuals which <EM>should include Ciao manual(s) in a separate area</EM> (you may need to log out and back in so that your shell variables are reinitialized for this to work).
<LI>Opening with a
<A NAME="IDX9967"></A>
WWW browser (e.g.,
<A NAME="IDX9968"></A>
<CODE>netscape</CODE>) the directory or <CODE>URL</CODE> corresponding to the <CODE>DOCROOT</CODE> setting should show a series of Ciao-related manuals. Note that
<A NAME="IDX9969"></A>
<A NAME="IDX9970"></A>
<EM>style sheets</EM> should be activated for correct formatting of the manual.
<LI>Typing <CODE>man ciao</CODE> should produce a man page with some very basic general information on Ciao (and pointing to the on-line manuals).
<LI>The <CODE>DOCROOT</CODE> directory should contain the manual also in the other formats such as <CODE>postscript</CODE> or <CODE>pdf</CODE> which specially useful for printing. See section <A HREF="ciao_3.html#SEC41">Printing manuals (Un*x)</A> for instructions.
</UL>
<P>
Finally, if
<A NAME="IDX9971"></A>
<CODE>emacs</CODE> is installed, after starting it (typing <CODE>emacs</CODE>) the following should work:
<P>
<UL>
<LI>Typing <KBD>^H</KBD> <KBD>i</KBD> (or in the menus <CODE>Help->Manuals->Browse Manuals with Info</CODE>) should open a list of manuals in info format in which the Ciao manual(s) should appear.
<LI>When opening a Prolog file, i.e., a file with <CODE>.pl</CODE> or <CODE>.pls</CODE> ending, using <KBD>^X</KBD><KBD>^F</KBD><CODE>filename</CODE> (or using the menus) the code should appear highlighted according to syntax (e.g., comments in red), and <CODE>Ciao/Prolog</CODE> menus should appear in the menu bar on top of the
<A NAME="IDX9972"></A>
<CODE>emacs</CODE> window.
<LI>Loading the file using the <CODE>Ciao/Prolog</CODE> menu (or typing <KBD>^C</KBD> <KBD>l</KBD>) should start in another emacs buffer the Ciao toplevel shell and load the file. You should now be able to switch the the toplevel shell and make queries from within
<A NAME="IDX9973"></A>
<CODE>emacs</CODE>.
</UL>
<P>
<STRONG>Note:</STRONG> when using
<A NAME="IDX9974"></A>
<CODE>emacs</CODE> it is <EM>very convenient</EM> to swap the locations of the (normally not very useful) <KBD>Caps Lock</KBD> key and the (very useful in
<A NAME="IDX9975"></A>
<CODE>emacs</CODE>) <KBD>Ctrl</KBD> key on the keyboard. How to do this is explained in the
<A NAME="IDX9976"></A>
<CODE>emacs</CODE> frequently asked questions FAQs (see the
<A NAME="IDX9977"></A>
<CODE>emacs</CODE> download instructions for their location).
<H2><A NAME="SEC900" HREF="ciao_toc.html#TOC900">Cleaning up the source directory</A></H2>
<P>
After installation, the source directory can be cleaned up in several ways:
<UL>
<LI><CODE>gmake uninstall</CODE> removes the installation but does not touch the source directories.
<LI><CODE>gmake totalclean</CODE> leaves the distribution is its original form, throwing away any intermediate files (as well as any unneeded files left behind by the Ciao developers), while still allowing recompilation.
</UL>
<P>
Other useful <CODE>make</CODE> targets are listed at the beginning of <CODE>$(SRC)/Makefile</CODE>.
<H2><A NAME="SEC901" HREF="ciao_toc.html#TOC901">Multiarchitecture support</A></H2>
<P>
<A NAME="IDX9978"></A>
<A NAME="IDX9979"></A>
<P>
As mentioned before, Ciao applications (including the compiler and the top level) can run on several machines with different architectures without any need for recompiling, provided there is one Ciao engine (compiled for the corresponding architecture) accessible in each machine. Also, the Ciao libraries (installed in <CODE>LIBROOT</CODE>, which contain also the engines) and the actual binaries (installed in <CODE>BINROOT</CODE>) can themselves be shared on several machines with different architectures, saving disk space.
<P>
For example, assume that the compiler is installed as:
<P>
<CODE>/usr/local/share/bin/ciaoc</CODE>
<P>
and the libraries are installed under
<P>
<CODE>/usr/local/share/lib</CODE>
<P>
Assume also that the <CODE>/usr/local/share</CODE> directory is mounted on, say, a number of
<A NAME="IDX9980"></A>
Linux and a number of
<A NAME="IDX9981"></A>
Solaris boxes. In order for <CODE>ciaoc</CODE> to run correctly on both types of machines, the following is needed:
<OL>
<LI>Make sure you that have done <CODE>gmake install</CODE> on one machine of each architecture (once for Linux and once for Solaris in our example). This recompiles and installs a new engine and any architecture-dependent parts of the libraries for each architecture. The engines will have names such as <CODE>ciaoengine.LINUXi86</CODE>, <CODE>ciaoengine.SolarisSparc</CODE>, and so on.
<LI>In multi-architecture environments it is even more important to make sure that users make the modifications to their startup scripts using
<A NAME="IDX9982"></A>
<CODE><LIBROOT>/ciao/DOTcshrc</CODE> etc. The selection of the engine (and architecture-dependent parts of libraries) is done in these scripts by setting the environment variable <CODE>CIAOARCH</CODE>, using the <CODE>ciao_get_arch</CODE> command, which is installed automatically when installing Ciao. This will set <CODE>CIAOARCH</CODE> to, say, <CODE>LINUXi86</CODE>, <CODE>SolarisSparc</CODE>, respectively, and <CODE>CIAOENGINE</CODE> will be set to <CODE>ciaoengine.</CODE><EM>CIAOARCH</EM>.
However, note that this is not strictly necessary if running on only one architecture: if <CODE>CIAOARCH</CODE> is not set (i.e., undefined), the Ciao executables will look simply for <CODE>ciaoengine</CODE>, which is always a link to the latest engine installed in the libraries. But including the initialization files provided has the advantage of setting also paths for the manuals, etc.
</OL>
<H2><A NAME="SEC902" HREF="ciao_toc.html#TOC902">Installation and compilation under Windows</A></H2>
<P>
There are two possibilities in order to install Ciao Prolog on Windows machines:
<UL>
<LI>Installing from the Windows <EM>precompiled</EM> distribution. This is the easiest since it requires no compilation and is highly recommended. This is described in section <A HREF="ciao_232.html#SEC905">Installing Ciao from a Win32 binary distribution</A>.
<LI>Installing the standard Ciao Prolog (Un*x) system source distribution and compiling it under Windows. This is somewhat more complex and currently requires the (freely available) Cygnus Win32 development libraries --described below.
</UL>
<P>
<A NAME="IDX9983"></A>
<A NAME="IDX9984"></A>
<A NAME="IDX9985"></A>
<A NAME="IDX9986"></A>
In order to compile Ciao Prolog for Win32 environments you need to have the (public domain)
<A NAME="IDX9987"></A>
<A NAME="IDX9988"></A>
<EM>Cygnus Win32</EM> and development libraries installed in your system. Compilation should be performed preferably under Windows NT-type systems.
<UL>
<LI>Thus, the first step, if Cygnus Win32 is not installed in your system, is to download it (from, e.g., <A HREF="http://www.cygnus.com/misc/gnu-win32">http://www.cygnus.com/misc/gnu-win32</A>) and install it. The compilation process also requires that the executables <CODE>rm.exe</CODE>, <CODE>sh.exe</CODE>, and <CODE>uname.exe</CODE> from the Cygnus distribution be copied under <CODE>/bin</CODE> prior to starting the process (if these executables are not available under <CODE>/bin</CODE> the compilation process will produce a number of errors and eventually stop prematurely).
<LI>Assuming all of the above is installed, type <CODE>make allwin32</CODE>. This will compile both the engine and the Prolog libraries. In this process, system libraries that are normally linked dynamically under Un*x (i.e., those for which <CODE>.so</CODE> dynamically loadable files are generated) are linked statically into the engine (this is done instead of generating <CODE>.dll</CODE>s because of a limitation in the current version of the Cygnus Win32 environment). No actual installation is made at this point, i.e., this process leaves things in a similar state as if you had just downloaded and uncompressed the precompiled distribution. Thus, in order to complete the installation you should now:
<LI>Follow now the instructions in section <A HREF="ciao_232.html#SEC905">Installing Ciao from a Win32 binary distribution</A>.
</UL>
<P>
A further note regarding the executables generated by the Ciao compiler and top-level: the same considerations given in section <A HREF="ciao_232.html#SEC905">Installing Ciao from a Win32 binary distribution</A> apply regarding <CODE>.bat</CODE> files, etc. However, in a system in which Cygnus Win32 is installed these executables can also be used in a very simple way. In fact, the executables can be run as in Un*x by simply typing their name at the
<A NAME="IDX9989"></A>
<CODE>bash</CODE> shell command line without any associated <CODE>.bat</CODE> files. This only requires that the
<A NAME="IDX9990"></A>
<CODE>bash</CODE> shell which comes with Cygnus Win32 be installed and accessible: simply, make sure that
<A NAME="IDX9991"></A>
<CODE>/bin/sh.exe</CODE> exists.
<H2><A NAME="SEC903" HREF="ciao_toc.html#TOC903">Porting to currently unsupported operating systems</A></H2>
<P>
If you would like to port Ciao to a currently unsupported platform, there are several issues to take into account. The main one is to get the <EM>engine</EM> to compile in that platform, i.e., the C code under the <CODE>engine</CODE> directory. The procedure currently followed by Ciao to decide the various flags needed to compile is as follows:
<UL>
<LI>The shell script <CODE>$(SRC)/etc/ciao_get_arch</CODE> is executed; it returns a string describing the operating system and the processor architecture (e.g., LINUXi86, SolarisSparc, SolarisAlpha, etc.). You should make sure it returns a correct (and meaningful) string for your setup. This string is used trhoughout the compilation to create several architecture-dependant flags.
<LI>In the directory <CODE>$(SRC)/makefile-sysdep</CODE> there are files called mkf-<OS><ARCH> for every combination of operating system and architecture in which Ciao is know to (and how to) compile. They set several flags regarding, for example, whether to use or not threads, which threads library to use, the optimization flags to use, the compiler, linker, and it also sets separately the architecture name (ARCHNAME variable) and the operating system (OSNAME). You should create a new mkf file for your machine, starting from the one which is closest to you.
<LI>Most times the porting problems happen in the use of locks and threads. You can either disable them, or have a look at the files <CODE>$(SRC)/engine/locks.h</CODE> and <CODE>$(SRC)/engine/threads.h</CODE>. If you know how to implement native (assembler) locks for your architecture, enable HAVE_NATIVE_SLOCKS for your architecture and add the definitions. Otherwise, if you have library-based locks, enable them. The mechanism in <CODE>threads.h</CODE> is similar.
</UL>
<P>
Once a working engine is achieved, it should be possible to continue with the standard installation procedure, which will try to use a completely static version of the standalone compiler (<CODE>ciaoc.sta</CODE> in the <CODE>ciaoc</CODE> directory) to compile the interactive top-level (
<A NAME="IDX9992"></A>
<CODE>ciaosh</CODE>) and a new version of the standalone compiler (
<A NAME="IDX9993"></A>
<CODE>ciaoc</CODE>). These in turn should be able to compile the Prolog libraries. You may also need to look at some libraries (such as, for example,
<A NAME="IDX9994"></A>
<CODE>sockets</CODE>) which contain C code. If you do succeed in porting to a platform that is currently unsupported please send the
<A NAME="IDX9995"></A>
<CODE>mkf-CIAOARCH</CODE> and any patches to <A HREF="mailto:ciao@clip.dia.fi.upm.es">ciao@clip.dia.fi.upm.es</A>, and we will include them (with due credit, of course) in the next distribution.
<H2><A NAME="SEC904" HREF="ciao_toc.html#TOC904">Troubleshooting (nasty messages and nifty workarounds)</A></H2>
<P>
<A NAME="IDX9996"></A>
<A NAME="IDX9997"></A>
<P>
The following a list of common installation problems reported by users:
<UL>
<LI><STRONG>Problem:</STRONG> Compilation errors appear when trying a new installation/compilation after the previous one was aborted (e.g., because of errors).
<STRONG>Possible reason and solution:</STRONG> It is a good idea to clean up any leftovers from the previous compilation using <CODE>make engclean</CODE> before restarting the installation or compilation process.
<LI><STRONG>Problem:</STRONG>
During engine compilation, messages such as the following appear: <CODE>tasks.c:102:PTHREAD_CANCEL_ASYNCHRONOUS undeclared (first use of this function)</CODE>.
<STRONG>Possible reason and solution:</STRONG>
Your (Linux?) system does not have (yet) the
<A NAME="IDX9998"></A>
Posix threads library installed. You can upgrade to one which does have it, or download the library from
<A HREF="http://pauillac.inria.fr/~xleroy/linuxthreads/index.html">http://pauillac.inria.fr/~xleroy/linuxthreads/index.html</A>
and install it, or disable the use of threads in Linux: for this, edit the
<A NAME="IDX9999"></A>
<CODE>SETTINGS</CODE> file and specify <CODE>USE_THREADS=no</CODE>, which will avoid linking against thread libraries (it will disable the use of thread-related primitives as well). Clean the engine with <CODE>make engclean</CODE> and restart compilation.
If you have any alternative threads library available, you can tinker with <CODE>engine/threads.h</CODE> and the files under <CODE>makefile-sysdep</CODE> in order to get the task managing macros right for your system. Be sure to link the right library. If you succeed, we (<A HREF="mailto:ciao@clip.dia.fi.upm.es">ciao@clip.dia.fi.upm.es</A>) will be happy of knowing about what you have done.
<LI><STRONG>Problem:</STRONG>
<CODE>-lpthread: library not found</CODE> (or similar)
<STRONG>Possible reason and solution:</STRONG>
Your (Linux?) system seems to have Posix threads installed, but there is no threads library in the system. In newer releases (e.g.,
<A NAME="IDX10000"></A>
RedHat 5.0), the Posix threads system calls have been included in <CODE>glibc.so</CODE>, so specifying <CODE>-lpthread</CODE> in <CODE>makefile-sysdep/mkf-LINUX</CODE> is not needed; remove it. <CODE>make engclean</CODE> and restart installation.
Alternatively, you may have made a custom installation of Posix threads in a non-standard location: be sure to include the flag <CODE>-L/this/is/where/the/posix/libraries/are</CODE> <STRONG>before</STRONG> <CODE>-lpthread</CODE>, and to update <CODE>/etc/ld.so.conf</CODE> (see <CODE>man ldconfig</CODE>).
<LI><STRONG>Problem:</STRONG>
<CODE>Segmentation Violation</CODE> (when starting the first executable)
<STRONG>Possible reason and solution:</STRONG>
This has been observed with certain older versions of
<A NAME="IDX10001"></A>
<CODE>gcc</CODE> which generated erroneous code under full optimization. The best solution is to upgrade to a newer version of
<A NAME="IDX10002"></A>
<CODE>gcc</CODE>. Alternatively, lowering the level of optimization (by editing the
<A NAME="IDX10003"></A>
<CODE>SETTINGS</CODE> file in the main directory of the distribution) normally solves the problem, at the cost of reduced execution speed.
<LI><STRONG>Problem:</STRONG> <CODE>ciaoc: /home/clip/lib/ciao/ciao-X.Y/engine/ciaoengine: not found</CODE>
<STRONG>Possible reason and solution:</STRONG>
<UL>
<LI>The system was not fully installed and the variable <CODE>CIAOENGINE</CODE> was not set.
<LI>The system was installed, the variable <CODE>CIAOENGINE</CODE> is set, but it is does not point to a valid ciaoengine.
</UL>
See the file <CODE>LIBROOT/ciao/DOTcshrc</CODE> for user settings for environment variables.
<LI><STRONG>Problem:</STRONG>
<CODE>ERROR: File library(compiler) not found - aborting...</CODE> (or any other library is not found)
<STRONG>Possible reason and solution:</STRONG>
<UL>
<LI>The system was not installed and the variable <CODE>CIAOLIB</CODE> was not set.
<LI>The system is installed and the variable <CODE>CIAOLIB</CODE> is wrong.
</UL>
See the file <CODE>LIBROOT/ciao/DOTcshrc</CODE> for user settings for environment variables.
<LI><STRONG>Problem:</STRONG>
<CODE>ERROR: File <some_directory>/<some_file>.itf not found - aborting...</CODE>
<STRONG>Possible reason and solution:</STRONG>
Can appear when compiling <CODE>.pl</CODE> files. The file to compile (<some_file>.pl) is not in the directory <some_directory>. You gave a wrong file name or you are in the wrong directory.
<LI><STRONG>Problem:</STRONG>
<CODE>*ERROR*: /(write_option,1) is not a regular type</CODE> (and similar ones)
<STRONG>Possible reason and solution:</STRONG>
This is not a problem, but rather the type checker catching some minor inconsistencies which may appear while compiling the libraries. Bug us to remove it, but ignore it for now.
<LI><STRONG>Problem:</STRONG>
<CODE>WARNING: Predicate <some_predicate>/<N> undefined in module <some_module></CODE>
<STRONG>Possible reason and solution:</STRONG>
It can appear when the compiler is compiling Ciao library modules. If so, ignore it (we will fix it). If it appears when compiling user programs or modules, you may want to check your program for those undefined predicates.
<LI><STRONG>Problem:</STRONG>
<CODE>gmake[1]: execve: /home/clip/mcarro/ciao-0.7p2/etc/collect_modules: No such file or directory</CODE>
<STRONG>Possible reason and solution:</STRONG>
Check if collect_modules is in $(SRC)/etc and is executable. If it is not here, your distribution is incorrect: please let us know.
<LI><STRONG>Problem:</STRONG>
<CODE>make: Fatal error in reader: SHARED, line 12: Unexpected end of line seen</CODE>
<STRONG>Possible reason and solution:</STRONG>
You are using standard Un*x make, not GNU's make implementation (gmake).
<LI><STRONG>Problem:</STRONG>
<CODE>WARNING</CODE>s or <CODE>ERROR</CODE>s while compiling the Ciao libraries during installation.
<STRONG>Possible reason and solution:</STRONG>
It is possible that you will see some such errors while compiling the Ciao libraries during installation. This is specially the case if you are installing a Beta or Alpha release of Ciao. These releases (which have "odd" version numbers such as 1.5 or 2.1) are typically snapshots of the development directories, on which many developers are working simultaneously, which may include libraries which have typically not been tested yet as much as the "official" distributions (those with "even" version numbers such as 1.6 or 2.8). Thus, minor warnings may not have been eliminated yet or even errors can sneak in. These warnings and errors should not affect the overall operation of the system (e.g., if you do not use the affected library).
</UL>
<P><HR><P>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_230.html">previous</A>, <A HREF="ciao_232.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
</BODY>
</HTML>
