STXXL  1.4.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Options for Build Configuration

STXXL has some optional features and compile switches that can be changed at build time.

  • Maybe the most important one is switching between Debug and Release builds. Debug builds are very slow, as STXXL contains many assertions (which are a feature not a bug). With cmake the mode is easily defined by using
    $ cmake -DCMAKE_BUILD_TYPE=Debug ...
    <or>
    $ cmake -DCMAKE_BUILD_TYPE=Release ...
    
    The mode mostly changes CXXFLAGS.
  • Some parts of STXXL have been parallelized using the __gnu_parallel (aka MCSTL) library. Currently, with CMake one can only use the newer __gnu_parallel library by defining
    $ cmake -DUSE_GNU_PARALLEL=ON ...
    
    when building. Parallel is now ON by default for gcc, if it can be detected. The cmake script will check availability of the corresponding header files.
  • Use Boost for file I/O, multi-threading support and more. Boost is required on Windows for older MSVC versions and is CMake tries to automatically find it. On Linux/Unix it is optional and not recommended, but can be activated using
    $ cmake -DUSE_BOOST=ON ...
    
  • STXXL contains many small example programs, which can be built by defining
    $ cmake -DBUILD_EXAMPLES=ON ...
    
  • STXXL contains a set of unit tests in tests/, which verify most of the libraries functionality. These programs are not built by default, because this makes it easier for STXXL to be used as CMake subproject (Including STXXL as a CMake Subproject). The test suite can be built and run using
    $ cmake -DBUILD_TESTS=ON ...
    <compile>
    $ make test
    
    Defining BUILD_TESTS also builds everything in examples/. There is also a BUILD_EXTRAS configuration flag to build even more, longer running tests. Be advised that the test suite need quite some space on your disks.
  • CMake can be instructed to use other compilers, by setting, for example
    $ cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ...
    
  • CMake can install the library and all public headers into a prefix by running:
    $ cmake -DCMAKE_INSTALL_PREFIX=/some/dir ...
    <compile>
    $ make install
    
    Additionally, the installation subdirectories can be specified using the following options:
    INSTALL_BIN_DIR=bin
    INSTALL_LIB_DIR=lib
    INSTALL_INCLUDE_DIR=include
    INSTALL_PKGCONFIG_DIR=lib/pkgconfig
    INSTALL_CMAKE_DIR=lib/cmake/stxxl
    
  • The CMake script by default only builds a static library. Shared libraries in Linux incur a small overhead for each library call, which should be insignificant for STXXL. However, keeping a stable binary interface for shared libraries is currently not planned. Nevertheless, you can build static and/or shared library via the following switches:
    $ cmake -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=ON ..
    
  • On Unix the pthreads library is used for threading, on Windows the Boost or STL thread library is used. For testing compilation, the STL thread library can optionally also be used on Unix/Linux by setting the -DUSE_STD_THREADS=ON switch.
  • For build testing, the CMake script can check that all header files in include/ compile by themselves. This is required since each header must be self-sufficient and include other headers appropriately. These test compiles are trigged with -DTRY_COMPILE_HEADERS=ON.
  • Again for testing, the CMake script can be instructed to run all tests and examples
    # with valgrind by setting
    $ cmake -DUSE_VALGRIND=ON ...
    # with gcov for test coverage analysis by setting
    $ cmake -DUSE_GCOV=ON ...
    
    The valgrind option also enables a few additional lines of code that clear memory areas that are intentionally uninitialized. The gcov coverage report can be automatically created using the additional targets test-coverage (runs everything) or lcov-html to generate the HTML report after running the test suite.