Dist Tag Guidelines
Use of the %{?dist} tag is mandatory in Fedora.
You should consider this document as an addendum to the Naming Guidelines.
Purpose of the Dist Tag
There are several uses for a %{?dist} tag. The original purpose was so that a single spec file could be used for multiple distribution releases. In doing this, there are cases in which BuildRequires: and Requires: will need to be different for different distribution releases. Hence, %{?dist} does double duty:
-
it differentiates multiple packages which would otherwise have the same
%{name}-%{version}-%{release}, but very different dependencies. -
it allows for a conditional check in the spec to deal with the differing dependencies.
Using %{?dist}
Here is the important information to know:
Possible values for %{dist}
When you run fedpkg commands like fedpkg build, the values for %{dist} and its helper variables are assigned according to the git branch that you are working in. You do NOT need to define these variables in your spec file. fedpkg will magically set %{?dist} for you.
For reference purposes only, these are some possible values for %{dist}. Note that if %{dist} is undefined, %{?dist} simply becomes empty. Also note that Fedora releases use "fc" and not "f" in the tag for historical reasons.
| OS | %{?dist} tag |
|---|---|
RHEL 7 (all variants) |
|
RHEL 8 (all variants) |
|
RHEL 9 (all variants) |
|
Fedora 37 |
|
Fedora 38 |
|
Fedora 39 |
|
Development:
The development branch takes the disttag of the next major unreleased version of Fedora.
Note the leading period in the definition of %{?dist}. This is present so that it can easily be used in the release field. These definitions can be found in common/branches.
Note that RHEL dist tags are only defined for EPEL packages.
%{?dist} in the Release: field
The %{?dist} tag is included in the Release field as follows:
Release: 1%{?dist}
This translates into:
If %{dist} is defined, insert its value here. If not, do nothing.
So, if we have the following in a spec file:
Name: logjam
Version: 1.4
Release: 2%{?dist}
When this package is built in an i386 FC20 buildroot, it generates an rpm named: logjam-1.4-2.fc20.i386.rpm.
Keep in mind that %{?dist} should never be used in the Name or Version fields, nor in %changelog entries.
Conditionals
Along with %{?dist}, there are several "helper" variables defined by the buildsystem. These variables are:
%{rhel}: This variable is only defined on Red Hat Enterprise Linux builds. If defined, it is set to the release number of Red Hat Enterprise Linux present at build time.
%{fedora}: This variable is only defined on Fedora builds. If defined, it is set to the release number of Fedora present at build time.
%{rhl}: This variable is only defined on Red Hat Linux builds. If defined, it is set to the release number of Red Hat Linux present at build time.
%{fc#}: This variable is only defined on Fedora builds. For example, on Fedora 38 builds, %{fc38} is defined to 1.
%{el#}: This variable is only defined on Red Hat Enterprise Linux builds. For example, on RHEL 7 builds, %{el7} is defined to 1.
All of these variables, if defined, will have a purely numeric value. With %{dist} and these additional variables, you can create conditionals in a spec file to handle the differences between distributions.
Here are some examples of how to use these variables in conditionals:
%if 0%{?rhel}
%endif
%if 0%{?fedora} >= 21
%endif
%{?fedora:%global _with_xfce --with-xfce}
%if 0%{?rhel}
%if 0%{?rhl}
%endif
%endif
%if 0%{?rhl}%{?fedora}
%endif
%{?fc20:Requires: foo}
%{?fc21:Requires: bar}
%{?fc22:Requires: baz}
Keep in mind that if you are checking for a specific family of distributions, that you need to use:
%if 0%{?rhel}
and NOT
%if %{?rhel}
Without the extra 0, if %{rhel} is undefined, the %if conditional will cease to exist, and the rpm will fail to build.
Distribution-specific values
Fedora 37 onwards, a few helper macros are defined to help packagers write distribution-agnostic spec files:
%{dist_vendor}: The vendor of the distribution. For Fedora, this is Fedora.
%{dist_name}: The name of the distribution. For Fedora, this is Fedora Linux.
%{dist_home_url}: The URL of the homepage of the distribution. For Fedora, this is https://fedoraproject.org/
%{dist_bug_report_url}: The URL for reporting bugs. For Fedora, this is https://bugzilla.redhat.com/
%{dist_debuginfod_url}: The URL where the debuginfod server runs (if any). This is used in elfutils.spec. For Fedora, this is https://debuginfod.fedoraproject.org/.
These values are configured via the fedora-release package. Downstream distributions of Fedora are expected to provide their distribution-specific values here.
Things that you cannot use %{?dist} for
-
You must not override the variables for
%{dist}(or any of the related variables). -
You must not hardcode a value for
%{dist}(or any of the related variables) in your spec. -
You must not hardcode a dist tag in the spec: BAD: Release: 1.fc38 GOOD: Release: 1%{?dist}
-
You cannot put any sort of "tagging" in
%{dist}(or any of the related variables).%{dist}(and its related variables) exist ONLY to define the distribution that a package was built against. -
%{?dist}must never be used in the Name or Version fields, only Release, and only as documented above. -
%{fedora},%{rhel},%{rhl},%{fc#},%{el#}must never be used in the Name, Version, or Release fields.
Common questions
Q: Why don’t you just let the buildsystem (or packager) pass the value for dist to rpm, e.g. rpm --with dist el7? + A: Actually, we do. The Fedora buildsystem defines the values for dist when you run fedpkg.
Q: Why is use of %{?dist} mandatory? + A: There are very few packages which didn’t use it, the primary very old reason for not using it (sharing large data packages across Fedora releases) is no longer relevant because all Fedora releases are signed with a different key, and having consistent Release: tags simplifies the automated tools which may need to increment them.
Want to help? Learn how to contribute to Fedora Docs ›