Qbs Manual | Command-Line Interface | build

Qbs 1.16.0

# build

## Synopsis

      qbs build [options] [[config:configuration-name] [property:value] ...]

## Description

Builds projects in one or more configurations.

You can specify project, product, or module properties, as well as a profile separately for each configuration.

This is the default command.

If the build directory does not exist, it will be created.

For more information, see Building Applications.

## Options

### `--all-products`

Processes all products, even if their `builtByDefault` property is `false`.

### `--build-directory|-d <directory>`

Specifies a `<directory>` where build artifacts are stored.

The default value is the current directory unless `preferences.defaultBuildDirectory` is set.

Relative paths will be interpreted relative to the current directory.

You can use the following special values as placeholders:

- `@project` is expanded to the name of the project file excluding the extension `.qbs`.
- `@path` is expanded to the name of the directory containing the project file.

### `--changed-files <file>[,<file>...]`

Assumes that the files specified by `<file>`, and only those files, have changed.

### `--check-outputs`

Forces transformer output artifact checks.

Verifies that the output artifacts declared by rules in the project are actually created.

### `--check-timestamps`

Forces timestamp checks.

Retrieves the timestamps from the file system, instead of using the file timestamps that are stored in the build graph.

### `--clean-install-root`

Removes the installation base directory before installing.

### `--command-echo-mode <mode>`

Determines what kind of output to show when executing commands.

Possible values of `<mode>` are:

- `silent`
- `summary` (default value)
- `command-line`
- `command-line-with-environment`

### `--dry-run|-n`

Performs a dry run. No commands will be executed and no permanent changes to the build graph will be done.

### `[--file|-f <file>]`

Uses `<file>` as the project file. If `<file>` is a directory and it contains a single file with the extension `.qbs`, that file will be used.

If this option is not given at all, the behavior is the same as for `-f <working-dir>`.

### `--force-probe-execution`

Forces re-execution of all Probe items' configure scripts, rather than using the cached data.

### `--jobs|-j <n>`

Uses `<n>` concurrent build jobs, where `<n>` must be an integer greater than zero.

The default is the number of logical cores.

### `--job-limits <pool1>:<limit1>[,<pool2>:<limit2>...]`

Sets pool-specific job limits. See here for more information on job pools.

### `--enforce-project-job-limits`

Normally, job limits defined in project files via the JobLimit item get overridden by those set on the command line. If this option is passed, they get maximum priority instead. Use it if there are product-specific limits that make more sense for that part of the code base than the generic ones you'd like to apply globally.

### `--keep-going|-k`

Keeps going when errors occur, if at all possible.

### `--less-verbose|-q`

Becomes more quiet by decreasing the log level by one. This option can be given more than once. Excessive occurrences have no effect.

If the option `--log-level` appears anywhere on the command line in addition to this option, its value is taken as the base for the decrease.

### `--log-level <level>`

Uses the specified log level.

Possible values of `<level>` are:

- `error`
- `warning`
- `info` (default value)
- `debug`
- `trace`

### `--log-time`

Logs the time that the operations involved in this command take.

This option is implied in log levels `debug` and higher.

This option is mutually exclusive with `--show-progress`.

### `--more-verbose|-v`

Becomes more verbose by increasing the log level by one. This option can be given more than once. Excessive occurrences have no effect.

If the option `--log-level` appears anywhere on the command line in addition to this option, its value is taken as the base for the increase.

### `--no-install`

Does not install any artifacts as part of the build process.

### `--products|-p <name>[,<name>...]`

Takes only the products specified by `<name>` and their dependencies into account.

### `--settings-dir <directory>`

Reads all settings (such as profile information) from the specified `<directory>`. If the directory does not exist, it will be created.

The default value is system-specific. For example:

- Linux: `$HOME/.config/QtProject/qbs`
- Windows: `%APPDATA%\QtProject\qbs`
- macOS: `$HOME/Library/Preferences/qbs`

### `--show-progress`

Shows how command execution is progressing.

This option is mutually exclusive with `--log-time`.

### `--no-fallback-module-provider`

If this option is set, then Qbs will not fall back to a pkg-config based module provider if a dependency is not found.

### `--wait-lock`

Waits indefinitely for other processes to release the build graph lock.

This option is typically used by generators, which may re-invoke multiple Qbs processes on the same project simultaneously.

## Parameters

### `config:configuration-name`

Specifies the build configuration to use.

Qbs can build a project for one or multiple configurations at once, each having a different set of parameters. The `config` parameter has a special function: with each occurrence a new configuration instance begins and all subsequent parameters until the next `config` are assigned to this instance. Parameter assignments before the first occurrence of `config` are applied to all build configurations. Inside products and modules, the current active build configuration can be retrieved via qbs.configurationName.

In the following snippet, a profile `clang` is applied to all configurations while `cpp.optimization` is different for `debug` and `release`:

      profile:clang config:debug cpp.optimization:none config:release cpp.optimization:small

The value of `config` determines the name of the build folder and affects the default value of the qbs.buildVariant property. Qbs knows the `config` values `"debug"` and `"release"`, but in general any name can be chosen. When naming configurations created for special purposes, follow the rules for legal names generally used in programming languages:

- The first character must be a letter (a-z), an underscore (_), or a dollar sign ($).
- Subsequent characters may be letters, digits, underscores, or dollar signs.

### `property:value`

Property values set in project files or profiles can be overridden on the command line. The syntax is:

      <prefix>.<property-name>:<property-value>

For more information, see Overriding Property Values from the Command Line.

## Examples

Builds the application specified by the `.qbs` file in the current directory using the default profile:

      qbs

Builds the application using four concurrent build jobs:

      qbs -j 4

Builds the default configuration of an application using the profile called `Android`:

      qbs build profile:Android

Builds the application using different cpp module properties for debug and release configurations. For the debug configuration, warnings will cause the build to fail, whereas for the release configuration, the size of the build artifacts will be optimized. Both configurations are built with a profile named `"qt"`:

      qbs build profile:qt config:debug modules.cpp.treatWarningsAsErrors:true config:release modules.cpp.optimization:small