Specifying Build Settings | Qt Creator Manual

- Qt Creator Manual
- Specifying Build Settings
- Qt Creator Manual 4.13.3

Adding Debuggers ◦ Specifying Run Settings

# Specifying Build Settings

Different build configurations allow you to quickly switch between different build settings. By default, Qt Creator creates debug, release, and profile build configurations. A debug build contains additional debug symbols that you need for debugging the application but that you can leave out from the release version. Generally, you use the debug configuration for testing and the release configuration for creating the final installation file.

If you selected CMake as the build system for the project, you can use a minimum size release build configuration to create the final installation file. It is a release build that makes the size of the binary package as small as possible, even if this makes the application slower.

A profile build (which is called release with debug information when using CMake) is an optimized release build that is delivered with separate debug information. It is best suited for analyzing applications.

## Managing Build Configurations

You specify build settings in the Projects mode. To add a new build configuration, click Add and select the type of configuration you would like to add. The options you have depend on the build system that you selected for the project. You can add as many build configurations as you need. You can also select Clone to add a build configuration that is based on the currently selected one.

Select Rename to give the currently selected build configuration a new name.

To delete the build configuration currently selected, click Remove.

## Editing Build Configurations

Select the build configuration to edit in the Edit build configuration field.

The available build settings depend on the build system that you selected for the project.

### Compiling QML

Since Qt 5.11, you can compile QML source code into the final binary. This improves the startup time of the application and eliminates the need to deploy QML files together with the application. For more information, see Ahead-of-Time Compilation.

Qt Creator project wizard templates create Qt Quick projects that can be compiled, because they are set up to use the Qt Resource System. To compile Qt Quick code, select Enable in the Qt Quick Compiler field. To use default settings, select Leave at Default.

Note: In earlier Qt versions, this was a commercial feature. For more information, see Qt Quick Compiler.

### qmake Build Configuration

By default, Qt Creator builds projects in a separate directory from the source directory, as shadow builds. This keeps the files generated for each build and run kit separate. If you only build and run with a single kit, you can deselect the Shadow build checkbox.

To make in-source builds the default option for all projects, select Tools > Options > Build & Run > Default Build Properties, and enter a period (.) in the Default build directory field.

You can create separate versions of project files to keep platform-dependent code separate. You can use qmake scopes to select the file to process depending on which platform qmake is run on.

To generate debug symbols also for applications compiled in release mode, select Enable in the Separate debug info field. For more information, see Using the Performance Analyzer. To use default settings, select Leave at Default.

To set the default build properties, select Tools > Options > Build & Run > Default Build Properties.

### CMake Build Configuration

Configuring medium-sized to large CMake projects in Qt Creator can be a challenge due to the number of options that you need to pass to CMake to configure the project correctly. Qt Creator creates an initial configuration for you based on the kit settings and displays it in the Initial CMake parameters field.

In the Value column, you can view and edit the actual values of the parameters that are passed to CMake. Parameter names are listed in the Key column. Names with a common prefix (up to the first underscore character) are grouped under the prefix. To view all parameters, select the Advanced check box.

To add parameters, select Add, and then select the type of the parameter that you are adding: Boolean, String, Directory, or File.

To change the type of the selected parameter, select Force to bool, Force to file, Force to directory, or Force to string.

To modify the value of a parameter, double-click it, or select it, and then select Edit. To save the changes, select Apply Configuration Changes. Keep in mind that a configuration change might trigger a follow-up configuration change.

To remove a parameter, select Unset.

To reset the changes that you made, select Reset.

The parameter values that you change are passed via `-D<option>=<value>` to CMake, which stores the options in the CMakeCache.txt file. This means that if you remove the build directory, all the custom parameters that are not part of the initial CMake parameters are also removed.

To reconfigure a project after making changes to the initial parameters, select Build > Clear CMake Configuration, which removes the CMakeCache.txt file. This enables you to do a full rebuild.

### Meson Build Configuration

Settings are grouped by category by Meson. All items are user modifiable except `backend` which is forced to Ninja, `buildtype`, `debug` as well as `optimization` to ensure a good compatibility with Qt Creator.

