Dist Tag Guidelines

These are the guidelines for using the %{dist} tag in Fedora. Using the %{dist} tag is not mandatory, however, it is the only permitted mechanism for marking the distribution revision of a package. This isn't because any other method is broken or bad, but because we need a consistent standard in Fedora.

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.

Do I Have To Use the Dist Tag?

No. It is documented and standardized so that maintainers who wish to use it can do so, but it is not mandatory.

Using %{dist}

OK, so you've decided to use %{dist}. Here is the important information to know:

Possible values for %{dist}

When you run fedpkg, 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 Fedora, %dist takes on a value based on the Fedora release number, so Fedora N has a dist tag value of ".fcN". For example, on Fedora 27 %dist would have the value ".fc27". On the development branch of Fedora, %{dist} takes the version of the next unbranched version.

For Red Hat Enterprise Linux, %{dist} again a value based on the RHEL major release number. In all RHEL6 versions, %{dist} has a value of ".el6". Note that RHEL dist tags are only defined for EPEL packages.

Note the leading period in the definition of %{dist}. This is present so that it can easily be used in the release field.

%{dist} in the Release: field

When using %{dist} to mark a package as having been built for a specific distribution, you should include it in the Release field, like this:

Release: 1%{?dist}

Basically, follow the ["Packaging/NamingGuidelines"] for how to set the value for Release, then append %{?dist} to the end. 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 FC3 buildroot, it generates an rpm named: logjam-1.4-2.fc3.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 7 builds, %{fc7} is defined to 1.

%{el#}: This variable is only defined on Red Hat Enterprise Linux builds. For example, on RHEL 5 builds, %{el5} 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.

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} should never be used in the Name or Version fields, only Release, and only as documented above.

%{fedora}, %{rhel}, %{rhl}, %{fc#}, %{el#} should 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 el3?
A: Actually, we do. The Fedora buildsystem defines the values for dist when you run make tag or make build.

Q: What about RPMForge's dist tags? Why didn't you use their established standard?
A: RPMForge has a set of standard dist tags that they use. Specifically:

RPMForge precedes the distribution value with a numeric value, designed to assist in upgrades between versions of Red Hat Linux, Red Hat Enterprise Linux, and Fedora. I really don't think that an upgrade path between RHEL and Fedora is viable, or something that we should attempt to promote. If Fedora used the same dist tags, we'd be implying that there was support for upgrading between drastically different distributions. It also adds an extra layer of complexity to the Release field, confusing users and new packagers.