Instructions for Building a Patched Version of ProductionExe

This file is located in the FarmTools package. To modify it checkout the package on fcdflnx3, edit FarmTools/doc/make_release.html and commit it to CVS. See CVS tips for instructions on how to do this. It is up to the production coordinators, offline shifters, and offline operations manager to keep this up to date. No one else will do it for us. Please fix problems as they are found. Shifters should report problems to the production coordinators if they are unsure how to fix them.

Building a Patched Version of ProductionExe (for Production Coordinators)

We would prefer the production farms use a version of ProductionExe from a frozen release such as 5.1.1, but we use patches to save the time and effort involved in creating frozen releases. Patches should only be used when the changes affect a small amount of code and make little or no difference in reconstruction results. Typical changes would be bug fixes that prevent rare crashes and have no effect on events other than the ones that cause crashes. Another typical patch would be a change to errorLogger messages. More significant changes should be approved by the Project Engineer (Liz Sexton) and Offline Operations Manager (Pasha Murat) and coordinated with any other interested people.

Notes before beginning

For each file to be patched into the release, you will need the filename, the path to the file from the top level of the release, and the version of the file to be patched.
In the instructions below, 5.1.1 is used as an example base release and 5.1.1g as an example of a patched release. Replace them with appropriate values for the release and patch you are working on.
A patch release should be frozen at the instant its tarball is sent to the farms. After a tarball for a patch release is sent to the farms, do not change it any more. If there are further changes to the patch release, then make a new patch release.

Naming conventions

Patch releases are named by appending a letter to the base release name. The first patch to a given release uses the letter "a", the second the letter "b", and so on. For example, the first patch to 5.1.1 was 5.1.1a, then 5.1.1b, and so on.
The definitions of all patch releases are reposited into CVS in the Release package. For example, the contents of the patched release 5.1.1g are defined by the file Release/patches/5.1.1g.patches (code browser link to 5.1.1g.patches)

Patching ProductionExe

Consider creating patch "g" to frozen release 5.1.1:

First, we assume a test release based on 5.1.1 has already been built. If not follow the instructions to build it ( Building ProductionExe and an Offline Operations Test Release.).
Second, we assume all the previous patches are already defined in a file called 5.1.1f.patches. (For the first patch to a release there will be no previous patches and no previous patch file.)

Log into fcdflnx3 as cdfopr and set things up.


  ticket
  cd /cdf/scratch/cdfopr/testRel/5.1.1
  source_me
  relwrite

Create the file defining the patches. If this is not the first patch for a release, then you start by copying the previous patch file as shown below. If it is the first patch, then skip the copy step shown below and create a new file.


  cd Release/patches
  cp 5.1.1f.patches 5.1.1g.patches
  chmod u+w 5.1.1g.patches
  emacs 5.1.1g.patches &
  ... edit and save file ...
  cvs add 5.1.1g.patches
  cvs commit -m "new patch file 5.1.1g" 5.1.1g.patches
  cd ../..

Add lines similar to the following lines at the end of the file. Do NOT delete the lines that list the previous patches. You only add new lines at the end.
```
#
#  Eliminate crashes in new data due to lack of silicon 
#  calibration tables.  From Jason
#
TrackingObjects/TrackingObjects/SiData/ChipStatus.hh -r 1.2
TrackingObjects/src/ChipStatus.cc -r 1.4
#
# Fix from Kurt to include timeouts
#
TrackingKal/src/KalZ3DVertexFinder.cc -r 1.20
#
# No changes, but this needs to be rebuilt for the ChipStatus changes
#
TrackingMods/
```
The lines starting with a "#" are comment lines. Include a brief one or two line comment for each change to remind people what the change was for and who wrote it.

There will be one line for each file modified in the patch. The line starts with the name of the file including its path from the top level of the release. Then one space and a "-r". Then one more space and the version number of the modified file.

There is also a directory shown at the end. This kind of entry is necessary when a package needs to be recompiled as a result of a patch even though no files in the package are modified. This is necessary sometimes when a header file is patched. Note the trailing "/". In general we try to avoid patching header files. Exceptions are made if we know for certain that the header file is only included in a limited number of known places.

Note that there are no spaces at the beginning or end of each line.

If the files modified by this patch were already modified in an earlier patch, you need to go back and comment out the earlier line for the previous patch or patches.

Changes to the cdfopr, FarmTools, Release, and Stntuple packages are not listed in the 5.1.1g.patches file. These packages are not used to build ProductionExe and we are not using the base release version of these files. Listing them as patches in 5.1.1g.patches will cause problems.
Go back and check the file you just created. You will make a mess in the next step if there are errors in it.
Install the modified files and packages in the test release. The following script will do this.
```
  bin/Linux2-KCC_4_0/checkout_patches 5.1.1g >& install.5.1.1g.log
```
The script reads the 5.1.1g.patches file to figure out what to do. If there are errors in that file it will not work properly. There are a few things that must be done before running the script above. The FarmTools and Release package must have been added to the test release and "gmake FarmTools.all" must have been executed. This should already have been done when the test release was created.

If patches from the previous release were already installed into the release, then the script will only install the new patches. If the previous patches were not installed, then it will install all the patches for the release including the previous ones. This is useful if you want to start over and build a new test release from scratch.
Double check that everything is OK. Check the log file you just created. You should see that the new packages were installed first. After the last package completes installing, there should be one line for each file that was checked out and installed in the test release. Check that the correct files were installed and that no other files were unintentionally modified.

This is important and you do not want mistakes so check some more things. Use the following commands to check that the correct packages are present and you have the correct version of the files in the test release.
```
  ls
  cvs status TrackingObjects/TrackingObjects/SiData/ChipStatus.hh
  cvs status TrackingObjects/src/ChipStatus.cc
  cvs status TrackingKal/src/KalZ3DVertexFinder.cc
```
If you found errors in the previous step, then fix them. Ask for help if you do not know how.
Clean up the libraries of the packages relying on the newly added packages. Example:
```
gmake CalorTimeObjects.clean
gmake CalorTimeMods.clean
....
```

Rebuild the libraries and executables. It is a good idea to do them all and keep them all in a consistent state. The next guy to use the test release will not know that you decided to only rebuild the maxopt libraries because you did not need the other ones.


  gmake nobin
  gmake Production.bin
  gmake FrameMods.bin
  gmake Stntuple.bin
  gmake FarmTools.all

  gmake Stntuple._base USESHLIBS=1
  gmake Stntuple._data USESHLIBS=1
  gmake Stntuple._obj  USESHLIBS=1
  gmake Stntuple._alg  USESHLIBS=1
  gmake Stntuple._ana  USESHLIBS=1
  gmake Stntuple._geom USESHLIBS=1
  gmake Stntuple._loop USESHLIBS=1
  gmake Stntuple._mod  USESHLIBS=1
  gmake Stntuple._val  USESHLIBS=1

  srt_setup -a SRT_QUAL=maxopt
  gmake nobin
  srt_setup -a SRT_QUAL=maxopt
  gmake Production.bin
  srt_setup -a SRT_QUAL=maxopt
  gmake FrameMods.bin

The final step is to test the release. Always, at least process the Z to ee validation sample, check the log files, and check that the histograms made from Stntuple's did not change compared to a previous release (or that the changes are understood). This is adequate only if the changes are very minor. One must decide on what tests to perform based on what software was changed. Do not send a tarball to the farms without testing it.
For more information on the CVS and SoftRelTools see CDF Note 3891

Last updated 28 February, 2005 by Mircea Coca
Original Author and maintained by Pasha Murat
Legal Notices