Build Wrapper

The build wrapper script aims at calling the CMake superbuild with proper arguments using a one line call. It wraps the download, clean, configure, build, and test steps. If tests are executed, the analysis script will run afterwards as well.

By default, this wrapper script does nothing. To enable a project, use --with=<project> and --test. A minimal call for building and testing would sum up to the following command:

export TOOLCHAIN=bull/bull-intel+mpi+mkl
# ./ is the first argument (hpcw directory)
# the script will look for ${TOOLCHAIN}.env.sh in the toolchains/ directory
./toolchains/build-wrapper.sh ./ ${TOOLCHAIN}.env.sh --with=ectrans --test

Usage

./toolchains/build-wrapper.sh usage:
    $1                HPCW directory
    $2                Environment file (.env.sh); the build wrapper script will lookup the file in the $HPCW_SOURCE_DIR/toolchains/ directory; or the user can specify an absolute path
    -h|--help)        display this message
    --shell)          opens a shell with all environment configured, right before exiting
    --no-shell)       opposite of --shell (default)
    --no-analysis)    disable execution of analysis script after the tests
    --with)           activate a project (e.g., --with=ectrans)
    --reconfigure)    force the reconfigure step; implies rebuild
    --clean)          erase build directory, forcing reconfigure & rebuild
    --rebuild)        force rebuild
    --test)           launch test
    --cmake-flags)    add to CMake flags
    --ctest-flags)    add to CTest flags
    --build-dir)      custom build directory;
    --install-dir)    custom install directory;
    --log-dir)        custom log directory;
    --)               skip following arguments

The build, install and log directories can also be controlled via the environment variables HPCW_{BUILD,INSTALL,LOG}_DIR. The build and install directories default to $PWD/{build,install} respectively. The log directory defaults to ${HPCW_BUILD_DIR}/logs.

How-Tos

Run a Specific Test Case for a Project

Use the --ctest-flags argument to specify a regular expression to filter the test name:

./toolchains/build-wrapper.sh $(pwd) ${TOOLCHAIN}.env.sh \
    --with=ectrans --test \
    --ctest-flags="-R ectrans-cpu-small" # small size problem

The regular expression is interpreted as *<test name>*. That is, --ctest-flags="-R small" will run all the small test cases for the activated projects (if there are any).

Override the Job Launcher or Stage-in

The toolchains usually define a launcher, using the following syntax:

# ${TOOLCHAIN}.env.sh
cmakeFlags+=" -DCMAKE_TOOLCHAIN_FILE=$HPCW_SOURCE_DIR/toolchains/${TOOLCHAIN}.cmake"
 
# ${TOOLCHAIN}.cmake
set(HPCW_JOB_LAUNCHER ${CMAKE_SOURCE_DIR}/toolchains/bull-job-launcher.sbatch) # launcher
set(HPCW_JOB_STAGEIN ${CMAKE_SOURCE_DIR}/toolchains/job-stagein.sh)            # stage-in

To override theses values, Use the --cmake-flags argument and set the CMake variable HPCW_JOB_LAUNCHER :

./toolchains/build-wrapper.sh $(pwd) ${TOOLCHAIN}.env.sh \
    --with=ectrans --test \
    --cmake-flags="-DHPCW_JOB_LAUNCHER=<launcher>"

Override the Default Configure Flags

For exploring purposes, it is possible to override the default flags on a per-project basis. This is done by passing down specific flags to the superbuild CMake, that will then add CMake flags to the projects, as described here:

# express flags
ectrans_cmake_CFLAGS="-O3 -march=native -mtune=native"
ectrans_cmake_FFLAGS="-O3 -march=native -mtune=native -heap-arrays 32"
 
# build a list of cmake flags to pass the flags down
# 1. Make sure this is a cmake list (separate flags with ';')
# 2. also make sure the arguments are surrounded with escaped quotes (either ' or \")
# 3. Finally make sure there is no space/line return in between cmake flags
#
# Note: this also applies to configure and make arguments : they are all treated as
#       a CMake list before getting passed down.
ectrans_cmake_args="-DCMAKE_C_FLAGS='$ectrans_cmake_CFLAGS';-DCMAKE_Fortran_FLAGS='$ectrans_cmake_FFLAGS';-DCMAKE_BUILD_TYPE=None"
 
