CLion 2023.2 Help

How to work with OpenMPI projects in CLion

OpenMPI is an open-source implementation of the Message Passing Interface (MPI) library, which is a standard designed to support high-performance parallel computing. OpenMPI combines technologies and resources from several MPI projects.

This tutorial will guide you through the steps of setting up, building, running, and debugging an OpenMPI project in CLion. The instructions are general, and you can apply them to your sources. To illustrate the steps, we use a simple C++ application that includes OpenMPI functions. The instructions are given for the case of working on macOS.

0. Before you start: install OpenMPI on your system

  1. Download and build OpenMPI. In case of errors, try the troubleshooting tips given on the same official FAQ page.

  2. As a simple check, run mpicc from the command line - your system should recognize the command.

1. Create a new project in CLion

  1. Select File | New | Project... from the main menu or click New Project on the welcome screen.

  2. Starting a new C++ project

    In the left-hand pane, choose the project type (C++ Executable in our example).

    Provide the project location and set the language standard.

    Click Create.

  3. CLion will generate a stub CMake project:

    Stub CMake project

2. Add your source files

  1. Copy your source files to the project folder.

    In our example, the files are openmpi_test.cpp and openmpi_test.h. Copy-paste the code below if you would like to use them as a sample, or take your own files:

    #include <mpi.h> #include <cstdio> void print_processors() { // Initialize the MPI environment MPI_Init(nullptr, nullptr); // Get the number of processes int world_size; MPI_Comm_size(MPI_COMM_WORLD, &world_size); // Get the rank of the process int world_rank; MPI_Comm_rank(MPI_COMM_WORLD, &world_rank); // Get the name of the processor char processor_name[MPI_MAX_PROCESSOR_NAME]; int name_len; MPI_Get_processor_name(processor_name, &name_len); // Print off a hello world message printf("Hello world from processor %s, rank %d out of %d processors\n", processor_name, world_rank, world_size); // Finalize the MPI environment. MPI_Finalize(); }
    #ifndef OPENMPI_TEST_OPENPMI_HELLO_H #define OPENMPI_TEST_OPENPMI_HELLO_H void print_processors(); #endif //OPENMPI_TEST_OPENPMI_HELLO_H
    #include "openmpi_test.h" int main() { print_processors(); return 0; }

    At this point, new files are not yet added to the CMake project structure, and OpenMPI code is not recognized by the IDE:

    OpenMPI files are not recognized
                until added to CMakeLists.txt
  2. Add the files to CMake.

    • To add a single file, click Add to CMake Project in the notification bar.

    • To add multiple files, select them in the Project tree and call Add to CMake Project from the context menu.

    Select the target, and CLion will add the files automatically:

    Adding a file to a CMake target

3. Tune CMakeLists.txt and load the project

Open the CMakeLists.txt file and make the following changes:

  1. Add this line before add_executable:

    find_package(MPI REQUIRED)
  2. Add this line after add_executable:

    target_link_libraries(<your_project_name> PRIVATE MPI::MPI_CXX)

    An example of CMakeLists.txt content:

    cmake_minimum_required(VERSION 3.25) project(openmpi_test) set(CMAKE_CXX_STANDARD 17) # Add MPI Package to Project find_package(MPI REQUIRED) add_executable(openmpi_test main.cpp openmpi_hello.cpp) # Link MPI libraries target_link_libraries(openmpi_test PRIVATE MPI::MPI_CXX)
  3. When you make changes in CMakeLists.txt, CLion shows the icon suggesting to reload the project structure. Click it or press the shortcut:

    Reloading CMake

    CMake reload and project build should finish successfully:

    Building an OpenMPI project after changing the
CMakeLists.txt script

    If there are errors, double-check your CMakeLists.txt and your OpenMPI installation.

    You can find the binary in the cmake-build-debug folder (or another build location, in case you have changed it):

    Binary file in the build directory

4. Build your program

Use one of the options:

  • Call Build | Build Project from the main menu.

    For more information about this action, refer to Build actions.

  • CLion automatically creates a configuration of the type CMake Application for each of the targets detected in CMakeLists.txt.

    To build a target using the configuration, select it in the switcher and click the hammer icon or press Control+F9:

    Building a configuration

5. (Optional) Configure CMake profiles

In CMake profile settings, you can adjust build options, environment variables, build directory, and other parameters.

  1. Go to Settings | Build, Execution, Deployment | CMake.

    In this dialog, you can edit profile settings and create/remove profiles. For more information, refer to CMake profiles.

    Debug and Release profiles
  2. Project profiles are listed in the configuration switcher. Make sure to select the required profile before building a CMake configuration.

    Profiles in the configuration switcher

5. Run the application

OpenMPI programs should run under special launchers, mpiexec, mpirun, or orterun (synonyms for the case of executing serial and parallel jobs in OpenMPI). To invoke them with the required program arguments, use CLion's Shell Script configuration.

  1. Go to Run | Edit Configurations.

  2. Click App general add and select Shell Script:

    Adding a Shell Script configuration
  3. Adjust the configuration settings:

    • Edit the configuration name.

    • In Execute:, select Script text.

    • In Script text, specify the command to run your program.

      In our example, it's mpiexec -n 4 ./cmake-build-debug/openmpi_test

    Shell Script configuration settings
  4. Save the settings, then select the newly created configuration in the switcher and click The Run button or press Shift+F10.

    Running a Shell Script
                configuration

    Your program should launch successfully. CLion will show the output in the Terminal tool window:

    OpenMPI program output in console

6. Debug by attaching to process

In order to debug an OpenMPI application in CLion, you need to launch it first and then attach the debugger to each of the running processes.

  1. Place breakpoints in your code by clicking in the left gutter next to the desired lines.

  2. Add the following piece of code before each breakpoint:

    int i = 0; while (!i) sleep(5);
  3. Place a breakpoint on the sleep(5); line.

    Breakpoints in the code to debug
  4. Rebuild with Build | Build Project or using a configuration.

    Make sure the Debug profile is selected.

  5. Run the Shell Script configuration. Select it in the switcher and click The Run button or press Shift+F10.

    Running a Shell Script
                configuration
  6. Press Control+Alt+F5 or select Run | Attach to Process from the main menu.

  7. In the dialog that opens, search for the process you want to attach to and click Attach with ....

    Attaching to process
  8. In the Variables pane of the Debug tool window, select i and press F2. Set a non-zero value:

    Setting a variable value
  9. Continue debugging as usual.

    With the debugger attached, you can use all the CLion debug features, such as breakpoints of different types, stepping actions, memory and disassembly view, expressions evaluating, and so on.

    Stepping through a program with attached debugger
  10. Repeat the steps 6-9 to debug another process.

Last modified: 31 October 2023