Qbs Manual | Command-Line Interface | config

Qbs 1.16.0

# config

## Synopsis

      qbs config [--settings-dir <directory>] [--user|--system] [--list [<root> ...]]
                 [--unset <key>] [--export <file>] [--import <file>]
      qbs config [--settings-dir <directory>] [--user|--system] <key>
      qbs config [--settings-dir <directory>] [--user|--system] <key> <value>

## Description

Manages Qbs settings, such as preferences and profiles. You can list all keys and remove the specified key, as well as import settings from a file or export them to a file.

The second form of this command displays the specified `<key>`.

The third form sets the specified `<key>` with the specified `<value>`.

There are two sets of settings: The system-level settings affect all users, while the user-level settings are specific to the current user. By default, the read operations consider both sources. If the same key is present in both settings, then for list values, the system value is appended to the user value, while for other types of values the user-level one takes precedence. Write operations go to the user-level settings by default. Use the `--user` and `--system` options to change this behavior.

Note: It is conceivable that the default system value of the `preferences.qbsSearchPaths` setting could pull in unwanted Qbs modules, in particular when doing cross-builds. In such a case, you can set `preferences.ignoreSystemSearchPaths` to exclude the search paths coming from the system settings. You'll typically do this for a specific profile:

      $ qbs config profiles.myprofile.preferences.ignoreSystemSearchPaths true

You can use the config-ui command to open the Qbs Settings tool for managing settings in a hierarchical view.

For more information, see Configuring Profiles and Preferences, Managing Qt Versions, Modules, List of Modules, and Custom Modules and Items.

## Options

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

### `--list [<root> ...]`

Lists keys under the key `<root>` or all keys if the root is not specified.

Possible values are:

- `defaultProfile` is the default profile to use if a profile is not specified
- `preferences` accepts build preferences as second-level keys
- `profiles` accepts profile names as second-level keys

### `--unset <key>`

Removes the specified `<key>`.

### `--export <file>`

Exports settings to the specified `<file>`.

### `--import <file>`

Imports settings from the specified `<file>`.

### `--user`

Causes read operations to display only the user-level settings, while the system-level settings are ignored. Write operations will target the user-level settings, which is also the default.

### `--system`

Read and write operations will consider only the system-level settings.

### `--help|-h|-?`

Displays help for the command.

## Parameters

### `<key>`

Typically, a `<key>` consists of several levels separated by periods. The first level shows a root value, such as preferences or profiles. The root determines whether the second-level keys are build preferences or profile names. The lower level keys consist of a module name, followed by a property name.

## Examples

Lists the existing profiles:

      qbs config --list profiles

Shows the default profile:

      qbs config defaultProfile

Note: If no output is shown, the default profile used is the built-in profile `none`, which sets no properties.

Sets the profile called `gcc` as the base profile of the Qt profile called `myqt`:

      qbs config profiles.myqt.baseProfile gcc

Adds the location of a custom module to your preferences, to make the module accessible in several projects:

      qbs config preferences.qbsSearchPaths /usr/local/share/custom-qbs-extensions