Qbs Manual | run

Qbs 1.14.0

# run

## Synopsis

      qbs run [options] [config:configuration-name] [property:value] ... [ -- <arguments>]

## Description

Runs the specified product's executable with the specified `<arguments>`. If the project has only one product, the `--products` option may be omitted.

The product will be built if it is not up to date, unless the `--no-build` option is specified. For more information, see build.

For more information about running applications, see Running 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.

### `--install-root <directory>`

Installs into the specified `<directory>`. If the directory does not exist, it will be created.

The default value is `<build` dir>/install-root.

Use the special value `@sysroot` to install into the `sysroot`. That is, the value of the qbs.sysroot property.

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

### `--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-build`

Does not re-build the project before installing or running it.

### `--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`

### `--setup-run-env-config`

A comma-separated list of strings. They will show up in the `config` parameter of all setupRunEnvironment scripts.

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

## Arguments

### `--` <arguments>

Command-line arguments to be passed to the program to be run.

## Examples

Runs the Qt Creator application:

      qbs run --products qtcreator