Author: Timo Bingmann (2013)

Precondition: Make sure GNU make, CMake >= 2.6.4, git and a C++ compiler are installed. See Supported Compilers and Platforms which systems and compilers are currently supported.

There are three methods to use STXXL:

The first is recommended for small prototype projects consisting of only a few source files. It uses the local/ directory within the STXXL directory tree.
For larger development projects, the STXXL library can be linked as a library inside a subdirectory.
For distributing independent sources, the STXXL library can be localed using CMake's find_package() mechanism.

There are quite some Options for Build Configuration, which you can use when building STXXL with CMake.

First-Time Compile and Simple Projects in local/

Clone the STXXL project repository as my-project.

$ git clone http://github.com/stxxl/stxxl.git my-project

Compile the STXXL library in a build subdirectory, including the example in local/.

$ mkdir my-project/build
$ cd my-project/build
$ cmake ..
<lots of output by cmake>
$ make
<lots of compilation messages>

Run the example program test1 in local/

(inside my-project/build/)
$ cd local
$ ./test1
<lots of output>

For your own prototype project you can immediately start modifying test1.cpp or create a new .cpp in local/. The CMake scripts will automatically compile and link all .cpp files in local/ correctly with STXXL.

The CMake file has many build options (see Options for Build Configuration). Maybe the most important are BUILD_TESTS and BUILD_EXAMPLES. By setting them with "-DBUILD_EXAMPLES=ON -DBUILD_TESTS=ON" on the CMake line, additional subprojects are added to the build.

By default, STXXL compiles in Debug mode and includes many assertions and run-time checks, which typically slow down performance dramatically. To use STXXL at full speed, please set the build type to Release by adding -DCMAKE_BUILD_TYPE=Release to the cmake line.

Including STXXL as a CMake Subproject

The second method is for including STXXL in a larger program as a subproject. This is particularly easy with CMake: one can just add_directory(stxxl) in a CMakeLists.txt. The following guide shows how to start a simple CMake project and use STXXL in a subdirectory.

The advantage of this method is that the STXXL is a subproject of your's. Thereby it will always be compiled with the same set of CFLAGS or CMAKE_BUILD_TYPE as your project. This is most convenient for developing projects, as the STXXL has a lot of debug code. When running experiments or going into production, the whole project must be built with CMAKE_BUILD_TYPE=Release or similar to remove the debug code.

Create an empty directory "my-project" and clone the STXXL inside it.

$ mkdir my-project
$ cd my-project
$ git clone http://github.com/stxxl/stxxl.git

Create a file named CMakeLists.txt inside your my-project folder with the following sample content:

# CMakeLists.txt example for STXXL

project(my-project)
cmake_minimum_required(VERSION 2.8)

# disallow in-source builds
if("${PROJECT_SOURCE_DIR}" STREQUAL "${PROJECT_BINARY_DIR}")
  message(SEND_ERROR "In-source builds are not allowed.")
endif("${PROJECT_SOURCE_DIR}" STREQUAL "${PROJECT_BINARY_DIR}")

# enable warnings (always good)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -W -Wall")

# include the STXXL library in my-project
add_subdirectory(stxxl)

# apply STXXL CXXFLAGS to our configuration
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${STXXL_CXX_FLAGS}")

# add STXXL includes path
include_directories(${STXXL_INCLUDE_DIRS})

# build a program and link it with STXXL.
add_executable(project main.cpp)
target_link_libraries(project ${STXXL_LIBRARIES})

To show how that this build system works, we now copy the test1.cpp from STXXL to the new project as main.cpp and build it.

$ cp stxxl/local/test1.cpp main.cpp
$ mkdir build
$ cd build
$ cmake ..
<lots of output by cmake>
$ make
<lots of compilation messages>

Test the compilation by running project
```
$ ./project
```

Including STXXL as a Library

STXXL compiles into a static (and optionally shared) library plus template include files, which may be included in binary distributions.

If a binary STXXL package is installed, the following few CMake lines will automatically detect it and configure a program to build with the appropriate CXXFLAGS, include directories and libraries:

# search for stxxl-config.cmake which contains the library's configuration
find_package(STXXL REQUIRED)

# print some info (this can be removed)
message(STATUS "STXXL_CXX_FLAGS: ${STXXL_CXX_FLAGS}")
message(STATUS "STXXL_INCLUDE_DIRS: ${STXXL_INCLUDE_DIRS}")
message(STATUS "STXXL_LIBRARIES: ${STXXL_LIBRARIES}")

# apply CXXFLAGS to our configuration
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${STXXL_CXX_FLAGS}")

# add STXXL include directory
include_directories(${STXXL_INCLUDE_DIRS})

# create and executable and linke with STXXL
add_executable(your_program main.cpp)
target_link_libraries(your_program ${STXXL_LIBRARIES})

We have create a simple example project, which contains the lines above and an example program. The source is available via github:

git clone http://github.com/stxxl/myproject.git

See the README at http://github.com/stxxl/myproject

Create a Disk Configuration File

For STXXL to function beyond very simple examples, you must define the disk configuration file . The simplest method is to create a file named '.stxxl' the same directory as you execute the program. A basic configuration might be:

# file path,maximum capacity of the disk,access method
disk=/tmp/stxxl,1G,syscall unlink

Please see Disk Configuration Files for further available options.

Notes for Linux Distribution Package Maintainers

Package maintainers should make sure that both Debug and Release static libraries are available via the distribution package system. We currently cannot keep a stable binary interface for the library, thus providing versioned shared libraries is not a good idea.

The CMake build scripts will generate static and exclude shared libraries when run with "-DBUILD_STATIC_LIBS=ON -DBUILD_SHARED_LIBS=OFF".
Debug libraries are suffixed with "_debug". Due to CMake's system, the library must be compiled once in Debug mode and once in Release mode! (see below)
Running "make install" will correctly install the tree into CMAKE_INSTALL_PREFIX.
The binary package should only contain the stxxl_tool (since we do not provide shared libraries). Alternatively, the tool can packaged in an additional tools package, thus leaving the binary package empty. The test1 binary must not be included.
The development package must contain all installed headers, and both "libstxxl.a" and "libstxxl_debug.a".
The CMake script will also install CMake project files in lib/cmake/stxxl , which must be included in the development package.
We also provide a pkg-config file, which installs by default into lib/pkgconfig/ as stxxl.pc and stxxl_debug.pc
Binary Unix packages should not use Boost.

A typical build sequence would be

mkdir debug; cd debug
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_STATIC_LIBS=ON $SRCDIR
make -j4 && make install
cd ..
mkdir release; cd release
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_STATIC_LIBS=ON $SRCDIR
make -j4 && make install

When building in this order the stxxl_tool will be built twice, and the Debug binary will be overwritten with the Release binary.