• HPX Builder Docker Image
  • Table of Contents
  • Introduction
  • Features
  • Getting Started
    • Prerequisites
    • Pulling the Docker Image
    • Running the Builder Container
  • Using the HPX Builder
    • Locating HPX Libraries and Headers
    • Configuring Your C++ Application
    • Compiling and Linking Your Application
  • Example: Simple HPX Application
    • Project Structure
    • CMake Configuration
    • Example HPX Application
    • Building the Example
    • Running the Example
  • Advanced Usage
    • Custom Build Arguments
    • Mounting Volumes for Development
    • Integration with CI/CD
  • License

The HPX Builder Docker Image provides a pre-configured environment for C++ developers to efficiently build and develop applications using HPX, a high-performance parallel and distributed runtime system. By leveraging Docker, this image ensures a consistent development setup across different machines and environments, eliminating the "it works on my machine" problem.

• Precompiled HPX Libraries: Quickly integrate HPX into your projects without manual compilation.
• Boost.Asio Integration: Utilizes Boost.Asio for asynchronous operations, ensuring compatibility and performance.
• Memory Allocator Support: Configured to use jemalloc for optimized memory management.
• Customizable Builds: Supports build arguments to tailor the HPX build to your specific requirements.
• Efficient Docker Layers: Optimized Dockerfile structure for faster builds and smaller image sizes.
• Comprehensive Logging: Provides detailed build logs to assist in monitoring and debugging.

• Docker: Ensure Docker is installed on your system. You can download it from here.
• C++ Development Environment: Familiarity with C++ and CMake for building HPX applications.

Retrieve the latest HPX Builder image from Docker Hub:

docker pull brakmic/hpx-builder:latest

Launch an interactive container using the HPX Builder image:

docker run --rm -it brakmic/hpx-builder:latest /bin/bash

This command starts a container and opens a bash shell, allowing you to interact with the HPX environment.

Within the running container, HPX is installed at /usr/local/hpx. The libraries and headers can be found in the following directories:

• Headers: /usr/local/hpx/include/
• Libraries: /usr/local/hpx/lib/

To utilize HPX in your C++ project, configure your CMakeLists.txt to find and link against the HPX libraries provided by the builder image.

Example CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(MyHPXApp)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Specify the path to HPX installation
set(HPX_ROOT "/usr/local/hpx")

# Find HPX
find_package(HPX REQUIRED)

add_executable(my_hpx_app src/main.cpp)

# Link HPX libraries
target_link_libraries(my_hpx_app PRIVATE HPX::hpx HPX::wrap_main)

Within the builder container, navigate to your project directory and build your application using CMake and Make.

Steps:

1. Navigate to Project Directory:

   cd /path/to/your/project

2. Create a Build Directory:

   mkdir build && cd build

3. Configure the Project with CMake:

   cmake .. -DCMAKE_PREFIX_PATH=/usr/local/hpx

4. Build the Project:

   make -j$(nproc)

This process compiles your application and links it against the precompiled HPX libraries.

To demonstrate the usage of the HPX Builder image, let's walk through building a simple HPX-based C++ application.

my_hpx_app/
├── CMakeLists.txt
└── src/
    └── main.cpp

CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(MyHPXApp)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Specify the path to HPX installation
set(HPX_ROOT "/usr/local/hpx")

# Find HPX
find_package(HPX REQUIRED)

add_executable(my_hpx_app src/main.cpp)

# Link HPX libraries
target_link_libraries(my_hpx_app PRIVATE HPX::hpx HPX::wrap_main)

src/main.cpp:

#include <hpx/hpx_main.hpp>
#include <hpx/include/parallel_sort.hpp>
#include <vector>
#include <algorithm>
#include <iostream>

int main()
{
    // Initialize a vector with unsorted integers
    std::vector<int> data = {50, 20, 40, 10, 30};

    std::cout << "Before HPX sort: ";
    for(auto num : data)
        std::cout << num << " ";
    std::cout << std::endl;

    // Perform parallel sort using HPX
    hpx::sort(hpx::execution::par, data.begin(), data.end());

    std::cout << "After HPX sort: ";
    for(auto num : data)
        std::cout << num << " ";
    std::cout << std::endl;

    return 0;
}

1. Start the Builder Container:

   docker run --rm -it -v $(pwd)/my_hpx_app:/app brakmic/hpx-builder:latest /bin/bash

   This command mounts your local my_hpx_app directory to /app inside the container.

2. Navigate to the Application Directory:

   cd /app

3. Create and Navigate to Build Directory:

   mkdir build && cd build

4. Configure the Project with CMake:

   cmake .. -DCMAKE_PREFIX_PATH=/usr/local

5. Build the Application:

   make -j$(nproc)

After a successful build, run the application:

./my_hpx_app

Expected Output:

Before HPX sort: 50 20 40 10 30 
After HPX sort: 10 20 30 40 50 

This output confirms that HPX successfully sorted the vector in parallel.

The HPX Builder image supports build arguments to customize the HPX build process.

• HPX_TAG: Specifies the HPX version to build.

  • Default: v1.11.0
  • Usage:

    docker build -t brakmic/hpx-builder:v1.11.0 \
      -f docker/hpx-builder.Dockerfile \
      --build-arg HPX_TAG=v1.11.0 \
      .

• HPX_WITH_ASIO: Configures HPX to use either Boost.Asio or standalone Asio.

  • Options: Boost, ASIO
  • Default: ASIO
  • Usage:

    docker build -t brakmic/hpx:v1.11.0-asio \
      -f docker/hpx-builder.Dockerfile \
      --build-arg HPX_WITH_ASIO=ASIO \
      .

For an efficient development workflow, mount your local project directory into the container. This allows you to edit files locally and build within the container.

Example Command:

docker run --rm -it \
  -v $(pwd)/my_hpx_app:/app \
  brakmic/hpx-builder:latest \
  /bin/bash

Inside the Container:

1. Navigate to the Mounted Directory:

   cd /app

2. Build as Usual:

   mkdir build && cd build
   cmake .. -DCMAKE_PREFIX_PATH=/usr/local
   make -j$(nproc)

Integrate the HPX Builder image into your Continuous Integration/Continuous Deployment (CI/CD) pipelines to automate the build and testing of your HPX-based applications.

Example GitHub Actions Workflow:

name: Build and Test HPX Application

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Repository
      uses: actions/checkout@v3

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v2

    - name: Build HPX Builder Image
      run: |
        docker build -t brakmic/hpx-builder:latest \
          -f docker/hpx-builder.Dockerfile \
          .

    - name: Build Application
      run: |
        docker run --rm -v ${{ github.workspace }}/my_hpx_app:/app \
          brakmic/hpx-builder:latest \
          bash -c "cd /app && mkdir build && cd build && cmake .. -DCMAKE_PREFIX_PATH=/usr/local && make -j$(nproc)"

    - name: Run Tests
      run: |
        docker run --rm -v ${{ github.workspace }}/my_hpx_app:/app \
          brakmic/hpx-builder:latest \
          bash -c "cd /app/build && ./my_hpx_app"

This project is licensed under the MIT License.