1. Format of the egg description file
    1. Global properties
      1. version
      2. synopsis
      3. author
      4. maintainer
      5. category
      6. license
      7. dependencies
      8. test-dependencies
      9. build-dependencies
      10. foreign-dependencies
      11. platform
        1. distribution-files
      12. components
      13. host
      14. target
      15. component-options
    2. Components
      1. extension
      2. data
      3. generated-source-file
      4. c-include
      5. scheme-include
      6. program
    3. Component properties
      1. host
      2. target
      3. linkage
      4. types-file
      5. inline-file
      6. custom-build
      7. csc-options
      8. link-options
      9. source
      10. install-name
      11. component-dependencies
      12. source-dependencies
      13. destination
      14. files
      15. modules

Format of the egg description file

An egg description is basically an association list holding information about the components of the egg. An egg may contain multiple components: libraries, programs, Scheme or C include files and arbitrary data files. Dependencies between eggs can be specified as can be dependencies between components of an egg.

A list of valid properties follows.

Global properties

version

[egg property] (version STRING)

Specifies version string for this egg. STRING should have the format <MAJOR>.<MINOR>.<PATCHLEVEL>, where only the <MAJOR> part is mandatory.

Eggs from remote egg servers are automatically versioned - the version is part of the protocol to retrieve the egg and does not have to be specified in the .egg file. Eggs installed from local directories (see below) should explicitly specify a version.

synopsis

[egg property] (synopsis STRING)

Gives a short description of this egg.

author

[egg property] (author STRING)

Names the author or authors of the contained code.

maintainer

[egg property] (maintainer STRING)

Names the maintainer of this code, if different from author(s).

category

[egg property] (category NAME)

Gives the category under which this egg should be contained. See the egg index for a list of currently used categories.

license

[egg property] (license STRING)

Names the license under which this code is available.

dependencies

[egg property] (dependencies EGG ...)

Lists eggs that this egg depends on, and which should be built and installed if they do not already exist in the repository. EGG should be whether a symbol or a list of the form EGGNAME VERSION, where the former means to install the newest available egg with this name and the latter specifies a specific version or higher.

test-dependencies

[egg property] (test-dependencies EGG ...)

Lists eggs that are required for this egg to run the tests (if tests exist.) This only has an effect if the -test option has been given to chicken-install.

build-dependencies

[egg property] (build-dependencies EGG ...)

Lists eggs that are build-time dependencies for this egg, i.e. there are required to build, but not to run the contained code. Currently this is treated identical to dependencies.

foreign-dependencies

[egg property] (foreign-dependencies NAME ...)

Lists external dependencies like native code libraries or system-specific packages and is currently only used for documentation purposes.

platform

[egg property] (platform PLATFORM)

Specifies for which platform this egg is intended. PLATFORM should be a symbol naming the target platform (windows, linux or unix) or a boolean combination of platform values, allowed are (not PLATFORM), (or PLATFORM ...) and (and PLATFORM ...). If the expression can not be satisfied, then installation of this egg will abort.

distribution-files
[egg property] (distribution-files FILE ...)

List of files required for the installation of the egg. This form is not handled by chicken-install, but by henrietta-cache to determine what to cache. If the repository contains additional files that are unneeded for the egg to be installed, you can list all the required files in this clause to reduce the amount of data cached by egg servers.

components

[egg property] (components COMPONENT ...)

Lists components (extensions, programs, include- or data files) that this extension installs. See below for information on how to specify component-specific information.

host

[egg property] (host PROP ...)

Recursively process PROP ..., but only for the host (build) platform, in case this is a "cross-chicken", a CHICKEN installation intended for cross compilation.

target

[egg property] (target PROP ...)

Recursively process PROP ..., but only for the target platform, in case this is a "cross-chicken", a CHICKEN installation intended for cross compilation.

component-options

[egg property] (component-options OPTIONSPEC ...)

Specifies global options for all programs and extensions compiled for this egg. OPTIONSPEC may be csc-options or link-options specifications.

Components

extension

[egg property] (extension NAME PROP ...)

Specifies an extension library component. The properties PROP... are processed recursively and apply only to this component.

data

[egg property] (data NAME PROP ...)

Specifies one or more arbitrary data files.

