Lattice Builder
Software Package for Constructing Rank-1 Lattices
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Friends Groups Pages
Building

Building Lattice Builder consists of the following steps:

Requirements

C++11-Compliant Compiler

Compiling Lattice Builder requires a C++ compiler that partially supports the C++11 standard, such as g++ from the GNU Compiler Collection version 4.7 or later.

The C++11 features that Lattice Builder uses are:

  • auto-typed variables
  • range-based for-loop
  • std::function and std::bind
  • rvalue references
  • move constructors and assignment operators
  • static assertions
  • extern templates
  • null pointer constant
  • strongly typed enums
  • initializer lists
  • non-static data member initializers
  • template aliases

Boost C++ Libraries

The Lattice Builder library depends on the following Boost libraries:

In addition to these, the Lattice Builder command-line tool also depends on the following Boost libraries:

Only the Program Options and Chrono libraries require building and linking; the others are header-only libraries.

Installation instructions for the Boost libraries can be found on the Getting Started page for Unix variants or for Microsoft Windows.

Alternatively, you can customize and run the script install-boost.sh that can found under the scripts directory with the source code.

FFTW Library

The fast CBC implementation of Lattice Builder depends on the FFTW library.

Boost.Build

In order to facilitate cross-platform compatibility, Lattice Builder uses Boost.Build as its build system (installation instructions). The nightly-build version is recommended.

If you installed Boost.Build as indicated to some prefix B2_PREFIX, the installation system should have created the file B2_PREFIX/share/boost-build/site-config.jam. Make sure that it contains at least a line that indicates which default toolset should be used. On Linux systems, this line should look like:

using gcc ;

The space before the semicolon is important.

To check if Boost.Build is installed and available in the path, try either:

b2 --version

or

/path/to/b2 --version

replacing /path/to with the actual path to which Boost.Build was installed.

Configuring Boost.Build

Site-Specific Configuration

To compile Lattice Builder, Boost.Build needs to know where to find the Boost header files and how to link to the Boost and FFTW libraries. These settings are specific to the platform on which Lattice Builder is to be built and should be customized in the file B2_PREFIX/share/boost-build/site-config.jam, where B2_PREFIX is the directory under which Boost.Build was installed. If the file cannot be found at that location, it can be created if the user has proper access permissions (otherwise see User-Specific Configuration (optional)). If all libraries are installed under standard paths, the site-config.jam file can only contain:

# Copyright (c) 2012 David Munger, Pierre L'Ecuyer, Université de Montréal.
#
# This file is part of Lattice Builder.
#
# Lattice Builder is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Lattice Builder is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Lattice Builder. If not, see <http://www.gnu.org/licenses/>.
project site-config ;
using gcc ;
# nothing special to do to use the boost header-only libraries
alias boost ;
# declare libboost_program_options, libboost_system and libfftw3 with standard
# linking options
lib boost_program_options boost_system fftw3 ;
# declare the boost_chrono library as dependent upon libboost_system and librt,
# and as requiring linkage with libboost_chrono (whence the <name> feature)
lib boost_chrono : boost_system rt : <name>boost_chrono ;
# always link the shared version of librt
lib rt : : <link>shared ;

Otherwise, the following site-config.jam file could be customized with the following content:

