The standalone command-line builder

Introduction to the build process

This picture shows a detailed view all the elements of the build and installation process of a bundle or collection of bundles.

    Phase 0-
       Bootstrapping the build system
    Phase 1-
       SOURCE ---(configure)--> CONFIG
    Phase 2- (needs CONFIG)
       SOURCE ---(build)--> BUILD --(install)--> INSTALLED

Above, arrows specify actions and nodes are collections of files:

SOURCE

Source code

CONFIG

Configuration of the source

BUILD

Binaries, compiled libraries, and generated documentation (.pdf, .html, etc.)

INSTALLED

Copies of BUILD that exclude temporary files (mostly caches for separate and incremental compilation).

The source distribution only contains SOURCE elements. The actions build and install create the BUILD and INSTALLED elements.

NOTE: Bootstrapping is a transparent process and its details are not needed to understand and use the build system. See Bootstrapping the build system for more details on phase 0.

NOTE: Out-of-tree builds (where all the intermediate compiler output, including .po/.itf files are stored in the build/cache directory) are enabled by default for bundles. This can be disabled setting the environment variable CIAOCCACHE=0. Note that bootstrapping the system with CIAOCCACHE=0 is not recommended, as it will merge .po/.itf files of (potentially) incompatible compiler iterations.

Configuration and build

Configuration and build can be reverted with clean commands. The meaning of clean and distclean is based on their standard meaning (see the Makefile example at http://www.gnu.org/software/make/manual/html_node/Complex-Makefile.html), except for realclean that cleans both the system and the bootstrap (equivalent to distclean and boot-clean).

The following table summarizes the actions that undo each build or install operation:

    ('undo' reverts the effect of each marked 'action') 
                  ,--------+-----------+-----------.
   actions \ undo | clean  | distclean | realclean |
 .----------------+--------+-----------+-----------+
 | boot-build     |        |           |    x      |
 +----------------+--------+-----------+-----------+
 | configure      |        |     x     |    x      |
 +----------------+--------+-----------+-----------+
 | build          |   x    |     x     |    x      |
 `----------------+--------+-----------+-----------+

Installation

Different installation areas are supported. For personal installations, the installation area can overlap with the build staging area, such that no extra space is necessary.

      .............         install             ...........
      .           .---------------------------->.         .
      .           .        (generated           .         .
      .............         files such          ...........
       Build Staging Area       as binaries)      Installation Area
           .^.                                 _
            | build                            /|
            |                                 /
      .............          install         /
      .           .-------------------------'
      .           .         (source files
      .............          such as examples,
       Source Code           images, etc.)

The install command is undone with the uninstall command.

Bootstrapping the build system

The ciao-boot.sh (or ciao-boot.bat in Windows) command automatically bootstraps and invokes the Ciao build system. The process is described below.

Bootstrapping is the process that compiles the Ciao compiler and builder in an environment where no existing Ciao binary exists. We follow the same phase 1 and phase 2 steps above but the whole process is driven by a very simplified version written in (portable) shell-script code (since there is no running Ciao) and using the ciaoc bootstrap compiler.

The ciaoc bootstrap compiler comes in a pre-compiled bytecode form. This bytecode, together with the engine parts written in C, can be executed in most systems with a C compiler.

Once this bootstrap compiler is available, the system compiles the bootstrap ciao_builder, which drives the rest of the build and installation process.

This step is transparent to the user and separated in a different build directory (build-boot/). However, there are options to force the recompilation and cleaning of that part (see ciao-boot.sh help for more information).