Quattor Build Tools
TracNav
Table of Contents
The quattor build tools aim to wrap up all the functions commonly used by developers to manage code in the quattor repository. They provide facilities for creating new releases of software modules, and include automatic checks for required elements. This page is a technical guide for developers who want to contribute code to quattor.
Any part of quattor susceptible of being packaged in a software unit is called a product. We distinguish two classes of products:
- NCM components which live in the subtrees
{trunk/,tags/}ncm-components/; - core modules all the others.
Each core module has its own pointer to the build tools, which appears as a normal subdirectory named quattor-build-tools in the checkout directory. For NCM components there is instead a single pointer located at quattor/ncm-components/. In any case, please, refrain from making any change to the content of any quattor-build-tools directory'''
System requirements
The framework is based on GNU make, sed, grep, perl, etc. Please make sure you're using some version of GNU/Linux. MacOS, BSD and others are not supported. Then of course, you need a recent version (at least >= 1.4.4) of svn.
Workspace setup
First, make sure your finger information is up-to-date. This is needed to fill the 'author' field in the change logs. If needed run the following command:
$ chfn -f <full-name> -o <email-address> <your-login>
We recommend to check out repository directories with their original names, f.i.:
$ svn co https://quattor.svn.sourceforge.net/svnroot/quattor/trunk/foo/bar quattor/foo/bar
The above command makes $PWD/quattor your working directory (a.k.a. the quattor checkout root). If however you prefer to use a different checkout root as a working directory, you should set the following environment variable:
$ export QTTR_CO_ROOT=/your/quattor/working/dir
Better off placing it in your ~/.bashrc. Make sure you have write permission on /your/quattor/working/dir! The above variable will help the build tools to guess where to create the tags in your local system.
Note: working copy of Quattor repository must always comme from Quattor trunk.
Core modules
In order to work with core modules, just check out the directory you're interested in, f.i.:
$ svn co https://quattor.svn.sourceforge.net/svnroot/quattor/trunk/ccm quattor/trunk/ccm
then
$ cd quattor/trunk/ccm $ make ...
NCM components
In order to work with NCM components, you need to check out the whole components' tree, i.e., for the head revisions:
$ svn co https://quattor.svn.sourceforge.net/svnroot/quattor/trunk/ncm-components \ quattor/trunk/ncm-components
and for the tags:
$ svn co https://quattor.svn.sourceforge.net/svnroot/quattor/tags/ncm-components \ quattor/tags/ncm-components
then, f.i.:
$ cd quattor/tags/ncm-components/core/ncm-pakiti/1.0.0/ $ make ...
Build Tools Available Targets
From now we assume each target is called via make. For example, to invoke the help command inside a given product directory, f.i. ncm-components/core/ncm-grub/:
$ make help
usage: make target [target...]
most frequently used targets:
buildtools -- insert a pointer to the HEAD version of the build tools
check -- check for:
* 'obsolete' mark in config.mk
* mandatory files (defined in 'quattor.mk')
* deprecated files (defined in 'quattor.mk')
* mandatory comments in source files (needs _SRC_FILES to be defined)
* mandatory meta tags in 'config.mk'
* deprecated patterns in Pan template files - mainly for NCM components
(needs _DIRTY_TPL_FILES to be defined)
clean -- remove backup files and other garbage
dist --> pack
header -- add a header to all source files (needs _SRC_FILES to be defined)
majorversion -- increase version X+1.y.z, commit and tag in SVN
markobsolete -- add to config.mk an 'OBSOLETE' mark and commit in SVN (no tag is added)
minorversion -- increase version x.Y+1.z, commit and tag in SVN
pack -- build a tar.gz package for distribution
release -- increase version x.y.Z+1, commit and tag in SVN
rpm -- build an RPM package for distribution
tagstable -- tag in SVN the HEAD revision with 'STABLE'
test -- run the tests, if any, coming with the module
The build also include other targets for use by developers of the quattor build tools. For details, consult the file quattor-build-tools/quattor-buildtools.mk.
Since "tags" are meant as read-only directories, many of the above tags will fail when called inside the tags/ tree.
Versioning
Module versions are made up of a 3-digit version number and a 1-digit release number:
x.y.z-n
The two strings are placed in the special file config.mk (mandatory for any Quattor module):
VERSION=x.y.z RELEASE=n
The VERSION string x.y.z is automatically modified by the build tools, whereas the RELEASE string n must be modified manually in special situations, such as when back porting fixes to an old version.
Checking in releases
After the initial check-in to add a module to the repository, subsequent releases are handled via the following make targets:
| Target | Result | Scope |
release | commit and tag a release x.y.Z+1 | a very minor change, such as bug fixes and new options |
minorversion | commit and tag a minor version x.Y+1.0 | minor changes, such as schema add-ons, support for new functionalities and status change from test to stable |
majorversion | commit and tag a milestone X+1.0.0 | major changes, such as whole rewrite or refactoring |
Please, avoid direct usage of svn commit, since this bypasses the checks meant for improving code quality'''
The svn commands involved in these operations are silent, but if you like to see what's actually going on, just define the shell variable SVN_VERB, f.i.
$ make SVN_VERB=1 release
The above targets create some subdirectories in your local working directory. If you followed the tips above, you should see the result of your check-in in /your/quattor/working/dir/tags/.
Tagging a release as stable
There are two kinds of release:
- Development: a release which can be incomplete, non-functional, or under testing. Such a release is not suitable for use in a production environment
- Stable: a release which has been well-tested, possibly in a production-like environment
A stable release is unique for each module. When checking in a release via one of the above targets, you will be asked whether you would like to tag it as 'stable'. If the release has received sufficient testing, answer 'yes'. If you answer 'no', you can tag the trunk revision of the component at a later stage as follows:
$ make tagstable
This will cause a stable tag to be created with the contents of the current revision.
Checking code
In order to improve the quality of our code base, the build framework runs some automatic checks when
performing checkins. You can run these checks manually using the check target. Further details of the checks performed may be found here?.
Deprecating a module
When a module or NCM component is deprecated for any reason, it should be marked as 'obsolete'.
The convention for obsolete modules is to have an OBSOLETE tag in config.mk with three possible values:
1: default value, no special reason given;<mod-name>: wheremod-nameis the component/module to use instead of the deprecated one;<another-particular-reason>: where an appropriate explanation is given.
You don't need to edit config.mk by hand, just call:
$ make OBSOLETE_MSG=<your reason or module name> markobsolete
which will modify config.mk and commit it (no special tag is added).
Once a module is marked as obsolete, unless you define the shell variable CHKOBS_OK, make check fails. Other targets depending on check, such as rpm, will also fail.
Running unit tests
If your module comes with unit tests, you can call them via make test, provided that a test harness is found in your checkout. Further details may be found on CERN's Perl unit test page.
Updating a core module's pointer to the build tools
Normally, each core module has a pointer to a specific version of the build tools, set as an svn:externals property. You can query it by running svn pg svn:externals, f.i. for the aii core module:
$ cd <your-svn-co>/trunk/aii $ svn pg svn:externals quattor-build-tools -r15 https://quattor.svn.sourceforge.net/svnroot/quattor/quattor-build-tools
At any time, the developer of a given module can update its pointer to the head revision, by running
$ make buildtools
Should the above command fail, you can proceed as follows.
- Get the head revision number of the build tools
$ svn info https://quattor.svn.sourceforge.net/svnroot/quattor/quattor-build-tools | egrep Revision Revision: 211
- Update the "svn:externals" property on the local module checkout, commit and update:
$ svn ps svn:externals "quattor-build-tools -r211 \ https://quattor.svn.sourceforge.net/svnroot/quattor/quattor-build-tools" ./ $ svn ci -m "Updated pointer to the qbt" $ svn up
Note: NCM components use always the head revision of the build tools, thus the above procedure does not apply to them.
Updating all pointers to the build tools
From the top-level trunk directory it is possible to update all the pointers to the latest build tools in just one go:
$ cd <your-svn-co>/trunk/ $ svn update $ make refreshbt
Note. Only the modules/component listed in the "release" file <your-svn-co>/trunk/release-list will be affected. Please keep the list up-to-date.
