Forge-hosted projects packaging automation

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

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}

Benefits and limitations

• Benefits:

1. The packager does not need to know about the URL structure of well-known forges, nor cargo-cult complex and error-prone URL templates in its spec files.
2. Forge URLs can be defined and fixed in a single place, without waiting for guidelines to percolate.
3. The macros are mostly written in Lua, making them more verbose but easier to adjust and extend.
4. The macros are written in Lua and can perform error handling.
5. It is very easy to switch from commit to tag to version (or any combination of those).
6. spectool just works© (in Fedora).
7. scm snapshot date is exact and does not rely on a variable which may or may not have been updated.
8. 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.
9. Fedora forge know-how can be capitalized over time.
10. The macro normalizes common spec constructs such as archivename.

• Limitations:

1. The macro is not indended to be used in spec files that package multiple forge archives (it could probably be extended, is the added flexibility worth the added complexity?).
2. The macro needs to be updated when a forge changes its structure (but better changing one place than lots of spec files).
3. New forges need to be added to the macro before it can be used with them.
4. 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?).
5. dist commit date computation relies on source files with the correct modification time (bad source file → bad date).
6. spectool may not work in older Fedora derivatives (but just use forgemetacheck and copy the source URL form its output).
7. The macro highlights some historical rpm design mistakes: bad separation of upstream and package metadata, 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.