CLion 2018.1 Help

Configuring CMake

This article is a guide to the set of basic, but important setting up procedures to configure the building process. Here you will learn how to configure a CMake profile, load and unload CMake project, adjust a build type exactly for your project needs, create a list of toolchains and so on.

CMake profile

In CLion, all the settings required for building a project are incorporated in CMake profile. It accumulates toolchains, build type, CMake options, environment variables, etc. or in other words, the compiler, linker and CMake default and customized settings. You can create the different profiles with the same build type and different toolchains:

cl CMakeProfile
For example, such approach allows you to use different compilers in one project, or to build different CMake targets with different CMake settings.

To build a target using a specific profile, select the necessary CMake Profile in the run configuration switcher on the toolbar:

cl profileSwitcher
or use Shift+Alt+F10 (run) or Shift+Alt+F9 (debug).

Changing build configuration types

Here we are going to discuss the ways of optimizing the project generation depending on the purpose of a particular build.

Let's consider the debugging process. As a rule, debugging needs a lot of interstitial information, therefore you have to include a number of code fragments for logging, printing, etc. On the other hand, such code affects performance and increases the code size of your project.

To avoid such a conflict, CMake offers you an instrument known as a build type.

The following default build configuration types are provisioned by CMake:

  • Debug;
  • Release;
  • RelWithDebInfo;
  • MinSizeRel.

You can select the required build type in CMake settings dialog.

CLion lets you create as many build types as needed for your development lifecycle using the CMake Settings dialog and choosing the configuration among them that is optimal for the current purposes. For example, the following code sample will be executed only if the Debug build type had being selected:

int main(int argc, const char* argv[]) { #if DEBUG printf("Executing as \"%s\"\n", argv[0]); #endif ...
and be ignored when another configuration type (Release, for instance) is used.

In this example, DEBUG must be defined in CMakeLists.txt file as follows:

if (CMAKE_BUILD_TYPE MATCHES Debug) add_definitions(-DDEBUG=1) endif()

Loading and unloading CMake project

Suppose you have faced the following cases when working on your project:

CMakeLists.txt file is not detected

If you opened a project in CLion, but the IDE had not detected any CMakeLists.txt file (e.g project opened without CMakeLists.txt file or it is located out of the project root folder), you can see that there is no CMake tool window opened in the IDE. Besides, the CMake related options such as Reload CMake Project, Change Project Root Directory and other options of the main and context menus are unavailable: the project is not associated with CMake build system in this case. To associate your project with CMake build system, click the Select CMakeLists.txt file IDE prompt (the right position of the warning message):

cl SelectCMake
Select the desired CMakeLists.txt in the dialog that opens.

CLion detected improper CMakeLists.txt file

In case when CLion detects CMakeLists.txt file, but this is not the one that must be used as the main file for your project, you need to disassociate a project from CMake and link with the proper CMakeLists.txt file after that (i.e, load CMake again). To do that:

  1. Go to the Tools | CMake main menu option and select Unload CMake Project option from the drop down menu:

    cl SelectUnloadCmake

  2. Upon this action the state of the IDE is as described in the case #1. Now you can do one of the following:

    • Click the Select CMakeLists.txt file IDE prompt and select a proper CMakeLists.txt file from the dialog.
    • Find the desired CMakeLists.txt file in the Project View and right click it. Select Load CMake Project from the context menu:
      cl SelectLoadCmake

Unload CMake

Suppose you need to unlink your project off CMake build system completely. For example, you have several build systems and would like to use a system other than CMake for a particular project. To do that just unlink your project from CMake and switch to the desired build system.

Compiler settings

In addition to toolchain setting, you can specify a compiler using CMake options. Go to File | Settings | Build, Execution, Deployment | CMake (or CLion | Preferences | Build, Execution, Deployment | CMake for macOS users) and specify the desired compiler by passing following command:

-D CMAKE_<LANG>_COMPILER=[fully qualified compiler name]
The LANG part specifies the language to compile (C for C and CXX for C++). You need to provide the full path to the compiler, for example:
Note: if you specify a compiler in this way, you will override the same selection made in toolchains setting dialog.

Environment variables

The CMake settings in CLion let you define the options for CMake project generation, such as e.g., defining your own variables. To do that, click the browseButton button of the Environment field and define your variables in the Custom variables pane that opens. Use Show link of that pane to see the list of system environment variables and their values:

cl TutorialCompilerSettings2

Advanced options

Changing build directory

The CMake settings dialog provides an input box for specifying the build options, and also lets you change the CMake files generation path.
Please note that since version 2016.3 CLion supports in-source builds: you can specify a directory for generated files within the source folder.

Creating multiple toolchains

Why do we need such an option? Obviously, you may want to have an individual set of tools ready to be used in different projects (e.g projects require different environments or CMake executables). Or you need in different toolchains that you can use in one project but for different CMake profiles (see above detailed description of build configurations). CLion lets you create and manage the list of named toolchains and use them further in CMake profiles.

Let's continue with our previous example, when we have created a single MinGW 32 bit toolchains:

  • Open the CMake settings dialog (Build, Execution, Deployment | CMake ) and expand the Toolchain drop down list.
    cl CMakesettingsToolchain
  • Select the newly configured toolchain from the list and set up other parameters required for this certain CMake profile.

Setting custom build types

You can extend the list of available build types with custom ones by setting them explicitly in the CMakeLists.txt file.

To adjust the list of build types for a certain project, do the following:

  • in CMakeLists.txt file, specify CMAKE_CONFIGURATION_TYPES variable as in example below:
    cmake_minimum_required(VERSION 3.6) project(exampleProject) # setting two custom build types # variable CMAKE_CONFIGURATION_TYPES shall be defined prior to other definitions: set(CMAKE_CONFIGURATION_TYPES "CustomType1;CustomType2" CACHE STRING "" FORCE) set(CMAKE_CXX_STANDARD 11) # setting the language standard set(SOURCE_FILES main.cpp) add_executable(exampleProject ${SOURCE_FILES})

You can check the results in the CMakeCache text file by pressing the icon config button of the CMake tool window.

Last modified: 24 July 2018