Build system notes

This is an guideline for discussion, as we institute procedures for defining builds and tests on our supported platforms. It will also be a log.

20-Mar-2003

Done: ScienceTools, individual compilation.

Not Done: New Packages

9-Mar-2003

Wish list for Alex: 

• ScienceTools  pages, similar to GlastRelease: Alex will implement this immediately, starting a new set of web pages
   

•  Individual compilation: This means that the system attempts to compile all packages even if another package one depends on has failed, and will put the output into separate files for Web access, like the test results. This is “not too hard to do”, the skeleton already exists, and Alex estimates will take a “week or two”. The compilation process will include an initial test for validity of the package.
   

•   New packages: Alex will start a cvs branch of the GlastRelease package, for packages to appear on the “latest” list without actually being included in GlastRelease. No time estimate yet.

• Reliability: Understand and fix the cause for failures of the system to run every evening.

• Documentation: At least a skeleton description of the code.

Other issues:

• Design and functionality of  a package status web page, similar to Alex's RM status page, but with indications of the build status, access to source, and  doxygen output (see below)

• A web-based system by which GlastRelease is modified.

• Implementation of a system to run doxygen. I note that there is a script in the repository that might be a starting point for someone. (Who?) See this link.

30 Jan status

Package guidelines

• folder conventions
  • cmt - requirements file
  • <package> - external header files: if there are none (the case for packages not defining interfaces), need not exist.
  • src - all other header files, source to build binaries. Can have folders below.
  • src/test - test program code
  • doc - release.notes.
    • doxy-html/  for doxygen output. Expect a mainpage.h file in either src or the include folder.
    • html/ for static html-format documentation
• test program

  An executable named test_<package> is assumed to be a comprehensive test program. It must build, and run without errors. A pattern, package_test, is defined in GlastPolicy v3 and afterward, to facilitate this. It uses a main program that returns the Gaudi error condition. (Non-zero if any error.)

Policy Issues (identified by KY), with THB comments

• Build log files must be kept, and be made readily available. I suggest a web-based system, with liberal use of  red color to indicate packages that did not build. Do not send detailed logs as mail, just URL's.
• Release manager can automatically (when detecting a new tag) generate new Doxygen docs, and run the build. But since individual packages do not identify the specific versions of dependent packages, what are the rules to determine these? Not the latest tagged version! I suggest instead using a CMTPATH which will have possible values from previous successful builds.

Status following core meeting 4 Sept

• KY will implement a web viewer for the log files, expected to be ready Oct 7.
• THB defines a use case, which is not clear that GLAST_RM can solve: there is a new version of trigger (v2) which depends on a revised GlastPolicy (v3). The rest of trigger's dependencies can be satisfied by pdrApp v6r4. Further, trigger implements a formal test program, with the help of a new pattern in GlastPolicy. KY will send instructions.

Last Update: 06/01/2010 15:45 -0700

Karl's note to Richard, Toby and Heather:

As per Richard's request in the core meeting this is an outline of some of the policy issues (as I understand them) that need to be resolved before the appropriate button(s) for the release manager is(are) put in place. Feel free to add or remove any. Where to build: This isn't really an issue but for completeness I've added it to the list. Obviously we want the button to distribute, build and run tests on the 3 supported platforms. This is straightforward for Linux and Unix; the only remaining issue is how to do this on Windows; e.g. since vcmt is really an interactive tool would it be better to just invoke a script that runs the cmt and test commands directly (I vaguely recall that there are (or at least were) command line equivalents for most of the things that can be done in Visual Studio). Also, I don't know how to invoke scripts remotely on Windows boxes (other than via something like Citrix); is this easy on the UW server ? What to build: The most logical structure as I saw it was to build and run tests for packages at the request of package maintainers and possibly also try to build the head versions of a specified set of packages periodically (nightly...?). The main model was that some software committee decrees that it's time for a release and somebody then pushes the button. Building the head versions was more of an afterthought and meant as a convenience for maintainers. As such the current version of the release manager will take as argument a package and version and try to build that and run tests, in the executables directory with the name test_packageName. Currently the release manager only checks the return value of the test and reports it and any output to the maintainer. An important policy issue is to determine a standard output format for tests and a way of presenting that output to the package maintainer. The release manager also has a mode that checks for new tags and if found currently only generates doxygen documentation and updates the web pages specifying the list of current packages, and provides links to the new documentation. This was partly a vestige of incorporating some of Thomas's scripts but also provides infrastructure (in the form of a perl library) for performing various operations (e.g. builds) if triggered by finding new tags. Given this library it would be easy to implement (via invocation of cmt commands, as the build mode currently does) various build scenarios like the one Toby mentioned in the meeting (building all the latest tagged packages). Building the head versions of packages can be easily implemented by just checking for the latest tags (via the above library  functions) and performing the cvs "add a later tag trick", then building and testing as is currently done by request. It's not clear that an automated build and test mode (as opposed to just pushing the button when we want to release a package) is that useful as it seems we're typically in rapid development mode. This would generate a lot of messages and developers might just start to ignore them. BTW if anybody wants to try the current version on their favorite package (or least favorite for that matter) the program is: /afs/slac.stanford.edu/g/glast/ground/scripts/ReleaseManager/GLAST_RM.pl If you're going to move the program anywhere; you'll need the module libraries: CMTpackages.pm and Doxygenator.pm that are in the same directory. Note: the -c option to GLAST_RM.pl to check for new tags and build the docs won't work until we get some more web space (I forgot to request some from SCS but will do so tomorrow)

