Quick CMake tutorial

Start a sample CMake project

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:

   

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:

   

New executable target

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:

   

New library target

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:

   

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 Ctrl+F9 or click the build icon:

    

    As the result, the libcmake_testapp_lib.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.

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, 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:

   

3. CLion will start a CMake debug session:

   

   For further information, refer to CMake debug features.

Add CTest to the sample project

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.

Add the code to be tested

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);

Edit the CTest configuration

1. In the main menu, 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:

   

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:

   

Run the CTest configuration and explore the results

1. Select All CTest in the configuration switcher and click or press Shift+F10.

   

2. Find results in the Test Runner window: