Introduction

The L1Calo scripts package (l1calo/scripts) includes the following utilities each of which is described in more detail below.

• buildpkg: builds a package (make, make install)
• ifdep.sh: executes a command if the current package is dependent on another named package
• getpkg: checks out the head, latest or specific version of a package
• getallpkg: checks out the head or latest version of all our packages
• updallpkg: does a cvs update -d for all checked out packages
• importpkg.pl: does a cvs import of a new package
• remoldver.pl: removes old versions of packages
• makerel.pl (and related scripts): builds a complete release of our software: either for the nightly build or specific versions
• latest: returns the latest tagged version of a package
• pkginfo.pl: returns a list of all our packages and information about them
• cdpkg: little utility for navigating package directories
• doxpkg.pl: runs Doxygen (or Javadoc) on a specified package
• doxallpkg.pl: runs Doxygen (or Javadoc) on all our packags
• downloadcmt.pl: downloads and installs versions of CMT
• setupcmt.sh: script to setup the L1Calo software
• edconf: wrapper for oks_data_editor useful for editing configuration database files in the dbFiles package area.

CMT related utilities

Some of these are copied/adapted from the datacollection group.

buildpkg

The buildpkg script builds a package via CMT using make then make install. The script can be run from anywhere in the package directory tree (ie you dont have to cd to your cmt directory).

Usage:

  buildpkg

  buildpkg QUIET=1

  buildpkg -l logdir
  buildpkg -L

  cmt broadcast buildpkg -l logdir

  buildpkg -K

NB you can set the environment variable BUILDPKG_ARGS (eg in your login scripts) to provide default arguments. Eg

  export BUILDPKG_ARGS=QUIET=1

NB the -l, -L, -K options must come first. Any other options are passed to make.

ifdep.sh

The ifdep.sh script executes a command if the current package is dependent on another named package. This can be useful in a cmt broadcast where you may want to rebuild just a few packages that depend on another package which has been updated.

Usage:

  ifdep.sh changedPkg command

  cmt broadcast ifdep.sh changedPkg buildpkg -L

NB the command is taken as the rest of the line so may be any number of arguments and does not need to be in quotes.

getpkg

Usage:

  getpkg -h dbFiles

  getpkg dbFiles

  getpkg dbFiles dbFiles-00-01-00

  getpkg -v -h dbFiles

getallpkg

The getallpkg script uses getpkg to check out all our packages. By default, like getpkg, it checks out the latest tagged version. Use the -h option to get the HEAD version of all packages. The list of packages is obtained from the pkginfo.pl utility. As with getpkg, you can also give the -v flag (as the first argument) to get the old style two level CMT directory structure. The default is -nv for no intermediate version directory.

Usage:

  getallpkg -h

updallpkg

The updallpkg script ensures that all checked out packages are up to date by doing cvs update -d in each one. The list of known packages is obtained from the pkginfo.pl utility. You can use the -n option to run cvs -n update -d to check what would be updated without actually doing it.

importpkg.pl

The importpkg.pl script imports a new package into CVS. Everything in and below the current directory is imported, but before this is done, a few checks and cleanups are made. The current directory must contain a cmt subdirectory. If either the current or cmt directories are missing a .cvsignore file, a suitable one is created for each directory. Then any files in the cmt subdirectory which CMT regenerates (*.make,*.sh, *.csh) are deleted. The script also deletes any binary directories it finds (eg i686-slc3-gcc323* etc). You will be shown the list of files and directories to be deleted and can cancel at this point. After all the cleanups, the remaining files and directories are imported into the CVS repository as the 00-00-00 version of the specified package (which must not already exist).

Usage:

  importpkg.pl myPkg

remoldver.pl

The remoldver.pl script is a simple utility to remove old versions of packages. As developers tag new versions of their packages, if you use getallpkg you will accumulate successive versions in your l1calo area (if you are using the two level CMT version directory style). Sometimes CMT seems to pick the wrong version to use, so it makes life easier if you only have one version around. If you run remoldver.pl from your l1calo area, it looks for old versions and asks if you want them to be deleted.

This script is only useful if you checked out packages with the old style CMT two level directory structure. If you do not have the extra version directory, this script should not be used.

makerel.pl (and related scripts)

The checkoutrel.pl, makerel.pl and finishrel.pl scripts build complete releases of all L1Calo software. The typical use is to make the nightly build of the HEAD versions of all our packages. Alternately they can be used to build a specific release using particular tagged versions of (a subset of) our packages. In the latter case, the set of tagged versions appropriate for an identified L1Calo release are obtained from the pkginfo.pl utility.

The scripts are used as follows. First checkoutrel.pl checks out all required packages from CVS. Next, makerel.pl is used to build the release for a given CMTCONFIG value. It does both debug and non-debug versions. makerel.pl can be used several times with different CMTCONFIG values. Finally finishrel.pl builds the reference documentation, checks for build failures, invokes relpage.pl to write web pages and cleans up. Optionally finishrel.pl can send emails to package developers if their packages failed to build.

Usage:

  checkoutrel.pl pid release relDir relPkg cvsroot guru emailAuthors cmtconfig
  makerel.pl     pid release relDir relPkg cvsroot guru emailAuthors cmtconfig
  finishrel.pl   pid release relDir relPkg cvsroot guru emailAuthors cmtconfig

