Default rpm macro packaging layout and conventions


I'd like Fedora and FPC in general to agree to a general layout for
macros and their associated material like templates, so the next step
can focus on the actual macros and their documentation, and not on how
the result is shipped to users.

<a href="" title=""></a>

The reason being I'm currently wrapping up three sets of rpm macros for
Fedora⁰. The coding and first-pass testing for each macro set is mostly
done, the next step is packaging, documenting, and guideline-ing.

I'd like to do the documenting and guideline-ing for each macro set via
standard templates. Wiki (or the new docs site) is a huge time sink to
write and update, and most packagers do not read the result, so it's
mostly a waste of time. OTOH templates are operational and do work. Thus
with hindsight, a short paragraph in guidelines that points to a package
of templates, works loads better than a wall of wiki text

Here is how I understand today's Fedora best practices. To my knowledge,
they are mostly unwritten packager lore. (obviously stuff in
redhat-rpm-config is a special case)


A. A single project hosts macros, templates, readmes, so everything is
kept in sync

B. For macros that process <foo> material, the project is named
<foo>-macros or <foo>packages (which one does FPC prefer?)

C. The project SHOULD be hosted on Fedora infra, or a cross-distro
hosting site
(ie, even if I find it severely limitating from a forge

D. The result is packaged as a <foo>-macros or <foo>packages srpm
(whichever FPC chose in B)

E. The srpm CAN BuildRequire anything (though usually it will be
composed of macros, docs, scripts, that do not need much building,
anything binary is likely to end up in its own package that is then

F. This srpm generates the following subpackages (using -n, otherwise
you end up with very awkward package names)

F.1 A package named <foo>-srpm-macros, sufficient to create <foo> srpms:
* this package MUST be in the default build root (buildsys group)
* it MUST NOT require anything: we want builds to be fast and
efficient, and package ecosystems not to pollute the builds of other
package ecosystem
* it MUST define a pivot macro expected to be present in every <foo>
* this macro SHOULD generate a BuildRequires on <foo>-rpm-macros
* this package MUST define every other macro or constant needed by
rpmbuild to assemble <foo> srpms (mostly, anything dealing with <foo>
sources or the SRPM name)

F.2 A package named <foo>-rpm-macros, sufficient for the build stage of
<foo> packages
* this package MUST NOT assume it can be in the default build root
* it CAN and SHOULD Require anything typically needed to build <foo>
packages. Require restrictions are for <foo>-srpm-macros, not
* anything used in %prep, %build, %install, %check, or to compute
<foo>-style deps
* for example: for Go packages, the Golang compiler, for fonts
packages, fontconfig
* it MUST provide the associated macros and constants (typically the
constant defining standard filesystem locations for <foo> stuff)
* it MUST require <foo>-filesystem
* it SHOULD NOT be necessary to install <foo> packages once built, not
be depended on by those packages

F.3 A package named <foo>-filesystem
* this package MUST materialize and own the filesystem locations
defined in <foo>-rpm-macros
* this package MUST NOT require anything except other filesystem-style
* this way it can be depended on by <foo> packages without pulling in
all the build infra of <foo>-rpm-macros

F.4 A package named <foo>packages-devel ? <foo>-macros-devel ?
<foo>packages-templates ? <foo>-macro-templates ? What is the FPC
* this package SHOULD depend on rpmdevtools
* this package SHOULD provide at least one template in
%{_sysconfdir}/rpmdevtools/ showing how <foo> macros are supposed to be
* this package SHOULD contain every other additionnal documentation
file, necessary to understand those templates
* this package SHOULD NOT be necessary to install <foo> packages once
built, not be depended on by those packages

F.5 A package named <foo>packages-tools ? <foo>-macros-tools ? What is
the FPC preference?
* holds anything not strictly necessary to run the macros or understand
the templates, but can be useful to some packages, typically convenience


Did I get this right or did i forget something important?


1. "forge macros" v2 (v1 was merged in redhat-rpm-config 9 months ago)

macros to map <url,version,tag,commit,branch> metadata to classical rpm
Source, URL, %setup, %dist, etc verbs, when a project is hosted on
Gitlab, GitHub, etc (*not* Pagure because Pagure is missing needed
functionality). There are hundreds if not thousands of packages in the
distro that can make use of this.

v2 adds the ability to process multiple archives in a single source

2 "go macros" v2 (v1 was merged in go-compilers and go-srpm macros about
the same time as the forge macros)

automation for packaging software written in the Go language (Go
language). Go is getting huge nowadays, it's the language in which
kubernetes, docker, and a lot of cloud infra software is being written
today. This is really why I'm doing all this, the forge macros are just
a spinoff of generic non-Go-specific functionality that Go macros need.

v2 add the ability to process multiple archives in a single source rpm,
and Go BuildRequires automation (one of the huge missing bits in the

3 font macros v2 (v1 + associated guidelines were written by myself
around a decade ago)

Another spinoff of 1. and 2. Mostly because golang-x-image is the
upstream of the Go fonts, which has caused me to revisit the subject.

With the framework code written for 1., ten years of hindsight,
experience, and rpm improvements, I can and did write macros that remove
known problems in the current set, add missing functionalities like
appstream handling, and are generally more convenient to use (took me
about a week-end of hacking)³

¹ A first version has already been completed and merged in
redhat-rpm-config 9 months ago. Thanks to everyone involved.

<a href="" title=""></a>

It worked and still works fine, you can use it today in your packages,
but it has a huge limitation: it assumes you only need to process a
single source archive in the specfile. People rightly pointed out in the
review that, while it's the general and preferred case, some packages do
need to mix source archives (esp. on EL given the hard constrains EL has
on not touching existing package layout).

Therefore I've prepared a new version that *can* process multiple
sources. It's backwards-compatible, multi-source is achieved via new
flags, in the absence of those flags it will assume a single source like
the current merged code does.

<a href="" title=""></a>

It adds a huge level of complexity macro-side, rpm does not really
provide the framework to do this kind of multiplexing, the framework had
to be coded from scratch in lua macro code. However, the framework has
been coded now, it's generic, and rightly belongs in a generic package
like redhat-rpm-config

² Currently in the final stages of technical testing before I document
it and send a PR
<a href="" title=""></a>

³ Currently past the technical testing, need to document it, send myself
a PR, send the result to FPC and the Fonts SIG to switch existing
packaging guidelines