bdep-init(1) bdep 0.17.0

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

The following set of invocations achieves the same end result but using the `bdep-config(1)` command to manage configuration.

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

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