workdir is the package used to run virtually all BaBar applications. Simple scripts with flexible options are used to run the programs; input and output remain local to the workdir directory.

The workdir package accommodates running several different applications. When the workdir package is checked out it comes with the following files:

CVS/: Directory with information about repository the workdir package was checked out from and which version of workdir was checked out
GNUmakefile: makefile for the workdir package
README: general information file
RooAlias.C: Subroutines that are loaded during ROOT initialisation
RooLogon.C: Initialisation code executed at the start of a ROOT session
kumac/: directory of useful kumac macros (for PAW)
pawlogon.kumac: Default kumac which is executed when PAW starts up in the workdir

The main focus of the workdir is on the Beta application.

Setup

Before starting to work from the workdir directory you must set it up by making the setup target.

gmake setup

(From workdir, the command is "gmake setup". From the RELEASE directory, as in the Quicktour, the command is "gmake workdir.setup").

This target is defined in the GNUmakefile of the workdir package, thus the command must be issued from that directory.

A main result of gmake setup is that several symbolic links are created. These links are: (Consistent with some Unix systems; * indicates an executable, / indicates a directory, and @ indicates a symbolic link.)

PARENT: This is a link to the production release directory under BFDIST that corresponds to the base release with which the new release was created.
RELEASE@: By default this is a link to the directory one level up in the tree, the release directory: ../
bin: This link points to the bin directory of the RELEASE directory: RELEASE/bin/
shlib: This link points to the shlib directory of the RELEASE directory: RELEASE/shlib/

Currently, if you do a gmake clean from within the workdir package itself, several of the soft links get deleted or reset, including the bin link which will no longer point to your own bin area - meaning that you will not be able to directly access your own executables such as BetaMiniApp which we used in the QuickTour. To remake these links correctly, you simply repeat the

gmake setup

command from your workdir directory.

Using workdir to Run Applications

workdir is designed to run applications. Since input and output remains local to the workdir directory, the locations of input and output files must be given with respect to the workdir directory.

Beta

An executable called BetaMiniApp* is created by the Beta packages discussed in Beta: the Analysis Package. This executable is run directly from within the workdir package.

The executable needs to be run with a tcl script as an argument. The tcl script has the responsibility of defining the analysis path of the user's application. The BetaMiniUser package provides example tcl files for several different possible BetaMiniApp* jobs:

MyMiniAnalysis.tcl: Bare outline of an analysis, suitable for filling in with additional code
MyDstarMiniAnalysis.tcl: Search for the decay chain D*+ -> pi+ D0, D0->K-pi+
MyK0MiniAnalysis.tcl: Search for a K0 -> pi+ pi- decay.
MyTimePointAnalysis.tcl: Fetch a specified FCT (Fast Control and Timing system) time point from the event.

Any one of these files can be used as an argument to BetaMiniApp.

The command to run a Beta executable from workdir is:

  workdir> BetaWhateverApp ../<Beta package>/<filename>.tcl

The second argument locates filename.tcl with respect to workdir. There are a few other ways to do this (besides "../"). You could make use of the RELEASE pointer

  workdir> BetaMiniApp RELEASE/<Beta package>/<filename>.tcl

or you could copy the tcl file into the workdir directory (or, better, place a symbolic link in the workdir directory without moving the existing file - see the WorkBook section on Unix) and issue:

  workdir> BetaMiniApp <filename>.tcl

In the Quicktour, you ran the job with the command:

workdir> BetaMiniApp snippet.tcl

snippet.tcl is actually NOT one of BetaMiniUser's tcl files, but it sources (executes) MyMiniAnalysis.tcl right away after setting a few parameters. You could just as well have changed the parameters in MyMiniAnalysis.tcl itself, and issued:

workdir> BetaMiniApp ../BetaMiniUser/MyMiniAnalysis.tcl

However most people prefer to use their own personal snippet tcl files to set parameters. That way, they avoid modifying standard BaBar tcl files more than they have to. Among other things, this makes it easier to describe your analysis when you ask other BaBar people for help.

As in the Quicktour, Beta applications often write output histogram files. The default name of this histogram for the BetaMiniApp* job run with MyMiniAnalysis.tcl is MyMiniAnalysis.root, but snippet.tcl overrides that and sets it to myHistogram.root. After analyzing some events with this Beta executable a file of this name is written to the workdir directory. Since workdir is the location of this ROOT file, workdir is also the directory from which you need to initiate a ROOT session to view the histograms.

Others

Recall that gmake setup generates a link bin->RELEASE/bin. Executables that you have generated in the release directory (pointed to by RELEASE) are on the standard SRT path. This enables the user to run any executable in the release directory from workdir. The input and output files of such an executable may thus remain local to the workdir directory.

In the Quicktour, this meant that when you issued the command "BetaMiniApp snippet.tcl", the system looked in RELEASE/bin/$BFARCH/ for your BetaMiniApp executable.

More Uses for the workdir Package

In some development situations it may be useful to switch base releases frequently. The workdir package accommodates this. Packages must be checked out from a test release directory. However, once checked out, the workdir directory tree can be moved out of the release directory tree you obtained it in and into a stable, personal working area such as your home directory. Thereafter it can be used with a user-selectable release directory.

A gmake target, migrate, has been defined to move the complete workdir directory tree to another location in a user's AFS space. The complete syntax (from the workdir directory) is:

  gmake migrate TODIR=<directory path>

For example, gmake migrate TODIR=~/workdir would move the whole workdir structure into a directory named workdir in the users home directory. In practice I found that the ~ character for a users home directory was not recognized by the migrate target. If you have troubles try relative path names (for example TODIR=../../workdir). Also, migrate is a misnomer since the workdir directory tree is not moved to the new location but rather copied to the TODIR.

Recall that RELEASE (in the workdir directory) is a link to the directory of the test release to be used by workdir. The default of gmake setup sets RELEASE to ../. This is presumably the directory of the test release used to acquire the workdir package. After you have moved the workdir package directory tree outside of a test release, you need to issue gmake setup to setup with respect to any given test release. The syntax is as follows:

   gmake setup RELDIR=<release path>

You will also need to reissue gmake setup in the original workdir directory. After the initial setup this command can be used (from the new workdir directory) to easily change test releases. This way you can work in a stable environment (for example your home directory) and switch between releases as you please.

Care about using gmake clean in workdir

Often when compiling your work you will want to issue a "gmake clean" command to clear out libraries and binaries from a previous problem with compiling or linking. This should always be done from your release directory. However, if often happens that one accidentally issues a "gmake clean" command from the workdir directory. The main effect of this command in workdir is that is removes the symbolic link that workdir has to your /bin directory - meaning workdir can no longer 'see' any binaries you have built. This is easy to fix... whenever you accidentally do a "gmake clean" command in your workdir, just issue a

gmake setup

command from workdir to rebuild the link. (Or you can do

gmake
workdir.setup

from your release directory.)

Back to Workbook Front Page

Author: Tracey Marsh
Contributors:
Jenny Williams

Last modification: 20 January 2006
Last significant update: 13 June 2005