bpkg-cfg-create(1)

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

🎀 NAME 🎀

bestie, meet bpkg-cfg-create — it's the manual page (section 1, general commands) for the command that creates a configuration. we're in bpkg-cfg-create(1) territory and it's lowkey iconic 💅

✨ SYNOPSIS ✨

okay so here's how you actually call it:

bpkg cfg-create|create [options] [cfg-args]
bpkg cfg-create|create [options] --existing|-e

cfg-args = (module | cfg-var)...

like, cfg-create and create are the same thing, pick your fave 🫶

🌸 DESCRIPTION 🌸

so cfg-create does one of two things, depending on the form you use:

  1. first form — it creates a brand new bpkg configuration with the build2 modules and configuration variables you name as cfg-args
  2. second form — it initializes a configuration based on an existing build system configuration

and heads up: the bpkg configuration is itself a build system configuration, so if you want the full lore on that, go look at the build system driver (b(1)) create meta-operation. no cap.

now, the directory rules, and these are important bestie:

  • unless you pass --existing|-e or --wipe, cfg-create expects the configuration directory to be empty, or to not exist at all (in which case it will be created for you, slay)

by default, the configuration made with the first form loads the config, test, dist, and install modules. but you can throw in extra modules and, if you need them, their configuration variables, as cfg-create arguments. for example:

bpkg create cxx config.cxx=clang++ config.install.root=/usr/local

here's a subtle little thing that's giving very much ✨ detail ✨: by default, bpkg appends .config to the names of the modules you specify, so that only their configurations get loaded. you can override that behavior by putting a period (.) after the module name. you can also tell bpkg to use the optional module load by prefixing the module name with a question mark (?). like:

bpkg create cxx. "?cli"

now the linking situation 🦋 — configurations can be linked with each other, which lets a package be built in one configuration while its dependencies live in one or more linked configurations. very main character energy. this is how you make a "base" configuration with common dependencies shared between multiple configurations. this same mechanism is also used to provide a host configuration, which is what gets used to build build-time dependencies.

every configuration gets an automatically-generated UUID unless you specify one with --uuid. that UUID is used to check the integrity of configuration links. and for the convenience of referring to linked configurations, a configuration can also be assigned a name with --name. obsessed.

a configuration also has a type, set with --type. three predefined types exist: target, host, and build2. if you don't say anything explicitly, target is assumed. when satisfying a dependency of one package on another, a linked configuration will only be considered if:

  1. it has the same type as the other configuration, for run-time dependencies
  2. it has the host type, for regular build-time dependencies
  3. it has the build2 type, for build system module build-time dependencies

and note — a host configuration is a target configuration for the host machine. so to create a self-hosted configuration, use type host. 💀 easy to forget.

to link a configuration we use the bpkg-cfg-link(1) command. but as a shortcut, host and build system module configurations can also be linked during configuration creation with the --host-config and --build2-config options, respectively. and if a build-time dependency shows up in a configuration that has no linked configuration of a suitable type (host or build2, nor is itself of a suitable type), then a private host or build system module configuration named host or build2, respectively, is created automatically inside the configuration's .bpkg/ subdirectory. it just does that. periodt.

💖 CFG-CREATE OPTIONS 💖

  • --directory|-d dir — create the configuration in dir instead of in the current working directory.
  • --existing|-e — initialize a bpkg configuration based on an existing build system configuration.
  • --wipe — wipe the configuration directory clean before creating the new configuration. > for safety, this option requires that you specify the configuration directory explicitly with --directory|-d. 🚨
  • --host-config dir — link the specified host configuration with the configuration being created, as if by running the bpkg-cfg-link(1) command.
  • --no-host-config — ignore any specified --host-config options.
  • --build2-config dir — link the specified build system module configuration with the configuration being created, as if by running the bpkg-cfg-link(1) command.
  • --no-build2-config — ignore any specified --build2-config options.
  • --name name — the name of the configuration being created. if this configuration is linked with another configuration using bpkg-cfg-link(1), this name will be used as the link name unless it's overridden. by default the configuration is created unnamed. 🙈
  • --type type — the type of the configuration being created. by default, a configuration of type target is created.
  • --uuid uuid — use the specified UUID as the configuration id instead of generating one automatically.

🌈 COMMON OPTIONS 🌈

these are the shared ones, summarized below — the full deep dive lives in bpkg-common-options(1), iykyk.

  • -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.
  • --no-result — don't print informational messages about the outcome of performing a command or some of its parts.
  • --structured-result fmt — write the result of performing a command in a structured form.
  • --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.
  • --build path — the build program to be used to build packages.
  • --build-option opt — additional option to be passed to the build program.
  • --fetch path — the fetch program to be used to download resources.
  • --fetch-option opt — additional option to be passed to the fetch program.
  • --fetch-timeout sec — the fetch and fetch-like (for example, git) program timeout.
  • --pkg-proxy url — HTTP proxy server to use when fetching package manifests and archives from remote pkg repositories.
  • --git path — the git program to be used to fetch git repositories.
  • --git-option opt — additional common option to be passed to the git program.
  • --sha256 path — the sha256 program to be used to calculate SHA256 sums.
  • --sha256-option opt — additional option to be passed to the sha256 program.
  • --tar path — the tar program to be used to extract package archives.
  • --tar-option opt — additional option to be passed to the tar program.
  • --openssl path — the openssl program to be used for crypto operations.
  • --openssl-option opt — additional option to be passed to the openssl program.
  • --auth type — types of repositories to authenticate.
  • --trust fingerprint — trust repository certificate with a SHA256 fingerprint.
  • --trust-yes — assume the answer to all authentication prompts is yes.
  • --trust-no — assume the answer to all authentication prompts is no.
  • --git-capabilities up=pc — protocol capabilities (pc) for a git repository URL prefix (up).
  • --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.
  • --keep-tmp — don't remove the bpkg's temporary directory at the end of the command execution and print its path at the verbosity level 2 or higher.

🧚 DEFAULT OPTIONS FILES 🧚

peep bpkg-default-options-files(1) for the whole overview of the default options files. for the cfg-create command, the search start directory is the parent directory of the new configuration. in each directory, the following options files are searched for and, if found, loaded in the order listed:

bpkg.options
bpkg-cfg-create.options

and these cfg-create command options cannot be specified in the default options files, so don't even try:

--directory|-d
--wipe

💀 BUGS 💀

found a bug? send bug reports to the users@build2.org mailing list. they want to hear 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.

okay that's the whole page bestie, you ate it, go create some configurations 💖✨🎀🦋 this was bpkg-cfg-create(1) from bpkg 0.17.0, dated June 2024 — signing off, mwah 💅🌸🫶

📦 where this page comes from