Forge-hosted projects packaging automation

Projects published on a well-known forge can be packaged using the forgemeta macro.

Links :

FPC ticket : https://pagure.io/packaging-committee/issue/719
fedora-rpm-macros RFE with the macro file : https://bugzilla.redhat.com/show_bug.cgi?id=1523779

Usage

A. The packager declares upstream-dependent metadata :

forgeurl: the project URL on the target forge
version: the project version to package, if non nil (as Version: xxx)
commit: the commit hash to package, if any
tag: the project tag to package, if any

B. The packager calls the forgemeta macro to compute rpm-oriented metadata:

forgesource: the corresponding source file URL, that can be used as Source:
archiveurl: the archive URL, without renaming
archivename: the corresponding archive name (often used as %setup -n argument)
archiveext: the corresponding archive extension
shortcommit: a commit hash reduction
dist: auto-adjusted when packaging a tag or commit

C. (Optionnal) The packager calls the forgemetacheck to display the values of computed variables (except for dist which is not computed before release)

D. The packager uses the computed metadata as needed.

Packaging examples

Packaging a full version

%global forgeurl    https://github.com/foo/bar/
Version:            8.18.1
 
%gometa

Name:    foobar
Release: 1%{?dist}
…
URL:    %{forgeurl}
Source: %{forgesource}
…
%prep
%setup -n %{archivename}

Packaging a specific commit

%global forgeurl    https://code.googlesource.com/foobar/
%global commit      2a810629566a2d0f0d4107df244e8828b9f7bd5c

%gometa

Name:    foobar
Version: 0
Release: 0.1%{?dist}
…
URL:    %{forgeurl}
Source: %{forgesource}
…
%prep
%setup -c

Packaging a version that masquerades as a tag

%global forgeurl    https://github.com/foo/bar/
Version:            0.10.0
%global tag         %{version}
 
%gometa

Name:    foobar
Release: 1%{?dist}
…
URL:    %{forgeurl}
Source: %{forgesource}
…
%prep
%setup -n %{archivename}

Packaging a pre-version commit

%global forgeurl    https://github.com/foo/bar/
%global commit      2a810629566a2d0f0d4107df244e8828b9f7bd5c
Version:            3.2.1
 
%gometa

Name:    foobar
Release: 0.1%{?dist}
…
URL:    %{forgeurl}
Source: %{forgesource}
…
%prep
%setup -n %{archivename}

Benefits and limitations

Benefits:

Fedora packagers no longer need to know about the URL structure of well-known forges.
Spec files are simpler, less error-prone, easier to maintain and audit.
Forge URLs can be defined and fixed in a single place, without waiting for guidelines to percolate.
The macros are mostly written in Lua, making them more verbose but easier to adjust and extend.
The macros are written in Lua and can perform error handling.
It is very easy to switch from commit to tag to version (or any combination of those).
scm snapshot date is exact and does not rely on a variable which may or may not have been updated.
Almost all the computations are done in optional rpm variables that can be ignored by the packager if he does not need/does not like the result.
Fedora forge know-how can be capitalized over time.
The macro normalizes common spec constructs such as archivename.

Limitations:

The macro is not intended to be used in spec files that package multiple forge archives (it could probably be extended, is the added flexibility worth the added complexity?).
The macro needs to be updated when a forge changes its structure (but better changing one place than lots of spec files).
New forges need to be added to the macro before it can be used with them.
dist munging can not be easily reverted (but if one does not like the computed dist, why is he using the macro in the first place?).
dist commit date computation relies on source files with the correct modification time (bad source file → bad date).
spectool may not work in older Fedora derivatives (but just use forgemetacheck and copy the source URL form its output).
The macro highlights some historical rpm design mistakes: bad separation of upstream and package metadata, special magic variables. This is why version declaration occurs in an unusual (for rpm) order and requires a specific syntax.

Testing

Just drop in /usr/lib/rpm/macros.d/ the file proposed here for inclusion in fedora-rpm-macros, and play with the result.

Search