SCONS for online
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. The result is that package developers will likely only need to make one-line modifications to SCONS scripts to build their package.
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, is 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, Java code in the java directory. Scripts reside in src/scripts:
$ ls src/ binsrc/ libsrc/ scripts/ test/
Java code should be organized as follows:
$ tree 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 here. SCONS will descend the directory tree and build the libraries, executables, etc. that it comes across (hidden subdirectories in the source areas old 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 myPackage 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 roots:
$ setenv CMSGROOT someDir
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.
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 (required to have your package deployed in the production environment).
