Installing Ciao from the source distribution

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

This describes the installation procedure for the Ciao system, including libraries and manuals, from a source distribution. For more specific details, please read also the INSTALLATION file that comes with each component of Ciao. However, in most cases following this summary suffices.

If you find any problems during installation, please refer to Troubleshooting (nasty messages and nifty workarounds). See also Downloading new versions and Reporting bugs.

Obtaining the sources

The source code for the latest stable and development versions of Ciao is available from http://ciao-lang.org in the form of compressed packages (.tgz or .tbz2 files). Another method to get the sources is from the Git repository (available for Ciao developers).

Supported platforms

Ciao supports Unix-like operating systems (Linux, BSD, Mac OS X) and Windows for serveral 32-bit and 64-bit architectures (amd64, x86, arm).

Requirements for build and installation

A minimal build requires:

Although Ciao implements its own build system, the GNU implementation of the make Unix command is (still) used internally. If any of the installation steps stop right away with make error messages, you probably need to install gmake.

Emacs (https://www.gnu.org/software/emacs/) is highly recommended: the Ciao distribution includes a very powerful application development environment which is based on emacs and which enables, e.g., syntax coloring, source code formatting, embedded top-level, source-level debugging, context-sensitive on-line help, etc.

In any case, it is easy to use Ciao from a terminal and edit code with any editor of your choice. The toplevel includes some minimal editing facility when rlwrap is available (https://github.com/hanslub42/rlwrap).

Finally, documentation generation in PDF format requires TeX and ImageMagick.

Installing dependencies before build

Depending on the operating system and package management tool, you may need to install the following dependencies (using sudo or as administrator or root user):

  • Debian/Ubuntu (14.04):
    $ apt-get install build-essential
    # Required for 32 bits compatibility mode (x86)
    $ apt-get install gcc-multilib libc6-i386 libc6-dev-i386 g++-multilib
    # Required for emacs-based IDE
    $ apt-get install emacs
    # Optionally, for rlwrap
    $ apt-get install rlwrap
    # Required for generating documentation in .pdf format
    $ apt-get install texlive texinfo imagemagick
    
    (valid for both x86 and arm architectures)

  • Fedora:
    $ dnf install gcc make which kernel-headers kernel-devel emacs
    # Required for emacs-based IDE
    $ dnf install emacs
    # Required for 32 bits compatibility mode (x86)
    $ dnf install glibc-devel.i686 glibc-devel libstdc++-devel.i686
    # Optionally, for rlwrap
    $ dnf install rlwrap
    # Required for generating documentation in .pdf format
    $ dnf install texlive texinfo texinfo-tex ImageMagick
    
    (use yum instead of dnf above in older versions of Fedora)

  • Arch Linux:
    # Optional, upgrade if needed
    $ pacman -Syu
    # Dependencies for build and development environment
    # (base-devel: includes gcc, make, which)
    $ pacman -S base-devel linux-headers
    # Required for 32 bits compatibility mode
    # NOTE: Remember to enable multilib (https://wiki.archlinux.org/index.php/Multilib)
    $ pacman -S lib32-glibc lib32-libstdc++5
    # Required for emacs-based IDE
    $ pacman -S emacs
    # Optionally, for rlwrap
    $ pacman -S rlwrap
    # Required for generating documentation in .pdf format
    $ pacman -S texlive-core texinfo imagemagick
    

  • Mac OS X:
    • Install command line tools for Xcode (from the App store)
    • Install emacs and ImageMagick (and texinfo if needed, but recent versions of Mac OS X include it). A software management tool like homebrew or macports is recommended, e.g. (as root/sudo):
      $ brew install emacs-mac imagemagick
      
    • Install TexLive. If using homebrew we recommend installing the MacTeX distribution, available from: https://www.tug.org/mactex.
    • Optionally, for rlwrap:
      $ brew install rlwrap
      

  • FreeBSD:
    • Install GCC or clang and the following packages:
    $ pkg install gmake
    # Required for emacs-based IDE
    # (without X11)
    $ pkg install emacs-nox ImageMagick-nox expat 
    # (with X11)
    $ pkg install emacs ImageMagick expat
    # Optionally, for rlwrap
    $ pkg install rlwrap
    # Required for generating documentation in .pdf format
    $ pkg install texinfo texlive-full
    

  • NetBSD:
    • Install GCC or clang and the following packages:
    $ pkgin install gmake
    # Required for emacs-based IDE
    $ pkgin install emacs ImageMagick expat
    # Optionally, for rlwrap
    $ pkgin install rlwrap
    # Required for generating documentation in .pdf format
    $ pkgin install tex-texinfo texlive-collection-latex
    

Additional dependencies:

Official relases for the latest emacs versions can be downloaded from https://www.gnu.org/software/emacs/#Obtaining (See the gnu/emacs and gnu/windows/emacs directories in FTP mirrors). You can find answers to frequently asked questions (FAQ) about emacs in general at http://www.gnu.org/software/emacs/manual/efaq.html and about the Windows version at http://www.gnu.org/software/emacs/manual/efaq-w32.html.

Some advanced libraries and components, like the cost analysis, require an additional set of software packages:

# Debian/Ubuntu:
$ apt-get install libgsl0-dev libgsl0ldbl ant ant-optional \
    sun-java6-jdk g++
$ update-java-alternatives --set java-6-sun

# Fedora:
$ yum install gsl gsl-devel ant gcc-c++

To install the Java JDK on Fedora, please visit Sun Java website (http://java.sun.com/javase/downloads/index.jsp) and follow the installation instructions there.

Quick installation from source

Installation of Ciao from source is driven by the ciao-boot.sh script (ciao-boot.bat in Windows), which bootstraps and invokes the Ciao build system.

Note: It is recommended that you read the full installation instructions. However, in most cases following this summary suffices:

  1. Type ./ciao-boot.sh configure. This command will attempt to detect the configuration options for your system automatically and select reasonable defaults.

    Options can be configured interactively using ./ciao-boot.sh configure --interactive or passed explicitly as arguments from the command-line (see ./ciao-boot.sh help for more information). In particular, make sure the location of the emacs executable is set correctly.

  2. Type ./ciao-boot.sh build. This will build executables, compile libraries, and generate the documentation.

  3. Type ./ciao-boot.sh install. This will install everything in the specified directories.

Alternatively, ciao-boot.sh provides shorthands to perform configure, build, and install in a single command:

  1. Type ./ciao-boot.sh local-install. This will do a user-local installation (that will be accessible just for your user).

  2. Type ./ciao-boot.sh global-install. This will do a system-wide installation (e.g., as administrator or root user).

The system will include appropriate code at the end of your startup scripts. This will make the documentation and executables accessible, make sure the correct mode is set when opening Ciao source files in emacs, etc.

If you need more advanced control of the configuration please read the following sections.

Full installation instructions

  1. Select installation options: From the directory where the sources are stored, run:

    ./ciao-boot.sh configure
    

    It will perform a default configuration, where the system will be configured to be installed as the system administrator (root) in a standard directory available for all users in the machine (e.g., /usr/local). For 32-bit builds in 64-bit architectures use the --core:m32=yes configuration flag.

    The option --instype=local will prepare Ciao to run from the sources directly, and configured in the user's home directory (recommended for Ciao developers or users without admin rights).

    In case you want to install elsewhere, or change any of the installation options, you can use a customized configuration procedure (see ./ciao-boot.sh help for more information). The meaning of some important options is as follows:

    • ciao:install_prefix: prefix for the default values of installation directories (<prefix>/bin, <prefix>/lib, etc).

    • ciao:install_bindir: directory where the Ciao commands will be installed. For example, if ciao:install_bindir is set to /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.

    • ciao:install_libdir: directory where the run-time libraries will be installed.

    • The Ciao installation procedure will create a new subdirectory ciao below ciao:install_libdir, denoted here as INSTALL_STOREDIR. A subdirectory will be created below INSTALL_STOREDIR for each Ciao component and version installed. For example, if ciao:install_libdir is /usr/local/lib and you have LPdoc version x.y, then the libraries will be installed under /usr/local/lib/ciao/lpdoc-x.y. This allows you to install site-specific programs under INSTALL_STOREDIR and they will not be overwritten if a new version of Ciao is installed. It also again allows having several Ciao versions installed simultaneously.

    • lpdoc:docdir: directory where the manuals will be installed. In server installations, it is often convenient if this directory is accessible via WWW (like /var/www/ciao).

  2. Build Ciao: At the ciao top level directory type ./ciao-boot.sh build.

  3. Install Ciao: To install Ciao in the directories selected in the configuration script during step 2 above, type ./ciao-boot.sh install. This will:

    • Install the executables of the Ciao program development tools (i.e., the general driver/top-level ciao, the standalone compiler ciaoc, the script interpreter ciao-shell, miscellaneous utilities, etc.) in the selected binary directory. In order to use these tools, make sure that the PATH environment variable contains such path.

    • Install the Ciao libraries under INSTALL_STOREDIR (these will be automatically found).

    • Install under lpdoc:docdir 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 specified at lpdoc:docdir.

    • Install under INSTALL_STOREDIR 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 ciao-mode-init containing the emacs initialization commands which are needed in order to use the Ciao emacs interface.

  4. Set up user environments: The installation process leaves the files INSTALL_STOREDIR/DOTcshrc (for csh-like shells), INSTALL_STOREDIR/DOTprofile (for sh-like shells), and INSTALL_STOREDIR/ciao-mode-init (for emacs) with appropriate definitions which will take care of all needed environment variable definitions and emacs mode setup. If you has indicated in the configuration that the startup files must be modified, then the install process will do it for you, otherwise you can modify by hand these files making the following modifications in your startup scripts, so that these files are used (<libroot> must be replaced with the appropriate value):

    • For users a csh-compatible shell (csh, tcsh, ...), add to ~/.cshrc:

              if ( -e <libroot>/ciao/DOTcshrc ) then
                 source <libroot>/ciao/DOTcshrc
              endif
      

      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 file has been loaded. We believe 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

    • For users of an sh-compatible shell (sh, bash, ...), the installer will add to ~/.bashrc the next lines:

              if [ -f <libroot>/ciao/DOTprofile ]; then
                 . <libroot>/ciao/DOTprofile
              fi
      

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

    • Also, if you use emacs (highly recommended) the install will add the next line to your ~/.emacs file:

              (load-file "<libroot>/ciao/ciao-site-file.el")
              (if (file-exists-p "<libroot>/ciao/ciao-site-file.el")
                (load-file "<libroot>/ciao/ciao-site-file.el")
              )
      

    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 /etc/bashrc, /etc/csh.login, /etc/csh.cshrc, /etc/skel, /usr/share/emacs/.../lisp/site-init.pl, etc.).

  5. Check installation / read documentation: You may now want to check your installation (see Checking for correct installation on Unix) and read the documentation, which is stored in the directory specified at lpdoc:docdir and can be easily accessed as explained that same section. There are special “getting started” sections at the beginning of the manual.

If you have any problems you may want to check Troubleshooting (nasty messages and nifty workarounds).

The system can be uninstalled by typing ./ciao-boot.sh uninstall in the top directory. Configuration should have not changed since installation, so that the same directories are cleaned (i.e. the variables in SETTINGS should have the same value as when the install was performed).

Checking for correct installation on Unix

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

  • Typing ciao (or ciaosh) should start the typical Prolog-style top-level shell.

  • In the top-level shell, Ciao library modules should load correctly. Type for example use_module(library(dec10_io)) --you should get back a prompt with no errors reported.

  • To exit the top level shell, type halt. as usual, or ^D.

  • Typing ciaoc should produce the help message from the Ciao standalone compiler.

  • Typing 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 Ciao, i.e., files which do not need any explicit compilation to be run.

Also, the following documentation-related actions should work:

  • If the 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).

  • Opening with a WWW browser the directory or URL corresponding to the lpdoc:docdir setting should show a series of Ciao-related manuals.

  • Typing man ciao should produce a man page with some very basic general information on Ciao (and pointing to the on-line manuals).

  • The lpdoc:docdir directory should contain the manual also in the other formats such as pdf.

Finally, if emacs is installed, after starting it (typing emacs) the following should work:

  • Typing ^H i (or in the menus Help->Manuals->Browse Manuals with Info) should open a list of manuals in info format in which the Ciao manual(s) should appear.

  • When opening a Ciao file, i.e., a file with .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.

  • Loading the file using the 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).

