home | help 
bdep-config(1)		     General Commands Manual		  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 cre-
	    ate 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  con-
	    figuration	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 con-
	    figuration directory is assumed to be prj-dir-cfg-name. Note that in
	    case of create, cfg-dir must be preceded with -- (double  dash)  op-
	    tion  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 spec-
	    ified 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 cre-
	    ated  build configuration of each type is designated as the default.
	    Several bdep commands use such a configuration by default if no con-
	    figuration 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 ini-
	    tialized 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 configu-
	    ration,  then  they must have a consistent auto-synchronization set-
	    ting.

     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 configura-
	    tion 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 associ-
	    ated with the project. Unless one or more configurations are  speci-
	    fied  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  op-
	    tion),  then the output is a JSON array of objects which are the se-
	    rialized 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 con-
	    figuration	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 configura-
	    tion directory. Note that an explicit bdep-sync(1)	command  is  re-
	    quired  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-con-
	    figs(1) for various ways to specify build configurations.

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

CONFIG OPTIONS
     --type|--config-type typ
	    The type of the configuration being created. By default,  configura-
	    tion  of  type  target  is created. See bpkg-cfg-create(1) for back-
	    ground 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 synchro-
	    nized.

     --existing|-e
	    Initialize a bpkg configuration based on an  existing  build  system
	    configuration.

     --wipe Wipe  the configuration directory clean before creating the new con-
	    figuration.

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

     --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 di-
     rectory. 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 op-
     tions 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.

bdep 0.18.0			   April 2026			  bdep-config(1)
home | help