# NAME

`bdep-config` – manage project build configurations

# SYNOPSIS

`bdep config add [options] [prj-spec] [@cfg-name] cfg-dir
bdep config create [options] [prj-spec] [@cfg-name] cfg-dir [cfg-args]
bdep config link [options] [prj-spec] cfg-spec cfg-spec
bdep config unlink [options] [prj-spec] cfg-spec cfg-spec
bdep config list [options] [prj-spec] [cfg-spec...]
bdep config move [options] [prj-spec] cfg-spec cfg-dir
bdep config rename [options] [prj-spec] cfg-spec cfg-name
bdep config remove [options] [prj-spec] cfg-spec... | --all|-a
bdep config set [options] [prj-spec] cfg-spec... | --all|-a
[--[no-]default]
[--[no-]forward]
[--[no-]auto-sync]`

`cfg-spec = @cfg-name | --config|-c cfg-dir
prj-spec = --directory|-d prj-dir
cfg-args = [-- [bpkg-options]] [--existing|-e | (module | cfg-var)...]`

# DESCRIPTION

The `config` command provides the following subcommands for managing project's build configurations. If no project directory is specified, then the current working directory is assumed.

# CONFIG SUBCOMMANDS

`add`
`create`
  The `add` subcommand adds an existing `bpkg(1)` build configuration in directory `cfg-dir` to the project's build configuration set. The `create` subcommand creates a new configuration in directory `cfg-dir` by executing the `bpkg-cfg-create(1)` command and passing to it `cfg-args`, if any. It then proceeds as `add` by adding the new configuration to the project's build configuration set.

  In both subcommands, if `cfg-name` is specified, then the added configuration is given this name. Several `bdep` commands can use such names as a more convenient way to specify build configurations (see `bdep-projects-configs(1)` for details).

  As a shortcut, if `cfg-name` is not specified and `cfg-dir` is a simple path that starts with `@`, then it is treated as the name and the configuration directory is assumed to be `prj-dir-cfg-name`. Note that in case of `create`, `cfg-dir` must be preceded with `--` (double dash) option to disambiguate it from `@cfg-name`. For example, assuming the project directory is `hello`:

      $ bdep config add @clang                        # ../hello-clang
      $ bdep config create -- @gcc cc config.cxx=g++  # ../hello-gcc

  A configuration also has a type that is specified with the `--type` option (or `--config-type` from `bdep-new(1)`). If the type is not specified explicitly, then `target` is assumed. See `bpkg-cfg-create(1)` for background on configuration types.

  Unless the `--no-default` option is specified, the first added or created build configuration of each type is designated as the default. Several `bdep` commands use such a configuration by default if no configuration was specified explicitly (see `bdep-projects-configs(1)` for details). To make a subsequently added configuration the default use the `--default` option. Note also that in case of multiple default configurations any given package within a project can only be initialized in one such configuration.

  The default build configuration of each type is also designated as forwarded unless the `--no-forward` option is specified or another configuration of this type is already designated as forwarded. When a project is initialized in a forwarded build configuration, its source directory is configured to forward to this configuration (see `b(1)` for details on forwarded configurations). To designate a non-default configuration as forwarded use the `--forward` option. Note also that it is possible to have multiple forwarded configurations, however, any given package within a project can only be initialized in one such configuration.

  Unless the `--no-auto-sync` option is specified, an added or created build configuration will be automatically synchronized on every build system invocation. Note that this flag affects the entire build configuration and if multiple projects share the same configuration, then they must have a consistent auto-synchronization setting.

`link`
  The `link` subcommand links the first specified build configuration with the second by executing the `bpkg-cfg-link(1)` command. See `bpkg-cfg-create(1)` for background on linked configurations.
`unlink`
  The `unlink` subcommand unlinks the first specified build configuration from the second by executing the `bpkg-cfg-unlink(1)` command. See `bpkg-cfg-create(1)` for background on linked configurations.
`list`
  The `list` subcommand prints the list of build configurations associated with the project. Unless one or more configurations are specified explicitly, `list` prints all the associate configurations. Note that the output is written to `stdout`, not `stderr`.

  If the output format is `json` (see the `--stdout-format` common option), then the output is a JSON array of objects which are the serialized representation of the following C++ `struct` `configuration`:

      struct package
      {
        string name;
      };

      struct configuration
      {
        uint64_t         id;
        string           path;
        optional<string> name;
        string           type;
        bool             default;
        bool             forward;
        bool             auto_sync;
        vector<package>  packages;
      };

  For example:

      [
        {
          "id": 1,
          "path": "/tmp/hello-gcc",
          "name": "gcc",
          "type": "target",
          "default": true,
          "forward": true,
          "auto_sync": true,
          "packages": [
            {
              "name": "hello"
            }
          ]
        }
      ]

  See the JSON OUTPUT section in `bdep-common-options(1)` for details on the overall properties of this format and the semantics of the `struct` serialization.

  The `id` member is a numeric configuration id that can be used to identify the configuration instead of the name or path (see the `--config-id` option). The `path` member is an absolute path to the configuration directory. The `packages` member contains the array of packages belonging to this project that have been initialized in this configuration. See the `create` subcommand for the meaning of other members (`name`, `type`, `default`, etc).

