Subsections


A. Installing Charm++

Charm++ can be installed manually from the source code or using a precompiled binary package. We also provide a source code package for the Spack package manager. Building from the source code provides more flexibility, since one can choose the options as desired. However, a precompiled binary may be slightly easier to get running.

A.1 Manual installation

A.1.1 Downloading Charm++

Charm++ can be downloaded using one of the following methods:

If you download the source code from the website, you will have to unpack it using a tool capable of extracting gzip'd tar files, such as tar (on Unix) or WinZIP (under Windows). Charm++ will be extracted to a directory called ``charm''.


A.1.2 Installation

A typical prototype command for building Charm++ from the source code is:


./build $<$TARGET$>$ $<$TARGET ARCHITECTURE$>$ [OPTIONS] where,

TARGET
is the framework one wants to build such as charm++ or AMPI.
TARGET ARCHITECTURE
is the machine architecture one wants to build for such as netlrts-linux-x86_64, pamilrts-bluegeneq etc.
OPTIONS
are additional options to the build process, e.g. smp is used to build a shared memory version, -j8 is given to build in parallel etc.

In Table A.1, a list of build commands is provided for some of the commonly used systems. Note that, in general, options such as smp, --with-production, compiler specifiers etc can be used with all targets. It is advisable to build with --with-production to obtain the best performance. If one desires to perform trace collection (for Projections), --enable-tracing --enable-tracing-commthread should also be passed to the build command.

Details on all the available alternatives for each of the above mentioned parameters can be found by invoking ./build --help. One can also go through the build process in an interactive manner. Run ./build, and it will be followed by a few queries to select appropriate choices for the build one wants to perform.


Table A.1: Build command for some common cases
Net with 32 bit Linux ./build charm++ netlrts-linux --with-production -j8
Multicore (single node, shared memory) 64 bit Linux ./build charm++ multicore-linux-x86_64 --with-production -j8
Net with 64 bit Linux ./build charm++ netlrts-linux-x86_64 --with-production -j8
Net with 64 bit Linux (intel compilers) ./build charm++ netlrts-linux-x86_64 icc --with-production -j8
Net with 64 bit Linux (shared memory) ./build charm++ netlrts-linux-x86_64 smp --with-production -j8
Net with 64 bit Linux (checkpoint restart based fault tolerance) ./build charm++ netlrts-linux-x86_64 syncft --with-production -j8
MPI with 64 bit Linux ./build charm++ mpi-linux-x86_64 --with-production -j8
MPI with 64 bit Linux (shared memory) ./build charm++ mpi-linux-x86_64 smp --with-production -j8
MPI with 64 bit Linux (mpicxx wrappers) ./build charm++ mpi-linux-x86_64 mpicxx --with-production -j8
IBVERBS with 64 bit Linux ./build charm++ verbs-linux-x86_64 --with-production -j8
OFI with 64 bit Linux ./build charm++ ofi-linux-x86_64 --with-production -j8
Net with 64 bit Windows ./build charm++ netlrts-win-x86_64 --with-production -j8
MPI with 64 bit Windows ./build charm++ mpi-win-x86_64 --with-production -j8
Net with 64 bit Mac ./build charm++ netlrts-darwin-x86_64 --with-production -j8
Blue Gene/Q (bgclang compilers) ./build charm++ pami-bluegeneq --with-production -j8
Blue Gene/Q (bgclang compilers) ./build charm++ pamilrts-bluegeneq --with-production -j8
Cray XE6 ./build charm++ gni-crayxe --with-production -j8
Cray XK7 ./build charm++ gni-crayxe-cuda --with-production -j8
Cray XC40 ./build charm++ gni-crayxc --with-production -j8


As mentioned earlier, one can also build Charm++ using the precompiled binary in a manner similar to what is used for installing any common software.

When a Charm++ build folder has already been generated, it is possible to perform incremental rebuilds by invoking make from the tmp folder inside it. For example, with a netlrts-linux-x86_64 build, the path would be netlrts-linux-x86_64/tmp. On Linux and macOS, the tmp symlink in the top-level charm directory also points to the tmp directory of the most recent build.

Alternatively, CMake can be used for configuring and building Charm++. You can use cmake-gui or ccmake for an overview of available options. Note that some are only effective when passed with -D from the command line while configuring from a blank slate. To build with all defaults, cmake . is sufficient, though invoking CMake from a separate location (ex: mkdir mybuild && cd mybuild && cmake ../charm) is recommended.

A.2 Installation through the Spack package manager

Charm++ can also be installed through the Spack package manager (https://spack.io/).

A basic command to install Charm++ through Spack is the following:


 $ spack install charmpp

By default, the netlrts network backend with SMP support is built. You can specify other backends by providing the backend parameter to spack. It is also possible to specify other options, as listed in Section A.1.2, by adding them to the Spack command prepended by a '+'. For example, to build the MPI version of Charm++ with the integrated OpenMP support, you can use the following command:


 $ spack install charmpp backend=mpi +omp

To disable an option, prepend it with a '~'. For example, to build Charm++ with SMP support disabled, you can use the following command:


 $ spack install charmpp ~smp

By default, the newest released version of Charm++ is built. You can select another version with the '@' option (for example, @6.8.1). To build the current git version of Charm++ , specify the @develop version:


 $ spack install charmpp@develop

A.3 Charm++ installation directories

The main directories in a Charm++ installation are:

charm/bin
Executables, such as charmc and charmrun, used by Charm++ .

charm/doc
Documentation for Charm++ , such as this document. Distributed as LaTeX source code; HTML and PDF versions can be built or downloaded from our web site.

charm/include
The Charm++ C++ and Fortran user include files (.h).

charm/lib
The static libraries (.a) that comprise Charm++ .

charm/lib_so
The shared libraries (.so/.dylib) that comprise Charm++ , if Charm++ is compiled with the -build-shared option.

charm/examples
Example Charm++ programs.

charm/src
Source code for Charm++ itself.

charm/tmp
Directory where Charm++ is built.

charm/tests
Test Charm++ programs used by autobuild.

A.4 Reducing disk usage

The charm directory contains a collection of example-programs and test-programs. These may be deleted with no other effects. You may also strip all the binaries in charm/bin.