Installing Ciao

Requirements and dependencies

Ciao supports many operating systems, including:

• Linux distributions
• macOS
• Windows (with WSL)
• Android (with Termux).

Installing Emacs or Ciao support for VSCode is highly recommended: the Ciao distribution includes a very powerful application development environment which enables, e.g., syntax coloring, source code formatting, embedded top-level, source-level debugging, context-sensitive on-line help, generating documentation, etc., etc.

In any case, it is easy to use Ciao from a terminal and edit code with any editor of your choice. The top level includes some minimal editing facilities when rlwrap is available.

Upgrading or uninstalling components

Bundles installed via ciao get must be uninstalled and removed explicitly. Currently, this needs to be done manually per bundle. Upgrading a bundle requires uninstallation followed by (re)installation.

E.g., uninstalling the development environment (if installed) requires:

ciao uninstall ciao_emacs; ciao rm ciao_emacs; ciao rm devenv

Upgrading or uninstalling Ciao

For full cleanup, first remove all installed bundles (see above).

Once all bundles have been removed, the core Ciao system can be uninstalled running ./ciao-boot.sh uninstall from the source directory; then, remove the directory.

If installed using curl, the system is installed in a per-version subdirectory under ~/.ciaoroot, i.e., ~/.ciaoroot/<ciao_version>. The development version is installed at ~/.ciaoroot/master. Proper uninstallation requires first executing ./ciao-boot.sh uninstall inside that directory and then removing the whole ~/.ciaoroot/<ciao_version> directory.

This can be automated with a script such as (e.g., for master):

( cd ~/.ciaoroot/master; ./ciao-boot.sh uninstall )
rm -rf ~/.ciaoroot/master
rmdir ~/.ciaoroot > /dev/null 2>&1 || true

Network-based installation options

The network installer is delivered as an HTTPs redirection to https://raw.githubusercontent.com/ciao-lang/ciao/master/ciao-boot.sh (which contains the latest version of the ciao-boot.sh script). The bootstrap script recognizes that it is being called without sources automatically. Ciao can be installed from the network using a curl pipe from https://ciao-lang.org/boot to sh in a terminal. This is probably the fastest/easiest way to install Ciao in binary or source form.

Examples:

# Interactive
curl https://ciao-lang.org/boot -sSfL | sh
# Minimal local installation with prebuilt binaries
curl https://ciao-lang.org/boot -sSfL | sh -s -- --prebuilt-bin local-install
# Full environment
curl https://ciao-lang.org/boot -sSfL | sh -s -- get devenv
# Show network installer help
curl https://ciao-lang.org/boot -sSfL | sh -s -- --help

Manual installation from source

You can get the source code for the latest stable and development versions of Ciao by cloning the Ciao repository:

git clone https://github.com/ciao-lang/ciao

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.

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 Customize your installation and ./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 fetch devenv (for the full development environment, optional). This will fetch the source of other components required for the development environment. This step is not needed when compiling Ciao from the monorepository.
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).
3. Type ./ciao-boot.sh get devenv to fetch, configure, and install the full environment (devenv bundle).

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.

Customize your installation

You can configure and customize your Ciao installation with the command:

./ciao-boot.sh configure

By default, it will perform a default configuration, where the system will be configured to run from the sources directly, and configured in the user's home directory (recommended for Ciao developers or users without admin rights).

The option --instype=global will prepare Ciao 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.

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:

• --prefix: prefix for the default values of installation directories (<prefix>/bin, <prefix>/lib, etc).
• --bindir: directory where the Ciao commands will be installed. For example, if --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.
• The Ciao installation procedure will create a new subdirectory ciao/<vers> denoted INSTALL_CIAOROOT below --prefix. The <vers> directory indicate the Ciao system version. It allows having several Ciao versions installed simultaneously.
• --mandir: directory where the manuals in man format will be installed.
• --infodir: directory where the manuals in info format will be installed.

Once configured, the ./ciao-boot.sh build command and ./ciao-boot.sh install command will build and install Ciao, respectively, using the selected configuration options. 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_CIAOROOT (these will be automatically found).
• Install the Ciao manuals in several formats (such as GNU info, html, pdf, etc.) under INSTALL_CIAOROOT and other documentation-specific paths. 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 --mandir and --infodir. Documentation in other formats can be accesed with the ciao doc command.
• Install under INSTALL_CIAOROOT the Ciao interface with GNU emacs (which provides an interactive interface to the Ciao program development tools, as well as some other auxiliary files).

Finally, the installation will modify the user startup files automatically by default to set up user environments. If you disable this option in the configuration or you wish to switch between different installations, it would be necessary to modify the startup files manually.

The installation process generates a ciao-env command to update the environments for sh-like and cshlike shells. It also generates a INSTALL_CIAOROOT/ciao-mode-init (for emacs) with appropriate definitions which will take care of all needed environment variable definitions and emacs mode setup.

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

  if ( -x <prefix>/bin/ciao-env ) then
     eval `<prefix>/bin/ciao-env --csh`
  endif

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

  if [ -x <prefix>/bin/ciao-env ]; then
     eval "$(<prefix>/bin/ciao-env --sh)"
  fi

• For users of an zsh shell, the same lines will be added to ~/.zshrc.

  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 "INSTALL_CIAOROOT/ciao-site-file.el")
  (if (file-exists-p "INSTALL_CIAOROOT/ciao-site-file.el")
    (load-file "INSTALL_CIAOROOT/ciao-site-file.el")
  )

If you are installing Ciao globally in a multi-user machine, make sure that you instruct all users that 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.).

Checking for correct installation

If you have any problems you may want to check Troubleshooting. Otherwise, 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).

• Typing ciao doc alldocs should open a series of Ciao-related manuals in a WWW browser.

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

• The documentation 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).

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 variable CIAOROOT, which tell the Ciao executables where to look for engines and system libraries.

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.