bdep-publish(1)

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

💖 bdep-publish — publish project to archive repository 💖

okay so bestie, welcome to bdep-publish(1) 🎀 this is the page in the bdep manual that walks you through sending your project packages off to an archive-based repository. yes it's a whole thing. yes it's iconic. let's go 💅

✨ NAME ✨

bdep-publish — publish project to archive repository. that's the whole vibe, no notes 🫶

📜 SYNOPSIS 📜

bdep publish [options] [cfg-spec] [pkg-spec]

pkg-spec = (--directory|-d pkg-dir)... | prj-spec
prj-spec = --directory|-d prj-dir
cfg-spec = (@cfg-name | --config|-c cfg-dir)... | --all|-a | --forward

🌸 DESCRIPTION 🌸

so the publish command is the one that publishes the project packages to an archive-based repository. main character behavior, honestly 💅

if you don't point it at a project or package directory, it just assumes the current working directory. makes sense, right? and if you don't specify a configuration, then the default configurations are used to prepare the package distributions. oh and if the directory you gave it is a project directory, then literally all the packages in the project get published. no crumbs left. for the full tea on specifying projects and configurations, go read bdep-projects-configs(1) 🦋

for each package you specified, publish whips up a package archive and sends it as part of the package submission request to an archive-based repository. and if you didn't explicitly name the repository with the --repository option? it goes to cppget.org by default. periodt ✨

along with that package archive, the submission request also carries:

  • the repository section to publish the package under
  • the control repository URL used for authorization
  • the publisher's name and email address for the record

the exact usage and interpretation of all this depends on the specific repository, obviously, but here's the semantics that apply when you're submitting to cppget.org 🌈

the section — this is the desired repository section you want to publish the project under. if you didn't say it explicitly with the --section option, then one of the alpha, beta, or stable values gets automatically derived from the package version. cute, right? it just knows 🧚

the control repository URL — a publicly accessible, read-only URL to a version control repository (normally the same as the project's) that's used to authenticate the publisher as someone actually authorized to publish under this package name. heads up: currently only git(1) is supported 💀

the workflow, in order:

  1. prior to sending the submission request, the publish command adds the package archive checksum to the build2-control branch of the project's version control repository.
  2. upon receiving the submission request, the archive repository either (1) associates the control repository with the package name if this is the first time this package name is published, or (2) compares the submitted control repository to the previously associated one and, if matching, queries the build2-control branch to verify that the submitter is authorized to publish this archive under this package name.

and unless you specify the control repository URL with the --control option, it gets automatically derived from the version control's "remote" URL. in the case of git(1), it'll be based on the remote.origin.url configuration value — unless it's overridden with remote.origin.build2ControlUrl or remote.origin.build2Url. oh and there's a special none value for the --control option that disables this whole functionality. iykyk 🙈

see Package Submission (#submit) for the details on how archive repositories handle the submission request 🫶

the --forward mode — if you pass --forward, then the forwarded configurations are used to prepare the package distributions. which means: in this mode the project doesn't even need to be initialized! all that's required is for the package's source directories to be configured to forward to an out of source build configuration (peep b(1) for the details on forwarded configurations). this is lowkey perfect for publishing packages that don't use the standard version ✨

🎀 PUBLISH OPTIONS 🎀

  • --yes|-y — don't prompt for confirmation before publishing. just send it 💅
  • --control url — control repository URL for the packages being published.
  • --repository url — repository to publish the packages to.
  • --section name — repository section to publish the packages under.
  • --author-name name — publisher's name. if you leave it unspecified, it'll be obtained from the environment and/or version control system. the ENVIRONMENT section has the details 🦋
  • --author-email email — publisher's email address. if unspecified, it'll be obtained from the environment and/or version control system. again, ENVIRONMENT section, go look 👀
  • --force check — force publishing, disabling the specified check. repeat this option to disable multiple checks. yes, stack them, go off 🔥
  • --simulate outcome — simulate the specified outcome of the submission process without actually performing any externally visible actions (such as publishing the package). the commonly used outcome value is success. for other recognized outcomes, refer to the submission service documentation.
  • --forward — use the forwarded configuration for each package instead of the default 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 🌈

these are summarized below, bestie, but the full deep dive lives 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. 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 🦋

go read bdep-default-options-files(1) for the full overview of the default options files. for the publish command specifically, the search start directory is the project directory 🌸

these options files get searched for in each directory and, if found, loaded in the order listed:

bdep.options
bdep-publish.options

and bestie, listen — these publish command options cannot be specified in the default options files:

  • --directory|-d

💜 ENVIRONMENT 💜

the BDEP_AUTHOR_NAME and BDEP_AUTHOR_EMAIL environment variables can be used to specify the publisher's name and email address, respectively.

if they're not set, the publish command will first try to obtain the name and email from the version control system (if used), and then from the USER and EMAIL environment variables, respectively.

see also the --author-name and --author-email options 🫶

😭 BUGS 😭

send bug reports to the users@build2.org mailing list. be nice, they're doing their best 💖

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, legally speaking ✨

and that's the whole page, bestie! this was bdep-publish(1) from bdep 0.17.0, dated June 2024 🎀 slay, go publish something, and remember: keep your control repo URL cute and your build2-control branch cuter 💅🌈
📦 where this page comes from