Each setting type has its own editor. To modif any setting, double-click it, either edit the field, or select your choice depending on the control. To apply changes, select Apply configuration changes. This will trigger a `meson configure` command if there were any configuration changes. If for any reason the build directory configuration is broken, select Wipe project. This should fix any build directory.

Note: Any modified setting will remain in bold until Apply configuration changes is selected.

## Starting External Processes

Qt Creator executes external processes to accomplish tasks such as building and running applications. To execute the processes, Qt Creator uses shell commands that are native to the system. It constructs the commands from an executable name and optional command line arguments.

The executable name is specified in the executable fields: qmake, Make, Command, or Executable. It is either derived from the project or specified manually. When you specify executables manually, you can reference environment variables and Qt Creator variables. However, no quoting rules apply.

You can specify command-line arguments in the arguments fields: Arguments, Additional arguments, CMake arguments, Command arguments, Default arguments, Extra arguments, Make arguments, or Tool arguments. You can create shell command lines that can contain redirection and other advanced constructs. However, some more complex use cases, such as piping test data into the application being tested or grouping commands, are not supported because the value of the Executable field is always placed first when constructing the command.

You can use environment variables as values in the fields. In addition, you can use Qt Creator variables in arguments, executable paths, and working directories.

## Build Steps

In Build Steps you can change the settings for the build system selected for building the project: qmake, CMake, Meson, or Qbs. You can use Incredibuild to accelerate the build process when using qmake or CMake.

### qmake Build Steps

Qt Creator builds qmake projects by running the `make` or `nmake` command from the Qt version defined for the current build configuration.

To override the shell command that Qt Creator constructs by default, disable or remove the build step and add a custom build step that specifies another shell command.

By default, Qt Creator uses all the CPU cores available to achieve maximum build parallelization. On Linux and macOS, you can specify the number of parallel jobs to use for building in the Parallel jobs field. Select the Override MAKEFLAGS check box to override existing MAKEFLAGS variables.

### CMake Build Steps

Qt Creator builds CMake projects by running `cmake . --build`, which then runs the CMake generator specified in the project configuration: `make`, `mingw32-make`, `nmake`, or `ninja`, for example. The CMake generator produces project files for Qt Creator.

You can add arguments to pass to CMake and the generator and targets for the build command in Build Steps.

Note: While the other CMake generators are installed together with Qt, you usually need to install Ninja yourself. For more information, see Using Ninja as a CMake Generator.

### Qbs Build Steps

To specify build steps for Qbs:

1. In the Build variant field, select Debug to include debug symbols in the build for debugging the application and Release to create the final installation file.
2. In the Parallel jobs field, specify the number of parallel jobs to use for building.
3. In the Properties field, specify the properties to pass to the project. Use colons (:) to separate keys from values. For more information, see Modules in the Qbs Manual.
4. In the Flags field:
   - Select Keep going to continue building when errors occur, if possible.
   - Select Show command lines to print actual command lines to the compile output pane instead of high-level descriptions.
   - Select Force probes to force re-execution of the configure scripts of Probes.
5. In the Installation flags field:
   - Select Install to copy artifacts to their install location after building them. This option is enabled by default.

     Note: On Windows, the build will fail if the application is running, because the executable file cannot be overwritten. To avoid this issue, you can deselect this check box and add a Qbs Install deployment step in the run settings that will be performed just before running the application.

   - Select Clean install root to remove the contents of the install root directory before the build starts.
   - Select Use default location to install the artifacts to the default location. Deselect the check box to specify another location in the Installation directory field.

The Equivalent command line field displays the build command that is constructed based on the selected options.

### Meson Build Steps

Qt Creator builds Meson projects by running `ninja -v target`.

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

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

### IncrediBuild Build Steps

To use IncrediBuild, select Add Build Step > IncrediBuild for Linux or IncrediBuild for Windows.

IncrediBuild automatically detects the build step by iterating over the build steps you already defined. The initial build step settings will be part of your IncrediBuild build step, so your usual build tool will still be used, but with the added benefit of IncrediBuild's build acceleration and graphical Build Monitor.

In the Target and configuration group, specify the command helper and arguments that will be used to construct the build command.

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

