LCFG Build Tools : Metadata

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.

Required Fields

name

This is the name of the project.

Example

name: foo

version

This is the version of the project and must have 3 fields, separated by a period

Example

version: 1.2.3

Optional Fields

abstract

This is a short description of the project (i.e. a couple of sentences at most).

Example

abstract: The LCFG file component

author

This is the name of the project author (or authors). This is specified using list syntax.

Example

author:
  - Fred Bloggs <fred@example.com>
  - John Smith <john@example.org>

base

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.

Example

base: lcfg

date

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.

Example

date: 07/25/08 13:49:07

group

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.

Example

group: LCFG/Component

license

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.

Example

license: GPLv2

platforms

This is a list of the supported platforms and is specified using list syntax.

Example

platforms: 
  - FedoraCore5
  - FedoraCore6
  - ScientificLinux5

release

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.

Example

release: 3

schema

This is the schema version of an LCFG component.

Example

schema: 1

translate

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"

vendor

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.

Example

vendor: University of Edinburgh

Controlling the Revision Control System

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.

Example

vcs:
  checkcommitted: 0
  genchangelog: 1
  logname: Changes
  type: CVS

The example shows all the currently supported options.

checkcommitted

Controls whether the build tools should check that all files are committed into the revision-control system before making a new release.

genchangelog

Controls whether the build tools should generate the change log file from the logs stored in the revision-control system.

logname

The name of the change log file being used for this project.

type

The type of revision-control system being used, e.g. CVS.

Controlling the Build System

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.

Example

build: 
  gencmake: 0
  translate_before_pack: 1

The example shows all the currently supported options.

gencmake

Controls whether CMake build files (CMakeLists.txt and lcfg.cmake) should be generated at source-packing-time for this project.

translate_before_pack

Controls whether any files matching the translate list should be translated prior to packing the source-code.

remove_input_after_translate

Controls whether to remove the input files (e.g. *.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.