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: 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: 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
...
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): 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:
-
Go to the Unload CMake Project option from the drop down menu:
main menu option and select -
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:
- Click the Select CMakeLists.txt file IDE prompt and select a proper
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 command:
(or for macOS users) and specify the desired compiler by passing following-D CMAKE_<LANG>_COMPILER=[fully qualified compiler name]
-D CMAKE_CXX_COMPILER=C:\MinGW\bin\g++
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 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:
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 ( ) and expand the Toolchain drop down list.
- 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, specifyCMAKE_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 button of the CMake tool window.