Overview

Because of the number and complexity of its external dependencies, the The easiest way to build the SLIC simulator package slic binary is using the SimDist CVS project.

Depending on your system speed, the entire build process will take around 2 hours, but starting the automated build only takes about 5 minutes.

Packages in the Distribution

There are nine software packages built by SimDist, only one of which is optional.

These are described in the table below.

Versions are current as of 1/12/2011.

Supported Platforms

The SimDist project requires a Unix-like environment. The CVS head currently builds successfully on Linux (tested on Redhat Enterprise Linux), OSX, and Windows using Cygwin. The recommended compiler version is gcc 4.1 or greater, though depending on your platform, a gcc 3 series compiler might work.

Build Instructions

Required Build Tools

SimDist requires a number of different build tools beyond the standard ones you may have on your system. This is because the project has a lot of external dependencies, each of which has its own build system.

Here is the list of required tools to build SimDist successfully.

• gcc
• make
• cmake (optional)
• java
• wget

If one or more of these is not present, then you or your admin should install it before proceeding with these instructions. If you are unsure of which version to use, just get the most recent version that works on your platform. This should work fine.

Obtaining SimDist

SimDist is a module in the SLAC CVS repository. You can check it out with the following command.

cvs -d :pserver:anonymous@cvs.freehep.org:/cvs/lcd co SimDist

This will create a directory called SimDist in the directory where this command is run. The next sections will cover building SimDist once you have checked it out.

Basic Build Procedures

If you want to execute each step of the build yourself, these are the commands used by the build script (covered in next section).

...

This will create the log files configure.log and build.log, which might be useful if your build fails.

Configure Script

Simdist uses a configure script generated by Autoconf. This script only accepts a few options, as the slic binary has a standard set of external dependencies, none of which are optional.

The --disable-opengl option can be used to turn off OpenGL visualization support by Geant4. This may be useful if you only need to run slic in a batch computing environment.

cd SimDist
./configure --disable-opengl

The performance of the Geant4 package can also be improved if its informational messages are turned off.

./configure --enable-g4verbose=no

The arguments listed under "Fine tuning" and "Optional Packages" are generally not supported. For instance, you cannot disable individual packages, as they are all required. Also, the "influential environment variables" are generally ignored by SimDist, as each package has a different set of compiler arguments.

Disabling Geant4 Visualization

Sometimes it may be useful to disable Geant4 visualization entirely, as at has many dependencies that may not all be present on your host system. Execute this command from the SimDist directory to disable Geant4 visualization.

./configure --enable-g4vis-none

This should set the variable G4VIS_NONE to 1 in the Geant4 environment configuration file at packages/geant4/env.gmk.

Testing the Build

Try executing this script when the build completes.

...

If there is an error running the slic binary using this script, then check your build logs (starting at the top) for error messages.

Starting a Clean Build

To cleanup an existing build and start a new one from scratch, execute these commands in the SimDist directory.

make distclean
./configure [options]

This should remove all package binaries and return the project to a clean state. The build can then be executed in the normal fashion.

Creating a Tarball

The slic package includes a target for creating a .tar.gz file containing the slic binary and its runtime dependencies.

make dist

The tarball will be named based on the slic and Geant4 versions and your platform. It will appear one directory below your SimDist directory.

Troubleshooting Common Build Problems

...

If all of the above fails to get a working SimDist, then send email to jeremym AT slac DOT stanford DOT EDU edu with the following.

1. OS variety and kernel version e.g. for Linux

   No Format
   cat /etc/redhat-release; uname -a

2. gcc version

   No Format
   gcc -v

3. 32 or 64 bit

   No Format
   uname -m

4. log of global configure command

   No Format
   cd SimDist; ./configure &> myconfig.log

Please attach or inline the snippets containing build errors from your logs. I don't want full log files, if possible. Usually, the first error in the log is the most relevant.

Advanced

...

Build Commands

The SimDist build system is based on GNU Autoconf and Make. Individual packages can be manipulated using make commands from their appropriate package directories.

...

make              # execute standard build targets in order
make cvs          # checkout from cvs
make packageclean # removes the current build 
make download     # download a tarball of the package
make config       # execute configure script or commands
make compile      # compile the libraries or binary
make install      # install the package

Most packages support Each package supports either a cvs or a download command, depending on whether they are accessible it is contained in the SLAC cvs repository. Those External packages that are not in a SLAC cvs are most likely only accessible via wget download.are retrieved using the wget program.

How SimDist Works

Package System

SimDist operates on a loose system of package configuration, which sets a number of standard build variables in the configuration stage for each package in the packages directory. A configure script in the base directory generates the actual Make file fragments for the packages, depending on the configuration selected and on the properties of the local host. Following the Autoconf build system's conventions, there are .in files in the package directories that are used by the configure script to generate these Make fragments. The configuration of individual packages is defined in the Autoconf file at build/packages.m4. This sets and substitutes the necessary variables for the build system by calling the Autoconf macro associated with each package.

Each package also has a file called package.gmk where it may override or add build settings, where the default settings for packages are overridden or additional settings can be added.

For instance, sometimes it is useful to enable verbose compilation and linking when building slic (the final package to be built by an in-order build).

To do this, you can manually add an option to its package.gmk file in packages/slic/package.gmk.

...

Each package has different possible options for this particular variable. The above examples will not work on other packages with SimDist, only the slic package.

Package

...

Variables

The core of the SimDist build system is in build/package.gmk where a standard set of build procedures is defined for each a generic software package. This includes automation of the normal procedure of getting sources, configuring them, executing the build command (usually 'make'), and installing the binaries or These procedures include automation of fetching package source codes, configuration, execution of build commands, and installing binaries and headers.

Each package may have some or all of the following defined . The Make fragment is pretty flexible about working around missing informationwithin its package.gmk file generated by SimDist's global configure script. Most of these variables are given reasonable defaults and do not need to be specifically defined by a given package.

...

Both the package.gmk and env.gmk files are rewritten when a global configure command is executed from the SimDist base directory. This is by design, following the convention of Autoconf. If you really want changes to stay, the .in files can be edited. But only a few of the variables are likely going to be useful, such as PACKAGE_CONFIG_OPTS, for passing options to the package's configure script.

Package Versions

The version of each package is specified in the file VERSION within each package's directory. For example, the slic version is at packages/slic/VERSION. The format of this file is as follows.

[package_name] [package_version]

For example, this is used to specify slic's CVS head.

slic HEAD

Not all packages will support the HEAD argument, mostly just SLAC cvs packages like slic, lcdd, gdml, and lcio.

Specific tags should generally be in this format.

v[version]r[release]p[patch]

For instance, to use slic version 1.2.3 (a made-up example), the version file should contain this.

v1r2p3

SimDist can usually figure out how to manipulate these version tags into the format required for accessing the package's sources via cvs or download. The only exception to this currently is the HepPDT package. You should not change the version of this package, anyways. For other packages, it may be useful to override the defaults. For instance, selecting a different Geant4 version might be necessary. You can do this by editing the Geant4 version file at packages/geant4/VERSION. The Geant4 version string may also have a b instead of a p to designate beta versions.