bdep-init(1)

📦
version 0.17.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05

💖 bdep-init(1) — the girlies' guide to initializing ur project 💖

okay so bestie, this is bdep-init, from the General Commands Manual section, and it's literally the command that gets ur project set up in ur build configurations. i'm obsessed. let's go ✨

🌸 NAME 🌸

bdep-init — initialize project in build configurations 💅

✨ SYNOPSIS ✨

like, here's the whole vibe, verbatim, no cap:

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 🦋

so the init command initializes a project in one or more build configurations. that's the whole main character moment.

first form: it 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. that association thing lives in bdep-config(1) if u wanna go read it.

if no project directory is specified, then the current working directory is assumed. periodt. and if no configuration is specified, then the default configuration is assumed — which fails if multiple default configurations are present, so like, don't do that 🙈. head to bdep-projects-configs(1) for the full tea on specifying projects and configurations. the optional pkg-args are the additional dependency packages and/or configuration variables to pass to the underlying bpkg-pkg-build(1) command.

second form (--empty is specified): initializes an empty project database that u can later use to first add build configurations (bdep-config(1)) and then initialize project packages using the first form. it's giving "build it from scratch, queen" 💅

third (--config-add) and fourth (--config-create) forms: these are shortcuts to first adding an existing or newly created build configuration and then initializing project packages in that configuration. semantically they're equivalent to first performing the config add or config create commands (bdep-config(1)), respectively, followed by the first form. no cap.

optional cfg-args in the fourth form are the additional arguments to the underlying bpkg-cfg-create(1) command. now listen — in this case, to specify pkg-args without specifying cfg-args u have to use two -- separators, like:

$ 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 🎀

okay so 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, iykyk).

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. slay, options.

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. so like, half-done, come back later bestie.
  • --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. ⚠️ girl. it wipes. be so serious.
  • --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 💜

these are summarized below, with a more detailed description available in bdep-common-options(1). not me giving u the recap tho 💅

  • -v — print essential underlying commands being executed.
  • -V — print all underlying commands being executed.
  • --quiet, -q — run quietly, only printing error messages. shhh.
  • --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
⚠️ and listen, these init command options cannot be specified in the default options files: --directory|-d --config-add|-A --config-create|-C --wipe

like, they're just too powerful for the options files. respect the boundary 💅

😭 BUGS 😭

send bug reports to the users@build2.org mailing list. we listen, we fix. 🫶

copyright (c) 2014-2024 the build2 authors.

permission is granted to copy, distribute and/or modify this document under the terms of the MIT License. iconic, honestly.

and that's the whole thing bestie 💖 this was from bdep 0.17.0, dated June 2024, and yes it's the bdep-init(1) page — go initialize something, u got this ✨🎀🦋

📦 where this page comes from