CLion 2019.1 Help

Quick CMake Tutorial NEW VERSION

This tutorial will guide you the process of creating and developing a simple CMake project, covering the aspect you will most probably need when working with CMake in CLion. YOU CAN FOLLOW THROUGH THE EXAMPLE, IT'S GIVEN STEP BY STEP

CMake is a meta build system that uses scripts called CMakeLists.txt to generate build files for a specific environment (for example, makefiles on Unix systems).

To open an existing CMake project in CLion, you can:

  • Select File | Open and locate the project directory. This directory should contain a CMakeLists.txt file.

  • Select File | Open and point CLion to the top-level CMakeLists.txt file, then choose Open as Project.

  • Select File | Open and locate the CMakeCache.txt file then choose Open as Project.

New CMake project

Let’s create a simple CMake project with a single source file main.cpp (for this, go to File | New Project and choose C++ Executable). By default, we get the following project structure and the automatically created root CMakeLists.txt file:

new cmake project

Initially, CMakeLists.txt contains following commands:

Command

Description

cmake_minimum_required(VERSION 3.13)

specifies the minimum version of CMake

project(cmake_testapp)

defines the project name according to the name we’ve provided during project creation

set(CMAKE_CXX_STANDARD 14)

sets the variable CMAKE_CXX_STANDARD to a given value of 14 (the version of C++ standard we’ve selected).

This command helps, for example, to name a list of files for later usage: set(SOURCES test.cpp lib1.cpp lib2.cpp), then referred to as ${SOURCES}.

add_executable(cmake_testapp main.cpp)

adds the cmake_testapp executable target that is built from main.cpp

Build targets and Run/Debug configurations

Build target is an executable or a library to be built using a CMake script. A script can define multiple build targets.

For now, our test project has only one build target, cmake_testspp. Upon the project creation, CLion automatically added a Run/Debug configuration associated with this target:

default configuration for a new cmake project

Click Edit Configurations or select Run | Edit Configurations from the main menu to view the details. The name of the target and the name of the executable were taken directly from the CMakeLists.txt /MAKE ANOTHER SCREENSHOT/:

details of the default configuration for a new cmake project

Notice the 'Before launch' area of this dialog: the Build action is set by default, so we can use this configuration not only to debug or run our target, but also to perform the build.

HOW ABOUT BUILD ACTIONS

In the configuration editor, we can add new configurations or remove the existing ones. Removing is important because, for example, if you rename a target, it will lead to a stale configuration that will no longer be used. In this case, CLion will put an indicating red cross on top of its icon.

Adding targets and reloading the project

Now let’s add another source file called calc.cpp and create a separate executable target from it. When we add a file (right-click on the root folder in the Project tree and select New | C/C++ Source File), CLion prompts us to add it to an existing target:

add new fil to targets

If we clear the Add to targets checkbox, CLion notifies us that the new file currently does not belong to any target:

file not belonging to the project

To fix this, we need to add a line add_executable(cmake_testapp_calc main.cpp calc.cpp) to our CMakeLists.txt. Note that CLion treats CMake scripts as regular code files, so we can use code assistance features like syntax highlighting, auto-completion, and navigation. Every time when we introduce changes in CMakeLists.txt, CLion needs to reload it in order to update the project structure:

reload cmake project after adding a new target

We can Enable auto-reload to have the project reloaded automatically on any change, or reload only this particular change. The option for enabling/disabling auto-reload is also available in Settings / Preferences | Build, Execution, Deployment | CMake.

After we reload the changes, CLion creates a Run/Debug configuration for the new target:

configuration for the newly added target

The add_executable command is used to create executable targets. For library targets, we need to use the add_library command. As an example, let’s create a static library target out of the calc.cpp source file:

add_library (test_library STATIC calc.cpp)

As well as for executables, CLion creates a Run/Debug configuration for the library target after we reload the project:

configuration for the newly added library target

Adding include directories

In order to use additional headers located in separate directories, we can add them either to all the targets or to some specific ones. For example, let’s create three directories, includes, includes/general and includes/math, under the project root and write the following in CMakeLists.txt:

  1. include_directories(includes/general)
    - to include general for all targets;

  2. target_include_directories (cmake_testapp_calc PUBLIC includes/math)
    - to include math only for the cmake_testapp_calc target. Note that target_include_directories should be placed after add_executable (or add_library) for the target name to be already available.

Now we can include the headers located in includes/general or includes/math directly, for example:

including headers from search paths= directories

Linking libraries

Static libraries

Dynamic libraries (Boost)

Using Boost

The Boost libraries are the most popular C++ library set. While many libraries are header-only (meaning you don’t need to perform any linking, just include a few files), some libraries do, in fact, require compilation and linking.

So let’s get started by including the files. For this, you can use CLion’s incboost live template, which will generate the following:

find_package(Boost) IF (Boost_FOUND) include_directories(${Boost_INCLUDE_DIR}) endif()

Now, when it comes to libraries, Boost offers you options for both static and dynamic linking. There are also additional options, such as whether or not you want to enable multithreading (feel free to read up on this option, since it doesn’t actually make code parallel). Also, you can cherry-pick which Boost components you want:

set (Boost_USE_STATIC_LIBS OFF) # enable dynamic linking set (Boost_USE_MULTITHREAD ON) # enable multithreading find_package (Boost COMPONENTS REQUIRED chrono filesystem)
And finally, to get the libraries, you use the good old target_link_libraries() command:
target_link_libraries (my_target my_library another_library)

An alternative approach to using libraries is to use an external dependencies manager that can use CMake to configure and build projects.

Including sub-projects

Projects can have dependencies to other projects. CMake does not have the notion of a ‘solution’ — instead, it allows you to define dependencies between projects. Typically, you want to organize your multi-project workspace such that:

  • When opening the main project, the IDE shall open all the dependant projects as well.

  • All the settings of the main project shall be applied to the dependant projects automatically.

  • All the smart features (for example, refactoring, code completion, and so on) shall take effect in all the projects.

The above points can be achieved with proper configuration of the CMakeLists file. Essentially, you need to organize your projects as a tree of subdirectories with the top-level CMakeLists.txt file in the root directory. Then, each subdirectory of that tree shall represent a single sub-project and contain its own CMakeLists.txt file, which is then included to the main project in the top-level CMakeLists.txt file, as follows:

add_subdirectory (project1) # including project1 into the main project add_subdirectory (project2) # including project2 into the main project

CMake Cache

When you run CMake for the first time, what it will do is assemble the so-called CMake cache, collecting the variables and settings found in the system and storing them so it doesn’t have to regenerate them later on. In most cases, you should not worry about this cache, but if you want to fine-tune it, you can. Locate the CMakeCache.txt file and open it in the Editor.

If you’ve changed values, be sure to reset the CMake cache and reload your project so that your changes are actually internalized by CLion.

Last modified: 5 April 2019

See Also