`move`
  The `move` subcommand assigns the specified build configuration a new directory. It is normally used after moving/renaming the configuration directory. Note that an explicit `bdep-sync(1)` command is required for this change to take effect. See `bdep-projects-configs(1)` for various ways to specify a build configuration.
`rename`
  The `rename` subcommand gives the specified build configuration a new name. See `bdep-projects-configs(1)` for various ways to specify a build configuration.
`remove`
  The `remove` subcommand removes one or more build configurations from the project's build configuration set. Note that only configurations that have no initialized packages can be removed. See `bdep-projects-configs(1)` for various ways to specify build configurations.
`set`
  The `set` subcommand modifies various properties of one or more build configurations associated with the project. See `bdep-projects-configs(1)` for various ways to specify build configurations.

  The properties that can be modified include the default (`--[no-]default`), forward (`--[no-]forward`), and auto-synchronization (`--[no-]auto-sync`) flags. Note that changing any of these flags requires an explicit `bdep-sync(1)` command to take effect.

# CONFIG OPTIONS

`--type`|`--config-type` `typ`
  The type of the configuration being created. By default, configuration of type `target` is created. See `bpkg-cfg-create(1)` for background on configuration types.
`--default`
  Make the added or created configuration the default.
`--no-default`
  Don't make the first added or created configuration the default.
`--forward`
  Make the added or created configuration forwarded.
`--no-forward`
  Don't make the added or created configuration forwarded.
`--auto-sync`
  Make the added or created configuration automatically synchronized.
`--no-auto-sync`
  Don't make the added or created configuration automatically synchronized.
`--existing`|`-e`
  Initialize a `bpkg` configuration based on an existing build system configuration.
`--wipe`
  Wipe the configuration directory clean before creating the new configuration.
`--all`|`-a`
  Use all build configurations.
`--config`|`-c` `dir`
  Specify the build configuration as a directory.
`--directory`|`-d` `dir`
  Assume project/package is in the specified directory rather than in the current working directory.
`--config-name`|`-n` `name`
  Specify the build configuration as a name.
`--config-id` `num`
  Specify the build configuration as an id.

# COMMON OPTIONS

The common options are summarized below with a more detailed description available in `bdep-common-options(1)`.

`-v`
  Print essential underlying commands being executed.
`-V`
  Print all underlying commands being executed.
`--quiet`|`-q`
  Run quietly, only printing error messages.
`--verbose` `level`
  Set the diagnostics verbosity to `level` between 0 and 6.
`--stdout-format` `format`
  Representation format to use for printing to `stdout`.
`--jobs`|`-j` `num`
  Number of jobs to perform in parallel.
`--progress`
  Display progress indicators for long-lasting operations, such as network transfers, building, etc.
`--no-progress`
  Suppress progress indicators for long-lasting operations, such as network transfers, building, etc.
`--diag-color`
  Use color in diagnostics.
`--no-diag-color`
  Don't use color in diagnostics.
`--bpkg` `path`
  The package manager program to be used for build configuration management.
`--bpkg-option` `opt`
  Additional option to be passed to the package manager program.
`--build` `path`
  The build program to be used to build packages.
`--build-option` `opt`
  Additional option to be passed to the build program.
`--curl` `path`
  The curl program to be used for network operations.
`--curl-option` `opt`
  Additional option to be passed to the curl program.
`--offline`
  Do not attempt to download resources (packages, repository metadata, etc), instead taking them from the local fetch cache if available and failing otherwise.
`--no-fetch-cache`
  Disable local caching of download resources (packages, repository metadata, etc).
`--fetch-cache` `mode`
  Comma-separated list of local fetch cache modes.
`--fetch-cache-session` `id`
  The local fetch cache session.
`--pager` `path`
  The pager program to be used to show long text.
`--pager-option` `opt`
  Additional option to be passed to the pager program.
`--options-file` `file`
  Read additional options from `file`.
`--default-options` `dir`
  The directory to load additional default options files from.
`--no-default-options`
  Don't load default options files.

# DEFAULT OPTIONS FILES

See `bdep-default-options-files(1)` for an overview of the default options files. For the `config` command the search start directory is the project directory. The following options files are searched for in each directory and, if found, loaded in the order listed:

    bdep.options
    bdep-config.options
    bdep-config-add.options          # if the create subcommand
    bdep-config-<subcommand>.options # (subcommand-dependent)

The following `config` command options cannot be specified in the default options files:

    --directory|-d
    --wipe

# BUGS

Send bug reports to the users@build2.org mailing list.