chickadee » chicken » eggs » tools

Extension tools

The basic tools to install, uninstall and view "eggs" and the extensions are chicken-install, chicken-uninstall and chicken-status.

chicken-install can be used in two modes: first, as a simple package manager that downloads publicly available eggs (and their dependencies, if necessary) and compiles the contained extensions, installing them on a user's system.

For development of eggs, chicken-install can also be invoked without arguments, in a directory that contains an egg specification file and the associated source code, building all components and installing them.

chicken-status simply lists installed eggs, the contained extensions, and optionally the files that where installed with a particular egg.

Below you will find a description of the available command line options for all three programs. A specification of the egg description file format is here.

Security

When eggs are downloaded and installed one is executing code from potentially compromised systems. This applies also when chicken-install executes system tests for required eggs. As the code has been retrieved over the network effectively untrusted code is going to be evaluated. When chicken-install is run as root the whole system is at the mercy of the build instructions (note that this is also the case every time you install software via sudo make install, so this is not specific to the CHICKEN egg mechanism).

Security-conscious users should never run chicken-install as root. A simple remedy is to keep the repository inside a user's home directory (see the section "Changing repository location" below). Alternatively obtain write/execute access to the default location of the repository (usually /usr/local/lib/chicken) to avoid running as root. chicken-install also provides a -sudo option to perform the last installation steps as root user, but do building and other .setup script processing as normal. A third solution is to override VARDIR when building the system (for example by passing "VARDIR=/foo/bar" on the make command line, or by modifying config.make. Eggs will then be installed in $(VARDIR)/chicken/8.

Changing the repository location

When CHICKEN is installed a repository for eggs is created and initialized in a default location (usually something like /usr/local/lib/chicken/9/). It is possible to keep an egg repository in another location. This can be configured at build-time by passing VARDIR=<directory> to make(3) or by modifying the config.make configuration file. If you want to override this location after chicken is installed, you can create a repository directory, set the CHICKEN_INSTALL_REPOSITORY and/or CHICKEN_REPOSITORY_PATH environment variables to the full path of the new reopsitory and copy all files from the default repository into the new one.

Note that your binary version can differ from the one given in the examples here, if your chicken version is older or newer than the one used in these examples. Check your default location for the correct binary-version number.

CHICKEN_REPOSITORY_PATH is a directory (or a list of directories separated by :/;) where eggs are to be loaded from for all chicken-based programs. CHICKEN_INSTALL_REPOSITORY is the place where eggs will be installed and which the egg-related tools like chicken-install, chicken-uninstall and chicken-status consult and update.

Finally, CHICKEN_INSTALL_PREFIX allows you to override where any installed files should be stored, including extension libraries, programs and data files. Effectively this variable overrides the installation prefix given when building and installing chicken. When installing eggs, the location where dependency extensions and tools are installed will not be automatically found, so setting this variable usually only makes sense when used in combination with CHICKEN_REPOSITORY_PATH.

CHICKEN_INSTALL_PREFIX is intended for special situations and should be used with care. It is a last-resort utility to customize where build-results are placed.

Make sure the paths given in these environment variables are absolute and not relative.

Static linking

Static linking of extensions and programs is fully supported and should be transparent to the user. Every extension will by default be compiled into a dynamically loadable and a statically linkable entity. By passing -static on the csc command-line, eggs that are available in static form will be linked instead of the dynamically loadable version. Use the linkage egg description property to select in what modes a component should be built.

To identify the necessary object files during linking of extensions, csc creates so-called "link files" and installs them along the statically compiled object file in the local egg repository. These link files specify what objects should be linked when an application is using a static variant of an extension.

Locations

For experimentation or in-house builds of software it may be useful to have private egg repositories in addition to the official CHICKEN egg repository. This can be accomplished by defining so-called "locations", directories that contain egg source-code and description files and which should be scanned before trying to retrieve an egg via the network.

The file <PREFIX>/share/chicken/setup.defaults holds various parameters that define where eggs should be downloaded, together with more obscure options, and can be used to customize the sources where eggs will be retrieved from. Adding a line of the form

(location "<PATH>")

will add <PATH> as an additional egg source, where <PATH> should be a directory in the local filesystem that contains any number of eggs, one directory for each, including the source code and the .egg files for each egg.

Locations are searched before trying to retrieve from the network. Any number of locations may be defined.

The egg cache

Eggs are downloaded and built in the so called "egg cache", an intermediate location used for storing already downloaded source code and for providing a temporary location for building the eggs before they are installed.

By default the cache is located in the directory .chicken-install/cache in the user's home directory ($HOME on UNIX, or %USERPROFILE% on Windows. If the respective environment variable is not set, then /tmp or /Temp is used.

Built extensions and programs remain in the cache, to avoid rebuilding already compiled code and multiple downloads of eggs in case the installation of an egg fails - the dependencies will be cached after the first download and re-download is not needed.

chicken-install tries to take extreme care to avoid stale binaries, but should you be in doubt, simply delete the directory, or run chicken-install -purge to clear the cache or parts of it.

You can override the location of the cache by setting the CHICKEN_EGG_CACHE environment variable.

Egg installation in detail

Retrieval

First the egg names given on the command line (or, if no arguments are given, all eggs identified by .egg files in the current directory, including any in a subdirectory named chicken) must be retrieved, either from a local source or from the official egg repository. Should the egg exist in the egg cache we check whether this cached version is out of date. A cached egg is considered out of date, if a) it is locally available and all cached files belonging to the egg do not have newer timestamps than the local files, or b) if it is a remotely retrieved egg and no newer versions exist on the remote egg server and the last time the cache was filled from the remote location is not later than one hour. Additionally, if any changes in certain environment variables that may influence the compilation of an egg, or if the CHICKEN version changed, then retrieval of the egg sources is enforced in any case.

If the egg is in the current directory, or in a "location" (as described above), the files are copied into the cache. If the egg is remotely available, then it is retrieved via HTTP from one of the egg servers defined in setup.defaults.

Once the egg sources are retrieved and stored in the cache, their .egg files are loaded and validated. After this any egg dependencies are resolved and located in the cache, triggering a recursive retrieval, if necessary.

Preparation

Unless the -retrieve option was given, the eggs intended to be built and installed are now scheduled for compilation. The egg information from the .egg files is processed and translated into build and install scripts for the current platform - if this CHICKEN was configured for cross compilation, and no separate host- or target-build was selected, two sets of build/install scripts will be generated, one for the host system and one for the target.

Building and installation

Unless -dry-run was given on the command-line, the build- and install scripts are now executed, ordered by the dependency relationships between the full set of eggs that are scheduled for compilation. If the -test option was given and a file named run.scm exists in the tests subdirectory of the egg sources, then this script is executed. Should it terminate with an error or a non-zero exit code, the installation is still performed and chicken-install does not abort. Only after all scheduled eggs have been installed, chicken-install will terminate with a non-zero exit code.

Note that the build process attempts to minimize re-building of already compiled files in the cache, using the chicken-do program. See the manual page for chicken-do for more details.

From the egg-information in the .egg file, the set of files installed for a particular egg are added to the egg-information and stored together with the build-artifacts produced by the build scripts.

chicken-install reference

Available options:

-h -help
show this message and exit
-version
show version and exit
-force
don't ask, install even if versions don't match
-k -keep
keep temporary files
-s -sudo
use external command to elevate privileges when installing or removing files
-no-install-dependencies
do not install dependencies
-r -retrieve
only retrieve egg into cache directory, don't install (giving -r more than once implies -recursive)
-recursive
if -retrieve is given, retrieve also dependencies
-dry-run
do not build or install, just print the locations of the generated build + install scripts
-list-versions
list available version for an extension (HTTP transport only)
-n -no-install
do not install, only build the egg.
-purge
remove cached files for given eggs (or purge cache completely)
-cached
install from cache, do not download
-host
when cross-compiling, compile egg for host only
-target
when cross-compiling, compile egg for target only
-test
run included test-cases, if available
-u -update-db
update export database
-repository
print path to egg repository
-override FILENAME
override versions for installed eggs with information given in FILENAME, which can be generated by -scan or by the -list option of the chicken-status program
-from-list FILENAME
install eggs given in FILENAME, in the same format as produced by the -list option in chicken-status; this option may be given multiple times
-v -verbose
be verbose
-D -feature NAME
defines a build feature, that can be tested using cond-expand in egg specifications
-defaults FILENAME
use FILENAME as defaults instead of the installed setup.defaults file

chicken-install recognizes the SUDO, http_proxy and proxy_auth environment variables, if set.

When running chicken-install with an argument NAME, for which no associated .egg file exists, then it will try to download the extension via HTTP from the CHICKEN code repository at http://code.call-cc.org/svn/chicken-eggs/. Extensions that are required to compile and/or use the requested extension are downloaded and installed automatically.

chicken-uninstall reference

-h -help
show usage information and exit
-version
show version and exit
-force
don't ask, delete whatever matches
-match
treat egg-names as glob patterns
-s -sudo
use external command to elevate privileges for deleting files
-host
when cross-compiling, remove eggs for host system only
-target
when cross-compiling, remove eggs for target system only

chicken-status reference

-h -help
show usage information and exit
-version
show version and exit
-f -files
list installed files
-match
treat egg-names as glob patterns
-host
when cross-compiling, show eggs for host system only
-target
when cross-compiling, show eggs for target system only
-list
list installed egg version in format suitable for chicken-install -override or -from-list
-c -components
list installed components
-cached
list eggs available in the cache directory

Previous: Extensions

Next: Egg specification format