build.md

title	description	published	tags	editor	date	dateCreated
Compiling Your Program		true		markdown	2023-07-13 15:15:00 UTC	2020-05-19 15:50:13 UTC

Building a software is the process of producing a machine executable code from source files. The simplest form of it, is a one-line call to the compiler. But more commonly, on Linux systems a makefile is used to build the code systematically. However more increasingly the larger projects choose to use a multi-step automated build system managed by tools like autotools or cmake.

In STE||AR group we use cmake for our build system. Since many general guides are available on how to build your program (our favorite one is this one form TACC portal), we decided to avoid repeating the instructions and only mention the important ones.

Building HPX on Rostam

The first setup is to setup your development environment by loading appropriate modules. Rostam provides three sets of compilers; gcc, llvm/clang and Intel. Choose your weapon wisely. For this guide you we use llvm compiler, for the others the instructions are similar.

Loading the compiler:

module load llvm		# Load default version of llvm/clang
# This set all variable and flags necessary to build HPX

Then load other HPX prerequisites, the list could vary based on your components and flags. These are the usual ones:

module load boost cmake git papi hwloc

It is a good practice that from early on, you organize your home and work directories. You are allocated 50GB in $HOME and 1TB in $WORK directories. There is no performance difference between the two. Keep the important codes and data in home and move large libraries and data to work.{.is-success}

Use cdw command to quickly switch to your work directory. {.is-success}

Let's assume you want to use work directory and you want to keep the source files in source directory and compiled programs in a directory named apps. First we create those directories and clone HPX in source:

mkdir $WORK/{source,apps}
cd $WORK/source
git clone https://github.com/STEllAR-GROUP/hpx.git

Now you have a fresh copy of HPX in $WORK/source/hpx. HPX's cmake requires to run cmake command on a separate directory than source code, it doesn't matter this build directory is inside or outside the source directory just it can't be the same as the source. Let's make a build directory inside source directory and do our business there.

mkdir $WORK/source/hpx/build
cd $WORK/source/hpx/build

Now we are ready for our first step of the build process, which is the cmake command. The cmake will read the instructions and generate the next step of the build process. By default on linux systems, cmake will generate makefile. Let's go with that:

cmake \
-DCMAKE_BUILD_TYPE=Release \
-DHPX_WITH_THREAD_IDLE_RATES=ON \
-DCMAKE_INSTALL_PREFIX=$WORK/apps/hpx-$(date +'%Y%m%d') \
$WORK/source/hpx/

Let's go over the command options one by one:

-DCMAKE_BUILD_TYPE=Release sets the build type flag. The options are Debug, Release, RelWithDebInfo.

The DHPX_WITH_THREAD_IDLE_RATES=ON is an optional flag but a good one to have. It is an example of HPX options, built-in on its cmake configuration. We placed it here to show the process.

The -DCMAKE_INSTALL_PREFIX= flag sets the installation destination. Here we chose $WORK/apps/hpx- + today's date.

It's a good practice to note the date you cloned the master to keep a record of how old your library is. If found it annoying to keep the track of your libraries path, you can create a soft link to hide the dates when using the library; ln -s $WORK/apps/hpx-$(date +'%Y%m%d') $WORK/apps/hpx {.is-success}

If everything goes according to the plan, cmake should populate your build directory (your current directory) with necessary makefiles to build HPX. Next step would be to invoke the make command to compile HPX, here we instruct make to use 12 concurrent jobs as an example:

make -j 12

In last step we invoke make install to copy the binary files to its destination:

make install

Voila! You successfully compiled HPX. Let's give it a test run:

$ cd $WORK/apps/hpx-$(date +'%Y%m%d')
$ ./bin/hello_world_1
Hello World!