Build recipes
How to Install HPX on Unix Variants
How to Install HPX on OS X (Mac)
How to Install HPX on Windows
How to Install HPX on BlueGene/Q
How to Install HPX on the Xeon Phi
How to Install HPX on Fedora Distributions
  • Create a build directory. HPX requires an out-of-tree build. This means you will be unable to run CMake in the HPX source tree.
cd hpx
mkdir my_hpx_build
cd my_hpx_build
  • Invoke CMake from your build directory, pointing the CMake driver to the root of your HPX source tree.
cmake -DBOOST_ROOT=/root/of/boost/installation \
      [other CMake variable definitions] \

for instance:

cmake -DBOOST_ROOT=~/packages/boost -DHWLOC_ROOT=/packages/hwloc -DCMAKE_INSTALL_PREFIX=~/packages/hpx ~/downloads/hpx_0.9.10
  • Invoke GNU make. If you are on a machine with multiple cores, add the -jN flag to your make invocation, where N is the number of parallel processes HPX gets compiled with.
gmake -j4
[Caution] Caution

Compiling and linking HPX needs a considerable amount of memory. It is advisable that at least 2 GB of memory per parallel process is available.

[Note] Note

Many Linux distributions use make as an alias for gmake

  • To complete the build and install HPX:
gmake install
[Important] Important

These commands will build and install the essential core components of HPX only. In order to build and run the tests, please invoke:

gmake tests && gmake test

and in order to build (and install) all examples invoke:

gmake examples
gmake install

For more detailed information about using CMake please refer its documentation and also the section Building HPX with CMake. Please pay special attention to the section about HPX_WITH_MALLOC as this is crucial for getting decent performance.

This section describes how to build HPX for OS X (Mac).

Build (and install) a recent version of Boost, using Clang and libc++
To build Boost with Clang and make it link to libc++ as standard library,
you'll need to set up either of the following in your `~/user-config.jam`
# user-config.jam (put this file into your home directory)
# ...

using clang
    : "/usr/bin/clang++"
    : <cxxflags>"-std=c++11 -fcolor-diagnostics"
      <linkflags>"-stdlib=libc++ -L/path/to/libcxx/lib"

(Again, remember to replace /path/to with whatever you used earlier.)

You can then use as build command either:
b2 --build-dir=/tmp/build-boost --layout=versioned toolset=clang install -j4


b2 --build-dir=/tmp/build-boost --layout=versioned toolset=clang install -j4

We verified this using Boost V1.53. If you use a different version, just remember to replace /usr/local/include/boost-1_53 with whatever include prefix you had in your installation.

Build HPX, finally
cd /path/to
git clone https://github.com/STEllAR-GROUP/hpx.git
mkdir build-hpx && cd build-hpx

To build with Clang 3.2, execute:

cmake ../hpx \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DBOOST_INCLUDE_DIR=/usr/local/include/boost-1_53 \
    -DBOOST_LIBRARY_DIR=/usr/local/lib \
    -DBOOST_SUFFIX=-clang-darwin32-mt-1_53 \

To build with Clang 3.3 (trunk), execute:

cmake ../hpx \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DBOOST_INCLUDE_DIR=/usr/local/include/boost-1_53 \
    -DBOOST_LIBRARY_DIR=/usr/local/lib \
    -DBOOST_SUFFIX=-clang-darwin33-mt-1_53 \

For more detailed information about using CMake please refer its documentation and to the section Building HPX with CMake for.

Alternative Installation method of HPX on OS X (Mac)

