bdep-config(1)

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.

--sqlite-synchronous mode
    Filesystem synchronization mode for the project SQLite database.

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

COPYRIGHT
Copyright (c) 2014-2026 the build2 authors. Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License.