Egg specification format

[[tags: manual]]
[[toc:]]


== 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 [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|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}}, {{link-options}} or {{linkage}} specifications.

==== cond-expand

 [egg property] (cond-expand CLAUSE ...)

Conditionally expand egg specification forms, depending on system 
features. Each {{CLAUSE}} should be of the form 
{{(TEST PROPERTY)}} where {{TEST}} is a feature identifier or a 
conditional form, in the same syntax as used in the {{cond-expand}}
syntactic form.

In addition to normal system-wide feature identifiers, feature identifiers
given via the {{-feature}} option to {{chicken-install}} are visible in
the tests. Also, the features {{target}}, {{host}}, {{dynamic}} and
{{static}} are visible, depending on surrounding egg specification
forms for constraining mode and linkage.

==== error

 [egg property] (error STRING ARG ...)

Signal an error and abort processing. Mostly useful inside {{cond-expand}} forms.

=== 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.

==== c-object

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

Specifies a compiled C/C++ object file. Usually this component type
is required if you want to link a separately compiled C/C++ module
with your extension or program. C-objects are compiled like Scheme
source files with the {{csc}} tool to ensure the same C compiler
options and toolchain is used as for regular Scheme files compiled
to C. If you want to pass compiler-specific options to the build
of the C object, use the {{csc-options}} property and precede
C compiler options with {{-C}}.


=== 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:

* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN
* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN
* {{CHICKEN_CSC}}: path to {{csc}}
* {{CHICKEN_CSI}}: path to {{csi}}


==== 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).

==== link-options

 [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).

Note that in order to pass linker options to the underlying C-compiler, these must
be prefixed with {{-L}}, eg. {{(link-options "-L" "-lpng")}}.

==== 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.

==== objects

 [egg property] (objects NAME ...)

Specifies that the components of type {{c-object}} should be linked
to this component and that the object components are dependencies.


==== 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}}. {{NAME}} must be a relative path and is
considered relative to CHICKEN's installation prefix.

This property should only be used in extreme cases, as it is recommended
to use the default installation locations, which are:

* for C include files: {{<PREFIX>/include/chicken/}}

* for Scheme include files: {{<PREFIX>/share/chicken/}}

* for data files: {{<PREFIX>/share/chicken/}}

==== 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.

==== cond-expand

 [egg property] (cond-expand CLAUSE ...)

Similar to the toplevel {{cond-expand}} clause and may appear inside
component specifications.

==== error

 [egg property] (error STRING ARG ...)

Similar to the toplevel {{error}} form, may appear inside component specifications.

---

Previous: [[Extension tools]]

Next: [[Units and linking model]]