Go to the first, previous, next, last section, table of contents.


Installing Ciao

Author(s): Manuel Carro, Daniel Cabeza, Manuel Hermenegildo.

Version: 1.3#120 (1999/11/26, 12:5:17 MET)

Version of last change: 1.3#117 (1999/11/25, 1:44:7 MET)

This describes the installation procedure for the Ciao Prolog system, including libraries and manuals. Please read section Un*x installation summary and section Un*x full installation instructions for the installation procedures from sources on Un*x (Linux, SunOS, Solaris, etc.) machines. Windows NT/95/98 users are referred to section Installation and compilation under Windows and section Windows installation from the precompiled distribution.

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.

Un*x installation summary

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:

  1. Uncompress and unpackage (using gunzip and tar -xpf) the distribution. This will put everyting in a new directory whose name reflects the Ciao version.
  2. Enter the newly created directory (SRC). Edit SETTINGS and check/set the variables SRC, BINROOT (where the executables will go), LIBROOT (where the libraries will go), and DOCROOT (where the documentation will go, preferably a directory accessible via WWW).
  3. Type 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) 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.
  4. Make the following modifications in your startup scripts. If you are installing Ciao globally in a multi-user machine, make sure that you instruct all users to do the same. This will make the documentation accessible, set the correct mode when opening Ciao source files in emacs, etc. (<LIBROOT> must be replaced by the appropriate value): 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 /etc/cshrc/ /etc/csh.cshrc, /etc/bashrc, /usr/share/emacs/.../lisp/site-init.pl, etc.).
  5. Downloading the emacs editor, if it is not available in the system, is highly recommended (see section Un*x full installation instructions).
  6. You may want to read now section Checking for correct installation and the documentation, which is stored in DOCROOT (copied from SRC/doc/reference) and can be easily accessed as explained in that same section.
  7. If you have any problems you may want to check the rest of the instructions. The system can be uninstalled by typing gmake uninstall.

Un*x full installation instructions

  1. Uncompress and unpackage: (using 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.
  2. Select Installation Options: Edit the file SETTINGS and set the following variables: For network-based installations, it is of utmost importance that the paths given be reachable in all the networked machines. Different machines with different architectures can share the same physical 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.
  3. Compile Ciao: At the ciao top level directory type 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: 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 C) differ from one architecture to the other. Standard Ciao Prolog code compiles into bytecode object files (.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.
  4. Check compilation: If the above steps have been satisfactorily finished, the compiler has compiled itself and all the distribution modules, and very probably everything is fine. To further check this before final installation you can type gmake test, which will compile and execute a small program containing several tests.
  5. Install Ciao: To install Ciao in the directories selected in the file SETTINGS during step 2 above, type gmake justinstall. This will:
  6. Set up user environments: In order to automate the process of setting the variables above, the installation process leaves the files 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. Thus, if you are installing in a multi-user machine, make sure that you instruct all users to make the following modifications in their startup scripts or that you follow these instructions yourself if you are installing Ciao only for your personal use (<LIBROOT> must be replaced by the appropriate value): 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 /etc/cshrc/ /etc/csh.cshrc, /etc/bashrc, /usr/share/emacs/.../lisp/site-init.pl, etc.).
  7. Download and install Emacs (optional): If the emacs editor is not available 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). The emacs editor (in all its versions: Un*x, Windows, etc.) can be donloaded 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. For example, at UPM it can be found at ftp://ftp.fi.upm.es/pub/mirrors/gnu/emacs and ftp://ftp.fi.upm.es/pub/mirrors/gnu/windows/emacs. You can find answers to frequently asked question 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.
  8. Check installation: You may want to read now section Checking for correct installation and the documentation, which is stored in DOCROOT (copied from SRC/doc/reference) and can be easily accessed as explained that same section.

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).

Installation and compilation under Windows

There are two possibilities in order to install Ciao Prolog on Windows NT/95/98 machines:

The two procedures are described in the following sections.

Windows installation from the precompiled distribution

This describes the installation of Ciao after downloading the Windows precompiled distribution. This is the simplest Windows installation, since it requires no compilation and is highly recommended.

Installation of the precompiled distribution

