home | help 
bdep-init(1)		     General Commands Manual		    bdep-init(1)

NAME
     bdep-init - initialize project in build configurations

SYNOPSIS
     bdep init [options] [pkg-spec] [cfg-spec] [pkg-args]
     bdep init [options] [prj-spec] --empty|-E
     bdep init [options] [pkg-spec] --config-add|-A cfg-dir [@cfg-name]
	       [pkg-args]
     bdep init [options] [pkg-spec] --config-create|-C cfg-dir [@cfg-name]
	       [cfg-args] [-- pkg-args]

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

DESCRIPTION
     The init command initializes a project in one or more build configurations.
     The  first  form initializes the specified project packages (pkg-spec), or,
     if the project itself is specified (prj-spec), all its available  packages,
     in one or more build configurations (cfg-spec) that have already been asso-
     ciated with the project (bdep-config(1)).

     If no project directory is specified, then the current working directory is
     assumed.  If  no configuration is specified, then the default configuration
     is assumed (failing if multiple default configurations are  present).  Note
     that  unlike  in  all  other commands, in init the package to initialize in
     pkg-spec cannot be specified as a pkg name, only as a directory with  --di-
     rectory|-d. See bdep-projects-configs(1) for details on specifying projects
     and  configurations.  Optional pkg-args are the additional dependency pack-
     ages and/or configuration variables to pass  to  the  underlying  bpkg-pkg-
     build(1) command.

     The  second  form (--empty is specified) initializes an empty project data-
     base that can later be used to first add  build  configurations  (bdep-con-
     fig(1)) and then initialize project packages using the first form.

     The  third  (--config-add) and fourth (--config-create) forms are shortcuts
     to first adding an existing or newly created build configuration  and  then
     initializing  project packages in that configuration. Semantically they are
     equivalent to first performing the config add  or	config	create	commands
     (bdep-config(1)),	respectively, followed by the first form.  Optional cfg-
     args in the fourth form are the  additional  arguments  to  the  underlying
     bpkg-cfg-create(1)  command.  Note  that  in  this case to specify pkg-args
     without specifying cfg-args you have to use two -- separators, for example:

     $ bdep init -C ../prj-gcc @gcc -- -- ?sys:libsqlite3/*

     Configuration variables can be specified to only apply to specific packages
     in pkg-args using the  argument  grouping	mechanism  (bdep-argument-group-
     ing(1)).  Additionally,  such  packages  can be placed into specific linked
     configurations by specifying the configuration with one  of  the  --config*
     options (or @ notation) using the same grouping mechanism. For example (as-
     suming gcc is linked to common):

     $ bdep init @gcc { @common config.liblarge.extra=true }+ ?liblarge

EXAMPLES
     As an example, consider project prj with two packages, foo and libfoo:

     prj/
     |-- foo/
     `-- libfoo/

     The following invocations illustrate the common init use cases (the current
     working directory is shown before the shell prompt).

     Create  new  build configuration in ../prj-gcc, call it gcc, and initialize
     project packages foo and libfoo in this configuration:

     prj/$ bdep init -C ../prj-gcc @gcc cc config.cxx=g++

     Create new build configuration in	../prj-clang  using  bpkg-cfg-create(1).
     Then  add	it  calling  it clang and initialize project package foo in this
     configuration:

     prj/$ bpkg create -d ../prj-clang cc config.cxx=clang++
     prj/$ cd foo
     foo/$ bdep init -A ../../prj-clang @clang

     Initialize project package libfoo in the build configuration clang:

     foo/$ cd ..
     prj/$ bdep init -d libfoo @clang

     To additionally configure libfoo add configuration variables to  the  above
     command line:

     prj/$ bdep init -d libfoo @clang config.libfoo.bar=true

     The following set of invocations achieves the same end result but using the
     bdep-config(1) command to manage configurations and bdep-sync(1) command to
     reconfigure a package.

     Initialize an empty project database:

     prj/$ bdep init --empty

     Create new build configuration in ../prj-gcc, call it gcc:

     prj/$ bdep config create ../prj-gcc @gcc cc config.cxx=g++

     Add existing build configuration in ../prj-clang, call it clang:

     prj/$ bdep config add ../prj-clang @clang

     Initialize  project packages foo and libfoo in build configurations gcc and
     clang:

     prj/$ bdep init @gcc @clang

     Or, alternatively, in all the build configurations:

     prj/$ bdep init -a

     Reconfigure libfoo in the build configuration clang:

     prj/$ bdep sync libfoo @clang config.libfoo.bar=true

INIT OPTIONS
     --empty|-E
	    Initialize an empty build configuration set.

     --config-add|-A dir
	    Add an existing build configuration dir.

     --config-create|-C dir
	    Create a new build configuration in dir.

     --no-sync
	    Enter the project into the database but do not initialize it in  the
	    build  configurations. The initialization can be finished later with
	    an explicit bdep-sync(1) command.

     --sys-no-query
	    Do not query the system package manager for the  installed	versions
	    of	packages  specified  with  the sys scheme. See the corresponding
	    bpkg-pkg-build(1) option for details.

     --sys-install
	    Instruct the system package manager to install available versions of
	    packages specified with the sys scheme  that  are  not  already  in-
	    stalled. See the corresponding bpkg-pkg-build(1) option for details.

     --sys-no-fetch
	    Do not fetch the system package manager metadata before querying for
	    available  versions  of  packages specified with the sys scheme. See
	    the corresponding bpkg-pkg-build(1) option for details.

     --sys-no-stub
	    Do no require a stub for packages specified with the sys scheme. See
	    the corresponding bpkg-pkg-build(1) option for details.

     --sys-yes
	    Assume the answer to the system package manager prompts is yes.  See
	    the corresponding bpkg-pkg-build(1) option for details.

     --sys-sudo prog
	    The sudo program to use for system package manager interactions that
	    normally  require administrative privileges (fetch package metadata,
	    install packages, etc). See the corresponding bpkg-pkg-build(1)  op-
	    tion for details.

     --create-host-config
	    Create  a  configuration  for build-time dependencies without prompt
	    (see bdep-sync(1) for details).

     --create-build2-config
	    Create a configuration for build system module dependencies  without
	    prompt (see bdep-sync(1) for details).

     --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 init 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 config-add}.options		     # if --config-add|-A
     bdep-{config config-add config-create}.options  # if --config-create|-C
     bdep-init.options

     The  following  init command options cannot be specified in the default op-
     tions files:

     --directory|-d
     --config-add|-A
     --config-create|-C
     --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-init(1)
home | help