Changes between Initial Version and Version 1 of Obsolete/Development/Build

Timestamp:

Mar 20, 2010, 10:27:00 PM (16 years ago)

Author:

loomis

Comment:

--

Obsolete/Development/Build

@@ +1 @@
+[[TracNav]]
+
+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 <tt>{trunk/,tags/}ncm-components/</tt>;
+* '''core modules''' all the others.
+
+Each core module has its own pointer to the build tools, which appears as a normal subdirectory named <tt>quattor-build-tools</tt> in the checkout directory. For NCM components there is instead a single pointer located at <tt>quattor/ncm-components/</tt>. '''In any case, please, refrain from making any change to the content of any <tt>quattor-build-tools</tt> directory!'''
+
+= System requirements =
+The framework is based on GNU <tt>make</tt>, <tt>sed</tt>, <tt>grep</tt>, <tt>perl</tt>, 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 <tt>>= 1.4.4</tt>) of <tt>svn</tt>.
+
+= 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/foo/bar quattor/foo/bar
+
+The above command makes <tt>$PWD/quattor</tt> 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 <tt>~/.bashrc</tt>. Make sure you have write permission on <tt>/your/quattor/working/dir</tt>! The above variable will help the build tools to guess where to create the tags in your local system.
+
+== 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 ...
+
+= Available targets =
+From now we assume each ''target'' is called via <tt>make</tt>. For example, to invoke the help command inside a given product directory, f.i. <tt>ncm-components/core/ncm-grub/</tt>:
+
+ $ 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 <tt>quattor-build-tools/quattor-buildtools.mk</tt>.
+
+Since "tags" are meant as read-only directories, many of the above tags will fail when called inside the <tt>tags/</tt> 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 <tt>config.mk</tt> (mandatory for any Quattor module):
+
+ VERSION=x.y.z
+ RELEASE=n
+
+The VERSION string <tt>x.y.z</tt> is ''automatically'' modified by the build tools, whereas the RELEAE string <tt>n</tt> 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 <tt>make</tt> targets:
+
+{| border="1"
+! Target !! Result !! Scope
+|-
+| <tt>release</tt> || commit and tag a release <tt>x.y.Z+1</tt> || a very minor change, such as bug fixes and new options
+|-
+| <tt>minorversion</tt> || commit and tag a minor version <tt>x.Y+1.0</tt> || minor changes, such as schema add-ons, support for new functionalities and status change from '''test''' to '''stable'''
+|-
+| <tt>majorversion</tt> || commit and tag a milestone <tt>X+1.0.0</tt> || major changes, such as whole rewrite or refactoring
+|}
+
+'''Please, avoid direct usage of <tt>svn commit</tt>, 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 [[#Workspace setup|above]], you should see the result of your check-in in <tt>/your/quattor/working/dir/tags/</tt>.
+
+=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 <tt>stable</tt> 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 <tt>check</tt> target. Further details of the checks performed may be found [[Build_Framework_Checks|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 <tt>OBSOLETE</tt> tag in <tt>config.mk</tt> with three possible values:
+* <tt>1</tt>: default value, no special reason given;
+* <tt><mod-name></tt>: where <tt>mod-name</tt> is the component/module to use instead of the deprecated one;
+* <tt><another-particular-reason></tt>: where an appropriate explanation is given.
+
+You don't need to edit <tt>config.mk</tt> by hand, just call:
+
+  $ make OBSOLETE_MSG=<your reason or module name> markobsolete
+
+which will modify <tt>config.mk</tt> and commit it (no special tag is added).
+
+Once a module is marked as obsolete, unless you define the shell variable <tt>CHKOBS_OK</tt>, <tt>make check</tt> fails. Other targets depending on <tt>check</tt>, such as <tt>rpm</tt>, will also fail.
+
+= Running unit tests =
+If your module comes with unit tests, you can call them via <tt>make test</tt>, provided that a test ''harness'' is found in your checkout. Further details may be found on [[https://twiki.cern.ch/twiki/bin/view/FIOgroup/SWDevUnitTestPerl 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 <tt>svn:externals</tt> property. You can query it by running <tt>svn pg svn:externals</tt>, f.i. for the <tt>aii</tt> 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
+
+'''<u>Note</u>: 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
+
+'''<u>Note</u>.''' Only the modules/component listed in the "release" file <tt><your-svn-co>/trunk/release-list</tt> will be affected. Please, keep the list up-to-date.
+