Developers Guide

Code management scripts for the developer 

We use FNAL SoftRelTools^? (SRT) as framework for code management. Below you can find the scripts that are useful for a developer. More information on SRT can be found at http://www.fnal.gov/docs/products/srt/.  

Within a base release, you can find default SRT scripts at SoftRelTools/scripts. SoftRelTools^? has the advantage of being highly customizable for your project (and for site), so default SRT scripts can be overriden. The SRT scripts we have customized for NEXT can be found at SRT_NEXT/special/scripts. This latter version has priority (will be used) instead of the default ones. Finally, we have expanded the set of SRT scripts with a few new ones, which can be found at SRT_NEXT/scripts.

How to set up a test /development) release: srt_environment, newrel and srt_setup

To do code development, first we need to create a test (development) release where to make our code changes. Before doing that, and after having set up the SRT base release by sourcing the setup_nextoffline script, type:

source srt_environment

As discussed in the InstallationGuide, the information printed on screen will show your current SRT environment. Note that SRT_PUBLIC_CONTEXT and SRT_BASE_RELEASE point to your base release, and that SRT_MAKEFLAGS, PATH and LD_LIBRARY_PATH include your base release include, bin and lib directories, respectively. On the other hand, SRT_PRIVATE_CONTEXT and SRT_LOCAL are set to ".".

Now create a test release by typing:

newrel -t $SRT_BASE_RELEASE <test release>

where <test release> is the directory name of your choice that will be created in the directory you executed newrel from. You only need to type newrel once for any test release area. For example:

newrel -t current currentdev

Instead of current as the base release, you can also use any other base release installed in your system. Now go to your development area:

cd <test release>

and type:

srt_setup -a

This will tell SRT you want to use this are as your area. The -a option automatically sets the SRT local context to the current test release. To cross check this, type again source srt_environment. You will now notice that SRT_PRIVATE_CONTEXT and SRT_LOCAL point to your test area, and that SRT_MAKEFLAGS, PATH and LD_LIBRARY_PATH now include also your development release include, bin and lib directories, respectively.

How to modify and build an existing package: addpkg, depend, lnkpkg, make

Say that you first want to modify a package that already exists within the base release, let's call it pkgA. First you need to get a copy of the SVN head revision of pkgA into your test release:

addpkg -h pkgA

SVN should tell you something like checked out revision xxxx. Now make the modifications you would like to the code.

Before building, we need to remember that nextoffline will use base release versions of pkgB, pkgC, etc. if not present in your test release. This can create problems if pkgB, pkgC, etc. depend upon pkgA, which we have just modified. There is a handy little script, depend, that is going to tell us which nextoffline packages depend upon pkgA:

depend pkgA

The output will be something like:

These packages in release R201x-yy-zz use include files from package pkgA:
pkgA
pkgD
pkgE

Now, say that you have no intention to change the code in pkgD, pkgE, and that code has not changed since the base release was tagged. For building purposes only, it is sufficient to link to base release versions of pkgD and pkgE to have a consistent development release with our modified pkgA, eg one that rebuilds the libraries for pkgD and pkgE as well. In this case, you should type:

lnkpkg pkgD <tag>

where <tag> is the pkgD tag for your base release (same for pkgE). You can find what <tag> is by looking at the base release file releaseDB/inventory, or by looking where the base release pkgA points to in the packages directory (ls -l <base release>/).

Alternatively, and in any case if the head revision of pkgD is different from the last tagged version of this package, you can also check out a working copy of the head revision of pkgD instead of linking to some version of it:

addpkg -h pkgD

Finally, you are ready to build:

make

If the build is successful, you should have populated the tmp and lib directories, and possibly the bin directory (if packages pkgA, pkgD or pkgE create some binaries). Since builds are different depending on the architecture/compiler used, the subdirectories $SRT_ARCH-$SRT_CXX will be populated, for example Linux2.6-GCC.

How to create and build a new package: newpkg, make

Say you want to create a brand new package, let's call it pkgNew. From the test release top directory, type:

newpkg pkgNew

This will create a new pkgNew directory with some template versions of several files in them: GNUmakefile, pkgNew.h, pkgNew.cxx, xml/GNUmakefile, xml/pkgNew.xml. It is now your task to customize these files and add additional files. In addition, the include directory in the top-level development release area now points to pkgNew include directory.

Now build your release with pkgNew in it as usual:

make

How to define new objects to store within the event: LinkDef.h and other ROOT CINT stuff

There is a number of general-purpose objects that can be used to store new event info from within your modified/new package. Those reside in the RecoBase and AnaBase libraries. However, you may need to define some new class, specific for your package, let's call it pkgCint.

First you need to tell SRT that your package will need to call the ROOT CINT interpreter during build, by adding:

ROOTCINT := YES

in the pkgCint GNUmakefile.

You then need to create your new object to be stored in the event, let's call it HitObject. You will need to define HitObject.h and HitObject.cxx in pkgCint. Do not forget the ROOT's ClassDef and ClassImp macros in them. Also, you will need to create a LinkDef.h file in pkgCint. Have a look at RecoBase for an example of ClassDef, ClassImp, and LinkDef.h usage.

How to import in the SVN repository your code development: svn commit, importpkg

In the modified version of pkgA in your test area, you may have noticed (for example with ls -a) a .svn directory. This means that pkgA is a SVN working copy, and you can use any SVN commands within that directory, for example:  svn info, svn log, etc.

The most important svn command is svn commit. Once you are satisfied with your code changes, within the pkgA directory, you should commit them into the SVN trunk with:

svn commit -m "some useful message" .

where the final dot indicates that changes in the whole directory will be committed.

If you have created some new files in pkgA, remember to use svn add on that file first:

svn add NewFile?

For more details on SVN commands, have a look at the SVN manual at: http://svnbook.red-bean.com/.

How about my new package pkgNew? This package does not have a .svn directory and cannot directly "talk" to SVN. In this case, once you are satisfied with your changes, you should type from the top-level development release area:

importpkg pkgNew

This will first import into the SVN repository your new package, and will also replace your pkgNew directory with a freshly checked out version of the same package, so that the usual SVN commands can be used in the following. In other words, you need to type importpkg only once per package.

Please commit and import, but do not tag: the offline software coordinator (at the time of writing, Michel Sorel) will take care of tagging packages, to ensure that consistent versions of packages end up into a production release (hopefully).

To obtain write permission for the NEXT SVN repository, please get in touch with the SVN repository administrator (at the the time of writing, Justo Martin-Albo)

TO BE CONTINUED... For now, just refer to code examples in: http://enrico1.physics.indiana.edu/fmwk/wiki/index.php?n=FMWK.FMWK?from=Main.HomePage 

Configuration data 

How to access and modify parameters within a module

How to access the configuration of a different module

Event data 

How to access and store FMWK event information in the event file

The AnaBase^?::Event BHEP class within the FMWK event structure

Histogram data 

How to declare and fill ROOT objects stored in the "histogram" file

Database data 

How to access and store NEXT offline DB information

-- MichelSorel - 12 Mar 2010