brakmic/hpx-builder repository overview

⁠HPX Builder Docker Image

⁠Table of Contents

• 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⁠

⁠Introduction

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.

⁠Features

• 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.

⁠Getting Started

⁠Prerequisites

• 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.

⁠Pulling the Docker Image

Retrieve the latest HPX Builder image from Docker Hub:

docker pull brakmic/hpx-builder:latest

⁠Running the Builder Container

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.

⁠Using the HPX Builder

⁠Locating HPX Libraries and Headers

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/

⁠Configuring Your C++ Application

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)

⁠Compiling and Linking Your Application

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
   

   Copy

2. Create a Build Directory:

   mkdir build && cd build
   

   Copy

3. Configure the Project with CMake:

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

   Copy

4. Build the Project:

   make -j$(nproc)
   

   Copy

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

⁠Example: Simple HPX Application

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

⁠Project Structure

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

⁠CMake Configuration

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)

⁠Example HPX Application

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;
}

⁠Building the Example

1. Start the Builder Container:

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

   Copy

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

2. Navigate to the Application Directory:

   cd /app
   

   Copy

3. Create and Navigate to Build Directory:

   mkdir build && cd build
   

   Copy

4. Configure the Project with CMake:

   cmake .. -DCMAKE_PREFIX_PATH=/usr/local
   

   Copy

5. Build the Application:

   make -j$(nproc)
   

   Copy

⁠Running the Example

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.

⁠Advanced Usage

⁠Custom Build Arguments

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 \
      .
    

    Copy

• 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 \
      .
    

    Copy

⁠Mounting Volumes for Development

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
   

   Copy

2. Build as Usual:

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

   Copy

⁠Integration with CI/CD

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"

⁠License

This project is licensed under the MIT License⁠.