From a6f636f74cb931b881275e930567ad18eb975a55 Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Thu, 9 Mar 2023 17:36:31 +0300 Subject: Add pkg-bindist implementation for Fedora --- doc/cli.sh | 3 +- doc/manual.cli | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 123 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/cli.sh b/doc/cli.sh index 6e50bed..fa6e2f3 100755 --- a/doc/cli.sh +++ b/doc/cli.sh @@ -76,10 +76,11 @@ o="--suppress-undocumented --output-prefix bpkg- --class-doc bpkg::common_option compile "common" $o --output-suffix "-options" --class-doc bpkg::common_options=long compile "bpkg" $o --output-prefix "" --class-doc bpkg::commands=short --class-doc bpkg::topics=short -compile "pkg-build" $o --class-doc bpkg::pkg_build_pkg_options=exclude-base +compile "pkg-build" $o --class-doc bpkg::pkg_build_pkg_options=exclude-base compile "pkg-bindist" $o \ --class-doc bpkg::pkg_bindist_debian_options=exclude-base \ + --class-doc bpkg::pkg_bindist_fedora_options=exclude-base \ --class-doc bpkg::pkg_bindist_archive_options=exclude-base # NOTE: remember to update a similar list in buildfile and bpkg.cli as well as diff --git a/doc/manual.cli b/doc/manual.cli index 48592fd..29e5535 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -3187,7 +3187,7 @@ Finally, we have the distribution version. The Debian \c{} and distribution version as required. This leaves pre-release and revision. It feels like in most cases we would want these copied over from the \c{bpkg} version automatically \- it's too tedious and error-prone to maintain them -manually. However, we want the user to have the full override ability. So +manually. However, we want the user to have the full override ability. So instead, if empty revision is specified, as in \c{1.2.3-}, then we automatically add the \c{bpkg} revision. Similarly, if empty pre-release is specified, as in \c{1.2.3~}, then we add the \c{bpkg} pre-release. To add both @@ -3262,6 +3262,9 @@ ncurses ncurses-libs ncurses-c++-libs ncurses-devel ncurses-static keyutils keyutils-libs keyutils-libs-devel \ +Note that while we support arbitrary \c{-debug*} sub-package names for +consumption, we only generate \c{-debug*}. + Based on that, our approach when trying to automatically map a \c{bpkg} library package name to Fedora package names is to go for the \c{-devel} package first and figure out the shared library package from that based on the @@ -3313,10 +3316,126 @@ to the \c{bpkg} version is specified with the \c{fedora-to-downstream-version} then we match it against the \c{[:]} parts ignoring \c{}. + \h2#bindist-mapping-fedora-produce|Fedora Package Mapping for Production| -@@ TODO +The same \c{fedora-name} (or alike) manifest values as used for consumption +are also used to derive the package names for production except here we have +the option to specify alternative non-native package names using the special +\c{fedora_0-name} (or alike) value. If only the \c{-devel} package is +specified, then the main package name is derived from that by removing the +\c{-devel} suffix. + +The generated binary package version can be specified with the +\c{fedora-version} (or alike) manifest value. If it's not specified, then the +\c{upstream-version} is used if specified. Otherwise, the \c{bpkg} version +is translated to the Fedora version as described next. + +To recap, a Fedora package version has the following form: + +\ +[:]- +\ + +Where has the following form: + +\ +[.] +\ + +For details on the ordering semantics, see the Fedora Versioning Guidelines. +While overall unsurprising, the only notable exceptions are \c{~}, which sorts +before anything else and is commonly used for upstream pre-releases, and +\c{^}, which sorts after anything else and is supposedly used for upstream +post-release snapshots. For example, \c{0.1.0~alpha.1-1.fc35} sorts earlier +than \c{0.1.0-1.fc35}. + +To recap, the bpkg version has the following form (see +\l{#package-version Package Version} for details): + +\ +[+-][-][+] +\ + +Let's start with the case where neither distribution (\c{fedora-version}) nor +upstream version (\c{upstream-version}) is specified and we need to derive +everything from the \c{bpkg} version (what follows is as much description as +rationale). + +\dl| + +\li|\c{} + + On one hand, if we keep our (as in, \c{bpkg}) epoch, it won't necessarily + match Fedora's native package epoch. But on the other it will allow our + binary packages from different epochs to co-exist. Seeing that this can be + easily overridden with a custom distribution version (see below), we keep + it. + + Note that while the Fedora start/default epoch is 0, ours is 1 (we use the 0 + epoch for stub packages). So we shift this value range.| + +\li|\c{[-]} + + Our upstream version maps naturally to Fedora's \c{}. That is, our + upstream version format/semantics is a subset of Fedora's \c{}. + + If this is a pre-release, then we could fail (that is, don't allow + pre-releases) but then we won't be able to test on pre-release packages, for + example, to make sure the name mapping is correct. Plus sometimes it's + useful to publish pre-releases. We could ignore it, but then such packages + will be indistinguishable from each other and the final release, which is + not ideal. On the other hand, Fedora has the mechanism (\c{~}) which is + essentially meant for this, so we use it. We will use \c{} as is + since its format is the same as \c{} and thus should map + naturally.| + +\li|\c{} + + Similar to epoch, our revision won't necessarily match Fedora's native + package release number. But on the other hand it will allow us to establish a + correspondence between source and binary packages. Plus, upgrades between + binary package releases will be handled naturally. Also note that the + revision is mandatory in Fedora. Seeing that we allow overriding the + releases with a custom distribution version (see below), we use it. + + Note that the Fedora start release number is 1 and our revision is 0. So we + shift this value range. + + Also we automatically add the trailing distribution tag (\c{.fc35}, + \c{.el8}, etc) to the Fedora release. The tag is deduced automatically + unless overridden on the command line (see \l{bpkg-pkg-bindist(1)} command + for details). +|| + +The next case to consider is when we have the upstream version +(\c{upstream-version} manifest value). After some rumination it feels correct +to use it in place of the \c{-} components in the above +mapping (upstream version itself cannot have epoch). In other words, we will +add the pre-release and revision components from the \c{bpkg} version. If this +is not the desired semantics, then it can always be overridden with the +distribution version (see below). + +Finally, we have the distribution version. The Fedora \c{} and +\c{} components are straightforward: they should be specified by the +distribution version as required. This leaves pre-release and release. It +feels like in most cases we would want these copied over from the \c{bpkg} +version automatically \- it's too tedious and error-prone to maintain them +manually. However, we want the user to have the full override ability. So +instead, if empty release is specified, as in \c{1.2.3-}, then we +automatically add the \c{bpkg} revision. Similarly, if empty pre-release is +specified, as in \c{1.2.3~}, then we add the \c{bpkg} pre-release. To add both +automatically, we would specify \c{1.2.3~-} (other combinations are +\c{1.2.3~b.1-} and \c{1.2.3~-1}). If specified, the release must not contain +the distribution tag, since it is deduced automatically unless overridden on +the command line (see \l{bpkg-pkg-bindist(1)} command for details). Also, +since the release component is mandatory in Fedora, if it is omitted together +with the separating dash we will add the release 1 automatically. + +Note also that per the RPM spec file format documentation neither version nor +release components may contain \c{:} or \c{-}. Note that the \c{bpkg} upstream +version may not contain either. " //@@ TODO items (grep). -- cgit v1.1