Qt Documentation

Qt Creator Manual
Setting Up a CMake Project
Qt Creator Manual 3.3.1

Using Other Build Systems Setting Up a Qbs Project

Setting Up a CMake Project

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.

Since Qt Creator 1.1, CMake configuration files are supported. Since Qt Creator 1.3, the Microsoft tool chain is supported if the CMake version is at least 2.8.

Setting the Path for CMake

You can set the path for the CMake executable in Tools > Options > Build & Run > CMake.

Note: Before you open a CMake project, you must modify the PATH environment variable to include the bin folders of mingw and Qt.

For instance, if the Qt 4 SDK is installed in C:\SDK, you would use the following command to set the environment variables in the command line prompt:

set PATH=C:\sdk\mingw\bin;C:\sdk\qt\bin;

Then start Qt Creator by typing:

C:\sdk\bin\qtcreator.exe

Opening CMake Projects

To open a CMake project:

Select File > Open File or Project.
Select the CMakeLists.txt file from your CMake project.

A wizard guides you through the rest of the process.

Note: If the CMake project does not have an in-place build, Qt Creator lets you specify the directory in which the project is built (shadow build).

The screenshot below shows how you can specify command line arguments to CMake for your project.

Normally, there is no need to pass any command line arguments for projects that are already built, as CMake caches that information.

Building CMake Projects

Qt Creator builds CMake projects by running make, mingw32-make, or nmake depending on your platform. The build errors and warnings are parsed and displayed in the Issues output pane.

By default, Qt Creator builds the all target. You can specify which targets to build in Project mode, under Build Settings.

Qt Creator supports multiple build configurations. You can change the build directory after the initial import.

Running CMake Projects

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

For more information about known issues for the current version, see Known Issues.

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 the root directory of the CMake project.

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:

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

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.
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.