CMake is an alternative to qmake for automating the generation of build configurations. It controls the software compilation process by using simple configuration files, called CMakeLists.txt files. CMake generates native build configurations and workspaces that you can use in the compiler environment of your choice.

Qt Creator automatically detects the CMake executable specified in the PATH. You can add paths to other CMake executables and use them in different build and run kits.

Qt Creator automatically runs CMake to regenerate makefiles when you edit a CMakeLists.txt configuration file in a project. If the project uses several configuration files, you can disable the automatic generation of makefiles by selecting Tools > Options > Build & Run > CMake. Makefiles are automatically regenerated when you build the project.

Adding CMake Tools

Qt Creator supports CMake version 3.0, or later. For best results you should use CMake version 3.3.2 or later. Earlier versions provide less information to the code model, which will then fail to resolve includes and defines.

To specify paths to CMake executables and to add them to kits:

1. Select Tools > Options > Build & Run > CMake > Add.

   

2. In the Name field, specify a name for the tool.
3. In the Path field, specify the path to the CMake executable.
4. Deselect the Autorun CMake check box to prevent Qt Creator from running CMake when you make changes to CMakeLists.txt files.
5. Select Apply to save your changes.
6. Select the Kits tab to add the CMake tool to a build and run kit. The kit also specifies the CMake Generator that is used for producing project files for Qt Creator and the configuration variables that are used:

   

   For more information, see Adding Kits.

Creating CMake Projects

To create a CMake project:

1. Select File > New File or Project > Non-Qt Project > Plain C Application or Plain C++ Application > Choose.
2. In the Name field, enter a name for the project.
3. In the Create in field, enter the path for the project files, and then select Next (or Continue on macOS).
4. In the Build system field, select CMake, and then select Next.
5. Select CMake kits for the platforms that you want to build the application for, and then select Next.
6. Review the project settings, and click Finish (or Done on macOS).
7. Select Run CMake to generate a .cbp file.

   

   Some projects require command line arguments to the initial CMake call. CMake will remember the arguments during subsequent calls.

Qt Creator generates a main.cpp and CMakeLists.txt file that you can modify in the Edit mode.

Opening CMake Projects

To open an existing CMake project:

1. Select File > Open File or Project.
2. Select the CMakeLists.txt file from your CMake project.
3. Select a kit that is configured to use CMake for building the project.
4. In Projects, right-click the project name to open the context menu, and then select Run CMake to have the project contents listed in the view.

Editing CMake Configuration Files

To open a CMakeLists.txt file for editing, right-click it in the Projects view and select Open with > CMake Editor.

The following features are supported:

• Pressing F2 when the cursor is on a filename to open the file
• Keyword completion
• Code completion
• Auto-indentation
• Matching parentheses and quotes

Building CMake Projects

To build CMake projects, select Build Project or press Ctrl+B (or Cmd+B on macOS).

Qt Creator builds CMake projects by running make, mingw32-make, nmake, or ninja depending on the selected kit.

By default, Qt Creator uses the Default build configuration. You can select another build configuration in Projects > Build Settings > Edit build configuration. In addition to debug and release build configurations, you can create a release build that contains debug information or a release build with the smallest possible size.

In the Build directory field, you can specify the directory in which the project is built (shadow build).

To view all settings, select the Advanced check box.

To modify the value of a build setting, select it, and then select Edit. The new value is displayed in italics until you save the changes by selecting Apply Configuration Changes. Any configuration change might trigger a follow-up configuration change, so keep saving until no more values are displayed in italics.

You can add arguments and targets for the build command in Build Steps.

You can add arguments and targets for the clean command in Clean Steps.

The build errors and warnings are parsed and displayed in the Issues output pane.

Running CMake Projects

Qt Creator automatically adds Run Configurations for all targets specified in the CMake project file.

To run CMake projects, select Run or press Ctrl+R (or Cmd+R on macOS).

Deploying CMake Projects to Embedded Linux Devices

Qt Creator cannot extract files to be installed from a CMake project, and therefore, only executable targets are automatically added to deployment files. You must specify all other files in the QtCreatorDeployment.txt file that you create and place in either the root directory of the CMake project or the build directory of the active build configuration. Currently, Qt Creator first checks the root directory and only if no QtCreatorDeployment.txt exists it checks the active build directory.

Use the following syntax in the file:

<deployment/prefix>
<relative/source/file1>:<relative/destination/dir1>
...
<relative/source/filen>:<relative/destination/dirn>

Where:

• <deployment/prefix> is the (absolute) path prefix to where files are copied on the remote machine.
• <relative/source/file> is the file path relative to the CMake project root. No directories or wildcards are allowed in this value.
• <relative/destination/dir> is the destination directory path relative to deployment/prefix.

To automate the creation of QtCreatorDeployment.txt file:

1. Define the following macros in the top level CMakeLists.txt file:

   file(WRITE "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "<deployment/prefix>\n")
   
   macro(add_deployment_file SRC DEST)
       file(RELATIVE_PATH path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR})
       file(APPEND "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "${path}/${SRC}:${DEST}\n")
   endmacro()
   
   macro(add_deployment_directory SRC DEST)
       file(GLOB_RECURSE files RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${SRC}/*")
       foreach(filename ${files})
           get_filename_component(path ${filename} PATH)
           add_deployment_file("${filename}" "${DEST}/${path}")
       endforeach(filename)
   endmacro()

2. Use add_deployment_file(<file/name>) to add files and add_deployment_directory(<folder/name>) to add directories (including subdirectories) to the QtCreatorDeployment.txt file.
3. Re-run cmake after you add or remove files using the macros.

Adding External Libraries to CMake Projects

Through external libraries, Qt Creator can support code completion and syntax highlighting as if they were part of the current project or the Qt library.

Qt Creator detects the external libraries using the FIND_PACKAGE() macro. Some libraries come with the CMake installation. You can find those in the Modules directory of your CMake installation.

Note: If you provide your own libraries, you also need to provide your own FindFoo.cmake file. For more information, see CMake FAQ.

Syntax completion and highlighting work once your project successfully builds and links against the external library.