Building Serialbox¶

Serialbox relies on CMake (>= 3.1), a cross-platform build-generator tool. CMake does not build the project, it generates the files needed by your build tool (GNU make, Visual Studio, etc.) for building Serialbox.

Quick start
Building the unittests
Building the Python3 module
Building the Fortran Interface
Dependencies
- Ubuntu (16.04)
- Mac OSX
Options and variables

Quick start ¶

To build Serialbox you need a C++11 toolchain, CMake and a fairly recent version of Boost. We use here the command-line, non-interactive CMake interface.

Make sure you have installed all the tools and dependencies, especially Boost and CMake. See Dependencies.
Clone the repository and create a build directory. Building Serialbox in the source directory is not supported:
```
$ git clone https://github.com/eth-cscs/serialbox2.git
$ cd serialbox2
$ mkdir build
$ cd build
```
Execute CMake:
```
$ cmake ../
```
CMake will detect your development environment, perform a series of tests, and generate the files required for building Serialbox. CMake will use default values for all build parameters. See the Options and variables section for a list of build parameters that you can modify.
After CMake has finished running, proceed to use IDE project files, or start the build from the build directory:
```
$ cmake --build .
```
The --build option tells cmake to invoke the underlying build tool (make, ninja, xcodebuild, msbuild, etc.)

The underlying build tool can be invoked directly, of course, e.g make -j4.
After Serialbox has finished building, install it from the build directory. The files will be installed into the top-level install directory (i.e serialbox2/install).
```
$ cmake --build . --target install
```
The --target option with install parameter in addition to the --build option tells cmake to build the install target (equivalent to make install).

Building the unittests ¶

Serialbox has an extensive test-suite. To build the unitests, proceed the in the same way as described in the Quick start section with the diffrence of passing -DSERIALBOX_TESTING=ON to CMake.

$ cmake -DSERIALBOX_TESTING=ON ../

Serialbox has several unittest which use the external library they are built for. For example, to build the unittests for the gridtools frontend:

$ cmake -DSERIALBOX_TESTING=ON -DSERIALBOX_TESTING_GRIDTOOLS=ON -DSERIALBOX_GRIDTOOLS_ROOT=<path-to-gridtools> ../

Similarly, you can build the unittest for STELLA and the compatible tests with the old Serialbox. If you clone those projects in external/, CMake will automatically find and build them. The following will enable all possible unittests:

$ cd $(git rev-parse --show-toplevel) # Change to top-level directory
$ git clone git@github.com:eth-cscs/gridtools.git external/gridtools
$ git clone git@github.com:MeteoSwiss-APN/stella.git external/stella
$ git clone https://github.com/MeteoSwiss-APN/serialbox external/serialbox
$ cd build
$ cmake -DSERIALBOX_TESTING=ON -DSERIALBOX_TESTING_GRIDTOOLS=ON -DSERIALBOX_TESTING_OLD_SERIALBOX=ON -DSERIALBOX_TESTING_STELLA=ON ../

To run the unittests via CTest:

$ cmake --build . --target test

Building the Python3 module ¶

The Python3 module relies on the C-Interface of Serialbox which is build by default. For furhter instructions see Building.

Building the Fortran Interface ¶

The Fortran interface can be built by setting the CMake variable SERIALBOX_ENABLE_FORTRAN to ON. Note that this requires a working Fortran compiler. See Building

Dependencies ¶

Serialbox requires a C++11 compatible compiler:

Compiler	Version
GNU gcc	>= 4.9
LLVM clang	>= 3.4
Intel icc	>= 17.0
XCode	>= 6.1

Serialbox depends on the Boost modules: filesystem and log. Optionally, Serialbox can be compiled with NetCDF-4 support. The Cray and PGI compilers are currently not able to compile the C++/C part of Serialbox.

Ubuntu (16.04)¶

The following will install all the necessary dependencies:

$ sudo apt-get install cmake libboost-all-dev python3-numpy python3-nose

and the following will furhter install all the optional dependencies:

$ sudo apt-get install libnetcdf-dev libssl-dev

Mac OSX ¶

Make sure you have the Xcode Command Line Tools installed.