Please follow these steps (below we use the terms folder and directory interchangeably):

  1. Download the precompiled distribution and unpack it into any suitable folder, such as, e.g., C:\Program Files (this will create there a folder whose name reflects the Ciao version). Due to limitations of Windows related to file associations, do not put Ciao too deep in the folder hierarchy. For unpacking you will need a recent version of a zip archive manager -- there are many freely available such as WinZip, unzip, pkunzip, etc.). If you have a previous version of Ciao installed, make sure you do not have any Ciao applications (including, e.g., a toplevel shell) running, or the extraction process may not be able to complete. You may want to delete the entire folder of the previous installation to save space.
  2. Run (e.g. by double-clicking on it) the install(.bat) script. This will update the windows registry (the file ciao.reg lists the additions) and also create some .bat files for running Ciao executables from the command line. It also creates initialization scripts for the emacs editor. After that, you may need to reboot for the changes in the registry to take effect.
  3. You may want to add a windows shortcut in a convenient place, such as the desktop, to ciaosh.cpx, the standard interactive toplevel shell. It is located inside the shell folder (e.g., click on the file ciaosh.cpx with the right mouse button and select the appropriate option, Send to->Desktop as shortcut).
  4. You may also want to add another shortcut to the file ciao.html located inside doc\reference\ciao_html so that you can open the Ciao manual by simply double-clicking on this shortcut.

Getting started after Windows installation

The actions and registry changes performed by the installation procedure, in addition to setting icons for ciao-related file types, make several other things possible:

Starting executables from the Windows command line

The installation script also creates a .bat skeleton file (bat_skel in folder Win32) which allows running Ciao executables from the command line. If you want to run a Ciao executable file.cpx from the command line, you normally copy the skeleton file to the folder were the executable is and rename it to file.bat, then change its contents as explained in a comment inside. Note that this .bat file is usually not necessary in NT, as its command shell understands file extension associations, i.e., in windows NT it is possible to run the file.cpx executable directly. Due to limitations of .bat files in Windows 95/98, in those OSs no more than 9 command line arguments can be passed to the executable (in NT there is no such restriction).

The installation script creates also ciaosh.bat and ciaoc.bat files (in the shell and ciaoc folders respectively). These allow calling the interactive top-level and the standalone compiler from the command line in Windows95/98.

Using the emacs environment under Windows

While it is easy to use Ciao with any editor of your choice, using it within the emacs editor/program development system is highly recommended: Ciao includes an emacs mode which greatly simplifies many program development tasks (see section Using Ciao inside GNU emacs for details on the capabilities of ciao/ emacs combination.

The emacs editor (in all its versions: Un*x, Windows, etc.) can be donloaded 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. For example, at UPM it can be found at ftp://ftp.fi.upm.es/pub/mirrors/gnu/emacs and ftp://ftp.fi.upm.es/pub/mirrors/gnu/windows/emacs. You can find answers to frequently asked question 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.

In order to allow emacs to load the Ciao mode automatically when editing and to access the documentation, open using emacs (^X^F)) the file ~/.emacs (or, perhaps, c:/.emacs) and add the following line to it:

        (load-file "<CIAODIR>/DOTemacs.el")

where you should put in place of <CIAODIR> the directory where you installed the Ciao distribution. After doing this (and exiting and restarting emacs) the following things should work:

Compiling the miscellaneous utilities under Windows

The etc folder contains a number of utilities, documented in the manual in PART V - Miscellaneous Standalone Utilities. In the Win32 distribution these utilities are not compiled by the installation process. You can create the executable for each of them when needed by compiling the corresponding .pl file.

Server installation under Windows

If you would like to install Ciao on a server machine, used by several clients, the following steps are recommended:

Uninstallation under Windows

To uninstall Ciao under Windows, simply delete the directory in which you put the Ciao distribution. If you also want to delete the registry entries created by the Ciao installation (not strictly needed) this must currently be done by hand. The installation leaves a list of these entries in the file ciao.reg to aid in this task. Also, all the register entries contain the word ciao. Thus, to delete all Ciao entries, run the application regedit (for example, by selecting Run from the Windows Start menu), search (^F) for ciao in all registry entries (i.e., select all of Keys, Values, and Data in the Edit->Find dialog), and delete each matching key (click on the left window to find the matching key for each entry found).