# Copyright (c) 2012 David Munger, Pierre L'Ecuyer, Université de Montréal.
#
# This file is part of Lattice Builder.
#
# Lattice Builder is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Lattice Builder is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Lattice Builder. If not, see <http://www.gnu.org/licenses/>.
# Example configuration file for Boost.Build.
#
# USAGE INSTRUCTIONS
#
# 1. Copy this file to B2_PREFIX/share/boost-build/site-config.jam
# where B2_PREFIX is the directory under which Boost.Build is installed.
#
# 2. Set the environment variables BOOST_PREFIX and FFTW_PREFIX to point to
# the directories under which the Boost and FFTW libraries are installed,
# respectively.
# Alternatively, customize the variables BOOST_PREFIX and FFTW_PREFIX below.
#
project site-config ;
#
# read BOOST_PREFIX and FFTW_PREFIX from environment
#
import os ;
local BOOST_PREFIX = [ os.environ BOOST_PREFIX ] ;
local FFTW_PREFIX = [ os.environ FFTW_PREFIX ] ;
#
# default to standard locations
#
BOOST_PREFIX ?= /usr ;
FFTW_PREFIX ?= /usr ;
#
# compiler settings
#
using gcc : : :
<cflags>"-march=native" <cxxflags>"-march=native" ;
#
# Boost header-only libraries
#
alias boost : : : :
<include>$(BOOST_PREFIX)/include/ ;
#
# rt library
#
lib rt : : <link>shared ;
#
# Boost libraries that require linkage
#
lib boost_program_options boost_system : : :
<search>$(BOOST_PREFIX)/lib/ :
<include>$(BOOST_PREFIX)/include/ ;
lib boost_chrono : boost_system rt : <name>boost_chrono :
<search>$(BOOST_PREFIX)/lib/ :
<include>$(BOOST_PREFIX)/include/ ;
#
# FFTW library
#
lib fftw3 : : :
<search>$(FFTW_PREFIX)/lib/ :
<include>$(FFTW_PREFIX)/include/ ;

To use this this configuration file, the environment variables BOOST_PREFIX and FFTW_PREFIX should be set to point to the directories under which the Boost and FFTW libraries are installed, respectively. The specification for lib rt indicates that the rt library should always be linked to as a shared library. The specification for lib boost_chrono indicates that it depends on lib boost_system and on lib rt. The spaces around the colons and before the semicolons are important.

The compilation process generates object files before linking them together into an executable program. Boost.Build can be told to put these temporary object files in any desired directory by changing the project line, for instance, to:

project site-config : build-dir /tmp/b2 ;

which would put them in /tmp/b2. As a more sophisticated example, we could put them into /tmp/$USER/b2, where $USER is the current user name, with:

import os ;
import path ;
local build-dir = [ path.join /tmp [ os.environ USER ] b2 ] ;
project site-config : build-dir $(build-dir) ;

User-Specific Configuration (optional)

As an alternative to editing site-config.jam, the customizations explained in Site-Specific Configuration can be applied to the user-config.jam file, which Boost.Build attempts to find at the root of the user's home directory. In that case, the library aliases in the project-config.jam file, which can be found at the Lattice Builder project's root directory, must be updated by replacing every occurrence of site-config with user-config. For example,

alias fftw3 : /site-config//fftw3 ;

should be replaced with

alias fftw3 : /user-config//fftw3 ;

Project-Specific Configuration

Finally, the appropriate compiler flags should set in project-config.jam to support the C++11 standard:

project latsoft : requirements <cxxflags>FLAGS ;

where FLAGS is the placeholder for those flags. For example, with GCC 4.7, this line would be:

project latsoft : requirements <cxxflags>"-std=c++11" ;

Compiling Lattice Builder

Change the current directory to the root directory of the package, which contains the tools and latbuilder subdirectories. First, the tcode utility, which produces C++ header files out of TeX code, must be built with:

b2 /tools

Then, if everything is configured correctly, the following command will build the Lattice Builder library and command-line tool:

b2 /latbuilder//install --prefix=/installation/path

with /installation/path replaced with the directory into which Lattice Builder should be installed. To check that the program installed correctly, try:

/installation/path/latbuilder --version

Help on usage can be obtained by replacing the –version switch with the –help switch.

To build using multiple processes in parallel, the -j switch with the number of processes as its argument can be added to the b2 command. For example:

b2 -j4 /latbuilder//install --prefix=/installation/path

would build Lattice Builder using 4 different threads in parallel.

Linking Software with Lattice Builder

An example Jamfile and Makefile to build a project that uses the Lattice Builder application programming interface (API) can be found under /installation/path/share/doc/examples/myproject.

A lot of example code using the Lattice Builder API can be found under the latbuilder/examples directory of the source package and in its subdirectories.

Remarks
Tip for interpreting compiler errors. Compiler error messages can be very verbose when the pertain to the usage of C++ templates. Compiler messages can be made easier to read by adding an empty line after each message, e.g., by piping the original messages through sed 'a\ ', then by using a text search function to locate the "error:" string.