Author(s): Manuel Carro, Daniel Cabeza, Manuel Hermenegildo.
Version: 1.10#7 (2006/4/26, 19:22:13 CEST)
Version of last change: 1.10#2 (2004/8/2, 19:25:49 CEST)
This describes the installation procedure for the Ciao Prolog system, including libraries and manuals, from a source 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 Installation and compilation under Windows for details.
If you find any problems during installation, please refer to section Troubleshooting (nasty messages and nifty workarounds). See also section Downloading new versions and section Reporting bugs.
Note: 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:
gunzip
and tar -xpf
) the distribution. This will put everything in a new directory whose name reflects the Ciao version.
SRC
). Edit
SETTINGS
and check/set the variables SRC
, CIAOROOT
(this defines where the installation will hang from) and DOCROOT
(where the documentation will go, preferably a directory accessible via
WWW). CIAOROOT
is used to give values to BINROOT
, LIBROOT
, and INCLUDEROOT
. You can give different values to these if you want.
gmake install
. This will build executables, compile libraries, and install everything in a directory LIBROOT/ciao
and in BINROOT
.
Note that gmake
refers to the
GNU implementation of the
make Un*x command, which is available in many systems (including all Linux systems and Mac OS X) simply as
make
. I.e., you can try simply typing make install
if gmake install
does not work. If typing make
stops right away with error messages it is probably an older version and you need to install gmake
.
emacs
, etc. Note that <LIBROOT>
must be replaced with the appropriate value:
csh
,
tcsh
, ...), add to
~/.cshrc
:
if ( -e <LIBROOT>/ciao/DOTcshrc ) then source <LIBROOT>/ciao/DOTcshrc endif
Mac OS X
users should add (or modify) the
path
file in the directory ~/Library/init/tcsh
, adding the lines shown above. Note: 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 setenv
function of Emacs-lisp, as in
(setenv "CIAOLIB" "<LIBROOT>/ciao")The same can be done for the rest of the variables initialized in
<LIBROOT>/ciao/DOTcshrc
sh
,
bash
, ...), add to
~/.profile
:
if [ -f <LIBROOT>/ciao/DOTprofile ]; then . <LIBROOT>/ciao/DOTprofile fiThis will set up things so that the Ciao executables are found and you can access the Ciao system manuals using the
info
command. Note that, depending on your shell, you may have to log out and back in for the changes to take effect.
emacs
(highly recommended) add this line to your
~/.emacs
file:
(load-file "<LIBROOT>/ciao/DOTemacs.el")
/etc/bashrc
,
/etc/csh.login
,
/etc/csh.cshrc
,
/etc/skel
,
/usr/share/emacs/.../lisp/site-init.pl
, etc.).
emacs
editor/environment is not installed in your system, we highly recommend that you also install it at this point (see section Un*x full installation instructions for instructions). While it is easy to use Ciao with any editor of your choice, the Ciao distribution includes a very powerful
application development environment which is based on
emacs
and which enables, e.g., source-level debugging, syntax coloring, context-sensitive on-line help, etc.
DOCROOT
(copied from SRC/doc/reference
) and can be easily accessed as explained in that same section. There are special "getting started" sections at the beginning of the manual.
gmake uninstall
.
gunzip
and tar -xpf
)
the distribution in a suitable directory. This will create a new directory called ciao-X.Y
, where X.Y
is the version number of the distribution. The -p
option in the
tar
command ensures that the relative dates of the files in the package are preserved, which is needed for correct operation of the Makefiles.
SETTINGS
and set the following variables:
SRC
: directory where the sources are stored.
BINROOT
: directory where the Ciao executables will go. For example, if BINROOT=/usr/local/bin
, then the Ciao
compiler (
ciaoc
) will be stored at /usr/local/bin/ciaoc
. Actually, it will be a link to ciaoc-
VersionNumber. 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 version installed latest will be the one started by default when typing ciao
, ciaoc
, etc.
LIBROOT
: directory where the
run-time libraries will be installed.
The Ciao installation procedure will create a new subdirectory ciao
below LIBROOT
and a subdirectory below this one for each Ciao version installed. For example, if LIBROOT=/usr/local/lib
and you have Ciao version x.y
, then the libraries will be installed under /usr/local/lib/ciao/ciao-x.y
. This allows you to install
site-specific programs under /usr/local/lib/ciao
and they will not be overwritten if a new version of Ciao is installed. It also again allows having several Ciao versions installed simultaneously.
DOCROOT
: directory where the
manuals will be installed. It is often convenient if this directory is accessible via
WWW (DOCROOT=/home/httpd/html/ciao
, or something like that).
SRC
directory during installation, since compilations for different architectures take place in dedicated subdirectories. Also, different machines/architectures can share the same LIBROOT
directory. This saves space since the architecture-independent libraries will be shared. See section Multiarchitecture support below.
gmake all
.
Important: use
GNU make (
gmake
), not the standard
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
make
or
gmake
: only make sure that it is GNU make.
This will:
$(SRC)/bin/$(CIAOARCH)
, where $(CIAOARCH)
depends on the architecture. The engine is the actual interpreter of the low level code into which Ciao Prolog programs are compiled.
ciaoc
), with the default paths set for your local configuration (nonetheless, these can be overridden by environment variables, as described below).
$(SRC)/lib
and $(SRC)/library
using this compiler.
$(SRC)/shell
directory.
etc
directory, and documented in the part of the manual on 'Miscellaneous Standalone Utilities').
.po
) and/or
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 Multiarchitecture support.
SETTINGS
during step 2 above, type gmake justinstall
. This will:
ciao
, the standalone compiler
ciaoc
, the script interpreter
ciao-shell
, miscellaneous utilities, etc.) in BINROOT
(see below). In order to use these tools, the PATH
environment variable of users needs to contain the path BINROOT
.
LIBROOT/ciao
(these will be automatically found).
DOCROOT
the Ciao manuals in several formats (such as GNU info
, html
, postscript
, etc.), depending on the distribution. In order for these manuals to be found when typing M-x info
within
emacs
, or by the standalone
info
and
man
commands, the MANPATH
and INFOPATH
environment variables of users both need to contain the path DOCROOT
.
LIBROOT/ciao
the Ciao GNU
emacs
interface (
ciao.el
, which provides an interactive interface to the Ciao program development tools, as well as some other auxiliary files) and a file
DOTemacs
containing the
emacs
initialization commands which are needed in order to use the Ciao
emacs
interface.
LIBROOT/ciao/DOTcshrc
(for
csh
-like shells), LIBROOT/ciao/DOTprofile
(for
sh
-like shells), and LIBROOT/ciao/DOTemacs
(for emacs) with appropriate definitions which will take care of all needed
environment variable definitions and
emacs mode setup. Make the following modifications in your startup scripts, so that these files are used (<LIBROOT>
must be replaced with the appropriate value):
csh
,
tcsh
, ...), add to
~/.cshrc
:
if ( -e <LIBROOT>/ciao/DOTcshrc ) then source <LIBROOT>/ciao/DOTcshrc endif
Mac OS X
users should add (or modify) the
path
file in the directory ~/Library/init/tcsh
, adding the lines shown above. Note: 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 setenv
function of Emacs-lisp, as in
(setenv "CIAOLIB" "<LIBROOT>/ciao")The same can be done for the rest of the variables initialized in
<LIBROOT>/ciao/DOTcshrc
sh
,
bash
, ...), add to
~/.profile
:
if [ -f <LIBROOT>/ciao/DOTprofile ]; then . <LIBROOT>/ciao/DOTprofile fiThis will set up things so that the Ciao executables are found and you can access the Ciao system manuals using the
info
command. Note that, depending on your shell, you may have to log out and back in for the changes to take effect.
emacs
(highly recommended) add this line to your
~/.emacs
file:
(load-file "<LIBROOT>/ciao/DOTemacs.el")
/etc/bashrc
,
/etc/csh.login
,
/etc/csh.cshrc
,
/etc/skel
,
/usr/share/emacs/.../lisp/site-init.pl
, etc.).
emacs
editor is not installed in your system, its installation is highly recommended (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
application development environment which is based on
emacs
and which enables, e.g., source-level debugging, syntax coloring, context-sensitive on-line help, etc.
The emacs editor (in all its versions: Un*x, Windows, etc.) can be downloaded from, for example, http://www.emacs.org/, and also from the many GNU mirror sites worldwide (See http://www.gnu.org/ for a list), in the gnu/emacs
and gnu/windows/emacs
directories. You can find answers to frequently asked questions (FAQ) about
emacs
in general at http://www.gnu.org/software/emacs/emacs-faq.text and about the Windows version at http://www.gnu.org/software/emacs/windows/ntemacs.html (despite the
ntemacs
name it runs fine also as is on Win9X and Win2000 machines).
DOCROOT
(copied from SRC/doc/reference
) and can be easily accessed as explained that same section. There are special "getting started" sections at the beginning of the manual.
Other useful make
targets are listed at the beginning of $(SRC)/Makefile
.
If you have any problems you may want to check section Troubleshooting (nasty messages and nifty workarounds).
The system can be uninstalled by typing gmake uninstall
in the top directory (the variables in
SETTINGS
should have the same value as when the install was performed, so that the same directories are cleaned).
If everything has gone well, several applications and tools should be available to a normal user. Try the following while logged in as a normal user (important in order to check that permissions are set up correctly):
ciao
(or
ciaosh
) should start the typical Prolog top-level shell.
use_module(library(dec10_io))
--you should get back a prompt with no errors reported.
halt.
as usual, or ^D.
ciaoc
should produce the help message from the Ciao
standalone compiler.
ciao-shell
should produce a message saying that no code was found. This is a Ciao application which can be used to write
scripts written in Prolog, i.e., files which do not need any explicit compilation to be run.
Also, the following documentation-related actions should work:
info
program is installed, typing info
should produce a list of manuals which should include Ciao manual(s) in a separate area (you may need to log out and back in so that your shell variables are reinitialized for this to work).
netscape
) the directory or URL
corresponding to the DOCROOT
setting should show a series of Ciao-related manuals. Note that
style sheets should be activated for correct formatting of the manual.
man ciao
should produce a man page with some very basic general information on Ciao (and pointing to the on-line manuals).
DOCROOT
directory should contain the manual also in the other formats such as postscript
or pdf
which specially useful for printing. See section Printing manuals (Un*x) for instructions.
Finally, if
emacs
is installed, after starting it (typing emacs
) the following should work:
Help->Manuals->Browse Manuals with Info
) should open a list of manuals in info format in which the Ciao manual(s) should appear.
.pl
or .pls
ending, using ^X^Ffilename
(or using the menus) the code should appear highlighted according to syntax (e.g., comments in red), and Ciao/Prolog
menus should appear in the menu bar on top of the
emacs
window.
Ciao/Prolog
menu (or typing ^C l) 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
emacs
.
Note: when using
emacs
it is very convenient to swap the locations of the (normally not very useful) Caps Lock key and the (very useful in
emacs
) Ctrl key on the keyboard. How to do this is explained in the
emacs
frequently asked questions FAQs (see the
emacs
download instructions for their location).
After installation, the source directory can be cleaned up in several ways:
gmake uninstall
removes the installation but does not touch the source directories.
gmake totalclean
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.
Other useful make
targets are listed at the beginning of $(SRC)/Makefile
.
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 LIBROOT
, which contain also the engines) and the actual binaries (installed in BINROOT
) can themselves be shared on several machines with different architectures, saving disk space.
For example, assume that the compiler is installed as:
/usr/local/share/bin/ciaoc
and the libraries are installed under
/usr/local/share/lib
Assume also that the /usr/local/share
directory is mounted on, say, a number of
Linux and a number of
Solaris boxes. In order for ciaoc
to run correctly on both types of machines, the following is needed:
gmake install
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 ciaoengine.LINUXi86
, ciaoengine.SolarisSparc
, and so on.
<LIBROOT>/ciao/DOTcshrc
etc. The selection of the engine (and architecture-dependent parts of libraries) is done in these scripts by setting the environment variable CIAOARCH
, using the ciao_get_arch
command, which is installed automatically when installing Ciao. This will set CIAOARCH
to, say, LINUXi86
, SolarisSparc
, respectively, and CIAOENGINE
will be set to ciaoengine.
CIAOARCH.
However, note that this is not strictly necessary if running on only one architecture: if CIAOARCH
is not set (i.e., undefined), the Ciao executables will look simply for ciaoengine
, 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.
There are two possibilities in order to install Ciao Prolog on Windows machines:
In order to compile Ciao Prolog for Win32 environments you need to have the (public domain) Cygnus Win32 and development libraries installed in your system. Compilation should be performed preferably under Windows NT-type systems.
rm.exe
, sh.exe
, and uname.exe
from the Cygnus distribution be copied under /bin
prior to starting the process (if these executables are not available under /bin
the compilation process will produce a number of errors and eventually stop prematurely).
make allwin32
. 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 .so
dynamically loadable files are generated) are linked statically into the engine (this is done instead of generating .dll
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:
A further note regarding the executables generated by the Ciao compiler and top-level: the same considerations given in section Installing Ciao from a Win32 binary distribution apply regarding .bat
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
bash
shell command line without any associated .bat
files. This only requires that the
bash
shell which comes with Cygnus Win32 be installed and accessible: simply, make sure that
/bin/sh.exe
exists.
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 engine to compile in that platform, i.e., the C code under the engine
directory. The procedure currently followed by Ciao to decide the various flags needed to compile is as follows:
$(SRC)/etc/ciao_get_arch
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.
$(SRC)/makefile-sysdep
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.
$(SRC)/engine/locks.h
and $(SRC)/engine/threads.h
. 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 threads.h
is similar.
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 (ciaoc.sta
in the ciaoc
directory) to compile the interactive top-level (
ciaosh
) and a new version of the standalone compiler (
ciaoc
). These in turn should be able to compile the Prolog libraries. You may also need to look at some libraries (such as, for example,
sockets
) which contain C code. If you do succeed in porting to a platform that is currently unsupported please send the
mkf-CIAOARCH
and any patches to ciao@clip.dia.fi.upm.es, and we will include them (with due credit, of course) in the next distribution.
The following a list of common installation problems reported by users:
make engclean
before restarting the installation or compilation process.
tasks.c:102:PTHREAD_CANCEL_ASYNCHRONOUS undeclared (first use of this function)
.
Possible reason and solution:
Your (Linux?) system does not have (yet) the
Posix threads library installed. You can upgrade to one which does have it, or download the library from
http://pauillac.inria.fr/~xleroy/linuxthreads/index.html
and install it, or disable the use of threads in Linux: for this, edit the
SETTINGS
file and specify USE_THREADS=no
, which will avoid linking against thread libraries (it will disable the use of thread-related primitives as well). Clean the engine with make engclean
and restart compilation.
If you have any alternative threads library available, you can tinker with engine/threads.h
and the files under makefile-sysdep
in order to get the task managing macros right for your system. Be sure to link the right library. If you succeed, we (ciao@clip.dia.fi.upm.es) will be happy of knowing about what you have done.
-lpthread: library not found
(or similar)
Possible reason and solution:
Your (Linux?) system seems to have Posix threads installed, but there is no threads library in the system. In newer releases (e.g.,
RedHat 5.0), the Posix threads system calls have been included in glibc.so
, so specifying -lpthread
in makefile-sysdep/mkf-LINUX
is not needed; remove it. make engclean
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 -L/this/is/where/the/posix/libraries/are
before -lpthread
, and to update /etc/ld.so.conf
(see man ldconfig
).
Segmentation Violation
(when starting the first executable)
Possible reason and solution:
This has been observed with certain older versions of
gcc
which generated erroneous code under full optimization. The best solution is to upgrade to a newer version of
gcc
. Alternatively, lowering the level of optimization (by editing the
SETTINGS
file in the main directory of the distribution) normally solves the problem, at the cost of reduced execution speed.
ciaoc: /home/clip/lib/ciao/ciao-X.Y/engine/ciaoengine: not found
Possible reason and solution:
CIAOENGINE
was not set.
CIAOENGINE
is set, but it is does not point to a valid ciaoengine.
LIBROOT/ciao/DOTcshrc
for user settings for environment variables.
ERROR: File library(compiler) not found - aborting...
(or any other library is not found)
Possible reason and solution:
CIAOLIB
was not set.
CIAOLIB
is wrong.
LIBROOT/ciao/DOTcshrc
for user settings for environment variables.
ERROR: File <some_directory>/<some_file>.itf not found - aborting...
Possible reason and solution:
Can appear when compiling .pl
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.
*ERROR*: /(write_option,1) is not a regular type
(and similar ones)
Possible reason and solution:
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.
WARNING: Predicate <some_predicate>/<N> undefined in module <some_module>
Possible reason and solution:
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.
gmake[1]: execve: /home/clip/mcarro/ciao-0.7p2/etc/collect_modules: No such file or directory
Possible reason and solution:
Check if collect_modules is in $(SRC)/etc and is executable. If it is not here, your distribution is incorrect: please let us know.
make: Fatal error in reader: SHARED, line 12: Unexpected end of line seen
Possible reason and solution:
You are using standard Un*x make, not GNU's make implementation (gmake).
WARNING
s or ERROR
s while compiling the Ciao libraries during installation.
Possible reason and solution:
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).
Go to the first, previous, next, last section, table of contents.