To get started with Boost.MPI, you will first need a working MPI implementation. There are many conforming MPI implementations available. Boost.MPI should work with any of the implementations, although it has only been tested extensively with:

You can test your implementation using the following simple program, which passes a message from one processor to another. Each processor prints a message to standard output.

#include <mpi.h>
#include <iostream>

int main(int argc, char* argv[])
{
  MPI_Init(&argc, &argv);

  int rank;
  MPI_Comm_rank(MPI_COMM_WORLD, &rank);
  if (rank == 0) {
    int value = 17;
    int result = MPI_Send(&value, 1, MPI_INT, 1, 0, MPI_COMM_WORLD);
    if (result == MPI_SUCCESS)
      std::cout << "Rank 0 OK!" << std::endl;
  } else if (rank == 1) {
    int value;
    int result = MPI_Recv(&value, 1, MPI_INT, 0, 0, MPI_COMM_WORLD,
			  MPI_STATUS_IGNORE);
    if (result == MPI_SUCCESS && value == 17)
      std::cout << "Rank 1 OK!" << std::endl;
  }
  MPI_Finalize();
  return 0;
}

You should compile and run this program on two processors. To do this, consult the documentation for your MPI implementation. With LAM/MPI, for instance, you compile with the mpiCC or mpic++ compiler, boot the LAM/MPI daemon, and run your program via mpirun. For instance, if your program is called mpi-test.cpp, use the following commands:

mpiCC -o mpi-test mpi-test.cpp
lamboot
mpirun -np 2 ./mpi-test
lamhalt

When you run this program, you will see both Rank 0 OK! and Rank 1 OK! printed to the screen. However, they may be printed in any order and may even overlap each other. The following output is perfectly legitimate for this MPI program:

Rank Rank 1 OK!
0 OK!

If your output looks something like the above, your MPI implementation appears to be working with a C++ compiler and we're ready to move on.

Boost.MPI uses version 2 of the Boost.Build system for configuring and building the library binary. You will need a very new version of Boost.Jam (3.1.12 or later). If you already have Boost.Jam, run bjam -v to determine what version you are using.

Information about building Boost.Jam is available here. However, most users need only run build.sh in the tools/build/jam_src subdirectory of Boost. Then, copy the resulting bjam executable some place convenient.

For many users using LAM/MPI, MPICH, or OpenMPI, configuration is almost automatic. If you don't already have a file user-config.jam in your home directory, copy tools/build/v2/user-config.jam there. For many users, MPI support can be enabled simply by adding the following line to your user-config.jam file, which is used to configure Boost.Build version 2.

using mpi ;

This should auto-detect MPI settings based on the MPI wrapper compiler in your path, e.g., mpic++. If the wrapper compiler is not in your path, see below.

To actually build the MPI library, go into the top-level Boost directory and execute the command:

bjam --with-mpi

If your MPI wrapper compiler has a different name from the default, you can pass the name of the wrapper compiler as the first argument to the mpi module:

using mpi : /opt/mpich2-1.0.4/bin/mpiCC ;

If your MPI implementation does not have a wrapper compiler, or the MPI auto-detection code does not work with your MPI's wrapper compiler, you can pass MPI-related options explicitly via the second parameter to the mpi module:

using mpi : : <find-shared-library>lammpio <find-shared-library>lammpi++
              <find-shared-library>mpi <find-shared-library>lam
              <find-shared-library>dl ;

To see the results of MPI auto-detection, pass --debug-configuration on the bjam command line.

The (optional) fourth argument configures Boost.MPI for running regression tests. These parameters specify the executable used to launch jobs (default: "mpirun") followed by any necessary arguments to this to run tests and tell the program to expect the number of processors to follow (default: "-np"). With the default parameters, for instance, the test harness will execute, e.g.,

mpirun -np 4 all_gather_test

Installation of Boost.MPI can be performed in the build step by specifying install on the command line and (optionally) providing an installation location, e.g.,

bjam --with-mpi install

This command will install libraries into a default system location. To change the path where libraries will be installed, add the option --prefix=PATH.

To build applications based on Boost.MPI, compile and link them as you normally would for MPI programs, but remember to link against the boost_mpi and boost_serialization libraries, e.g.,

mpic++ -I/path/to/boost/mpi my_application.cpp -Llibdir \
  -lboost_mpi-gcc-mt-1_35 -lboost_serialization-gcc-d-1_35.a

If you would like to verify that Boost.MPI is working properly with your compiler, platform, and MPI implementation, a self-contained test suite is available. To use this test suite, you will need to first configure Boost.Build for your MPI environment and then run bjam in libs/mpi/test (possibly with some extra options). For LAM/MPI, you will need to run lamboot before running bjam. For MPICH, you may need to create a machine file and pass -sMPIRUN_FLAGS="-machinefile <filename>" to Boost.Jam; see the section on configuration for more information. If testing succeeds, bjam will exit without errors.