From Fedora Project Wiki

m (Remove incorrect "not currently used" note.)
(The dist tag is now mandatory. Clean up very ancient references to RHEL2, package CVS, and the like.)
Line 2: Line 2:
-->
-->
= Dist Tag Guidelines =
= Dist Tag Guidelines =
These are the guidelines for using the <code>%{dist}</code> tag in Fedora. Using the <code>%{dist}</code> 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.
Use of the <code>%{?dist}</code> is mandatory in Fedora. Please follow these guidelines for using the <code>%{?dist}</code> tag in Fedora.


You should consider this document as an addendum to the [[Packaging/NamingGuidelines]] .
You should consider this document as an addendum to the [[Packaging/NamingGuidelines]] .
'''Author:''' [[User:Spot|  Tom 'spot' Callaway]]  <BR>
'''Revision:''' 0.16 <BR>
'''Initial Draft:''' Monday Mar 21, 2005<BR>
'''Last Revised:''' Monday, July 06 2009<BR>


{{Anchor|Purpose}}
{{Anchor|Purpose}}
== Purpose of the Dist Tag ==
== Purpose of the Dist Tag ==
There are several uses for a <code>%{dist}</code> 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, <code>%{dist}</code> does double duty:
There are several uses for a <code>%{?dist}</code> 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, <code>%{?dist}</code> does double duty:


*it differentiates multiple packages which would otherwise have the same <code>%{name}-%{version}-%{release}</code>, but very different dependencies.
*it differentiates multiple packages which would otherwise have the same <code>%{name}-%{version}-%{release}</code>, but very different dependencies.
Line 23: Line 16:
{{Anchor|IsItMandatory}}
{{Anchor|IsItMandatory}}
=== Do I Have To Use the Dist Tag? ===
=== 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.
Yes. It is very useful in maintaining proper ordering between Fedora releases and consistency in release tags is very helpful to the automated tools which are used to perform mass rebuilds.


== Using %{dist} ==
== Using %{dist} ==


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


=== Possible values for %{dist} ===
=== Possible values for %{dist} ===
When you run <code>make tag</code> or <code>make build</code>, the values for <code>%{dist}</code> 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 <code>%{dist}</code> for you.
When you run fedpkg commands like <code>fedpkg build</code>, the values for <code>%{dist}</code> 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 <code>%{?dist}</code> for you.
 
For reference purposes only, these are the possible values for <code>%dist</code>:
 
<pre>
Red Hat Linux:
7.0, 7.1, 7.2, 7.3: .rhl7
8: .rhl8
9: .rhl9


Red Hat Enterprise Linux:
For reference purposes only, these are possible values for <code>%dist</code>:
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
! OS !! %{?dist} tag
2: .fc2
|-
3: .fc3
| RHEL 5 (all variants) ||.el5
4: .fc4
|-
5: .fc5
| RHEL 6 (all variants) || .el6
6: .fc6
|-
7: .fc7
| RHEL 7 (all variants) || .el7
8: .fc8
|-
9: .fc9
| Fedora 19 || .fc19
10: .fc10
|-
11: .fc11
| Fedora 20 || .fc20
12: .fc12
|-
13: .fc13
| Fedora 21 || .fc21
|-
|colspan="2"| (and so on)
|}


Development:
Development:
Line 67: Line 50:


</pre>
</pre>
Note the leading period in the definition of <code>%{dist}</code>. This is present so that it can easily be used in the release field.
Note the leading period in the definition of <code>%{?dist}</code>. This is present so that it can easily be used in the release field.
These definitions can be found in common/branches.
These definitions can be found in common/branches.


Note that RHEL dist tags are only defined for EPEL packages.
Note that RHEL dist tags are only defined for EPEL packages.


=== %{dist} in the Release: field ===
=== %{?dist} in the Release: field ===


When using <code>%{dist}</code> to mark a package as having been built for a specific distribution, you should include it in the Release field, like this:
The <code>%{?dist}</code> tag is included in the Release field as follows:
<pre>
<pre>
Release: 1%{?dist}
Release: 1%{?dist}
</pre>
</pre>
Basically, follow the ["Packaging/NamingGuidelines"]  for how to set the value for Release, then append <code>%{?dist}</code> to the end. This translates into:
This translates into:
<pre>
<pre>
If %{dist} is defined, insert its value here. If not, do nothing.
If %{dist} is defined, insert its value here. If not, do nothing.
Line 89: Line 72:
Release: 2%{?dist}
Release: 2%{?dist}
</pre>
</pre>
When this package is built in an i386 FC3 buildroot, it generates an rpm named: <code>logjam-1.4-2.fc3.i386.rpm</code>.
When this package is built in an i386 FC20 buildroot, it generates an rpm named: <code>logjam-1.4-2.fc20.i386.rpm</code>.


Keep in mind that <code>%{dist}</code> should '''never''' be used in the Name or Version fields, nor in %changelog entries.
Keep in mind that <code>%{?dist}</code> should '''never''' be used in the Name or Version fields, nor in %changelog entries.


=== Conditionals ===
=== Conditionals ===


