Bundle management

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

The ciao command implements most bundle management operations. The most important commands are:

$ ciao list              # List bundles in current workspaces
$ ciao build [<tgts>]    # Build
$ ciao build -r [<tgts>] # Build, including dependencies
$ ciao fetch [<tgts>]    # Fetch all dependencies of a bundle
$ ciao get [<tgts>]      # Fetch, build, and install a bundle
$ ciao rm [<tgts>]       # Remove a bundle

Most commands accept one ore more targets (workspace paths, bundle directories, bundle names, or bundle aliases for location on the network). For example, valid targets are:

(empty) (in which case Ciao locates the bundle above the current directory)
bundle names (e.g., chat80)
paths to bundles (e.g., ~/ciao/chat80)
URL-like aliases to bundles (e.g., github.com/jfmc/chat80, where chat80 is the bundle name)

Execute ciao help to obtain a detailed list of commands.

Setting up workspaces

Ciao locates bundles by looking at one or more workspaces, given by the following (optional) environment variables:

CIAOPATH: colon-separated list of paths to individual workspaces
CIAOROOT: the root directory of this Ciao installation (either in binary or source form)

Workspaces from CIAOPATH are consulted from left to right. If CIAOPATH is undefined, a default value of ~/.ciao will be used. The first encountered workspace directory is denoted as the top workspace. The variable CIAOROOT is usually not needed, except when the binaries is being relocated on the filesystem.

Note: CIAOPATH should not point to CIAOROOT (it is not needed and it may produce inconsistent builds).

As mentioned in Installing Ciao, setting up the environment uses the ciao-env tool, which updates the PATH and other environment variables to make commands and documentation (man, info) accessible by default.

Configuring workspaces: The directory ~/ciao can be added permanently as a workspace as follows. Include the following at the ~/.emacs file:

(setenv "CIAOPATH" (expand-file-name "~/ciao"))

Then add these lines to the ~/.bashrc file:

export CIAOPATH=~/ciao

It is possible to change CIAOPATH temporarily from emacs (M-x setenv) or a shell in a terminal (executing export CIAOPATH=<path>)

Using and creating bundles

Creating new bundles: For creating new bundles it is recommended to define a workspace directory (e.g., ~/ciao) and set the CIAOPATH environment variable to that directory.

Bundles can be created from scratch or cloned from repositories, e.g.:

$ cd ~/ciao
$ git clone https://github.com/jfmc/chat80

At that point bundles can be managed with the ciao command. The ciao list should display chat80 as a recognized bundle, and it should be possible to configure, build, or install it (e.g., ciao build at chat80 directory or ciao build chat80 anywhere). Most commands will rescan the bundles at the workspace, but it can be done manually with:

$ ciao rescan-bundles

Note that existing toplevels may need to be restarted to recognize modules at the new bundles.

Network installation: It is possible to download, configure, build, and install automatically bundles from the network. For example:

ciao get github.com/jfmc/chat80

will fetch and install chat80 under the top workspace (~/.ciao if CIAOPATH is unset) (see bundle_fetch). The bundle name will be chat80, while the rest of the bundle alias is used to locate the location on the network. The command:

ciao rm chat80

removes the bundle (to prevent accidental data losses, only iff it has been marked as downloaded).

Workspaces during Ciao bootstrap

In the context of calls to <srcdir>/ciao-boot.sh, CIAOROOT is implicitly set to the directory where ciao-boot.sh is located (<srcdir>) and CIAOPATH is unset. Thus only bundles at <srcdir> (including bundle catalog directories) are considered.

This is useful to:

prevent existing CIAOPATH values interact with system builds
fetch bundles during system build (e.g., the devenv bundle)

Example: the following command will bootstrap Ciao from source, as well as fetch and install the full development environment:

./ciao-boot.sh get devenv

Generating binary distributions

The ciaoc_sdyn command can be used to generate binary distributions of executables with complex dependencies, including any 3rd-party dynamic libraries.

Example:

mkdir dist; cd dist
ciaoc_sdyn ../src/YOURMAINEXEC
cp ../src/SOMEASSET

This creates a platform specific binary YOURMAINEXEC at dist/ directory, together with the collection of shared libraries for the dependencies.

Copying .so or .dynlib that corresponds to system libraries are not a good idea. To fix the issue the following command can be used:

rm -f libc.so.* libgcc_s.so.* libm.so.* libstdc++.so.*

Adding assets to binary distributions

The bundle_path/3 predicate (at bundle/bundle_paths) can be used to obtain the absolute path name of a bundle or a relative path in a bundle.

Example:

:- use_module(library(system), [file_exists/1]).
:- use_module(library(pathnames), [path_concat/3]).
:- use_module(library(bundle/bundle_paths), [bundle_path/3]).

% Find file X in the same directory as the executable
% or in the sources.
find_asset(Name, Path) :-
    ( current_executable(ExecPath),
      path_split(ExecPath, Dir, _)
    ; bundle_path(<SomeBundle>, 'images', Dir)
    ),
    path_concat(Dir, Name, Path0),
    file_exists(Path0),
    !,
    Path = Path0.

The example predicate find_assert/2 above will look for arbitrary files in either the images/ directory or the directory of the current executable.

find_asset('spaceship.png', Sprite)

Troubleshooting

Q: Changing the (workspace) directory of a bundle.

A: It would be enough to rescan bundles and configure (clean and build is recommended too). Go to the workspace and type the following:

ciao rescan-bundles
ciao configure [<configuration-options>]

Q: Compilation of some module complains about missing dependencies (to seemingly auto-generated code and third-party libraries).

A: Make sure that the bundle and its dependencies are properly configured and build (e.g., calling ciao build for each of them or with ciao build -r). Some bundles (e.g., interfaces to external solvers) require pre-build steps to download and compile third-party code. This part of the compilation is not currently handled by the Ciao compiler.

Q: Alias paths configured at .ciaorc are not visible in executables.

A: The .ciaorc file is read only by the Ciao toplevel (not arbitrary Ciao executables). Configure alias paths through manifest files instead.