LOOS  v2.3.2
Building LOOS

Building Basics

LOOS requires SCons and the Boost (1.36+) libraries. For macs, it also requires XCode be installed (free download from the Mac App Store). On Linux, Atlas is strongly recommended, although the standard LAPACK and BLAS should work. If you plan to modify the parser (and you probably shouldn't), then you'll need the GNU utilities flex and bison. Although LOOS comes bundled with pre-built documentation, you can regenerate it. Doing so requires doxygen and graphviz be installed.

To build LOOS, go into the LOOS distribution directory and run scons. If your libraries are installed in non-standard locations, you may need to tell LOOS where its required components are. There are two ways you can tell SCons where to look for those libraries. The first is to specify it on the command-line. The second, described later, is to use a custom.py file.

Using the command line, if you have Boost installed in /usr/local/boost_1_54_0, build LOOS using:

scons BOOST=/usr/local/boost_1_54_0

This will tell SCons to look in /usr/local/boost_1_54_0/include for header files and /usr/local/boost_1_54_0/lib for libraries. In some cases, the directories may not follow this convention, so you will need to specify the individual directories explicitly:

scons BOOST_INCLUDE=/usr/local/include/boost BOOST_LIBPATH=/usr/local/lib

SCons will, by default, try to figure out the appropriate threaded Boost libraries to use and, if it cannot find those, it will use the non-threaded versions. While the build system can handle most variants of the Boost library names, it may not catch all. To explicitly set the libraries LOOS is linked with, set the BOOST_LIBS variable to a space-separated list of libraries. Note that you must include all libraries required by LOOS. For example:

scons BOOST_LIBS="boost_regex-gcc43-mt boost_program_options-gcc43-mt
boost_thread-gcc43-mt boost_system-gcc43-mt"

Similar configuration options are available for NetCDF and ATLAS/LAPACK. If threaded versions of ATLAS are found, these will be used by default. If you intend to run multiple LOOS tools concurrently, then you may get better performance by using the serial ATLAS libraries. You can force LOOS to build with the serial ATLAS libraries by using the threads option with scons,

scons threads=0

SCons will also prefer to use ATLAS if it's available, but will revert to LAPACK/BLAS if necessary. For Macs, the Accelerate FrameWork is used rather than ATLAS. NetCDF support is only included if the NetCDF library is found.

It is not necessary to always set these build options on the command-line. If a custom.py file exists, SCons will read it and set the variables appropriately. We provide an examples of how it can be used in custom.py-proto. Simply copy this file to custom.py and then uncomment and edit the appropriate lines. Note that variables set on the command-line or environment will have priority over what's in your custom.py file.

More complete build information, along with platform specific notes, can be found in the INSTALL file included with LOOS.

Installing

To install LOOS, use the "install" target:

scons install

This will cause SCons to copy the headers, tools, and library into /opt/loos. You can change where LOOS is installed by setting the PREFIX variable in either your custom.py file or on the command line. LOOS will create a /bin, /include, /lib, and /docs directory and copy the appropriate files. The recommended installation methodology is to install LOOS into a version-specific directory, and then set up a symlink from loos-latest to the most recent installed version:

scons PREFIX=/opt/loos-2.1 install
ln -s /opt/loos-2.1 /opt/loos-latest

Remember that any options you have previously provided to scons should be specified again when installing.

Important Note...

To use LOOS, your environment must be first setup:

  (bash)   source /path/to/loos/setup.sh
  (tcsh)   source /path/to/loos/setup.csh

Building PyLOOS, the Python Interface to LOOS

PyLOOS will be automatically built if you have a recent swig (2.0+) installed. PyLOOS now (as of LOOS 2.3.0) also requires NumPy. See the top of the INSTALL and the FAQ for PyLOOS for more information about building and using PyLOOS.

In some cases, scons may try to build PyLOOS when it isn't appropriate (i.e. supported). To disable PyLOOS, use the pyloos flag,

scons pyloos=0

General Notes

If you're using a compiler in a non-standard location (e.g. you have your own build of the latest and greatest gcc), SCons may not be using it even though your $PATH is set correctly. You can force which compiler is used to build LOOS by setting the CXX variable in your "custom.py" file.

Note: Settings in the custom.py file can be overridden using the command-line and the shell environment.

SCons supports building LOOS in parallel. If you have 4 cores, for example, use "scons -j4" to use all 4 cores.

Prebuilt documentation for LOOS is provided as part of the distribution. This is simply copied into the install directory as part of installation. Should you want to build a new version of the documentation, Doxygen is required. Moreover, due to an issue we ran into with SCons, documentation building and installation are decoupled. What this means is that you must explicitly build the docs (i.e. "scons docs") and -then- install, "scons install". Running "scons install" will -not- rebuild the documentation, even if it is out of date (or nonexistent).

Building Your Own Tools

You have two choices for building your own tools depending on LOOS. The simplest way is to work in the Packages/User directory. In that case, all you need to do to build against LOOS (other than write your application, of course) is edit the SConscript file in that directory, adding your program to the build list. Specifically, you edit the line that creates a variable "apps", appending your program's name to the end of the string. Then, run scons from the main LOOS directory, and your program will be built. We have included a number of trivial programs in the User directory; they don't actually do anything useful, but they provide basic templates for how to use the command line options, and get the basic setup you'll need. Note that tools in the User package will be installed if you choose to install LOOS.

If you wish to work outside the LOOS directory structure, copy the SConstruct and SConscript files from the Examples directory and edit them as needed. You can probably get by with just editing the SConscript file. To build, you will need to have sourced one of the LOOS setup scripts (e.g. setup.sh). This will set several environment variables that will tell your SConstruct where LOOS is and how it was built. If all goes well, running scons in your directory will build your tools. If not, you can change your environment variables or alternatively, not source the LOOS setup script and use a custom.py file.

Important Note

The environment always overrides what's in the SConstruct and in the custom.py file. If you create a custom.py file and change the LOOS_CCFLAGS variable, it will be ignored in favor of what LOOS_CCFLAGS was set to when you sourced the setup.sh script.


Targets

There are several build targets available:

TargetDescription
all (default)Build the library, tools, packages, and PyLOOS
coreBuilds the library and PyLOOS only
docsRebuilds the documentation
installInstalls library, toosl, PyLOOS, and all packages (except user)

Each package in LOOS is also a build target. The LOOS library and only that package will be built. The current set of packages are:

ENMElastic Network Models
HBondsHydrogen bonds analysis
ConvSimulation convergence analysis
DensityDensity/3D histogram tools
UserUser created tools
PythonPyLOOS-based scripts

There are several different build options that are available for LOOS. These are handled on the command-line by SCons as "foo=1" to turn the option on or "foo=0" to turn it off. Most options default to off. Finally, you can query the available options by passing the "-h" flag to SCons. The following table lists the principal build options:

OptionDefaultDescription
debug0Adds "-DDEBUG" to build
release1Turns on aggressive optimization (-O3)
regenerate0Regenerates the test verification data
reparse0Runs bison/flex to create the C++ files for parsing selections

Reparsing

To remove the dependency on Bison/Flex, the output from these tools for the grammar and scanner are included. If you want to rebuild them, you will need to use the 'reparse=1' option. The catch is that if you have a different version of flex installed, there is a good chance there will be a conflict with the bundled FlexLexer.h include file. If you see odd compiler errors, try removing that file and rebuilding. Alternatively, forcibly remove all generated files by doing "rm *.cc *.hh" (assuming you've added no files with those suffixes), then rebuild.