# Escape the string to pass down to the build wrapper
# see bash manpage for printf %q : https://linux.die.net/man/1/bash
build_wrapper_cmake_args="-Dectrans_cmake_args=\"$(printf "%q" "$ectrans_cmake_args")\""
 
# Finally call the build wrapper with the escaped arguments
./toolchains/build-wrapper.sh $PWD ${HPCW_TOOLCHAIN_PATH} \
        --with=ectrans  \
        --clean \
        --ctest-flags="-R ectrans-cpu-small" \
        --test \
        --cmake-flags="$build_wrapper_cmake_args"

# another example with FFTW (with a configure script)
fftw_configure_args="--disable-doc;--enable-fma"
fftw_build_args="-j1;VERBOSE=0"
build_wrapper_cmake_args="\
    -Dfftw_configure_args=\"$(printf "%q" "$fftw_configure_args")\" \
    -Dfftw_build_args=\"$(printf "%q" "$fftw_build_args")\""
./toolchains/build-wrapper.sh $PWD ${HPCW_TOOLCHAIN_PATH} \
        --with=fftw  \
        --clean \
        --cmake-flags="$build_wrapper_cmake_args"

See the toolchain documentation for adding this in the toolchain definitions, in a more reproducible way.

Examples

Compile (only, not run) ectrans :

#!/usr/bin/env bash
set -ue -o pipefail
 
export HPCW_SOURCE_DIR=$(pwd)
export TMP=/dev/shm
export TMPDIR=$TMP
export TEMP=$TMP
export TEMPDIR=$TMP
export HPCW_PARTITION=AMD
export envrc=bull-intel+mpi+mkl
export git_describe_tag=$(echo -n $(git --git-dir=$HPCW_SOURCE_DIR/.git --work-tree=$HPCW_SOURCE_DIR describe --tag --always --dirty))
export hpcw_install_dir=/scratch_na/users/$USER/hpcw/install/bb/ectrans
export hpcw_build_dir=/scratch_na/users/$USER/hpcw/build/bb/ectrans
export salloc_launch=${salloc_launch-salloc -N1 --exclusive -p AMD_7763_2s_64c_2t_hdr100_256GB_3200 -A pro_2023_clusster --licenses=scratch_na:1 -- srun -n1 -N1 --mem-per-cpu=0 --preserve-env --cpu-bind=no --mpi=none}
 
# compile model
cmakeFlags+=" -DENABLE_SVN_CHECKOUT=ON"
 
# submit compilation
$salloc_launch $HPCW_SOURCE_DIR/toolchains/build-wrapper.sh $HPCW_SOURCE_DIR $envrc.env.sh --build-dir=$hpcw_build_dir --install-dir=$hpcw_install_dir --cmake-flags="$cmakeFlags" --with=ectrans |& tee compile-ectrans.log
exit 0

Run ectrans; reuse $hpcw_build_dir from compile step if ran previously

set -ue -o pipefail
 
export HPCW_SOURCE_DIR=$(pwd)
export TMP=/dev/shm
export TMPDIR=$TMP
export TEMP=$TMP
export TEMPDIR=$TMP
export HPCW_PARTITION=AMD
export envrc=bull-intel+mpi+mkl
export git_describe_tag=$(echo -n $(git --git-dir=$HPCW_SOURCE_DIR/.git --work-tree=$HPCW_SOURCE_DIR describe --tag --always --dirty))
export hpcw_install_dir=/scratch_na/users/$USER/hpcw/install/bb/ectrans
export hpcw_build_dir=/scratch_na/users/$USER/hpcw/build/bb/ectrans
 
cd $hpcw_build_dir || exit 1
 
$HPCW_SOURCE_DIR/toolchains/build-wrapper.sh $HPCW_SOURCE_DIR $envrc.env.sh --build-dir=$hpcw_build_dir --install-dir=$hpcw_install_dir --with=ectrans --test |& tee ectrans.log