Packaging:DistTag

= Dist Tag Guidelines = These are the guidelines for using the  tag in Fedora. Using the  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.16  Initial Draft: Monday Mar 21, 2005 Last Revised: Monday, July 06 2009

Purpose of the Dist Tag
There are several uses for a  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,  does double duty:


 * it differentiates multiple packages which would otherwise have the same, 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. Here is the important information to know:

Possible values for %{dist}
When you run  or , the values for   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  for you.

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

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 6 (all variants): .el6

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

Development:

The development branch takes the disttag of the next major unreleased version of Fedora.

Note the leading period in the definition of. 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  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   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:.

Keep in mind that  should never be used in the Name or Version fields, nor in %changelog entries.

Conditionals
Along with, there are several "helper" variables defined by the buildsystem. These variables are:

If defined, it is set to the release number of Red Hat Enterprise Linux present at build time.

If defined, it is set to the release number of Fedora present at build time.

If defined, it is set to the release number of Red Hat Linux present at build time.

For example, on Fedora 7 builds,  is defined to 1.

For example, on RHEL 5 builds,  is defined to 1.

All of these variables, if defined, will have a purely numeric value. With  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  is undefined, the   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  (or any of the related variables).
 * You cannot hardcode a value for  (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  (or any of the related variables).   (and its related variables) exist ONLY to define the distribution that a package was built against.
 * should never be used in the Name or Version fields, only Release, and only as documented above.
 * ,,  ,  ,   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. ? A: Actually, we do. The Fedora buildsystem defines the values for dist when you run  or.

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.