Revision as of 16:32, 10 May 2013

How To Build Online Packages with the SCONS-Based Build System

Introduction

SCONS is used in the online build system due to its superior scripting abilities and built-in knowledge of dependencies in different languages (n.b. Make is used in the offline). It is based on Python, the main scripting language used in the online. Package building is vastly simplified via a library of SCONS scripts that implement the Hall D directory and installation scheme.

Note: package developers should only need to make minor modifications to a few SCONS scripts to build their package (see SConscript customization section below)

Developers need only deal with the individual packages and their directory structures, and should work from their own personal accounts. Deployment of packages into the production environment, and the directory structures used for deployment, are the concern of software system managers (via the hdsys account), and will not be discussed here.

SVN is used for code management for all packages We use the same repository as the offline, but in a separate online area. Code management will not be discussed here.

Creating a new package

To create a new package in your own directory execute the Python script:

$ create_online_package myPackage

This will set up a package root and directory structure that includes SCONS files needed for building the package:

$ ls myPackage/
doc/  java/ SConstruct  src/

C and C++ code resides in the src directory, scripts in src/scripts. A package can contain many executables but only one library (named libmyPackage.so):

$ ls muyPackage/src/
binsrc/  libsrc/  scripts/  test/

Java code resides in the java directory, and Java packages should be organized as follows:

$ tree myPackage/java
java
|-- org
|   `-- jlab
|       `-- halld
|           `-- HelloWorld.java
`-- SConscript

Note that one SConstruct file appears in the package root dir, and one SConscript file in each of the src directories and in the java directory. You will need to customize the SConscript files, see below.

Building a package

SConstruct is the top-level SCONS file, and the package can be built by executing the "scons" command in the package root directory. SCONS will descend the directory tree and build the libraries, executables, etc. that it comes across (hidden subdirectories in the source areas hold intermediate build files):

$ scons
scons: Reading SConscript files ...

Processing package: myPackage
  --> Building for architecture Linux_RHEL6-x86_64-gcc4.8.0

scons: done reading SConscript files.
scons: Building targets ...
scons: done building targets.

Executing "scons install" will install what was previously built into an architecture-dependent directory in the package root directory, with subdirectories for header files, libraries, etc:

$ scons install
scons: Reading SConscript files ...

Processing package: myPackage
 --> Building for architecture Linux_RHEL6-x86_64-gcc4.8.0

scons: done reading SConscript files.
 
scons: Building targets ...
scons: `install' is up to date.
scons: done building targets.

$ ls
doc/  java/  Linux_RHEL6-x86_64-gcc4.8.0/  SConstruct  src/

$ ls Linux_RHEL6-x86_64-gcc4.8.0/
bin/  include/	lib/  scripts/

You can change the installation directory via a command line argument (highest precedence) or by setting the INSTALL_DIR environment variable:

$ scons install INSTALL_DIR=myDir

Many command-line flags and environment variables can affect the build, type "scons -H" for a full listing.

External Packages and Customizing SConscript Files

Libraries or executables may depend on other packages, i.e. to compile and link you need to find header files, other libraries, etc. If so you must define environment variables to tell SCONS where to find the package root directories:

$ setenv CMSGROOT someDir     # just CMSG will work, too

You tell SCONS to look for external packages in the SConscript files using the define_dependencies() function. The SConscript file below indicates that the executables depend on the et, evio and codaobject packages:

$ more src/binsrc/SConscript 

#  SConscript for binsrc
#
#  to customize fill in package dependencies
#
#  ejw, 16-apr-2013


Import('*')
from halld_lib import define_dependencies, buildBin


#  define package dependencies
define_dependencies(binEnv,'et evio codaobject')


#  build programs
buildBin(binEnv)

Note that the second argument to define_dependencies() is a space-separated list of package names (lower case). Fill in the names of all other packages your package must be compiled and linked with. If you miss one you'll get a compiler or link error which should make it obvious what you forgot to list.

Important: This should be the only modification to the build system you will need to make!

Behind the scenes system programmers create package definition files that tell SCONS where to find the header files for the package, where the libraries reside, what libraries should be loaded, etc. Contact a member of the Online group if one of these must be created for your package (only required if you want your library to be deployed in the production environment).