Quick CMake tutorial

1. Select File | New Project from the main menu.

2. Choose C++ Executable on the left-hand pane. In our example, the project name is cmake_testapp and the selected language standard in C++17.

   

3. We get the default project with a single source file main.cpp and the automatically created root CMakeLists.txt containing the following commands:

   

   Command	Description
   cmake_minimum_required(VERSION 3.24)	Specifies the minimum required version of CMake, as set in the default toolchain. For most cases, if CMake executable was not changed intentionally, this is the bundled CMake version.
   project(cmake_testapp)	Defines the project name according to what we provided during project creation.
   set(CMAKE_CXX_STANDARD 17)	Sets the CMAKE_CXX_STANDARD variable to the value of 17, as we selected when creating the project.
   add_executable(cmake_testapp main.cpp)	Adds the cmake_testapp executable target to be built from main.cpp. We'll get into targets further below.

4. In the CMake tool window, you can check the progress and status of project load. To access it, call View | Tool Windows | CMake or switch to it in the tool windows bar:

   

   tip

   The CMake tool window opens up automatically in case of load failure.

1. Right-click the root folder in the Project tree and select New | C/C++ Source File:

   

2. Set the Add to targets checkbox to automatically add the file to an existing target:

   

3. Click OK, and the new file will be added to the add_executable command:

   

   tip

   In this case of adding a file automatically, CMake reload is also performed automatically in the background.

New executable target

1. Right-click the root folder in the Project tree and select New | C/C++ Source File again.

2. Since our goal now is to create a new target, we need to clear the Add to targets checkbox:

   

3. After we click OK, CLion opens the new file and notifies us that it does not belong to any target:

   

4. Let's declare a new target manually in the CMakeLists.txt. Note that CLion treats CMake scripts as regular code files, so you can use code assistance features like syntax highlighting, auto-completion, and navigation (see CMake editing tips below).

   

   tip

   When something goes wrong in your CMake script, use CLion CMake debugger to investigate the problem.

5. When we make changes in CMakeLists.txt manually, CLion shows notification that the project needs to be reloaded:

   

   We can either reload the project once (Reload changes) or enable automatic reload to let CLion silently apply all the changes in CMakeLists.txt.

   The option for enabling/disabling auto-reload is also available in Settings | Build, Execution, Deployment | CMake.

   After reload, you can find a new configuration in the list:

   

New library target

Up to this point, the targets we added were executables, and we used add_executable to declare them. For library targets, we need another command: add_library. As an example, let's create a static library from the calc.cpp.

1. Add the following line to the CMakeLists.txt script:

   add_library(test_library STATIC calc.cpp)

2. Similarly to executable targets, CLion creates configurations for library targets:

   

   However, this is a non-executable configuration, so if we attempt to run or debug it, we will get the Executable not specified error message:

   

3. To get the library file, we need to build the test_library target. For this, switch to the corresponding configuration and press , or call Build | Build "test_library":

   

   The libtest_library.a file will appear in the cmake-build-debug folder:

   

CMake presets

CMake Presets are a way to configure and share CMake options using two files:

• CMakePresets.json for project-wise builds. This file can be shared via VCS.

• CMakeUserPresets.json for developers' own local builds. This file should not be checked into VCS.

Both of these files have the same format and should be located in the project's root directory.

note

Find out more on using presets in CLion: CMake presets

CMake profiles

A profile includes toolchain and build type, as well as CMake options such as generators and environment variables. You can configure multiple profiles for your project in order to, for example, use different compilers or to build targets with differing settings.

See the next chapter for an example of adding a profile for Release build.

1. As an example, create three directories under the project root: includes, includes/general, includes/math.

2. Write the following commands in CMakeLists.txt:

   target_include_directories (cmake_testapp_calc PUBLIC includes/math)
   target_include_directories (cmake_testapp_calc PUBLIC includes/general)

3. These two commands make the headers located in general and math available for including from the sources of the cmake_testapp_calc target.

   For example, if we place a header called header_math.h inside the includes/math folder, we can then include it from calc.cpp using #include "header_math.h":

   

1. Place breakpoints in your CMakeLists.txt file or files.

2. Open the top-level CMakeLists.txt, click the gutter icon next to the first command, and select Debug:

   

   tip

   If CMake generation failed, click the debug hint in the CMake tool window:

   

3. CLion will start a CMake debug session:

   

   See CMake debug features.

Add CTest to the sample project

1. Create a subdirectory inside test and call it ctest.

2. Add two source files, addvalues_zero.cpp and addvalues_negpos.cpp, a header file (where we will place the assertion macro) assert_macro.h, and a CMakeLists.txt script:

   

3. Add the following lines to ctest/CMakeLists.txt:

   cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
   
   add_executable(ctest_exe_addvalues_zero         addvalues_zero.cpp)
   add_executable(ctest_example_addvalues_negpos   addvalues_negpos.cpp)
   
   add_test(ctest_addvalues_zero       ctest_exe_addvalues_zero)
   add_test(ctest_addvalues_negpos     ctest_example_addvalues_negpos)

   The first line states the minimum supported version of CTest, which corresponds to the version of CMake, 3.14.

   We are using the add_test command here to register our executables, ctest_exe_addvalues_zero and ctest_example_addvalues_negpos, with CTest.

4. Now we can place the actual code inside the test sources:

   • assert_macro.h:

     #include <iostream>
     #include <sstream>
     
     
     #define assertEqual( ... )               \
     do {                                            \
         if( !( __VA_ARGS__ ) ) {                     \
             std::cerr << "Unit test assert [ " \
             << ( #__VA_ARGS__ )             \
             << " ] failed in line [ "       \
             << __LINE__                     \
             << " ] file [ "                 \
             << __FILE__ << " ]"             \
             << std::endl;                     \
             err_code = 1;                           \
         }                                            \
     } while( false )

   • addvalues_zero.cpp:

     #include "assert_macro.h"
     
     int test_addvalues_zero() {
         int err_code = 0;
         assertEqual (0+0 == 0);
         assertEqual ((-5)+5 == 0);
         return err_code;
     }
     
     int main() {
         return test_addvalues_zero();
     }

   • addvalues_negpos.cpp:

     #include "assert_macro.h"
     
     int test_addvalues_negpos() {
         int err_code = 0;
         assertEqual ((-5)+10 == 5);
         assertEqual ((-10)+5 == -5);
         assertEqual (5+(10) == 5); //test to fail
         return err_code;
     }
     
     int main() {
         return test_addvalues_negpos();
     }

5. Next, we need to enable CTest and declare the subproject in the top-level CMakeLists.txt:

   enable_testing()
   add_subdirectory(test/ctest)

   The enable_testing command creates a built-in target test which will execute CTest.

6. Reload the project.