$ xcode-select --install

If you are using Homebrew, the following will install all the necessary dependencies:

$ brew update
$ brew install cmake boost

and the following will further install all the optional dependencies:

$ brew tap homebrew/science
$ brew install netcdf

The Python3 module of Serialbox further requires numpy.

Options and variables ¶

Variables customize how the build will be generated. Options are boolean variables, with possible values ON/OFF. Options and variables are defined on the CMake command line like this:

$ cmake -DVARIABLE=value ../

You can also edit the options and variables with CCMake

$ ccmake .

Frequently-used CMake variables ¶

Here are some of the CMake variables that are used often, along with a brief explanation and Serialbox-specific notes. For full documentation, consult the CMake manual, or execute cmake --help-variable VARIABLE_NAME.

CMAKE_BUILD_TYPE:STRING: Sets the build type for make-based generators. Possible values are Release, Debug, RelWithDebInfo and MinSizeRel (default is Release).
CMAKE_INSTALL_PREFIX:PATH: Path where Serialbox will be installed if “make install” is invoked or the “install” target is built (default is the top-level install directory)

Serialbox specific variables ¶

SERIALBOX_ENABLE_C:BOOL: Build the C interface of Serialbox (libSerialboxC). The options is ON by default.
SERIALBOX_ENABLE_PYTHON:BOOL: Build Python3 interface of Serialbox (requires SERIALBOX_ENABLE_C=ON). The options is ON by default. The module will be installed in python/serialbox.
SERIALBOX_ENABLE_FORTRAN:BOOL: Build the C interface of Serialbox (libSerialboxFortran). The options is OFF by default.
SERIALBOX_ENABLE_SDB:BOOL: Build stencil debugger sdb (requires SERIALBOX_ENABLE_PYTHON=ON). The options is ON by default. The module will be installed in python/sdb.
SERIALBOX_EXAMPLES:BOOL: Build the example executables in examples/. To build the gridtools examples, SERIALBOX_TESTING_GRIDTOOLS=ON is required.
SERIALBOX_BUILD_SHARED:BOOL: Build shared libraries of Serialbox. This is required for the Python module. The option is ON by default.
SERIALBOX_LOGGING:BOOL: Enable/disable the logging infrastructure. If logging is disabled, Boost.Log is not NOT required anymore. The option is ON by default.
SERIALBOX_ASYNC_API:BOOL: Enable the asynchronous API. This uses the C++11 STL multitheading infrastructure. The option is ON by default.
SERIALBOX_USE_OPENSSL:BOOL: Use OpenSSL library for fast hash-algorithms. By default the option is ON if NetCDF-4 was found.
SERIALBOX_USE_NETCDF:BOOL: Use NetCDF-4 library to build the NetCDF archive backend. By default the option is ON if NetCDF-4 was found.
SERIALBOX_TESTING:BOOL: Build the unittests (see Building the unittests)
SERIALBOX_TESTING_GRIDTOOLS:BOOL: Build gridtools unittests and examples.
SERIALBOX_TESTING_STELLA:BOOL: Build STELLA unittests.
SERIALBOX_TESTING_OLD_SERIALBOX:BOOL: Build the compatiblity unitests against the old Serialbox.
SERIALBOX_TESTING_DEATH_TESTS:BOOL: Compile the death-tests.
SERIALBOX_BENCHMARKING:BOOL: Build the benchmark exectuables.
SERIALBOX_DOCUMENTATION:BOOL: Build and install the documentation (requires doxygen and sphinx).
SERIALBOX_CODE_COVERAGE:BOOL: Generate code coverage (requires lcov and gcov)
SERIALBOX_VERBOSE_WARNINGS:BOOL: Enable verbose warnings (-Wall)

External project specific variables ¶

BOOST_ROOT:PATH: Install directory of Boost (see here).
GRIDTOOLS_ROOT:PATH: Main directory of gridtools.
SERIALBOX_OLD_ROOT:PATH: Install directory of old Serialbox.
STELLA_ROOT:PATH: Install directory of STELLA.
NETCDF_ROOT:PATH: Install directory of NetCDF-4.

Table Of Contents

Previous topic

Next topic

This Page