Alternatively, you can install a recent version of gcc as well as all required libraries via MacPorts:

  1. Install MacPorts
  2. Install CMake, gcc 4.8, and hwloc:

    sudo port install gcc48
    sudo port install hwloc

    You may also want:

    sudo port install cmake
    sudo port install git-core
  3. Make this version of gcc your default compiler:

    sudo port install gcc_select
    sudo port select gcc mp-gcc48
  4. Build Boost manually (the Boost package of MacPorts is built with Clang, and unfortunately doesn't work with a GCC-build version of HPX):

    wget http://sourceforge.net/projects/boost/files/boost/1.54.0/boost_1_54_0.tar.bz2
    tar xjf boost_1_54_0.tar.bz2
    pushd boost_1_54_0
    export BOOST_ROOT=$HOME/boost_1_54_0
    ./bootstrap.sh --prefix=$BOOST_DIR
    ./b2 -j8
    ./b2 -j8 install
  5. Build HPX:

    git clone https://github.com/STEllAR-GROUP/hpx.git
    mkdir hpx-build
    pushd hpx-build
    export HPX_ROOT=$HOME/hpx
    cmake -DCMAKE_C_COMPILER=gcc \
        -DCMAKE_CXX_COMPILER=g++ \
        -DCMAKE_FORTRAN_COMPILER=gfortran \
        -DCMAKE_C_FLAGS="-Wno-unused-local-typedefs" \
        -DCMAKE_CXX_FLAGS="-Wno-unused-local-typedefs" \
        -DHWLOC_ROOT=/opt/local \
    make -j8
    make -j8 install
  6. Note that you need to set BOOST_ROOT, HPX_ROOT, and DYLD_LIBRARY_PATH (for both BOOST_ROOT and HPX_ROOT) every time you configure, build, or run an HPX application.
  7. If you want to use HPX with MPI, you need to enable the MPI parcelport, and also specify the location of the MPI wrapper scripts. This can be done e.g. with the following command:
     -DMPI_C_COMPILER=openmpicc \
     -DMPI_CXX_COMPILER=openmpic++ \
     -DMPI_FORTRAN_COMPILER=openmpif90 \
     -DCMAKE_C_FLAGS="-Wno-unused-local-typedefs" \
     -DCMAKE_CXX_FLAGS="-Wno-unused-local-typedefs" \
     -DHWLOC_ROOT=/opt/local \
Installation of Required Prerequisites
Installation of the HPX Library
  • Create a build folder. HPX requires an out-of-tree-build. This means that you will be unable to run CMake in the HPX source folder.
  • Open up the CMake GUI. In the input box labelled "Where is the source code:", enter the full path to the source folder. The source directory is one where the sources were checked out. CMakeLists.txt files in the source directory as well as the subdirectories describe the build to CMake. In addition to this, there are CMake scripts (usually ending in .cmake) stored in a special CMake directory. CMake does not alter any file in the source directory and doesn't add new ones either. In the input box labelled "Where to build the binaries:", enter the full path to the build folder you created before. The build directory is one where all compiler outputs are stored, which includes object files and final executables.
  • Add CMake variable definitions (if any) by clicking the "Add Entry" button. There are two required variables you need to define: BOOST_ROOT and HWLOC_ROOT. These (PATH) variables need to be set to point to the root folder of your Boost and Portable Hardware Locality (HWLOC) installations. It is recommended to set the variable CMAKE_INSTALL_PREFIX as well. This determines where the HPX libraries will be built and installed. If this (PATH) variable is set, it has to refer to the directory where the built HPX files should be installed to.
  • Press the "Configure" button. A window will pop up asking you which compilers to use. Select the Visual Studio 10 (64Bit) compiler (it usually is the default if available). The Visual Studio 2012 (64Bit) and Visual Studio 2013 (64Bit) compilers are supported as well. Note that while it is possible to build HPX for x86, we don't recommend doing so as 32 bit runs are severely restricted by a 32 bit Windows system limitation affecting the number of HPX threads you can create.
  • Press "Configure" again. Repeat this step until the "Generate" button becomes clickable (and until no variable definitions are marked red anymore).
  • Press "Generate".
  • Open up the build folder, and double-click hpx.sln.
  • Build the INSTALL target.

For more detailed information about using CMake please refer its documentation and also the section Building HPX with CMake.

  • Download the CMake V3.4.3 installer (or latest version) from here
  • Download the Portable Hardware Locality (HWLOC) V1.11.0 (or latest version) from here and unpack it.
  • Download Boost libraries V1.60 (or latest version) from here and unpack them.
  • Build the boost DLLs and LIBs by using these commands from Command Line (or PowerShell). Open CMD/PowerShell inside the Boost dir and type in:


    This batch file will set up everything needed to create a successful build. Now execute:

    b2.exe link=shared variant=release,debug architecture=x86 address-model=64 threading=multi --build-type=complete install

    This command will start a (very long) build of all available Boost libraries. Please, be patient.

  • Open CMake-GUI.exe and set up your source directory (input field 'Where is the source code') to the base directory of the source code you downloaded from HPX's GitHub pages. Here's an example of my CMake path settings which point to my Documents/GitHub/hpx folder:

    Figure 3. Example CMake path settings

    Example CMake path settings

    Inside the 'Where is the source-code' enter the base directory of your HPX source directory (do not enter the "src" sub-directory!) Inside 'Where to build the binaries' you should put in the path where all the building process will happen. This is important because the building machinery will do an "out-of-tree" build. CMake is not touching or changing in any way the original source files. Instead, it will generate Visual Studio Solution Files which will build HPX packages out of the HPX source tree.

  • Set four new environment variables (in CMake, not in Windows environment, by the way): BOOST_ROOT, HWLOC_ROOT, CMAKE_INSTALL_PREFIX and HPX_WITH_BOOST_ALL_DYNAMIC_LINK

    The meaning of these variables is as follows:

    • BOOST_ROOT: the root directory of the unpacked Boost headers/cpp files.
    • HWLOC_ROOT: the root directory of the unpacked Portable Hardware Locality files.
    • CMAKE_INSTALL_PREFIX: the "root directory" where the future builds of HPX should be installed to.

    [Note] Note

    HPX is a BIG software collection and I really don't recommend using the default C:\Program Files\hpx. I prefer simpler paths without white space, like C:\bin\hpx or D:\bin\hpx etc.

    To insert new env-vars click on "Add Entry" and then insert the name inside "Name", select PATH as Type and put the path-name in "Path" text field. Repeat this for the first three variables.

    The last one: HPX_WITH_BOOST_ALL_DYNAMIC_LINK is a BOOL and must be checked (there will be a checkbox instead of a textfield).

    This is how variable insertion looks like:

    Figure 4. Example CMake Adding Entry

    Example CMake Adding Entry

    Alternatively you could provide BOOST_LIBRARYDIR instead of BOOST_ROOT with a difference that BOOST_LIBRARYDIR should point to the subdirectory inside Boost root where all the compiled DLLs/LIBs are. I myself have used BOOST_LIBRARYDIR which pointed to the bin.v2 subdirectory under the Boost rootdir. Important is to keep the meanings of these two variables separated from each other: BOOST_DIR points to the ROOT folder of the boost library. BOOST_LIBRARYDIR points to the subdir inside Boost root folder where the compiled binaries are.

  • Click the 'Configure' button of CMake-GUI. You will be immediately presented a small window where you can select the C++ compiler to be used within Visual Studio. In my case I have used the latest v14 (a.k.a C++ 2015) but older versions should be sufficient too. Make sure to select the 64Bit compiler
  • After the generate process has finished successfully click the 'Generate' button. Now, CMake will put new VS Solution files into the BUILD folder you selected at the beginning.
  • Open Visual Studio and load the HPX.sln from your build folder.
  • Go to CMakePredefinedTargets and build the INSTALL project:

    Figure 5. Visual Studio INSTALL Target

    Visual Studio INSTALL Target

    It will take some time to compile everything and in the end you should see an output similar to this one:

    Figure 6. Visual Studio Build Output

    Visual Studio Build Output

So far we only support BGClang for compiling HPX on the BlueGene/Q.

  • Check if BGClang is available on your installation. If not obtain and install a copy from the BGClang trac page <https://trac.alcf.anl.gov/projects/llvm-bgq>_
  • Build (and install) a recent version of Hwloc Downloads With the following commands:
./configure \
  --host=powerpc64-bgq-linux \
  --prefix=$HOME/install/hwloc \
  --disable-shared \
  --enable-static \
  CPPFLAGS='-I/bgsys/drivers/ppcfloor -I/bgsys/drivers/ppcfloor/spi/include/kernel/cnk/'
make install
  • Build (and install) a recent version of Boost, using BGClang:: To build Boost with BGClang, you'll need to set up the following in your Boost ~/user-config.jam file:
# user-config.jam (put this file into your home directory)
using clang
  : bgclang++11

You can then use this as your build command:

./b2 --build-dir=/tmp/build-boost --layout=versioned toolset=clang -j12
  • Clone the master HPX git repository (or a stable tag):
git clone git://github.com/STEllAR-GROUP/hpx.git
  • Generate the HPX buildfiles using cmake:
cmake -DHPX_PLATFORM=BlueGeneQ \
        -DCMAKE_TOOLCHAIN_FILE=/path/to/hpx/cmake/toolchains/BGQ.cmake \
        -DCMAKE_CXX_COMPILER=bgclang++11 \
        -DMPI_CXX_COMPILER=mpiclang++11 \
        -DHWLOC_ROOT=/path/to/hwloc/installation \
        -DBOOST_ROOT=/path/to/boost \
        -DHPX_WITH_MALLOC=system \
  • To complete the build and install HPX:
make -j24
make install
This will build and install the essential core components of HPX only. Use:
make -j24 examples
make -j24 install
to build and install the examples.
Installation of the Boost Libraries
  • Download Boost Downloads for Linux and unpack the retrieved tarball.
  • Adapt your ~/user-config.jam to contain the following lines:

    ## Toolset to be used for compiling for the host
    using intel
        : host
        : <cxxflags>"-std=c++0x"
    ## Toolset to be used for compiling for the Xeon Phi
    using intel
        : mic
        : <cxxflags>"-std=c++0x -mmic"
          <linkflags>"-std=c++0x -mmic"
  • Change to the directory you unpacked boost in (from now on referred to as $BOOST_ROOT) and execute the following commands:

    ./b2 toolset=intel-mic -j<N>

    You should now have all the required boost libraries.

Installation of the hwloc Library
  • Download Hwloc Downloads, unpack the retrieved tarball and change to the newly created directory
  • Run the configure-make-install procedure as follows
CC=icc CFLAGS=-mmic CXX=icpc CXXFLAGS=-mmic LDFLAGS=-mmic ./configure --host=x86_64-k1om-linux --prefix=$HWLOC_ROOT
make install
[Important] Important

The minimally required version of the Portable Hardware Locality (HWLOC) library on the Intel Xeon Phi is V1.6.

You now have a working hwloc installation in $HWLOC_ROOT.

Building HPX

After all the prerequisites have been successfully installed, we can now start building and installing HPX. The build procedure is almost the same as for How to Install HPX on Unix Variants with the sole difference that you have to enable the Xeon Phi in the CMake Build system. This is achieved by invoking CMake in the following way:

cmake                                             \
    -DCMAKE_TOOLCHAIN_FILE=/path/to/hpx/cmake/toolchains/XeonPhi.cmake \
    -DBOOST_ROOT=$BOOST_ROOT                      \
    -DHWLOC_ROOT=$HWLOC_ROOT                      \

For more detailed information about using CMake please refer its documentation and to the section Building HPX with CMake. Please pay special attention to the section about HPX_WITH_MALLOC as this is crucial for getting decent performance on the Xeon Phi.

[Note] Note

This section of the manual is based off of our collaborators Patrick Diehl's blog Installing HPX on Fedora 22.

  • Install all packages for minimal installation

    sudo dnf install gcc-c++ cmake boost-build boost boost-devel hwloc-devel \
      hwloc gcc-gfortran papi-devel gperftools-devel docbook-dtds \
      docbook-style-xsl libsodium-devel doxygen boost-doc hdf5-devel \
      fop boost-devel boost-openmpi-devel boost-mpich-devel
  • Get the development branch of HPX

    git clone https://github.com/STEllAR-GROUP/hpx.git
  • Configure it with CMake

    cd hpx
    mkdir build
    cd build
    cmake -DCMAKE_INSTALL_PREFIX=/opt/hpx ..
    make -j
    make install
[Note] Note

To build HPX without examples use:

  • Add the library path of HPX to ldconfig

    sudo echo /opt/hpx/lib > /etc/ld.so.conf.d/hpx.conf
    sudo ldconfig