# 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 associated 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 `--directory|-d`. See `bdep-projects-configs(1)` for details on specifying projects and configurations. Optional `pkg-args` are the additional dependency packages and/or configuration variables to pass to the underlying `bpkg-pkg-build(1)` command.

The second form (`--empty` is specified) initializes an empty project database that can later be used to first add build configurations (`bdep-config(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-grouping(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 (assuming `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 installed. 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)` option 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, 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 `init` 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 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 options files:

    --directory|-d
    --config-add|-A
    --config-create|-C
    --wipe

# BUGS

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