Windows installation from the standard source distribution

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.

A further note regarding the executables generated by the Ciao compiler and top-level: the same considerations given in section Windows installation from the precompiled 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.

Checking for correct installation

If everything has gone well, several applications and tools should be available to a normal user. The most important ones are the following:

Also, the following documentation-related actions should work:

Cleaning up the source directory

After installation, the source directory can be cleaned up in several ways:

Other useful make targets are listed at the beginning of $(SRC)/Makefile.

Environment variables used by Ciao executables

The executables generated by the Ciao compiler (including the ciao development tools themselves) locate automatically where the Ciao engine and libraries have been installed, since those paths are stored as defaults in the engine and compiler at installation time. Thus, there is no need for setting any environment variables in order to run Ciao executables (on a single architecture -- see section Multiarchitecture support for running on multiple architectures).

However, the default paths can be overridden by using the environment variables CIAOENGINE and CIAOLIB. The first one will tell the Ciao executables where to look for an engine, and the second will tell them where to look for the libraries. Thus, it is possible to actually use the Ciao system without installing it by setting these variables to the following values:

where $(CIAOARCH) is the string echoed by the command SRC/etc/ciao_get_arch (or BINROOT/ciao_get_arch, after installation).

This allows using alternate engines or libraries, which can be very useful for system development and experimentation.

Multiarchitecture support

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 machines, the following is needed:

  1. Make sure you that have done 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.
  2. In multi-architecture environments it is even more important to make sure that users make the modifications to their startup scripts using <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.

Architecture specific notes and limitations

Ciao makes use of advanced characteristics of modern architectures and operating systems such as multithreading, shared memory, sockets, locks, dynamic load libraries, etc., some of which which are sometimes not present in a given system and others may be implemented in very different ways across the different systems. As a result, currently not all Ciao features are available in all supported operating systems. Sometimes this is because not all the required features are present in all the OS flavors supported and sometimes because we simply have not had the time to port them yet.

The current state of matters is as follows:

LINUX:
multithreading, shared DB access, and locking working.
Solaris:
multithreading, shared DB access, and locking working.
SunOS 4:
multithreading, shared DB access, and locking NOT working.
Win 95/NT:
multithreading, shared DB access, locking, and dynamic linking of object code (C) libraries NOT working.

The features that do not work are disabled at compile time. If problems appear, please disable them explicitly in the SETTINGS file. We will make this more automatic sometime in the future.

Downloading new versions

Ciao and its related libraries and utilities are under constant improvement, so you should make sure that you have the latest versions of the different components, which can be dowloaded from:

http://clip.dia.fi.upm.es/Software

Keeping up to date: the Ciao users mailing list

We recommend that you join the Ciao users mailing list (ciao-users@clip.dia.fi.upm.es), in order to receive information on new versions and solutions to problems. Simply send a message to ciao-users-request@clip.dia.fi.upm.es, containing in the body only the word:

subscribe

alone in one line. Messages in the list are strictly limited to issues directly related to Ciao Prolog and your email address will of course be kept strictly confidential. You mail also want to subscribe to the comp.lang.prolog newsgroup.

There is additional info available on the Ciao system, other CLIP group software, publications on the technology underlying these systems, etc. in the CLIP group's WWW site http://clip.dia.fi.upm.es.

Reporting bugs

If you still have problems after downloading the latest version and reading the installation instructions you can send a message to ciao-bug@clip.dia.fi.upm.es. Please be as informative as possible in your messages, so that we can reproduce the bug.

Porting to currently unsupported operating systems

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. To this end, look under the directory $(SRC)/makefile-sysdep: there is a mkf-CIAOARCH file for every architecture/OS under which Ciao is known to compile. You can start from the closest one and customize it for your local distribution or installed tools. But please keep the original files! 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. Porting to other Un*x flavours should be easy while other operating system families may require more work. If you do succeed in porting to a platform that is currently please send the mkf-CIAOARCH and any patches to ciao@clip.dia.fi.upm.es, and we will include it (with due credit, of course) in the next distribution.

Troubleshooting (nasty messages and nifty workarounds)

The following a list of common installation problems reported by users:


Go to the first, previous, next, last section, table of contents.