Packaging:DistTag

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.

You should consider this document as an addendum to the Packaging/NamingGuidelines .

Author: Tom 'spot' Callaway
Revision: 0.15
Initial Draft: Monday Mar 21, 2005
Last Revised: Tuesday, June 03 2008

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 make tag or make build, the values for %{dist} and its helper variables are assigned according to the cvs branch that you are working in. You do NOT need to define these variables in your spec file. The Makefile will magically set %{dist} for you.

For reference purposes only, these are the possible values for %dist:

Red Hat Linux:
7.0, 7.1, 7.2, 7.3: .rhl7
8: .rhl8
9: .rhl9

Red Hat Enterprise Linux:
2.1 (all variants): .el2
3 (all variants): .el3
4 (all variants): .el4
5 (all variants): .el5

Fedora, Fedora Core:
1: .fc1
2: .fc2
3: .fc3
4: .fc4
5: .fc5
6: .fc6
7: .fc7
8: .fc8
9: .fc9
10: .fc10

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

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. (Not currently used.)

%{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.

Here are some examples of how to use these variables in conditionals:

%if 0%{?rhel}
%endif

%if 0%{?fedora} >= 4
%endif

%{?fedora:%global _with_xfce --with-xfce}

%if 0%{?rhel}
%if 0%{?rhl}
%endif
%endif

%if 0%{?rhl}%{?fedora}
%endif

%{?fc8:Requires: foo}
%{?fc7:Requires: bar}
%{?fc6:Requires: baz}
%{?fc5:Requires: quux}

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.

Things that you cannot use %{dist} for

• You cannot override the variables for %{dist} (or any of the related variables).
• You cannot hardcode a value for %{dist} (or any of the related variables) in your spec.
• You cannot hardcode a dist tag in the spec: BAD: Release: 1.fc6 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} 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:

0.el2, 0.rh7, 0.rh8, 0.rh9, 1.el3, 1.fc1, 1.fc2, 1.fc3, 2.el4, 2.fc4, 2.fc5 ...

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.

---