LCFG Build Tools : The Release Tools

All the release management for packages is done with the LCFG release tool - lcfg-reltool. This tool supports a number of sub-commands each with different specific options.

To get the list of supported commands you can run the tool with no command-line options:

[finlaggan]squinney: lcfg-reltool
lcfg-reltool help 

Available commands:

      commands: list the application's commands
          help: display a command's help screen

   checkmacros: Check for correct macro usage
     devosxpkg: Build MacOSX packages from the development source tree
       devpack: Package the development source tree
        devrpm: Build binary RPMS from the development source tree
  majorversion: Tag the source tree as a particular major release
  microversion: Tag the source tree as a particular release
  minorversion: Tag the source tree as a particular minor release
        osxpkg: Build MacOSX packages from the tagged source tree
          pack: Package the tagged source tree
           rpm: Build binary RPMS from the tagged source tree
          srpm: Build binary RPMS from the tagged source tree

To get help regarding the options for a particular command you just need to use the help command, for example:

$ lcfg-reltool help major
lcfg-reltool 

lcfg-reltool majorversion [long options...]
        --checkcommitted     Check for uncommitted changes
        --logname            The VCS log file name
        --genchangelog       Generate the change log from the VCS log
        --quiet              Less output to the screen
        --dryrun             Simulate operation
        --dir                Project working directory

For convenience, you can always use the shortest unique name to refer to a command. So you can use "major" instead of "majorversion", in fact you could even use "ma"

All commands support the following three options:

--quiet

Reduces the amount of output to the screen.

--dryrun

Simulate rather than carry out any commands which make permanent changes.

--dir

The project directory, if not specified the current working directory is used.

As with the commands you can use the shortest unique name for each option. So, "dryrun" could become "dry". Note though that single-dash versions of the options (e.g. -q for --quiet) are NOT currently supported.

Tagging Releases

There are three ways in which you can tag a new release of your code. Which you use depends on the significance of the changes you have made, particularly whether any APIs have been modified. The three commands are: majorversion, minorversion and microversion.

LCFG projects always have a version string composed of 3 parts which are joined with periods, e.g. 1.2.3. The first part (the 1) is the major version, the second part (the 2) is the minor version and the third part (the 3) is the micro version (sometimes referred to as the release but that is confusing as it is not related to the RPM release field).

It is entirely up to you how you alter the version of a package when you make a new release. Each tool works in the same way though by incrementing the associated field and resetting any smaller fields back to zero. For example, after a minor release the version string 1.2.3 would become 1.3.0 and after a major release the same initial version string would be 2.0.0. After an update of the micro part (using the microversion command) 1.2.3 would become 1.2.4

All three commands support the same options:

--checkcommitted

Check the source tree for uncommitted changes. This overrides the setting in the LCFG build metadata.

--genchangelog

Generate the change log file from the version-control system log. This overrides the setting in the LCFG build metadata.

--logname

Sets the name of the log file to use. This overrides the setting in the LCFG build metadata.

The checkcommitted and genchangelog options can also be negated to temporarily turn-off settings in the LCFG build metadata. This is done by using --no-checkcommitted and --no-genchangelog on the command line.

Examples

lcfg-reltool micro
lcfg-reltool major --dir ~/dice/lcfg-foo

Packing the Source

Traditionally LCFG software authors did not want to explicitly pack the source for a project as this will happen anyway as a by-product of generating binary RPMs. The aim of the new build tools is to generate source tar files and SRPMs which are platform-independent. From these source packages we can then generate the binary packages on any target platform. Most likely this building of binary packages will happen inside a chroot (using something like mock or koji on Fedora and RHEL/SL).

If you want to just generate a tar file of the source you can use the commands devpack and pack. If you also want to generate an SRPM you can use the srpm command. Alternatively, another way in which to generate just the SRPM is to pass the --sourceonly option to the devrpm or rpm commands, see below for full details of those two commands.

Source packaging can be carried out in two ways. The first works on the current "devel" tree which can contain changes which have not yet been tagged as a new release. This is done with the devpack command. The files may have been committed into the version-control system or they may contain uncommitted changes (depending on the setting of the checkcommitted option, of course). However, you MUST have actually added the file or directory to the version-control system for it to be put into the source package. When creating a devel package the version gets the string "_dev" appended if it is not already present.

The second approach generates the source package from the tagged release which matches the version in the LCFG build metadata. This is done with the pack or srpm commands. It exports the tagged version of the source tree from the version-control system repository. In the case of the srpm command you will get an SRPM, which contains the tar file and RPM spec file as well as the source tar file separately.

The following options are supported:

--resultsdir

Where the source package should be stored, defaults to $HOME/lcfgbuild

--gencmake

Controls whether the CMake files should be generated. This overrides the gencmake setting in the LCFG build metadata.

--translate

Controls whether the source files should be translated before packaging. This overrides the translate_before_pack setting in the LCFG build metadata.

--genmeta

This is a list of platforms for which to generate build files (e.g. the specfile on RPM based systems).

The gencmake and translate options can be negated to turn off the settings from the LCFG build metadata. For example, --no-gencmake stops the system generating CMake files.

Inside the results directory (which is usually $HOME/lcfgbuild) the release tools will create a sub-directory for the specific version of the package being built. Within this sub-directory the various generated products (the source tar file, the specfile, the SRPM, etc.) will be stored. For example, using the following command:

lcfg-reltool pack --dir dice/lcfg-file

produces a directory named $HOME/lcfgbuild/lcfg-file-1.1.16/ which contains:

$ ls lcfgbuild/lcfg-file-1.1.16/
lcfg-file-1.1.16.spec  lcfg-file-1.1.16.tar.gz

If you had used the srpm command it would have also contained lcfg-file-1.1.16-1.src.rpm.

The generated products are put into a directory like this rather than using the same tree as the rpmbuild command because the intention is to produce build files (and output) for many different platforms.

Building Binary Packages

Currently it is only possible to build binary RPMs, the aim is to also provide support for generating MacOSX packages and Solaris packages. Primarily these commands are intended as a convenient option for authors who want to install and test a package after they have just made some changes. The idea is that on whichever platform an author chooses to develop software the LCFG release tools will be used to generate source packages and a set of files for each supported platform which control the actual build process. The design is very much geared towards the process of going from a tagged release to a binary package become two-stages. This encourages good separation of concerns and should result in higher quality software which can be easily ported to other platforms.

There are currently two commands for building binary packages. These are rpm and devrpm, they inherit from pack and devpack respectively. These commands support all the options used in the source packaging process. They also support the following additional options:

--sourceonly

Only build the source package

--deps

Controls whether build dependencies should be checked before building packages.

Note that if you need to generate an SRPM from a development tree then currently the only way to do this is using the devrpm command along with the --sourceonly option.

Sometimes when you are building a package quickly just to test the installation you know that not all build dependencies are satisfied. If you are certain this will not affect the successful building of the application (maybe they are just for some tests which are actually optional) you can override the dependency checking with --no-deps.

As with the source packaging stage, the results from these commands will be put into $HOME/lcfgbuild in a directory for the version of the package built. If you have built RPMs they will also be in the directory hierarchy used by rpmbuild, this is a side-effect of using that tool to build binary packages.

Examples

lcfg-reltool devrpm --no-deps

lcfg-reltool rpm --dir ~/lcfg/lcfg-foo --resultsdir /tmp/squinney

Last modified: Mon Oct 27 10:08:09 2008