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.
Select File | New | Project... from the main menu or click New Project on the welcome screen.
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.
CLion will generate a stub CMake project:
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:
openmpi_test.cpp
{...}openmpi_test.h
{...}main.cpp
{...}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:
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):
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 CtrlF9:
tip
You can change configuration parameters and create more configurations in the Edit Configurations dialog.
In CMake profile settings, you can adjust build options, environment variables, build directory, and other parameters.
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.
tip
When you start a project, CLion creates a Debug profile. If you need a release build, add another profile of the type Release.
Project profiles are listed in the configuration switcher. Make sure to select the required profile before building a CMake configuration.
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.
In the main menu, go to Run | Edit Configurations.
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 ShiftF10.
Your program should launch successfully. CLion will show the output in the Terminal tool window:
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 Build | Build Project or using a configuration.
Make sure the Debug profile is selected.
Run the Shell Script configuration. Select it in the switcher and click
or press ShiftF10.
Press CtrlAltF5 or select Run | Attach to Process 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.
Thanks for your feedback!