How to work with OpenMPI projects in CLion

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. 

   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:

   

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:

   

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:

   

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:

   

   CMake reload and project build should finish successfully:

   

   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):

   

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 Ctrl+F9:

  

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.

   

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

   

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. In the main menu, go to Run | Edit Configurations.

2. Click and select Shell Script:

   

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

   

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

   

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

   

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.

   

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 or press Shift+F10.

   

6. Press Ctrl+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 ....

   

8. In the Variables pane of the Debug tool window, select i and press F2. Set a non-zero 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.

   

10. Repeat the steps 6-9 to debug another process.