Quick CMake tutorial

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

2. Select C++ Executable on the left-hand pane.

   In our example, the project name is cmake_testapp and the selected language standard in C++17.

   

   Click Create.

3. CLion will generate a stub project with a single source file main.cpp and a CMakeLists.txt script under the root.

   

   The automatically generated CMakeLists.txt contains the following commands:

   Command	Description
   cmake_minimum_required(VERSION 3.26)	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. Click on the left-hand toolbar of the IDE to open the CMake tool window, where you can check the progress and status of project load:

   

   tip

   The CMake tool window opens up automatically in case of a 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:

   

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

   

   tip

   When you add a file to a target this way, without manually editing the CMakeLists.txt script, CLion reloads the project automatically in the background.

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

2. Set the file name (calc in our example).

3. In the Add to targets field, clear the cmake_testapp checkbox.

4. Click the Add new target link:

   

5. Specify the target name (cmake_testapp_calc) and click Add:

   

6. The newly created target will appear in the list.

   Make sure that only the cmake_testapp_calc target is selected:

   

   Click OK.

7. CLion will add a new add_executable command to CMakeLists.txt and reload the project:

   

8. After reload, a new configuration will appear in the configuration switcher:

   

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

2. Provide the file name (calc_lib).

3. Clear the checkboxes in the Add to targets field.

4. Click Add new target.

   

5. In the drop-down list, select add_library:

   

   tip

   In this drop-down, you can find the commands for adding CUDA and Qt targets.

6. Set the target name (cmake_testapp_lib) and click Add.

   

7. The newly created target will appear in the list.

   Make sure that other targets' checkboxes are cleared.

   

   Set the Create an associated header checkbox to also add a header file, calc_lib.h.

   Click OK.

8. CLion will add a add_library command to CMakeLists.txt and reload the project:

   

9. Similarly to the case of executable targets, CLion automatically creates configurations for library targets:

   

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

   

10. To obtain the library file, you need to build this configuration. Select it in the switcher and press CtrlF9 or click the build icon:

    

    As the result, the libcmake_testapp_lib.a file will appear in the cmake-build-debug folder.

    

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

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, let's create three directories under the project root: includes, includes/general, and includes/math. Use the New | Directory option in the project tree context menu.

   

2. Open CMakeLists.txt and add the following commands:

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

   These two commands make the headers located in general and math available from the sources of the cmake_testapp_lib target.

   For example, if we place a header called header_math.h inside the includes/math folder, we can then include it from calc_lib.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

   When CMake generation fails, you can click the debug hint in the CMake tool window to start debugging:

   

   You can also ask the AI Assistant to explain the error.

3. CLion will start a CMake debug session:

   

   For further information, refer to CMake debug features.

1. Create a ctest directory under the project root.

2. Add the following files to the ctest directory:

   • A source file addvalues_zero.cpp. Don't link this file with any CMake target for now.

   • A header file assert_macro.h. Don't link this file with any CMake target for now.

   • A CMakeLists.txt script.

   

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

   cmake_minimum_required(VERSION 3.14.0 FATAL_ERROR)
   
   add_executable(ctest_exe_addvalues_zero addvalues_zero.cpp)
   
   add_test(ctest_addvalues_zero ctest_exe_addvalues_zero)

   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 the ctest_exe_addvalues_zero executable 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();
     }

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

   enable_testing()
   add_subdirectory(ctest)

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

6. Reload the project.

Let's prepare a code piece to be tested with CTest.

1. In calc_lib.cpp, add a simple function

   int add_values (int a, int b) { return a+b;}

2. In the associated header, calc_lib.h, add the function declaration:

   int add_values (int a, int b);

1. Go to Run | Edit Configurations.

2. Under the CTest Application node, you will find the automatically created All CTest configuration.

   Since the functions to be tested are located in the cmake_testapp_lib library, we need to change Target to build in the configuration settings:

   

   tip

   To apply this to all CTest configurations in the project, click Edit configuration templates, select CTest Application, and change the target in the template:

   

3. Let's also check the Test list to run field. Click the pen icon to open the List of Available Tests dialog, where we can view and adjust the set of tests:

   

tip

For more information about the CTest Application template, refer to CTest run/debug configuration.

1. Select All CTest in the configuration switcher and click or press ShiftF10.

   

2. Find results in the Test Runner window: