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. Create a new project in CLion
Select New Project on the welcome screen.
from the main menu or clickIn the left-hand pane, choose the project type (C++ Executable in our example).
Provide the project location and set the language standard.
Click Create.
CLion will generate a stub CMake project:
2. Add your source files
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:
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:
Add this line before
add_executable
:find_package(MPI REQUIRED)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)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
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:
5. (Optional) Configure CMake profiles
In CMake profile settings, you can adjust build options, environment variables, build directory, and other parameters.
Go to
.In this dialog, you can edit profile settings and create/remove profiles. For more information, refer to CMake profiles.
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.
Go to
.Click and select Shell Script:
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
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.
Place breakpoints in your code by clicking in the left gutter next to the desired lines.
Add the following piece of code before each breakpoint:
int i = 0; while (!i) sleep(5);Place a breakpoint on the
sleep(5);
line.Rebuild with using a configuration.
orMake sure the Debug profile is selected.
Run the Shell Script configuration. Select it in the switcher and click or press Shift+F10.
Press Control+Alt+F5 or select
from the main menu.In the dialog that opens, search for the process you want to attach to and click Attach with ....
In the Variables pane of the Debug tool window, select
i
and press F2. Set a non-zero value: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.
Repeat the steps 6-9 to debug another process.