Select the Keep original jobs num check box to stop IncrediBuild from overriding the `-j` command line switch, which controls the number of processes that the build tools executed by Qt Creator run in parallel. The default value set by IncrediBuild is 200.

The distribution control settings to specify depend on whether you are using Linux or Windows.

#### Distribution Control Settings on Linux

You can specify the following options for Linux builds:

- Nice value is a numeric value between -20 and 19
- Force remote forces `allow_remote` tasks to remote Helpers.
- Alternate tasks preference

#### Distribution Control Settings on Windows

You can specify the following options for Windows builds:

- Profile.xml defines how Automatic Interception Interface handles processes in a distributed job. It is not necessary for Visual Studio or Make and Build tools builds, but can be used to provide configuration options if those builds use additional processes that are not included in those packages. It is required to configure distributable processes in Dev Tools builds.
- Avoid local frees up resources on the initiator machine. This might be beneficial for distribution if the initiator turns into a bottleneck for the build because of high CPU usage.
- Maximum CPUs to utilize in the build specifies the maximum amount of remote cores to use in the build. Overrides the corresponding global setting.
- Newest allowed Helper machine OS and Oldest allowed Helper machine OS specify the newest and oldest operating system installed on a Helper machine to be allowed to participate as a Helper in the build.
- Build Title specifies a custom header line which will be displayed in the beginning of the build output text. This title will also be used for the Build History and Build Monitor displays.
- Save IncrediBuild monitor file writes a copy of the build progress (`.ib_mon`) file to the specified location. If only a folder name is given, IncrediBuild generates a GUID for the file name. A message containing the location of the saved `.ib_mon` file is added to the end of the build output.
- Suppress STDOUT does not write anything to the standard output.
- Output log file writes build output to a file.
- Show commands in output shows the command-line used by IncrediBuild to build the file.
- Show agents in output shows the Agent used to build each file.
- Show time in output shows the start and finish time for each file built.
- Hide IncrediBuild Header in output suppresses the IncrediBuild header in the build output.
- Internal IncrediBuild logging level overrides the internal Incredibuild logging level for this build. Does not affect output or any user accessible logging. Used mainly to troubleshoot issues with the help of IncrediBuild support.
- Set an environment variable sets or overrides environment variables for the context of the build.
- Stop on errors stops the execution as soon as an error is encountered. This is the default behavior in Visual Studio builds, but not for Make and Build tools or Dev Tools builds.
- Additional arguments are concatenated to the final buildconsole command line.
- Open Monitor opens an IncrediBuild Build Monitor that graphically displays the build's progress once the build starts.

### Adding Custom Build Steps

To add custom steps to the build settings, select Add Build Step > Custom Process Step.

By default, custom steps are enabled. To disable a custom step, select the (Disable) button.

### Executing Custom Commands

To execute custom commands when building for embedded devices, select Add Build Step > Custom Remote Command (via adb shell) (commercial only) and enter the command to execute.

## Clean Steps

You can use the cleaning process to remove intermediate files. This process might help you to fix obscure issues during the process of building a project.

You can define the cleaning steps for your builds in the Clean Steps.

- To add a clean step using make or a custom process, click Add Clean Step and select the type of step you want to add.

  By default, custom steps are enabled. To disable a custom step, select the Disable button.

- To remove a clean step, click Remove Item.
- To change the order of steps, click (Move Up) and (Move Down).

### CMake Clean Steps

When building with CMake, you can add arguments to pass to CMake and the generator and targets for the clean command in Clean Steps.

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

### Qbs Clean Steps

When building with Qbs, you can specify flags in Clean Steps:

- Select Dry run to test cleaning without executing commands or making permanent changes to the build graph.
- Select Keep going to continue cleaning when errors occur, if possible.

The Equivalent command line field displays the clean command that is constructed based on the selected options.

### Meson Clean Steps

When building with Meson, 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.

### IncrediBuild Clean Steps

When building with IncrediBuild, you can add arguments and targets for the clean command in Clean Steps.

For more information about the settings, see IncrediBuild Build Steps.

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

Adding Debuggers ◦ Specifying Run Settings