- Qbs Manual
- Command-Line Interface
- shell
- Qbs 3.1.0

# shell

## Synopsis

     qbs shell [options] [config:configuration-name] [property:value]

## Description

Opens a shell in the environment that a build with the specified parameters would use.

For more information, see Using the Shell.

## Options

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

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

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

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

Opens a shell with the same environment that Qbs uses when building the project:

     qbs shell