Cleaning up the source directory

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

  • ./ciao-boot.sh uninstall removes the installation but does not touch the source directories.

  • ./ciao-boot.sh realclean 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.

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 Multiarchitecture installation 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.

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

Multiarchitecture installation

In order to perform a multi-architecture installation, it is possible to repeat successively the build and installation process for several architectures from different machines sharing part of their filesystem.

The Ciao build and installation process maintains separate name spaces for platform- and architecture-dependant binaries (like the engine binary, or .so or .dll gluecode files for the foreign interface). Portable Ciao applications (i.e., except self-contained standalone executables) can run on several machines with different architectures without any need for recompiling, provided the Ciao engine and libraries are correctly installed.

Installation and compilation under Windows

There are two possibilities in order to install Ciao on Windows machines:

  • Installing from the Windows precompiled distribution. This is the easiest since it requires no compilation and is highly recommended. This is described in Installing Ciao from a Win32 binary distribution.

  • Installing the standard Ciao (Unix) 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.

In order to compile Ciao 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.

  • Thus, the first step, if Cygnus Win32 is not installed in your system, is to download it (from, e.g., http://www.cygnus.com/misc/gnu-win32) and install it. The compilation process also requires that the executables 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).

  • Assuming all of the above is installed, type ./ciao-boot.sh allwin32. This will compile both the engine and the Ciao libraries. In this process, system libraries that are normally linked dynamically under Unix (i.e., those for which .so dynamically loadable files are generated) are linked statically into the engine (this is done instead of generating .dlls 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:

  • Follow now the instructions in Installing Ciao from a Win32 binary distribution.

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

Troubleshooting (nasty messages and nifty workarounds)

The following a list of common installation problems:

  • Problem: Compilation errors appear when trying a new installation/compilation after the previous one was aborted (e.g., because of errors) or after a source upgrade from the development version.

    Possible reason and solution: It is a good idea to clean up any leftovers from the previous compilation. It the worst case, if none of the clean commands work, try ./ciao-boot.sh emergency-clean.

  • Problem: In Windows (under Cygwin or MSYS2), many programs (including emacs and ciao) exit with error messages like:

    Doing vfork: resource temporarily unavailable

    Possible reason and solution:

    Cygwin needs a special memory layout to implement the fork semantics in Win32 (http://cygwin.com/ml/cygwin/2009-05/msg00413.html). A workaround this problem is using the rebaseall command, which relocates all Cygwin DLLs into a layout that avoids collisions:

    • 1. End all cygwin processes.
    • 2. Run /bin/rebaseall from c:\cygwin\bin\ash (probably as administrator)