HOWTO Create a Hall-D Software Release
The source code kept in the Hall-D repository is occasionally tagged to provide readily identifiable snapshots of the entire source tree. These can be used as a basis for comparison for either multiple studies being done by separate individuals or as a baseline for advancements in the software as it is developed. The tagging of release will usually coincide with major changes to the main trunk though accumulation of many smaller changes may also trigger the tagging of a new release.
The responsibility for the tagged releases lies primarily with the Hall-D Software Coordinator. While anyone with write access to the repository can make a new release (there are no access restrictions preventing it), they should generally be done with the forewarning and consent of the collaboration via the software group. The mechanism here is deliberately informal as the repository is undergoing active and continuous development in preparation for data taking in 2014. It is likely that the mechanism will be made more formal as we begin commissioning the GlueX detector and taking of experimental data. The Hall-D Software Coordinator will maintain the right to reject a tagged release.
In addition to official tagged releases, those with repository write access have the ability to make private tags of the code without restriction. See the section on "Making private tags" below.
Locations of tagged software releases
The following give the relevant locations of tagged release material.
Tagged software releases are named using a string of the form:
where YYYY is the year, MM is the month and DD is the day (leading zeros supplied where needed). The package should be something like "sim-recon", "hdds", or "calib". The sim-recon tree will require tagging most frequently, but the calib tree should usually be tagged at the same time and the hdds tree of appropriate. This naming scheme will provide sequential, unique tags that will allow one to easily see not only what the latest tag is, but how long ago it was made.
Source code in the repository
The source code of a tagged release may be checked out from the tags directory in the repository. To see what tags are available, issue the following command:
The release-YYYY-MM-DD directory will typically contain a complete copy of src and a file containing the RELEASE notes. Since the entire src tree is included in the tag, it can take a little while to check out an entire release. Part of the release can be checked out however by specifying the specific directory of interest in the checkout command.
The RELEASE file should contain information on what versions of the external packages the build was made and tested with on the various platforms. These should include:
- gcc/g++ version
- gfortran version
- JANA version
- Xerces version
- ROOT version
- CERNLIB version
In addition, the repository changes since the last release should be appended to the end of the RELEASE file for easy browsing. This can be done with a command like the following:
svn log -r 4063:4650 --verbose https://halldsvn.jlab.org/repos/trunk/src >> RELEASE
Documenting on wiki
A list of releases is maintained on the wiki and should be updated when a new release is made. The relevant pages are:
Binaries on the JLab CUE
Tagged releases will be built on the JLab CUE on the Hall-D group disk in the directory:
The tagged releases should have binaries for at least the platforms maintained on the CUE farm and user machines (currently Fedora 8 and Red Hat EL5). The top-level directory of the release should have a setenv_*.csh file for each platform for which binaries were built. The "*" is the platform specific string returned by the osrelease.pl script that can be found at /group/halld/Software/scripts/osrelease.pl. In addition, there should be a generic setenv.csh script that can be called from any platform and will source the appropriate platform specific setenv_*.csh script. Also there a script that accesses the setenv.csh for the current production version via a symbolic link: /group/halld/Software/builds/sim-recon/set_env_prod.csh.
When building binaries for a release, one can generate the appropriate setenv_*.csh script using the mk_setenv.csh script which can be found here:
A tagged release should compile and run on the following platforms: (Note that these will naturally change as new releases of the OSes become available)
- CentOS 5.3 (Linux)
- Red Hat EL5.6 (Linux)
- Red Hat EL6 (Linux)
- Mac OS X 10.6
If the person making the tag does not have access to all of the above listed platforms, they should simply post a request to the halld-offline mailing list for someone who does have access to verify the tagged code compiles and runs there. It will be the responsibility of the person making the tag though to ensure at least 1 person does actually do this.
If someone with write access to the repository wishes to make a private tag, they can do so without restriction (provided it does not inappropriately spend large amounts of resources like disk space etc.). Several locations for private tags exist in the repository. For special simulation studies, consider creating a directory in the https://halldsvn.jlab.org/repos/trunk/Studies directory. See existing subdirectories there for the adopted naming scheme.
For private tags that are either temporary or exclusively for private use, place them in the https://halldsvn.jlab.org/repos/trunk/home/username directory where username is your username on the JLab CUE.