Program Builder

This page explains how run the program builder to create programs using the standard D0 frameworks, such as d0user.

Refer to the VMS program builder documentation in d0$docs:program_builder.doc for general information about the program builder.

Frameworks. Program builder frameworks.
Running program builder.
Program builder output files.
The program builder link script.
The program builder setup script.
Specifying input files.

Frameworks

The following frameworks are known to work reliably in UNIX.

d0reco
d0user
d0geant

The status of the following frameworks is uncertain. Undoubtedly they could be made to work (if they don't) if someone is interested in them.

calor_off
examine2

Running Program Builder

The UNIX version of the program builder is an executable file with the name "pbd" that resides in the top directory of the program_builder section of d0library ($d0program_builder). The directory containing the program builder executable is contained in the standard D0 PATH environment variable.

The program builder executable is invoked by typing "pbd" followed by any standard program builder command line switches (/frame, etc.). Note the following points:

Type "pbd" in lower case.
Program builder switches are preceded by / (slash), as in VMS.
The first switch must be separated from "pbd" by a space or tab character. Subsequent switches do not need to be separated.
Characters that are special to the shell (e.g. parentheses) should be escaped using \ (backslash) or quoted to protect them from the shell. The character % (percent) that is used to specify combined packages is not considered special.

Examples

A simple single package:

% pbd /frame=d0user/pack=isagen

Multiple packages:

% pbd /frame=d0user/name=isagen/pack=\(isagen,isanalyze\)

A combined package:

% pbd /frame=d0geant/pack=fulld0%

A complex example:

% pbd /frame=d0user \
    /name=bprime \
    /zebcom=200000 \
    /zebstp=500000 \
    /pawc=500000 \
    /packages=\(calor,\
                verify_zebra,\
                run_select,\
                strip_trig,\
                udst_to_dst,\
                reco_version_select,\
                duplicate_event_filter,\
                drop_caph_alg,\
                compute_em_quality,\
                compute_mu_quality,\
                cafix,\
                fix_jet_et,\
                particle_select,\
                top_btag,\
                make_udst,\
                unix_utility\)

As the last example shows, the UNIX command line can accomodate a large number of continuation lines (lines that end with \ are continued on the next line). Such a complex invocation of the program builder would normally be stored in a shell script. Alternatively, one can create a combined package.

Program Builder Output

In VMS, one invocation of the program builder produces the following output files:

Hooks file (.for and .obj).
Setup script (.com).
Link script (.lnk).
Debug and non-debug link options (.opt).

The UNIX version of the program builder also produces the above files (except .obj), but only the hooks file (.for) is useful. In addition, the UNIX version of the program builder produces the following shell script files.

Setup script (.csh).
Link script (_lnk.csh)

The UNIX specific (.csh) files may also be created in VMS by specifying the switch /unix on the command line. The /unix switch is intended for use during production releases.

In UNIX, the concept of link options files does not exist. Therefore, the content of the VMS .opt files is contained in the UNIX link script directly.

The UNIX version of the program builder does not automatically compile the fortran hooks file. This too is automatically handled by the link script.

Upon termination, the link and setup scripts generated by program builder are not executable. They must be made executable by hand. The following command suffices to do this:

% chmod +x *.csh

As in VMS, the UNIX version of the program builder looks for framework, package and combined package .pbd files in the current working directory and in the pbd section of d0library ($d0pbd).

Example

The following example shows all of the steps needed to create and run a program builder program.

% pbd /frame=d0user/pack=isagen     # Run program builder
% chmod +x *.csh                    # Make program builder scripts executable
% isagen_d0user_lnk.csh debug       # Link debug executable, deb_isagen_d0user.x
% isagen_d0user_lnk.csh             # Link optimized executable, isagen_d0user.x
% isagen_d0user.csh                 # Setup symbolic links
% isagen_d0user.x                   # Run optimized version of program

The Program Builder Link Script -- Linking Private Code

Ordinarily, the link script generated by program builder only knows about the hooks file and standard D0 libraries.

The first argument to the link script specifies whether to link in debug or optimized mode. If the first argument is the word "debug", or reasonable variants, such as "deb" or "DEBUG", then a debug executable is created. Otherwise, an optimized executable is created.

The second and subsequent arguments to the link script are interpreted as additional link objects (e.g. object files and libraries). These arguments are intended for the inclusion of private code, which can either be replacements for standard d0library code, or unreleased code.

Example

The following example shows how to link private code into a d0geant executable. The private code is stored in a subdirectory called "local."

% pbd /frame=d0geant/pack=fulld0%   # Run program builder
% chmod +x *.csh                    # Make program builder scripts executable
% userlib local/*.for               # Generate makefile for private code
% make debug                        # Compile private code into debug library,
                                    #   deb_userlib.a
% fulld0_d0geant_lnk.csh debug `force_load deb_userlib.a`
                                    # Link debug executable including private
                                    #   code from deb_userlib.a

The first three of the above steps only need to be done once. The last two steps should be done whenever any private code needs to be modified.

The Program Builder Setup Script

The only action of the UNIX program builder setup script is to make symbolic links to RCP files or other data files. Any required libtest's or libprod's must have been done beforehand.

The program builder setup script can be invoked with up to four arguments. The user is prompted for any missing arguments.

The fourth argument is always the "rcp type" argument. This argument takes values specified in package pbd files, such as "MC" for Monte Carlo data, "TB" for test beam data, "COSMIC" for cosmic ray data, and "" (nothing) for regular data. This argument is case sensitive and should normally be specified in upper case.

The first three arguments are framework specific. The d0user and d0geant frameworks do not look at these arguments. The d0reco framework interprets the framework-specific arguments as "input file", "sta directory" and "dst directory" respectively.

Specifying Input Files

Any program that reads events using the D0 event utility (see d0$event_util:event_io_guide.doc ), can read data using any of the following kinds of input files:

Zebra data file (sta, dst, udst, etc.) specified using native UNIX filename syntax.
Zebra data file specified using VMS filename syntax
FATMEN generic names.
D0DAD virtual streams.

In most cases when using disk resident data, the type of input being used is sensed automatically.

In the case of the d0user framework, an input stream consisting of multiple files of any of the above types can be specified using wildcards or file lists (see d0$d0user$frame:zbinpf.for ). A file list is a file or symbolic link with the specific name "file_names" that contains a list of input files to be processed.

Program Builder

Table of Contents

Frameworks

Running Program Builder

Examples

Program Builder Output

Example

The Program Builder Link Script -- Linking Private Code

Example

The Program Builder Setup Script

Specifying Input Files

Links to other D0 pages