Working the Workbook

(Anne 3/12: I'd take this login/setup stuff out and reference the 'getting started' page. This is redundant)

The source window and the build window

When you ran the script, it created a directory for you:

   /ds50/app/user/<your name>/workbook-tutorial

When the script finished, it left you in this directory. This is true whether you ran it for the first time or whether you ran it after logging out and logging in again. It also created two subdirectories of this directory:
art-workbook  build-workbook

In the following we will call art-workbook your source directory and build-workbook your build directory.

The most convenient way to use the art-workbook is to open two windows on ds50. You can either log in twice or open an xterm from the first window. In one window you should cd to your source directory and in the other you should cd to your build directory. We will call these windows your source window and your build window.

In the Source Window

Every time you log in, run:

source /ds50/app/ds50/ 
cd art-workbook

In the Build Window

Every time that you log in:

  • login
  • source /ds50/app/ds50/
  • cd to the build directory
  • source ../art-workbook/ups/setup_for_development -d

It is important that you do these steps in order. You do the same steps the first time you log in and on all subsequent logins.

The first time that you log into your build window and source /ds50/app/ds50/, it will create two files and two empty directories:

art_workbook-v0_00_01  bin  cetpkg_variable_report  diag_report  lib

It will also make printout. An example of printout from a successful setup is found at:


The last line of that printout tells you to use a particular cmake command; DO NOT type that command - it is not necessary.

Prerequisites (Anne suggests adding)

  • You need to know the C++ terms: module, library, header, #include, source, implementation (which I - Anne - think are like functions - check)
  • You need to know 'UPS package'
  • art_workbook vs art_workbook_base

Building the Workbook Exercise Code

Follow the instructions in the previous section for logging in to the build window. To build the code type the command:

  • buildtool

On an unloaded ds50, this will run in about 1 minute and an example of successful output can be found at:


If your build does not end in:
INFO: Stage build successful.

contact the art team.

At the DS50 tutorial, this might run more slowly due to contention from too many people working at once; we will learn.

When the build has completed, in your build directory type

ls lib*

This will show that the build system created a large number of shared library files, which end in .so.          

Now go back to the source window and type:
find . -name \*

You should see that there is a one to one correspondence between source files ending and libraries ending in The naming pattern should be clear: the library name contains the relative path to the module source, starting from the root of the package.

(Anne 3/12: say why this naming convention is important)

Need something about the build system here. And a link to details.

Finding External Headers Used by the Workbook

The instructions below will sometimes tell you to look at the source for included header files.

Source code for that art-workbook is available in your source window. You can also browse the source code repository, listed below. Many of the other packages used by the workbook have either a source code browser or an online reference manual. These can be found at:

There is also a second option for finding the headers, which may be particularly convenient for those with powerful ack/find/grep/awk/perl skills. All UPS packages define environment variables, that are used by the build system to find header files and libraries. You can use them, too, but only from your build window in which the necessary environment variables are defined. For example, to find the header file from the line, enter in your build window:

#include "artwb/MCDataProducts/GenParticleCollection.h" 

look in:
ls $ART_WORKBOOK_BASE_INC/artwb/MCDataProducts/GenParticleCollection.h

In almost all cases, the first element in the include path tells you which environment variable to use. (Anne: 'artwb' tells you to use $ART_WORKBOOK_BASE_INC?) Hopefully the other associations are reasonably clear; see the examples below. Some other examples are:

ls $ART_INC/art/Framework/Principal/Event.h
ls $CLHEP_INC/CLHEP/Vector/ThreeVector.h
ls $CETLIB_INC/cetlib/pow.h

ROOT delivers its headers in a single directory, given by $ROOT_INC. So for ROOT, enter:
The art-workbook exercises do not include GEANT4 but the obvious extension works for finding GEANT4 files, which are also delivered in a single directory and all of which begin with "G4".

When you wish to find source code for the implementation ( .cc ) files, you can often, but not always, find it in the UPS product:

ls $ART_DIR/source/art/Framework/Principal/

and similarly for the other packages.

Exercise 1

Exercise 2 and Beyond

The writeups for Exercises 1 through 9 are in Workbook Exercises
The original outline is available as bullet points on the art-workbook wiki . Work through the next exercises, using these notes as a guide. Ask lots of questions.

You might find these other web pages useful:
List of art related documentation from other experiments
The Mu2e documentation on the .fcl language
The art documentation on how art understands .fcl files