How to build ROOT at BNL and other sites (developer documentation)

Some of the above help is similar than what you will find in the PDSF page mentioned above.
Older help version could be found from the revision tab.

The build is in several steps ; we will assume for this example that we are building root version 5.12.00 ; the % sign is used for the Unix prompt.

IMPORTANT:

• Release “f” was assembled at STAR's request. Any version of ROOT 5.x prior is unfit to deployment in STAR and would break IO and schema evolution.
• Release "h" was released with patches for Xrootd related IO. If you use Xrootd, you MUST use this version to be mind free. However, the version exists in  our AFS based software repository only (location indicated below) and can be found under the name root_v5.12.00h-rc4.1.source.tar.gz .

1. Go to the $ROOT directory, create a directory named after the version i.e. 5.12.00, download the root code from root.cern.ch (the source tar balls are available on their site) and unpack it using
   
   % cd $ROOT
   % mkdir 5.12.00
   % cd 5.12.00
   % setenv ROOTB `pwd`
   
   One note : the ROOTB environment variable will be used throughout this help but is not used by the STAR environment. It only serves the purpose of finding back easily the base tree for the ROOT version you are trying to install. This being said
   ... bring the code via either ftp, scp, our download it via the http protocol ... for example
   % wget ftp://root.cern.ch/root/root_v5.12.00f.source.tar.gz
   % tar -xzf root_v5.12.00f.source.tar.gz
   
   If you are a STAR user, you can also find a copy of the package in AFS at the location
   /afs/rhic/star/common/General/Sources/ .
   Note that the tar ball will have the same naming scheme as above. While unpacking, this will create several CVS directories in the unpacked sources tree but this will need to be removed. One can use
   
   % find root/ -name CVS -exec rm -fr {} \;
   
   to eliminate those directories and start with a clean tree structure. Note: you may get messages like No such file or directory ; ignore them (it's just the order of the deletion which makes some sub-directories deleted before the top one).
   Why do we do this ? Because after unpacking the tar archive, several directories named CVS will appear in the directory tree. The CVS directories contains information about version and the original repository (that is, the one in CERN) and is not suitable for adding on top of the default distribution our patches and additions. If we do not remove those directories coming with the default root distribution, we will not be able to use our own CVS archive (it will stubbornly try to use the cern one).
   Finally, please, remember to remove the archive tar.gz file after unpacking. It is not helpful to keep it around.
   
2. The pre-compilation phase prepares the STAR specific layout. First, STAR patches to the ROOT software are saved in a CVS branch named root5 while in the past, we used to also save the root code in our CVS branch named root. Around April 2002, we changed this scheme by saving ONLY the our changes to the root code in the root5 CVS branch and ask remote sites to download the source codes from the root official site as mentioned above.
   In summary, the root5 branch is similar to the root tree directory structure and allows us to keep a clear separation in CVS of our STAR specific patches to the root core code. However, to map the two CVS branch to the same physical tree structure, we soft-link directories. To create the basic structure, you then need to
   
   % ln -s root root5
   % cvs co -r HEAD root5/etc # at BNL
   % cvs co -rv5-12-00f root5/etc # on remote sites
   
   -r HEAD for BNL ensure the check out of cvs of the latest version of our STAR configuration files. Be aware that CVS may fail in the checkout if our version diverge too much from the default root distribution. -rv5-12-00 should be used on remote sites facilities.
   
   On remote sites only (PDSF, Munich, etc ...) , you need to append to the current distributions the eventual changes made by the core team ensuring the code works fine with our software. We will work toward ensuring that our modifications get back to the ROOT developers. Until full convergence, the following command, or similar, may be needed
   % cvs co -rv5-12-00f root5/
   Note that this will check out and add to your tree only the code we have modified. You must do this before the next step.
   
3. The structure is not ready ... yet ... You still have to create the OS dependent tree structure we use to allow concurrent platform support in addition of the two layers (with debugging, without debugging information). This is done in a one-does-it-all script.
   
   % $STAR/mgr/MakeRootDir.pl
   
   This command needs to be executed ONCE on EACH supported platform.
   IMPORTANT NOTE: $STAR environment variable needs to be defined here but it case it is not, the latest version available in /afs/rhic.bnl.gov/star/packages/dev/mgr is the safest to use (because it is the latest available). You need to access this script from the AFS path (or make a local copy) if you start building a site from scratch as well (ROOT needs to be installed before $STAR).
   
4. The next step will give an example on how to build it under the linux platform. The above assumes that root is installed in AFS (to make it generic) and that .@sys allows to separate the OS/compiler flavors (which is the case, but not valid for off-site NFS resident tree structure where you will have to specifically use .$STAR_HOST_SYS instead of .@sys ).
   
   % cd $ROOTB/.$STAR_HOST_SYS/rootdeb
   % setenv ROOTSYS `pwd`
   % ./configure linux --build=debug --enable-qt ... remaining options ... +
   
   % cd $ROOTB/.$STAR_HOST_SYS/root
   % setenv ROOTSYS `pwd`
   % ./configure linux --enable-qt ... remaining options ... +
   
   The above examples are both building the standard root distribution and option. This IS NOT what we are using in STAR and the above table shows the default options currently in use. You MUST of course add the --build=debug flag where appropriate as shown above while using that table (i.e. the main point of the two commands as shown is that the rootdeb tree is build with the configure command --build=debug while the optimized version is not).
   Note1 : You MUST issue a similar command on ALL platform you are supporting before proceeding to the next step.
   Note2 : You need to run ./configure ONCE only. In case of any further updates, you should NOT repeat this action.
   
5. While running configure, you may also get a message like this
   ### Need libshift with this version of /cern/2003/lib/libpacklib.a ### Run configure with --enable-rfio or set --with-shift-libdir
   In principle, you do NOT need an extraneous dependencies in libshift but if you get this message from configure, this means that you have a libpacklib depending on RFIO/libshift. The solution for this is to edit config/Makefile.config and add to CERNLIBS something similar to the above (the year should match the year number displayed in the message and/or match the value $CERN_LEVEL):
   
   For Solaris, we are still using
   CERNLIBS := /cern/2002/lib/libpacklib_noshift.a /cern/2002/lib/libkernlib.a
   
   For RHL, we had
   CERNLIBS := /cern/2003/lib/libpacklib_noshift.a /cern/2003/lib/libkernlib.a
   
   For Scientific Linux 3, the minimal valid CERN library version is 2004.
   CERNLIBS := /cern/2004/lib/libpacklib_noshift.a /cern/2004/lib/libkernlib.a You may also have to change BUILDHBOOK := yes . In order to assist in this step, a script was written to automatically fix the reference as needed. As per the MakeRootDir.pl script, this script requires to have the STAR library installed (or at least, one checkout of the mgr/ tree).
   % $STAR/mgr/fixrootmk
   
6. Trouble ? Mysterious side effect
   Are we ready to compile ?? No. The configure command above had the side effect of removing our system.rootrc file and replacing it by a default file. You will have to restore this using
   
   % cd $ROOTB
   % rm -f root5/etc/system.rootrc
   % cvs co -r HEAD root5/etc
   % cvs co -rv5-12-00f root5/etc
   
   before starting the compilation process ... For this reason, it is best to do step (3) and (4) on all supported platforms first before starting compilation so you will have to do this step only once. Note that this has to be done again and again every time the configure script is used (hopefully, this will change in future).
   
7. Now we are ready to compile. To do this, simply
   
   % cd $ROOT
   % ! as defined above
   % cd $ROOTB/.$STAR_HOST_SYS/root
   % gmake
   % gmake qtcint
   % gmake cintdlls
   % gmake map
   %
   % cd $ROOTB/.$STAR_HOST_SYS/rootdeb
   % gmake
   % gmake qtcint
   % gmake cintdlls
   % gmake map
   
   Note 1: Ignore message make: *** No rule to make target `qtcint'. Stop. Expected for platforms where qt is not enabled (or disabled).
   Note 2 : the gmake step may display messages like No such file or directory . Please, ignore since this is normal and will trigger the proper directory tree creation.
   Note 3 : All is compiled AND INSTALLED. There is NO NEED to use make install.

Table of options

The difference in the options listed above is mainly due to the fact that our Linux deployed image already contains and includes a version of mysql client (native Linux support),Linux supports native libxpm etc ... while we have to make this support as an add-on under other platforms. --disable-xrootd should be used wherever you do not have Xrootd support (or do not need it).

List of updated files in CVS

The below list is provided for convenience but you should send a note if you note ANY differences from this list and the actual tagged list. The following files (should be) are tagged v5-12-00f and are in the root5/ branch of CVS (A=added, P=patched, U=updated):

P root5/cint/inc/G__ci.h
P root5/cint/inc/common.h
P root5/table/inc/TDataSetIter.h
P root5/qt/src/TQMimeTypes.cxx
P root5/qt/src/TGQt.cxx
P root5/qt/inc/TGQt.h
P root5/qt/src/TQtWidget.cxx
U root5/etc/system.rootrc

P root5/table/src/TVolume.cxx
P root5/table/src/TVolumeView.cxx
P root5/table/src/TTableDescriptor.cxx
P root5/table/src/TTableDescriptor.cxx
P root5/table/src/TTable.cxx
P root5/table/src/TDataSet.cxx
P root5/table/src/TFileSet.cxx
P root5/treeplayer/src/TChainIndex.cxx
P root5/qt/inc/TQtWidget.h
P root5/qt/src/TQtWidget.cxx

U root5/unix/src/TUnixSystem.cxx
P root5/table/src/TTableDescriptor.cxx
U root/xrootd/src/xrootd-20060523-1741-ROOT.src.tgz

 

Adding our own patch and releasing a new tagged (modified) root version for STAR

Since this is a BNL root-build support page, here are some notes on how to patch root code and port this back to the outside.
First, out root5 CVS tree is clearly identified with tags following the root version scheme. For example, root5/etc/root.mimes is tagged with tags such as v4-04-02, v5-12-00 etc ... This is a convention we should respect and follow. The matching is simple, for a root version XX.YY.ZZ , there is a CVS tag (if patches applies to that version) XX-YY-ZZ .

Now, at each new release, we need to re-tag the files we have in root5/etc/ . This directory contains the (latest) configuration files ( root.mimes and the system.rootrc file). We will keep the version example used above but one should substitute it with the proper value.

The first problem may be that the root5/etc may not update itself in step (5). For example, the following session may happen

% cvs co -r HEAD root5/etc
cvs checkout: Updating root5/etc
M root5/etc/root.mimes
? root5/etc/.cvsignore
%

This indicates that the root.mimes file, generated by the default root package, is no longer in-sync with our version. If this happens, we must merge the differences by hand. Either of the above procedure will be needed

Case 1 : a sticky tag exists ; this procedure was used for 3.03.09 (the sticky tag is now gone) and presented a-is as documentation (root3/ tree used)

% mv root5/etc/root.mimes root5/etc/root.mimes.new
% cvs co -r HEAD root5/etc/root.mimes
... hack it along i.e. You MUST modify root.mimes by the appropriate lines contained in root.mimes.new
% cvs commit -r1.2 root5/etc/root.mimes
%

The above CVS manipulation was necessary to remove the HEAD sticky tag and get back the the MAIN branch but a normal tag afterward would no longer require this to be done. Here, we knew that the preceding version was 1.1 and committed the file again with an upper revision. Normally, the procedure should only be something like

Case 2 : the sticky tag has been removed (by the above procedure or similar)

% cvs co root5/etc
... something fails and
% mv root5/etc/root.mimes root5/etc/root.mimes.new
% cvs co root5/etc/root.mimes
... hack it along i.e. Merge differences ...
% cvs commit root5/etc/root.mimes
% rm -f root5/etc/root.mimes.new

The above would automatically make the HEAD revision applied to the latest commit.

Adding modified files to our CVS repository

This unfortunately has to follow a slightly different procedure because you do not want, at this stage, to override code which are already in the sub-directories. We will give a specific example of a change on.

First, root5/ is our CVS repository base path as mentioned before in this document. Because of step 1 which has removed all erroneous CVS directories (that is, the directories unpacked with the root distribution), you have to recreate one.

The above removes the tag and commits the new files.

% mv -f root5/meta root5/meta-new
% cvs co -A root5/meta the -A flag starting from no directories removes the sticky tag as well
% rm -f root5/meta/src/*.cxx root5/meta/inc/*.h
% cp root5/meta-new/inc/*.h root5/meta/inc/
% cp root5/meta-new/src/*.cxx root5/meta/src/
% cvs commit root5/meta/inc/TDataMember.h root5/meta/inc/TStreamerElement.h root5/meta/src/TDataMember.cxx root5/meta/src/TStreamerInfo.cxx root5/meta/src/TStreamerElement.cxx

Further addition of files or modifications in this tree will no longer be a problem.

Directories may be added from one root version to another. If this happens, the CVS tree will not contain any information about the file you are about to commit. This is the easiest case (no sticky tag to remove ...). The following example is based on root5/table directory inclusion to CVS with the only file to be added (as per what was modified) being as follow

% cd $ROOTB
% cvs add root5/table

This adds root5/table in the HEAD of CVS but it is not sufficient. You need to work in a plain directory now to add the proper directory structure.

% cd ~/ && mkdir ROOT && cd ROOT
% cvs co -A root5/table
% mkdir root5/table/inc root5/table/src
% cvs add root5/table/inc root5/table/src
% cvs commit root5/table

After this is done, the newly (and empty) created CVS tree needs to be appended to the one in $ROOTB . Proceed as folow now, assuming what we commit are the only files we modified.

% cd $ROOTB
% mv root5/table root5/table-new
% cvs co root5/table
% cp root5/table-new/src/*.cxx root5/table/src/
% cp root5/table-new/inc/*.h root5/table/inc/
% cp root5/table-new/Module.mk root5/table/

% cvs add root5/table/inc/TTable.h root5/table/inc/Ttypes.h root5/table/inc/LinkDef.h root5/table/src/TTableDescriptor.cxx root5/table/src/TTable.cxx
% cvs commit -m “5.12.00 + changes” root5/table/inc/TTable.h root5/table/inc/Ttypes.h root5/table/inc/LinkDef.h root5/table/src/TTableDescriptor.cxx root5/table/src/TTable.cxx

Final tagging

% cvs tag v5-12-00f root5/etc/root.mimes root5/meta/inc/TDataMember.h root5/meta/inc/TStreamerElement.h root5/meta/src/TDataMember.cxx root5/meta/src/TStreamerInfo.cxx root5/meta/src/TStreamerElement.cxx root5/table/inc/TTable.h root5/table/inc/Ttypes.h root5/table/inc/LinkDef.h root5/table/src/TTableDescriptor.cxx root5/table/src/TTable.cxx root5/utils/src/rootcint.cxx

Adding new files or directories to the repository

Lesson learn, you should NEVER do that from $ROOTB tree as indicated above but from a private directory structure. Attempt to manipulate CVS from (adding new files) will result in inconsistent archiving. The above is an example of adding a new branch newdir to CVS.

% cd
% test -e work/ROOT || mkdir -l work/ROOT
% cd ~/work/ROOT
% cp -r $WHEREVER_THE_NEW_CODE_IS/root5/newdir root5/
% find root5/newdir -type d | grep -v CVS | awk '{print “cvs add “$1}' >new-files.ch
% find root5/newdir -type f | grep -v CVS | awk '{print “cvs add “$1}' >new-files.csh && chmod +x new-files.csh
% ./new-files.csh
% cvs commit -m “My first version of newdir package” root5/newdir This should do it ... Typically patched codes The following codes are tweaked