Here is the help for GLAST_RM extracted from the script.

Usage: GLAST_RM [-h] [-r package_version] [-d package_version] [-c]
-h print this usage message
-r process package_version as a release package
-d generate Doxygenator documentation for package_version
-c check for new tags of checkout packages and update the Doxygenator 
   documentation for them as well as updating the package list at:
   http://www.slac.stanford.edu/exp/glast/ground/software/LatestPackages/index.htm

Example 1: GLAST_RM -r pdrApp_v3r1 
    processes version 3 release 1 of the pdrApp package as a release 
    package (i.e. build and run tests)

Example 2: GLAST_RM -d pdrApp_v3r1 
   generate documentation for version 3 release 1 of the pdrApp package

Status Sept. 25

• To run the script, users need to add /afs/slac.stanford.edu/g/glast/ground/scripts to PATH.
• Packages are checked out and built at /afs/slac.stanford.edu/g/glast/ground/packages/vol1/pdr

  with two releases: pdr_v6r2 and pdr_v6r4. Each folder has the complete list, not allowing for sharing packages that have not changed, like all of Gaudi.

  Further problems: it all has group write privilege, so cannot serve as a common build.

• An attempt to test failed: I typed "GLAST_RM.pl -r GaudiSys_v7. It died with no output.

Status Sept. 27

Karl's preliminary scripts now available for users logged onto SLAC: testPack.pl, usage:

testPack.pl  packageName [version | head ]

What happens:

1. Does a recursive cvs checkout to /tmp/packageName_version
2. Builds with a cmt broadcast gmake from pacakgeName
3. puts log file in ~/packageName_version_out.txt
4. puts error in ~/packageName_version_err.txt
5. Send e-mail to user if errors
6. Error summary put into web, at http://www.slac.stanford.edu/exp/glast/ground/software/build_tests/

Problems:

• Cannot do it from command-line ssh, since needs to write to users home, in afs space
• recursive checkout is fatally flawed, must do it separately.
• Need to easily use  CMTPATH for previous builds. Perhaps as a parameter to set CMTPATH? Script should show the value, do a cmt show uses and cmt chow path for the error summary.
• Write to /tmp will fail if someone else has already checked it out/
• Error detection is flawed somehow: going in and doing it again by hand often is then successful

Status 30 Jan 2002

Most of the problems have been addressed. (Don't know which remain yet.)

Scripts for the Release manager have been moved to /afs/slac.stanford.edu/g/glast/ground/scripts/ReleaseManager.

help output for GLAST_RM is now:

 Usage: scripts/ReleaseManager/GLAST_RM.pl [-h] [-r package_version] [-d package_version] [-c]

 -h  print this usage message

 -r  process package_version as a release package

 -d  generate Doxygen documentation for package_version

 -c  check for new tags of checkout packages, update the Doxygen
     documentation for them, update package list at:
       http://www.slac.stanford.edu/exp/glast/ground/software/LatestPackages/index.htm

     and try to build head versions of checkout packages
     Example 1: scripts/ReleaseManager/GLAST_RM.pl -r pdrApp_v3r1  processes version 3 release 1 of
      the pdrApp package as a release package (i.e. build and run tests)

     Example 2: scripts/ReleaseManager/GLAST_RM.pl -d pdrApp_v3r1  generate documentation for version 3
      release 1 of the pdrApp package
      

And for testPack:

    Usage: scripts/ReleaseManager/testPack.pl package version [-c]
     -c use the users CMTPATH environment varaible

     Example 1: scripts/ReleaseManager/testPack.pl pdrApp v3r1 - try to build and 
     run test for version 3 release 1 of the pdrApp package

     Example 2: scripts/ReleaseManager/testPack.pl -c pdrApp head - try to build
      and run test for the version of the pdrApp package at the head of the cvs
       repository and use users CMTPATH
    

Example output from a testPack run this morning: Some requests:

• could the log be enclosed in <PRE> ..</PRE>?
• could the error reflect an actual error? (like a compilation error)
• could the output include the command line?
• how about saving the logs, rather than overwriting them?
• how about some diagnostic output, like running cmt show uses and cmt show path? (Capturing using <PRE> into a table?)

Suggestion: have one of the students work on fixing up the web display.

Notes added 16 Feb 2002

A page describing testPack now exists.

There is no longer a help output: the -h option is ignored:

noric02:~[688]$testPack.pl -h
Global symbol "$testNotExist" requires explicit package name at /afs/slac.stanford.edu/g/glast/ground/scripts/ReleaseManager/testPack.pl line 214.
Execution of /afs/slac.stanford.edu/g/glast/ground/scripts/ReleaseManager/testPack.pl aborted due to compilation errors.

The requests for formatting the output have not been addressed.