-- where the arguments which control the scripts behaviour are as follows (not all are actually used by each script):
pid -- is an arbitrary numeric suffix to uniquely label the temporary working directory. The PID of the parent process is a good choice.
release -- is the release to build. The default is "nightly". Any other value known to the pkginfo.pl utility may also be given.
relDir -- is the default directory in which to build the release. The default is $HOME. The release name is appended to relDir.
relPkg -- is the CMT package to use as the release package. The default is L1CaloRelease. Other packages might be given for test purposes.
cvsroot -- is the value of CVSROOT to use. By default the current environment variable (if any) is used.
guru -- is the email address of the person to whom emails about general errors should be sent. The default is the local user running the script.
emailAuthors -- is a flag which specifies whether emails should be sent to the authors of packages which fail to build. The possible values of this flag are "authors" which sends emails to package authors (and the guru) or "guru" which instead sends the emails only to the email address of the guru. This may be useful for test purposes. The default is not to send any emails.
cmtconfig -- is the CMTCONFIG to be used for a given invocation of makerel.pl. By default the current environment variable (if any) is used.

latest

The latest script returns the latest tagged version of a package. It relies on your CVSROOT environment variable being set correctly and also requires that some special CMT hooks have been installed in your CVS repository. Chapter 13 of the CMT manual (available from here) explains what is required. This has been done for our CVS r/epository at CERN.

Usage:

  latest dbFiles

pkginfo.pl

The pkginfo.pl script gives some information about our packages. So far you can get the list of all our packages and the tagged version of a package included in a particular overall release of the L1Calo software.

Usage:

  pkginfo.pl list

  pkginfo.pl tag dbFiles release

cdpkg.sh

cdpkg.sh is a utility script for navigating among the directories of a CMT package (or to other packages) for those who dont like typing cd ../../xxx/yyy a lot. It must be sourced to have any effect and is probably most useful if it is invoked from an alias. Unfortunately it needs to know if it is being sourced from bash or zsh as their behaviour is different.

Usage:

  alias sd="source ~/l1calo/scripts/cdpkg.sh -b   # (for bash)
  alias sd="source ~/l1calo/scripts/cdpkg.sh -z   # (for zsh)

  sd src

  sd newPkg cmt

  sd inc

  sd -q obj

Utilities for generating documentation

The following two scripts are used to extract source code documentation from our packages.

doxpkg.pl

The doxpkg.pl script runs Doxygen and/or Javadoc on a checked out CMT package to generate reference documentation from the source code.

The script must be run from the CMT working area, ie where all the package/version directory trees are found. It looks for a Doxygen control file called package/version/dox/Doxyfile and for java source directories package/version/jsrc and package/version/$CMTCONFIG/java where the latter is where generated java source code is expected. If none of these files or directories is found, doxpkg.pl exits silently.

Usage:

  cd l1calo              # expect confL1Calo/version here
  doxpkg.pl confL1Calo

NB the doxpkg.pl script has effectively been superceded by a new CMT fragment dox which you can use via make dox from with the cmt directory of your package. See the documentation on the L1CaloPolicy package.

doxallpkg.pl

The doxallpkg.pl script runs Doxygen and/or Javadoc on all checked out CMT packages found in the current directory.

The script must be run from the CMT working area, ie where all the package/version directory trees are found.

Usage:

  cd l1calo       # expect package/version directories here
  doxallpkg.pl

Utilities for downloading software

Obtaining and installing both CMT and especially the Online software involve a number of files and operations on them. For convenience, these operations have been collected into a number of scripts.

downloadcmt.pl

The downloadcmt.pl script obtains and installs a specified version of CMT.

The first time you try to get CMT, you will need to run the script from a directory named CMT which is where the software will be installed. Subsequently, assuming you have sourced the CMT setup.sh script, downloadcmt.pl will try to use the value of the CMTROOT environment variable to determine where your CMT directory is.

Usage:

  mkdir -p somedir/CMT    # if it doesnt already exist
  cd somedir/CMT          # if CMTROOT is not defined
  downloadcmt.pl v1r18p20041201

L1Calo configuration scripts

setupcmt.sh

The setupcmt.sh script is intended to be sourced from your shell rc file. It expects that the TDAQ software setup.sh scripts have already been sourced.

It then sets up all the extra environment variables and paths required to run the L1Calo software.

setup.sh

The setup.sh script is an similar alternative to setupcmt.sh and can be sourced to setup the L1Calo development environment. It in turn sources setup scripts which are generated automatically, by our L1CaloRelease package, from CMT commands in our package requirements files. This is in contrast to setupcmt.sh which is maintained manually. Like setupcmt.sh it expects that the TDAQ software setup.sh scripts have already been sourced.

Online software related utilities

edconf

The edconf script is a wrapper for the standard oks_data_editor utility.

Our database files are kept in a CVS package (dbFiles) but are installed into the $L1CALO_ROOT area. There are links between the different database files and these all point to the installation area.

However if you want to edit a set of linked files inside the dbFiles working area, you want to update the source versions of the linked files, not the (readonly) versions in the installed area. All edconf does is to redirect $L1CALO_ROOT to point to dbFiles before running oks_data_editor.

Usage:

  cd dbFiles/version/partitions    # directory of partition files
  edconf L1CaloSlice.data.xml      # edit specified partition