Bundles and workspaces

Author(s): Jose F. Morales, The Ciao Development Team.

In the same way that modules can be seen as collections of predicates, Ciao bundles define collections of modules. The visibility of bundles is determined by workspaces. A workspace is a directory that may contain bundles, each of them in a separate directory with the same name declared on its manifest. See Bundle management for details about creating and managing bundles.

Bundles

Bundles are usually organized as follows:

Manifest/        Metadata
cmds/            Modules implementing main/{0,1} (for CLI tools)
{src,lib,...}/   Source code (modules, packages, included files, etc.)

Bundles include some metadata describing versions, dependencies, (relative) path aliases, entry points for manuals and commands, additional pre-build, build, and installation rules, etc. This metadata is separated from the actual code into a single Manifest.pl file at the root of the bundle, or inside the Manifest/ directory. A typical Manifest.pl file has the following form:

:- bundle(<Name>).
version(<Version>).
depends([Dep1, ..., DepN]).
alias_paths([
    <Alias1> = <RelPath1>,
    ...
    <AliasN> = <RelPathN>
]).
lib(<RelPath>).
cmd(<CmdName>, [main=<RelPathMainMod>, ...]).
manual(<ManName>, [main=<RelPathDocCfg>, ...]).

where:

version/1 specifies the bundle version.
depends/1 declares dependencies with other bundles.
alias_paths/1 declares path aliases.
(multiple) lib/1 declares directories containing compilable modules.
(multiple) cmd/2 declares entry points for commands (executables).
(multiple) manual/2 declares entry points for manuals.

Versioning: Versions are specified as atoms (see version_strings) of the form 'X.Y.Z', where X, Y, and Z are non-negative integers, and an optional -Prerelease suffix. Omitted version numbers are assumed to be 0. Dependencies may include version constraints, e.g., core-[version>='1.15'] (see version_compare/3 for the definition of the comparison).

Currently the system supports only one version of a bundle at the same time. If two versions need to coexist at the same time, the bundles must be renamed (e.g. bndv1, bndv2).

Additional build rules: Although the Ciao compiler is incremental and performs the compilation on demand, some components may require configuration steps and pre-building. For example, this is often the case for bindings to foreign third-party libraries. Currently these rules must be written in a lower-level module Manifest/<bundle>.hooks.pl.

Workspaces

A workspace directory looks like:

build/           (Generated automatically)
<bundle1>/
...
<bundleN>/

Each workspace directory contains a build/ directory with intermediate and final results of compilation (build/bin/) and documentation generation (build/doc/).

Bundle catalogs: workspaces may contain directories holding bundles. Such directories must be marked with an empty BUNDLE_CATALOG file. In that case, bundles are visible only if they are marked with an empty ACTIVE file. This mecanism is useful to implement catalogs of bundles.