bdep-config(1)

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

🎀 bdep-config 🎀

okay bestie, welcome to bdep-config(1) — straight out of the General Commands Manual 💖 and it's literally the tool that manages project build configurations. That's the whole vibe. Let's get into it 👑

✨ 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)...]

like, look at all those little subcommands 😭 so organized. slay.

🦋 DESCRIPTION 🦋

So the config command ships with a whole set of subcommands for managing your project's build configurations. And here's the lil quality-of-life detail: if you don't specify a project directory, it just assumes the current working directory. easy ✨

💅 CONFIG SUBCOMMANDS 💅

add

the deets for this one live right under create, bestie — keep scrolling 👇

create

The add subcommand takes an existing bpkg(1) build configuration sitting in the directory cfg-dir and adds it to the project's build configuration set. 🫶

The create subcommand, on the other hand, makes a brand new configuration in the directory cfg-dir by running the bpkg-cfg-create(1) command and handing it cfg-args, if there are any. Then it carries on exactly like add and pops that new configuration into the project's build configuration set. 💖

For both of these subcommands: if cfg-name is specified, then the configuration that just got added gets given that name. A bunch of bdep commands can use these names as a way-more-convenient way to point at build configurations (peep bdep-projects-configs(1) for the details 👀).

Okay here's the shortcut, and it's lowkey cute: if cfg-name is not specified and cfg-dir is a simple path that starts with @, then it gets treated as the name, and the configuration directory is assumed to be prj-dir-cfg-name. 🎀

⚠️ heads up though — in the case of create, cfg-dir must be preceded with -- (double dash) so it doesn't get confused with @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

see?? iconic. 😌

A configuration also has a type, which gets specified with the --type option (or --config-type from bdep-new(1)). If you don't say the type explicitly, then target is assumed. Check bpkg-cfg-create(1) if you want the background on configuration types. 📚

Unless the --no-default option is given, the first added or created build configuration of each type gets designated as the default 👑. Several bdep commands use a configuration like that by default when no configuration was specified explicitly (again, bdep-projects-configs(1) has the deets). If you wanna make a subsequently added configuration the default, use the --default option. Also note: when you've got multiple default configurations, any given package within a project can only be initialized in one such configuration. no sharing, bestie 🚫

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 gets configured to forward to this configuration (see b(1) for the details on forwarded configurations). If you wanna designate a non-default configuration as forwarded, use the --forward option. Also note: you can have multiple forwarded configurations, but any given package within a project can only be initialized in one such configuration. same energy as before 💀

And unless the --no-auto-sync option is specified, an added or created build configuration will be automatically synchronized on every build system invocation. ⚡

⚠️ important: this flag affects the entire build configuration, so if multiple projects share the same configuration, then they must all have a consistent auto-synchronization setting. no chaos allowed 🙈

The link subcommand links the first specified build configuration with the second one by executing the bpkg-cfg-link(1) command. Want the background on linked configurations? That's bpkg-cfg-create(1). 🔗

The unlink subcommand unlinks the first specified build configuration from the second one by executing the bpkg-cfg-unlink(1) command. Again, bpkg-cfg-create(1) has the background on linked configurations. ✂️

list

The list subcommand prints out the list of build configurations associated with the project. Unless one or more configurations are specified explicitly, list prints all the associate configurations. And ngl this matters: the output is written to stdout, not stderr. 📝

If the output format is json (see the --stdout-format common option), then the output is a JSON array of objects, which are the serialized 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 the details on the overall properties of this format and the semantics of the struct serialization. 🧚

The id member is a numeric configuration id that you can use to identify the configuration instead of the name or the path (see the --config-id option). The path member is an absolute path to the configuration directory. The packages member holds the array of packages belonging to this project that have been initialized in this configuration. And for the meaning of the other members (name, type, default, etc) — scroll on back up to the create subcommand. 💜

move

The move subcommand assigns the specified build configuration a new directory. It's normally used after you move or rename the configuration directory. 📦

⚠️ note: you need an explicit bdep-sync(1) command for this change to actually take effect!

See bdep-projects-configs(1) for the 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 the 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: only configurations that have no initialized packages can be removed. like, empty ones only, bestie.

See bdep-projects-configs(1) for the 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-configs(1) for the various ways to specify build configurations.

The properties you can modify include the default (--[no-]default), forward (--[no-]forward), and auto-synchronization (--[no-]auto-sync) flags.

⚠️ note: changing any of these flags requires an explicit bdep-sync(1) command to take effect!

🔥 CONFIG OPTIONS 🔥

  • --type | --config-type typ — the type of the configuration being created. By default, a 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. 🔢

and that's where part 1 wraps up — more is coming, don't go anywhere bestie 🫶💖

✨ COMMON OPTIONS ✨

okay bestie these are the shared ones, the little besties that every bdep command gets to borrow 💖 and if you want the full tea on any of them, bdep-common-options(1) has you covered, no cap.

  • -v — shows you the essential underlying commands as they actually get run. like, the receipts, but only the important ones.
  • -V — shows you all the underlying commands being executed. every single one. the whole group chat scrollback. 🫶
  • --quiet|-q — run quietly, only printing error messages. silent mode, mysterious queen energy 💅
  • --verbose level — sets the diagnostics verbosity to level, and that level lives between 0 and 6.
  • --stdout-format format — the representation format to use when printing to stdout.
  • --jobs|-j num — how many jobs to do in parallel. multitasking icon. 🔥
  • --progress — displays progress indicators for long-lasting operations, like network transfers, building, etc.
  • --no-progress — suppresses those progress indicators for long-lasting operations, like network transfers, building, etc. no little spinner for you.
  • --diag-color — use color in diagnostics. pretty errors, we love to see it 🌈
  • --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 — an additional option to be passed to the package manager program.
  • --build path — the build program to be used to build packages.
  • --build-option opt — an additional option to be passed to the build program.
  • --curl path — the curl program to be used for network operations.
  • --curl-option opt — an additional option to be passed to the curl program.
  • --pager path — the pager program to be used to show long text.
  • --pager-option opt — an 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. periodt.

🌸 DEFAULT OPTIONS FILES 🌸

okay so the whole overview of default options files lives in bdep-default-options-files(1), go read that if you want the full lore. but for this command specifically? the search start directory is the project directory. cute.

in each directory it goes looking for these files and, if it finds them, loads them in exactly this order:

bdep.options
bdep-config.options
bdep-config-add.options          # if the create subcommand
bdep-config-<subcommand>.options # (subcommand-dependent)
🚨 heads up bestie: these two options below are not allowed to live in the default options files. like, do not even try it: - --directory|-d - --wipe

💀 BUGS 💀

found a bug? send those bug reports to the users@build2.org mailing list. they wanna hear about it, fr fr.

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. slay, and legally so ✨

and that's the whole page, bestie 🎀 this was bdep-config(1) from bdep 0.17.0, dated June 2024. go forth and configure your builds, you absolute main character 💖🦋

📦 where this page comes from