Each level in the hierarchy will need to provide a file named config.
Additionally, 3 special config files are considered to be above the top level of the hierarchy, intended for specification of some fields that are related to the local setup. These files are /etc/host-pkg.conf just above the top-level, .host-pkg.conf in the user home directory, and host-pkg.conf in the same directory as packager.pl in the host-package cvs module, the latter providing default values for these fields. These fields are, for example, those that refer to special locations in the file-system. As they are standard fields, this is not a way to override anything from the hierarchy: they are only seen if they are not defined at all in the hierarchy.
The syntax of these files is derived from Debian control-files, derived themselves from RFC-822 headers:
a config file is a list of key: value definitions
empty lines are ignored
lines with a leading # are ignored as comments
All fields (except from the Parents field, and its deprecated predecessors Parent and ParentTag, which define the hierarchy) are inherited from the parent configuration. Some fields (like Parents) are used by the tool itself, others are defined there for substitution in the templates files.
A valid configuration on which the tool is finally run must contain a number of fields. They may be inherited, but most of those are usually defined at the lowest level.
Mandatory fields:
the name of the host package to build. It should follow the rules dictated by the underlying OS for such names.
CVS tag for the packager module. This is required for reproducibility of a config, as subsequent releases of this script are not guaranteed to produce the same results from the same sources, or even to accept the same sources.
a shell command-line that will be run after merging all templates/ directories into a single target/ directory, and which is expected to produce one or more OS-specific package(s) into the packages/ directory.
Inheritance definition:
This field is a comma-separated list of parent declarations, allowing to bring templates from several hierarchies. The most common use case is to take informations from the standard distribution hierarchy we provide, and mix them with a local hierarchy in which a company would store local preferences.
Note: There are not yet any special mechanism to deal with multiple occurrences of a given parent in the ancestor graph. This will be fixed in the future.
Note: You should not rely yet on a particular interpretation of the ordering of the parents in the Parents clause. This will be defined in the future.
There are 2 available syntaxes for parent declarations.
Absolute syntax is a space-separated sequence of 4 elements:
repository type. The type of repository the parent module is stored in. The only allowed value at this time is cvs.
repository location. An identifier for locating the repository the parent module is stored in. For cvs this should be a repository suitable as a value for CVSROOT. If you access the repository using the pserver protocol, currently only empty passwords are supported, as needed for anonymous access to the savannah server.
module name. The module name of the parent in the repository defined by the previous field.
module revision. A string identifying the revision of the parent that is to be used. For CVS repositories, this should be a CVS tag.
Relative syntax is simplified version of the absolute syntax, to refer to a module in the same repository. Obviously in this case the first two fields are known, and only the module name and revision should be specified.
These are deprecated names for the 2 fields of the relative syntax in the Parents field.
Note on CVS tags: the CVS builtin tag HEAD can by during the development of a configuration, so that there is no need to re-tag a module and commit all its descendants each time you change a generic level, or to corrupt history by moving tags to avoid this. The use of this tag is however strongly discouraged for production configurations.