generated-source-file

[egg property] (generated-source-file NAME PROP ...)

Specifies a file that is generated during the process of building the egg.

c-include

[egg property] (c-include NAME PROP ...)

Specifies one or more C include files.

scheme-include

[egg property] (scheme-include NAME PROP ...)

Specifies one or more Scheme include files.

program

[egg property] (program NAME PROP ...)

Specifies an executable program.

Component properties

host

[egg property] (host PROP ...)

Process PROP ... recursively for the current component, but apply the properties only to the host (build) part, when using a CHICKEN installation intended for cross-compilation.

target

[egg property] (target PROP ...)

Process PROP ... recursively for the current component, but apply the properties only to the target part, when using a CHICKEN installation intended for cross-compilation.

linkage

[egg property] (linkage LINKAGE)

Define whether the component should be linked dynamically or statically. LINKAGE can be static or dynamic. This property only makes sense for extension libraries.

types-file

[egg property] (types-file [NAME])

Specifies that a "type-database" file should be generated and installed for this component. This property is only used for extension libraries. The name is optional and defaults to the name of the extensions (with the proper extension).

If NAME is a list of the form (predefined [NAME]), then no types file is created during compilation and an existing types file for this extension is assumed and installed.

inline-file

[egg property] (inline-file [NAME])

Specifies that an "inline" file should be generated and installed for this component. This property is only used for extension libraries. The name is optional and defaults to the name of the extensions (with the proper extension).

custom-build

[egg property] (custom-build STRING)

Specifies a custom build operation that should be executed instead of the default build operations. This property is mandatory for components of type generated-source-file. STRING should be the name of a shell command (e.g., a script) and thus may be platform sensitive. The path to the file is prepended implicitly, so you should not prefix it with ./. On Windows, a file with the .bat extension will be picked before a plain file with no extension.

The script will be made executable on UNIX systems, if necessary, and will be invoked like the csc program and is executed with the location of the CHICKEN binaries in the PATH. Also, the following environment variables are set in the execution environment of the script:

csc-options

[egg property] (csc-options OPTION ...)

Specifies additional compiler options for csc that should be used when building this component. If this property is not given, the default options are used, which are -O2 -d1 for extensions and programs and -O2 -d0 for import libraries.

Note that the options are quoted when passed to csc during the compilation of the extension, so multiple options should be specified as (csc-options "OPT1" "OPT2" ...) instead of (csc-options "OPT1 OPT2") (the latter would be a single option containing a whitespace character).

[egg property] (link-options OPTION ...)

Specifies additional link options for csc that should be used when building this component.

Note that the options are quoted when passed to csc during the compilation of the extension, so multiple options should be specified as (link-options "OPT1" "OPT2" ...) instead of (link-options "OPT1 OPT2") (the latter would be a single option containing a whitespace character).

source

[egg property] (source NAME)

Specifies an alternative source file, in case it has a name distinct from the component name. By default the source file for a component is named after the component, with the .scm extension added.

install-name

[egg property] (install-name NAME)

Specifies an alternative installation name of the component, if it differs from the actual component name. This property is most useful if an egg installs an extension and a program of the same name, but needs to distinguish the components during build time.

component-dependencies

[egg property] (component-dependencies NAME ...)

Specifies dependencies to other components. NAME ... must be the names of extension, program, scheme-include- or generated source file components that should be built before the current component.

source-dependencies

[egg property] (source-dependencies NAME ...)

Specifies dependencies to additional source files. NAME ... must denote filenames of which the program or extension depends. A program or extension implicitly depends on its source file and and on the egg-specification file.

destination

[egg property] (destination NAME)

Specifies an alternative installation destination for the built component and only applies to components of type data, c-include and scheme-include. This property should only be used in extreme cases, as it is recommended to use the default installation locations, which are:

files

[egg property] (files NAME ...)

Specifies source files for this component and only applies to components of type data, c-include and scheme-include. Both files and directories may be given and parent directories are created as needed.

modules

[egg property] (modules NAME ...)

Specifies modules that the component (usually an extension) contains. chicken-install will compile and install all import libraries for the given modules. If this property is not given, then it is assumed that the extension has a single module of the same name as the component.


Previous: Extension tools

Next: Units and linking model