Building ROOT in STAR

How to build ROOT at BNL and other sites (support 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.

ATTENTION:

• This version of ROOT requires additional command line option to build under SL3.0.5 (gcc 3.2.3) and especialy, Reflex need to be disabled. If you intend to support SL3.0.5, please be sure take note of that.
• BEWARE that the target for 64 bit machine is specific to your platform. We use linuxx8664gcc at BNL.
• Several patches are available for this revision (see at the bottom as usual). All sources were repackages in AFS as root_v5.22.00a_p1-star.source.tar.gz (this revision was last made on 2009/08/07).
  
• We substantially dropped several OS support since the previous release and this still applies to 5.22.00 i.e.:
  • cygwin not tested at all
  • Mac OSX not tested yet
  • Solaris and True64 are no longer available to us as build platform and hence, we cannot conclude
  • Linux revisions prior to 3.0.2 are no longer supported (this includes support for RH8, RH9, SL303 and SL304 which were made via backward assumption through 3.0.2).
• Only Pythia6 is supported in this version (and is default)
• This revision supports Qt4

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

1. Go to the $ROOT directory, create a directory named after the version i.e. 5.22.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.22.00
   % cd 5.22.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.22.00a.source.tar.gz
   % tar -xzf root_v5.22.00a.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-22-00a 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 add codes we may have patched as listed in the patch section. 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. Up to V5.22.00, we used to add a tag for all codes but noboddy used it so instead, checked-out code by code (or using a list).
    
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`
   % $STAR/mgr/fixrootmk -unlink
   % ./configure linux --build=debug ... remaining options ... +
   
   % cd $ROOTB/.$STAR_HOST_SYS/root
   % setenv ROOTSYS `pwd`
   % $STAR/mgr/fixrootmk -unlink
   % ./configure linux  ... 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).
   
   Notes:
   1. You MUST issue a similar command on ALL platform you are supporting before proceeding to the next step.
   2. You need to run ./configure ONCE only. In case of any further updates, you should NOT repeat this action.
      
    
5. Execute the following script before compiling
   % $STAR/mgr/fixrootmk
   This will check the configuration file for special tags (in the old versions, it would check and fix CERNLIB for example).
   Note that the same command prior with -unlink moved the system.rootrc aside before the configure and make local copies of some of the files which should not be shared between multiple-platforms. At the end of compilation, we will ask you to execute the script again to re-install the system.rootrc and similar files (i.e. make use of the global one for all platforms).
   
   
6. Now we are ready to compile. To do this, simply use the below sequence where you have configured the package.
   % gmake
   % gmake qtcint
   % gmake cintdlls
   % gmake map
   
   Notes:
   1. Ignore message make: *** No rule to make target `qtcint'. Stop.
      Expected for platforms where qt is not enabled (or disabled).
   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.
   3. All is compiled AND INSTALLED. There is NO NEED to use make install.
   4. For those compiling on AFS, if gmake (or make) keeps calling the reconfigure script over and over again, you have two solutions. Either 'sleep 1 && touch Makefile'  and type make again or use 'make --assume-new=Makefile'. The former will reset the Makefile timestamp to a second later of the last command executed and the later tell make to consider the timestamp of the Makefilefile as if it has just been modified.
    
7. As noted in step 5, execute
   % $STAR/mgr/fixrootmk -fix
   to finalize the build. You are now done.

Table of options

Notes:

1. --enable-mysql is now default in 5.22.00 (you do not need to add to the command line but keep it in mind)
2. To enable the build with QT4, you MUST define QTROOT to point to the QT4 directory prior to executing the configure script (the build will oherwise be silent on missing it)
3. You should use $OPTSTAR at remote sites having a local /opt/star and $XOPTSTAR if you provide support over AFS.
4. --disable-xrootd should be used wherever you do not have Xrootd support (or do not need it)
5. --disable-reflex was used for older gcc versions which would otherwise chock on some of the C++ semantics.
6. --with-f77=/usr/bin/g77 was initially used as I wanted to stay away from gfortran but STAR softwareworks fine with gfortran so there is no need to force a preference

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-22-00a and are in the root5/ branch of CVS (A=added, P=patched, U=updated):

     
     P root5/cint/cint/inc/G__ci.h
     P root5/cint/cint7/inc/G__ci.h

     U root5/etc/rootlogon.C
     U root5/etc/rootlogoff.C
     U root5/etc/root.mimes
     U root5/system.rootrc

     P root5/cint/cint7/lib/prec_stl/string
     U root5/hist/hist/src/TFormula.cxx
     U root5/geom/geom/src/TGeoVolume.cxx
     U root5/geom/geom/src/TGeoManager.cxx
     U root5/geom/geom/src/TGeoBuilder.cxx
     U root5/geom/geom/src/TVirtualGeoPainter.cxx
     U root5/geom/geom/src/TGeoShape.cxx
     U root5/geom/geom/inc/TGeoManager.h
     U root5/geom/geom/inc/TGeoVolume.h
     U root5/geom/geom/inc/TGeoBuilder.h
     U root5/geom/geom/inc/TVirtualGeoPainter.h
     U root5/geom/geom/inc/TGeoShape.h

     P root5/tree/tree/src/TBranch.cxx

Typical patched codes The following codes are tweaked

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.22.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 ...