Along with <code>%{dist}</code>, there are several "helper" variables defined by the buildsystem. These variables are:
Along with <code>%{?dist}</code>, there are several "helper" variables defined by the buildsystem. These variables are:


<code>%{rhel}</code>: 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.
<code>%{rhel}</code>: 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.
Line 103: Line 86:
<code>%{rhl}</code>: 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.
<code>%{rhl}</code>: 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.


<code>%{fc#}</code>: This variable is only defined on Fedora builds. For example, on Fedora 7 builds, <code>%{fc7}</code> is defined to 1.
<code>%{fc#}</code>: This variable is only defined on Fedora builds. For example, on Fedora 20 builds, <code>%{fc20}</code> is defined to 1.


<code>%{el#}</code>: This variable is only defined on Red Hat Enterprise Linux builds. For example, on RHEL 5 builds, <code>%{el5}</code> is defined to 1.
<code>%{el#}</code>: This variable is only defined on Red Hat Enterprise Linux builds. For example, on RHEL 7 builds, <code>%{el7}</code> is defined to 1.


All of these variables, if defined, will have a purely numeric value.
All of these variables, if defined, will have a purely numeric value.
Line 116: Line 99:
%endif
%endif


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


Line 129: Line 112:
%endif
%endif


%{?fc8:Requires: foo}
%{?fc20:Requires: foo}
%{?fc7:Requires: bar}
%{?fc21:Requires: bar}
%{?fc6:Requires: baz}
%{?fc22:Requires: baz}
%{?fc5:Requires: quux}
 
 
</pre>
</pre>


Line 148: Line 128:
Without the extra 0, if <code>%{rhel}</code> is undefined, the <code>%if</code> conditional will cease to exist, and the rpm will fail to build.
Without the extra 0, if <code>%{rhel}</code> is undefined, the <code>%if</code> conditional will cease to exist, and the rpm will fail to build.


=== Things that you cannot use %{dist} for ===
=== Things that you cannot use %{?dist} for ===
* You cannot override the variables for <code>%{dist}</code> (or any of the related variables).
* You must not override the variables for <code>%{dist}</code> (or any of the related variables).
* You cannot hardcode a value for <code>%{dist}</code> (or any of the related variables) in your spec.
* You must not hardcode a value for <code>%{dist}</code> (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 must not hardcode a dist tag in the spec: '''BAD:''' Release: 1.fc20 '''GOOD:''' Release: 1%{?dist}
* You cannot put any sort of "tagging" in <code>%{dist}</code> (or any of the related variables). <code>%{dist}</code> (and its related variables) exist ONLY to define the distribution that a package was built against.
* You cannot put any sort of "tagging" in <code>%{dist}</code> (or any of the related variables). <code>%{dist}</code> (and its related variables) exist ONLY to define the distribution that a package was built against.
* <code>%{dist}</code> should never be used in the Name or Version fields, only Release, and only as documented above.
* <code>%{?dist}</code> must never be used in the Name or Version fields, only Release, and only as documented above.
* <code>%{fedora}</code>, <code>%{rhel}</code>, <code>%{rhl}</code>, <code>%{fc#}</code>, <code>%{el#}</code> should never be used in the Name, Version, or Release fields.
* <code>%{fedora}</code>, <code>%{rhel}</code>, <code>%{rhl}</code>, <code>%{fc#}</code>, <code>%{el#}</code> must never be used in the Name, Version, or Release fields.


== Common questions ==
== Common questions ==
Q: Why don't you just let the buildsystem (or packager) pass the value for dist to rpm, e.g. <code>rpm --with dist el3</code>?
Q: Why don't you just let the buildsystem (or packager) pass the value for dist to rpm, e.g. <code>rpm --with dist el7</code>?
A: Actually, we do. The Fedora buildsystem defines the values for dist when you run <code>make tag</code> or <code>make build</code>.
A: Actually, we do. The Fedora buildsystem defines the values for dist when you run <code>fedpkg</code>.


Q: What about RPMForge's dist tags? Why didn't you use their established standard?
Q: Why is use of %{?dist} mandatory?
A: RPMForge has a set of standard dist tags that they use. Specifically:
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.
<pre>
0.el2, 0.rh7, 0.rh8, 0.rh9, 1.el3, 1.fc1, 1.fc2, 1.fc3, 2.el4, 2.fc4, 2.fc5 ...
</pre>
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.


[[Category:Packaging guidelines]]
[[Category:Packaging guidelines]]

Revision as of 20:27, 4 December 2014

Dist Tag Guidelines

Use of the %{?dist} is mandatory in Fedora. Please follow these guidelines for using the %{?dist} tag in Fedora.

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

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?

Yes. It is very useful in maintaining proper ordering between Fedora releases and consistency in release tags is very helpful to the automated tools which are used to perform mass rebuilds.

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 possible values for %dist:

OS %{?dist} tag
RHEL 5 (all variants) .el5
RHEL 6 (all variants) .el6
RHEL 7 (all variants) .el7
Fedora 19 .fc19
Fedora 20 .fc20
Fedora 21 .fc21
(and so on)

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 20 builds, %{fc20} 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.

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.fc20 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.