The build system is driven by the contents of the
lcfg.yml
file. Typically it looks something like this:
--- !!perl/hash:LCFG::Build::PkgSpec abstract: The LCFG file component author: - Paul Anderson <dcspaul@inf.ed.ac.uk> base: lcfg build: gencmake: 1 date: 07/15/08 15:16:01 group: LCFG license: GPLv2 name: file platforms: - Solaris9 - Fedora3 - Fedora5 - Fedora6 - Scientific5 release: 1 schema: 1 translate: - "*.cin" vcs: logname: ChangeLog type: CVS vendor: University of Edinburgh version: 1.1.16
The format is YAML, this is a structured format which is designed to be relatively easy for a person to read and edit by hand. The order of the fields within the file is not important but will be sorted alphabetically each time the file is written out by any of the build tools. This reduces the size of the revision-control diff and makes it easier to spot the changes. The amount of indentation for the list and hash sections is not important as long as it is consistent throughout.
Although it can be editted manually the recommended method is to
use the lcfg-pkgcfg
tool. This simplifies the querying
and manipulating of most of the fields. For example:
$ lcfg-pkgcfg --get abstract --in ~/dice/lcfg-file The LCFG file component $ lcfg-pkgcfg --set author='Fred Bloggs <fred@example.org>'
See the manual page for lcfg-pkgcfg
to get a full set
of examples.
There are a couple of required fields, everything else is optional. For full details see the Perl documentation for the module LCFG::Build::PkgSpec.
This is the name of the project.
name: foo
This is the version of the project and must have 3 fields, separated by a period
version: 1.2.3
This is a short description of the project (i.e. a couple of sentences at most).
abstract: The LCFG file component
This is the name of the project author (or authors). This is specified using list syntax.
author: - Fred Bloggs <fred@example.com> - John Smith <john@example.org>
This is a base project (such as "lcfg" or "dice") which allows one to differentiate between the full and short names of a component. For example, "lcfg-foo" versus "foo". If you are not building a component you do not need to consider this field.
base: lcfg
This is the date and time at which a release was made of this source tree. This will be updated automatically by the build tools and you should never need to edit this manually.
date: 07/25/08 13:49:07
The package group to which this software belongs. This field is only really meaningful for when you are generating RPM packages and want to control what goes into the specfile.
group: LCFG/Component
A string representing the license under which the software is released. This is typically the short code name (e.g. GPLv2), a good list is provided on the Fedora wiki.
license: GPLv2
This is a list of the supported platforms and is specified using list syntax.
platforms: - FedoraCore5 - FedoraCore6 - ScientificLinux5
This is the release part of the full package version string. It is optionaly as it is only really meaningful on platforms which are RPM or Debian based.
release: 3
This is the schema version of an LCFG component.
schema: 1
This is the list of files which need to be translated to carry out macro substitution. It is specified using list syntax. Any files with a ".cin" or ".in" suffix will have that removed automatically during the translation process. You can limit the directories in which a glob occurs with something like "perllibs/*.pm.cin". You can also specify individual file names, if they do not have a supported suffix the output, translated, file will replace the input file.
translate: - "*.cin"
This is the name of the vendor and is only really meaningful when building RPM packages. It is not recommended that you set this variable, it is provided for backwards-compatibility.
vendor: University of Edinburgh
There are a number of options which you can tweak to control the way in which the revision control system is used when doing a release of the project. These are all entries in the "vcs" hash and are specified using hash syntax in the metadata file.
vcs: checkcommitted: 0 genchangelog: 1 logname: Changes type: CVS
The example shows all the currently supported options.
There are a couple of options which you can tweak to control the way in which the source package is generated and what manages the building of the project. These are all entries in the "build" hash and are specified using hash syntax in the metadata file.
build: gencmake: 0 translate_before_pack: 1
The example shows all the currently supported options.
CMakeLists.txt
and lcfg.cmake
) should be generated at source-packing-time for this project.*.cin
) after the translation has taken place. This makes it possible to generate "pristine" source tar-files, this is likely to only be useful when combined with the translate_before_pack
option.The translate_before_pack option is very useful if you intend to use a different build system other than CMake (such as the Perl MakeMaker) but still want to do limited variable substitution. You can get access to all the macros representing the LCFG build metadata fields, for instance.