This tutorial will guide you step by step in creating and developing a simple CMake project. We will learn the basics of CMake as a build system, as well as the setup and operations of CLion for CMake projects.
Note:
The example project source code used in this tutorial can be found on GitHub.
1. Simple CMake Project
CMake is a meta-build system that uses a script called CMakeLists to generate build files for specific environments (for example, generating makefiles on Unix machines). When you create a new CMake project in CLion, a CMakeLists.txt file is automatically generated in the root directory of the project.
👇 Click to claim 👇
👉 Collection of C Language Knowledge Resources
Let’s create a new CMake project in CLion.
Select "File | New Project" from the main menu.
In the left pane, select "C++ Executable". In this example, the project name is cmake_testapp, and the selected language standard is C++17.
We will get a default project that includes a source file named main.cpp and an automatically generated root CMakeLists.txt file with the following commands:
Command Description
cmake_minimum_required(VERSION 3.24) specifies the minimum required version of CMake, just like what is set in the default toolchain. In most cases, this will be the bundled version of CMake unless the CMake executable has been intentionally changed.
project(cmake_testapp) defines the project name based on what we provided during project creation.
set(CMAKE_CXX_STANDARD 17) sets the value of the variable CMAKE_CXX_STANDARD to 17, just like we chose when creating the project.
add_executable(cmake_testapp main.cpp) adds the cmake_testapp executable target, which will be built from main.cpp. We will elaborate on the target further below. In the CMake tool window, you can check the progress and status of project loading. To access it, call View | Tool Windows | CMake, or switch to it in the tool window bar:
Note:
If loading fails, the CMake tool window will automatically open.
2. CMake Targets and CLion Configuration
A target is an executable or library built using CMake scripts. You can define multiple build targets in a single script.
Currently, our test project has only one build target, cmake_testapp. When the project is first loaded, CLion automatically adds a run/debug configuration associated with this target:
Click "Edit Configurations" to view details. The target name and executable name are the same as specified in CMakeLists.txt:
CLion automatically configures the run/debug settings based on the CMake targets of the project. This is a convenient feature as it ensures that the run and debug configurations match the actual build targets.
3. Adding Files to Existing Targets
In some cases, you may need to add new source files to an existing CMake target. Let’s try adding a new source file to the cmake_testapp target.
In the root directory of the project, create a new source file named utils.cpp. Add the following content to utils.cpp:
#include <iostream>
void printMessage() { std::cout << "Hello from utils!" << std::endl;}
In the CMakeLists.txt file, find the add_executable command associated with the cmake_testapp target. We will add the utils.cpp source file to this command.
add_executable(cmake_testapp main.cpp utils.cpp)
Your CMakeLists.txt file should now look like this:
cmake_minimum_required(VERSION 3.24)
project(cmake_testapp)
set(CMAKE_CXX_STANDARD 17)
add_executable(cmake_testapp main.cpp utils.cpp)
In the CMake tool window, click "Reload Changes" to reload the project configuration.
You have now successfully added the new utils.cpp file to the cmake_testapp target.
4. Adding New Targets
In CMake, you can define multiple targets, each corresponding to an executable or library. Let’s try adding a new library target.
Suppose we want to create a static library named mylib, consisting of two source files, lib.cpp and lib.h.
In the root directory of the project, create a new source file named lib.cpp. Add the following content to lib.cpp:
#include "lib.h"
int add(int a, int b) { return a + b;}
In the root directory of the project, create a new header file named lib.h. Add the following content to lib.h:
#ifndef MYLIB_H
#define MYLIB_H
int add(int a, int b);
#endif // MYLIB_H
Modify CMakeLists.txt to add the new library target. Below the project() command, add the following content:
add_library(mylib STATIC lib.cpp)
target_include_directories(mylib PUBLIC .)
By the add_library command, we define a static library target named mylib and add lib.cpp as its source file. By the target_include_directories command, we specify the include directory to access the lib.h header file from other locations in the project.
Your CMakeLists.txt file should now look like this:
cmake_minimum_required(VERSION 3.24)
project(cmake_testapp)
set(CMAKE_CXX_STANDARD 17)
add_executable(cmake_testapp main.cpp utils.cpp)
add_library(mylib STATIC lib.cpp)
target_include_directories(mylib PUBLIC .)
In the CMake tool window, click "Reload Changes" to reload the project configuration.
Now, you have successfully added a new library target named mylib.
5. Reloading the Project
In the steps above, we have mentioned "reloading" the project multiple times. When you manually edit the CMakeLists.txt file, you need to apply changes by reloading. Let’s summarize how to do this:
In the CMake tool window, click the refresh button to reload the project configuration:
Or
Use the File | Reload CMake Project menu item:
After reloading the project, CLion will re-parse the CMakeLists.txt file and apply any changes.
6. CMake Presets and CLion CMake Configuration Files
CMake presets are a set of command line options for CMake that allow you to configure CMake projects without editing CMakeLists.txt files. CLion supports CMake presets and provides a user interface for them.
To configure CMake presets in CLion, follow these steps:
In the main menu, select File | Settings (Ctrl+Alt+S).
In the settings dialog, go to Build, Execution, Deployment | CMake.
In the top tab, find and select Presets.
Click the + button and choose the desired preset. You can configure preset options as needed.
Click Apply or OK to save changes.
From now on, you can use CMake presets to configure CMake projects without manually editing CMakeLists.txt files.
7. Build Types
CMake build types allow you to specify different build configurations, such as "Debug" and "Release". Different build types may have different compiler flags and optimization options.
In CLion, you can easily configure and switch between different build types:
Click the build variants bar in the tool window:
Select the desired build type, such as "Debug" or "Release".
CLion will automatically reload the project to apply the new build type.
Conclusion
Congratulations! You have completed this concise CMake tutorial. You have learned how to create and configure CMake projects, add files to existing targets, add new build targets, and use CMake presets and different build types. CMake is a powerful build system that can help you manage complex projects and cross-platform development. We hope this tutorial helps you get started with the basics of CMake so that you can use it more effectively in your projects.
If you want to further expand your CMake knowledge and skills, you can try using CMake in your own projects and learn through practical application.
Popular Recommendations
-
CLion Tutorial – Project Format in CLion
-
C Language Algorithm – “Search in 2D Matrix” Algorithm Problem
-
C++ Tutorial – Detailed Explanation of Copy Constructor in C++ Language