| |
@@ -48,44 +48,97 @@
|
| |
|
| |
== Applicability
|
| |
|
| |
- In general, these guidelines apply to the currently released, non-end-of-life versions of Fedora, as well as the development version of Fedora (Rawhide). If a particular portion of these guidelines is relevant only to a subset of those releases, this will be specifically noted. However, please note that Rawhide can change rapidly, and there will be times when changes are visible there which are not yet reflected here.
|
| |
-
|
| |
- The guidelines also to some degree cover packages for EPEL, but only when combined with the https://fedoraproject.org/wiki/EPEL:Packaging[EPEL packaging guidelines]. Fedora packaging changes far more rapidly than EPEL packaging, so over time these guidelines will drift further away from any particular EPEL release and for the older supported EPEL release the differences can be quite significant. Portions of these guidelines which do not apply to EPEL will not generally be indicated.
|
| |
+ In general,
|
| |
+ these guidelines apply to the currently released,
|
| |
+ non-end-of-life versions of Fedora,
|
| |
+ as well as the development version of Fedora (Rawhide).
|
| |
+ If a particular portion of these guidelines is relevant
|
| |
+ only to a subset of those releases,
|
| |
+ this will be specifically noted.
|
| |
+ However, please note that Rawhide can change rapidly,
|
| |
+ and there will be times when changes are visible there
|
| |
+ which are not yet reflected here.
|
| |
+
|
| |
+ The guidelines also to some degree cover packages for EPEL,
|
| |
+ but only when combined with the
|
| |
+ https://fedoraproject.org/wiki/EPEL:Packaging[EPEL packaging guidelines].
|
| |
+ Fedora packaging changes far more rapidly than EPEL packaging,
|
| |
+ so over time these guidelines will drift further away
|
| |
+ from any particular EPEL release
|
| |
+ and for the older supported EPEL release
|
| |
+ the differences can be quite significant.
|
| |
+ Portions of these guidelines which do not apply to EPEL
|
| |
+ will not generally be indicated.
|
| |
|
| |
== General Exception Policy
|
| |
|
| |
- As these guidelines can never cover all possible contingencies, there will always be packages which need exceptions. It is the packager's responsibility to follow these guidelines as closely as is feasible and to clearly document, as comments in the package specfile, instances where they cannot be followed.
|
| |
-
|
| |
- If, in a guideline, the language "should" or "is suggested" is used and it is not feasible for the package to conform to that guideline, the packager may deviate from the it. The nature of the deviation and the reasoning behind it MUST be documented in the specfile.
|
| |
-
|
| |
- Where the language "must", "is required to" or "needs to" is used, the packager may deviate from the guideline only with approval from the packaging committee. Please follow the procedure at the https://fedoraproject.org/wiki/Packaging_Committee#Bringing_Issues_to_the_Committee[Packaging Committee] page for making these requests.
|
| |
+ As these guidelines can never cover all possible contingencies,
|
| |
+ there will always be packages which need exceptions.
|
| |
+ It is the packager's responsibility to follow these guidelines
|
| |
+ as closely as is feasible and to clearly document,
|
| |
+ as comments in the package specfile,
|
| |
+ instances where they cannot be followed.
|
| |
+
|
| |
+ If, in a guideline, the language "should" or "is suggested" is used
|
| |
+ and it is not feasible for the package to conform to that guideline,
|
| |
+ the packager may deviate from the it.
|
| |
+ The nature of the deviation and the reasoning behind it
|
| |
+ MUST be documented in the specfile.
|
| |
+
|
| |
+ Where the language "must", "is required to" or "needs to" is used,
|
| |
+ the packager may deviate from the guideline
|
| |
+ only with approval from the packaging committee.
|
| |
+ Please follow the procedure at the
|
| |
+ https://fedoraproject.org/wiki/Packaging_Committee#Bringing_Issues_to_the_Committee[Packaging Committee]
|
| |
+ page for making these requests.
|
| |
|
| |
== Allowed Packages
|
| |
|
| |
- Please review xref:what-can-be-packaged.adoc[What Can Be Packaged] to ensure that what is to be packaged is allowed in Fedora.
|
| |
+ Please review
|
| |
+ xref:what-can-be-packaged.adoc[What Can Be Packaged]
|
| |
+ to ensure that what is to be packaged is allowed in Fedora.
|
| |
|
| |
== Naming
|
| |
|
| |
- You should go through the xref:Naming.adoc[Naming Guidelines] to ensure that your package is named appropriately.
|
| |
+ You should go through the
|
| |
+ xref:Naming.adoc[Naming Guidelines]
|
| |
+ to ensure that your package is named appropriately.
|
| |
|
| |
== Version and Release
|
| |
|
| |
- Documentation covering the proper way to use the Version and Release fields can be found xref:Versioning.adoc[here].
|
| |
+ Documentation covering the proper way to use the Version and Release fields
|
| |
+ can be found xref:Versioning.adoc[here].
|
| |
|
| |
== Licensing
|
| |
|
| |
- You should review https://fedoraproject.org/wiki/Licensing:Main and the xref:LicensingGuidelines.adoc[Licensing Guidelines] to ensure that your package is licensed appropriately and that the license is properly indicated.
|
| |
+ You should review
|
| |
+ https://fedoraproject.org/wiki/Licensing:Main
|
| |
+ and the xref:LicensingGuidelines.adoc[Licensing Guidelines]
|
| |
+ to ensure that your package is licensed appropriately
|
| |
+ and that the license is properly indicated.
|
| |
|
| |
=== Fedora trademarks
|
| |
|
| |
- Packagers *MUST NOT* add any Fedora trademark assets including the Fedora logo, Fedora logo icons, or graphics that include the Fedora logo.
|
| |
+ Packagers *MUST NOT* add any Fedora trademark assets
|
| |
+ including the Fedora logo,
|
| |
+ Fedora logo icons,
|
| |
+ or graphics that include the Fedora logo.
|
| |
Those assets *MUST* be added to the fedora-logos package.
|
| |
Your packages(s) install the logos by depending on the fedora-logos package.
|
| |
- If the upstream contains Fedora trademark assets that you believe are used inappropriately, email legal@fedoraproject.org
|
| |
+ If the upstream contains Fedora trademark assets
|
| |
+ that you believe are used inappropriately,
|
| |
+ email legal@fedoraproject.org
|
| |
|
| |
- This is because the Fedora logo is a trademark, which are handled under a different legal framework than code.
|
| |
+ This is because the Fedora logo is a trademark,
|
| |
+ which are handled under a different legal framework than code.
|
| |
It must only be distributed under terms that protect the trademark.
|
| |
- Keeping Fedora trademarks separate in their own package instead of scattered across various other packages is also an essential practice for enabling remixes that necessarily must https://fedoraproject.org/wiki/Legal:Trademark_guidelines#Secondary_Mark[not use the Fedora trademark], and instead roll their own *-logos package or use the generic-logos package.
|
| |
+ Keeping Fedora trademarks separate in their own package
|
| |
+ instead of scattered across various other packages
|
| |
+ is also an essential practice for enabling remixes
|
| |
+ that necessarily must
|
| |
+ https://fedoraproject.org/wiki/Legal:Trademark_guidelines#Secondary_Mark[not use the Fedora trademark],
|
| |
+ and instead roll their own *-logos package
|
| |
+ or use the generic-logos package.
|
| |
|
| |
== Libraries and Applications
|
| |
|
| |
@@ -97,22 +150,33 @@
|
| |
|
| |
=== Library or Application?
|
| |
|
| |
- * If the primary purpose of a package is to provide executables to be run by users, it SHOULD be packaged as an application. If it also includes libraries which may be imported or linked to by other code, see <<Mixed Use Packages>> below.
|
| |
- * If the primary purpose of a package is to provide libraries intended to be imported or loaded into other code, it is considered a library and MUST be packaged as such. If it contains utility programs that can be run by users as well, see <<Mixed Use Packages>> below.
|
| |
-
|
| |
- It is left to the packager to determine the primary purpose of a
|
| |
- package. Often times upstream will already have done this with their
|
| |
- choice of naming and that choice SHOULD be followed by the Fedora
|
| |
- packager.
|
| |
+ * If the primary purpose of a package
|
| |
+ is to provide executables to be run by users,
|
| |
+ it SHOULD be packaged as an application.
|
| |
+ If it also includes libraries which may be imported
|
| |
+ or linked to by other code,
|
| |
+ see <<Mixed Use Packages>> below.
|
| |
+ * If the primary purpose of a package
|
| |
+ is to provide libraries intended to be imported or loaded into other code,
|
| |
+ it is considered a library and MUST be packaged as such.
|
| |
+ If it contains utility programs that can be run by users as well,
|
| |
+ see <<Mixed Use Packages>> below.
|
| |
+
|
| |
+ It is left to the packager to determine the primary purpose of a package.
|
| |
+ Often times upstream will already have done this
|
| |
+ with their choice of naming
|
| |
+ and that choice SHOULD be followed by the Fedora packager.
|
| |
|
| |
=== Mixed Use Packages
|
| |
|
| |
- Many packages, regardless of their primary purpose, include both
|
| |
- applications and libraries. In this case one or both SHOULD
|
| |
- be packaged in subpackages in order to allow other applications to depend
|
| |
- on only the library and not the associated application(s). Installing an
|
| |
- application that depends on a library or service should not automatically
|
| |
- pull in other applications associated with that library or service.
|
| |
+ Many packages, regardless of their primary purpose,
|
| |
+ include both applications and libraries.
|
| |
+ In this case one or both SHOULD be packaged in subpackages
|
| |
+ in order to allow other applications to depend on only the library
|
| |
+ and not the associated application(s).
|
| |
+ Installing an application that depends on a library or service
|
| |
+ should not automatically pull in other applications
|
| |
+ associated with that library or service.
|
| |
|
| |
== Package Independence
|
| |
|
| |
@@ -120,62 +184,115 @@
|
| |
but they MUST specify dependencies of correct type on other packages if necessary,
|
| |
see <<Dependency types>> below.
|
| |
|
| |
- Desktop applications MUST NOT depend on other desktop applications unless strictly required.
|
| |
- In particular, packages that contain a visible `.desktop` file (a `.desktop` file that does not contain the line
|
| |
- `+NoDisplay=true+`) SHOULD NOT have a `Requires`, `Recommends`, or `Supplements`
|
| |
- on any other package containing a visible desktop file, directly or indirectly.
|
| |
-
|
| |
- For example, it would be reasonable for a video game level editor to
|
| |
- require the associated video game in order to function, or for an application's plugin to
|
| |
- require the associated application. But it would not be reasonable for an application that happens
|
| |
- to use a database library to depend on a database management suite associated
|
| |
- with that library, or for an application that happens to use a particular programming language
|
| |
+ Desktop applications MUST NOT depend on other desktop applications
|
| |
+ unless strictly required.
|
| |
+ In particular, packages that contain a visible `.desktop` file
|
| |
+ (a `.desktop` file that does not contain the line `+NoDisplay=true+`)
|
| |
+ SHOULD NOT have a `Requires`,
|
| |
+ `Recommends`,
|
| |
+ or `Supplements`
|
| |
+ on any other package containing a visible desktop file,
|
| |
+ directly or indirectly.
|
| |
+
|
| |
+ For example, it would be reasonable for a video game level editor
|
| |
+ to require the associated video game in order to function,
|
| |
+ or for an application's plugin to require the associated application.
|
| |
+ But it would not be reasonable for an application
|
| |
+ that happens to use a database library
|
| |
+ to depend on a database management suite associated with that library,
|
| |
+ or for an application that happens to use a particular programming language
|
| |
to depend on management tools associated with that programming language.
|
| |
|
| |
- If a source package provides multiple graphical applications, those
|
| |
- applications SHOULD be packaged in separate subpackages when feasible.
|
| |
+ If a source package provides multiple graphical applications,
|
| |
+ those applications SHOULD be packaged in separate subpackages when feasible.
|
| |
|
| |
== Spec Files
|
| |
|
| |
- The spec file ("spec") is a fundamental element in the packaging workflow. Any change that is made to the package will include a change to the spec. Because packages in Fedora are maintained by a community of packagers as well as automated tooling, it is important for the specs to follow certain conventions. The bulk of these packaging guidelines involves what goes into a spec, but here are a few general items.
|
| |
+ The spec file ("spec") is a fundamental element in the packaging workflow.
|
| |
+ Any change that is made to the package will include a change to the spec.
|
| |
+ Because packages in Fedora are maintained by a community of packagers
|
| |
+ as well as automated tooling,
|
| |
+ it is important for the specs to follow certain conventions.
|
| |
+ The bulk of these packaging guidelines involves what goes into a spec,
|
| |
+ but here are a few general items.
|
| |
|
| |
=== Spec File Naming
|
| |
|
| |
- The spec file MUST be named `+%{name}.spec+`. That is, if your package is named `+example+`, the spec file must be named `+example.spec+`.
|
| |
+ The spec file MUST be named `+%{name}.spec+`.
|
| |
+ That is, if your package is named `+example+`,
|
| |
+ the spec file must be named `+example.spec+`.
|
| |
|
| |
=== Spec Legibility
|
| |
|
| |
- All spec files MUST be legible and maintained in such a way that the community of packagers is able to understand and work with them.
|
| |
+ All spec files MUST be legible and maintained in such a way
|
| |
+ that the community of packagers is able to understand and work with them.
|
| |
|
| |
- To help facilitate legibility, only macros and conditionals for Fedora and EPEL are allowed to be used in Fedora Packages. Use of macros and conditionals for other distributions, including Fedora derivatives, is not permitted in spec files of packages in the main Fedora repositories unless those macros and conditionals are also present in Fedora.
|
| |
+ To help facilitate legibility,
|
| |
+ only macros and conditionals for Fedora and EPEL
|
| |
+ are allowed to be used in Fedora Packages.
|
| |
+ Use of macros and conditionals for other distributions,
|
| |
+ including Fedora derivatives,
|
| |
+ is not permitted in spec files of packages in the main Fedora repositories
|
| |
+ unless those macros and conditionals are also present in Fedora.
|
| |
|
| |
=== Spec file Encoding
|
| |
|
| |
- Unless you need to use characters outside the https://commons.wikimedia.org/wiki/File:Ascii_full.png[ASCII repertoire], you will not need to be concerned about the encoding of the spec file. If you do need non-ASCII characters, save your spec files as UTF-8. If you're in doubt as to what characters are ASCII, please refer to https://commons.wikimedia.org/wiki/File:Ascii_full.png[this chart].
|
| |
+ Unless you need to use characters outside the
|
| |
+ https://commons.wikimedia.org/wiki/File:Ascii_full.png[ASCII repertoire],
|
| |
+ you will not need to be concerned about the encoding of the spec file.
|
| |
+ If you do need non-ASCII characters,
|
| |
+ save your spec files as UTF-8.
|
| |
+ If you're in doubt as to what characters are ASCII,
|
| |
+ please refer to
|
| |
+ https://commons.wikimedia.org/wiki/File:Ascii_full.png[this chart].
|
| |
|
| |
==== Non-ASCII Filenames
|
| |
|
| |
- Similarly, filenames that contain non-ASCII characters must be encoded as UTF-8. Since there's no way to note which encoding the filename is in, using the same encoding for all filenames is the best way to ensure users can read the filenames properly. If upstream ships filenames that are not encoded in UTF-8 you can use a utility like convmv (from the convmv package) to convert the filename in your %install section.
|
| |
+ Similarly, filenames that contain non-ASCII characters
|
| |
+ must be encoded as UTF-8.
|
| |
+ Since there's no way to note which encoding the filename is in,
|
| |
+ using the same encoding for all filenames is the best way
|
| |
+ to ensure users can read the filenames properly.
|
| |
+ If upstream ships filenames that are not encoded in UTF-8
|
| |
+ you can use a utility like convmv
|
| |
+ (from the convmv package)
|
| |
+ to convert the filename in your %install section.
|
| |
|
| |
=== Spec Maintenance and Canonicity
|
| |
|
| |
- Fedora's git repository is the canonical location for Fedora spec files. Maintainers MUST expect that other maintainers and automated tooling will make changes to their packages, potentially without communicating prior to doing so (though communication is always encouraged). If some maintainers are also attempting to keep copies of a spec in an outside repository, they MUST be prepared to merge changes made to the spec in Fedora's repository, and MUST NOT overwrite those changes with a copy from an external repository or using `+fedpkg import+`.
|
| |
+ Fedora's git repository is the canonical location for Fedora spec files.
|
| |
+ Maintainers MUST expect that other maintainers
|
| |
+ and automated tooling will make changes to their packages,
|
| |
+ potentially without communicating prior to doing so
|
| |
+ (though communication is always encouraged).
|
| |
+ If some maintainers are also attempting
|
| |
+ to keep copies of a spec in an outside repository,
|
| |
+ they MUST be prepared to merge changes made to the spec
|
| |
+ in Fedora's repository,
|
| |
+ and MUST NOT overwrite those changes
|
| |
+ with a copy from an external repository
|
| |
+ or using `+fedpkg import+`.
|
| |
|
| |
== Source File Verification
|
| |
|
| |
Where the upstream project publishes OpenPGP signatures of their releases,
|
| |
Fedora packages *SHOULD* verify that signature as part of the RPM build process.
|
| |
|
| |
- Although a checksum in the sources file certifies that a file retreived from the lookaside cache is the one that the packager uploaded,
|
| |
+ Although a checksum in the sources file certifies
|
| |
+ that a file retreived from the lookaside cache
|
| |
+ is the one that the packager uploaded,
|
| |
it is silent on whether the file is what the upstream project released.
|
| |
- A signature by the upstream developers certifies that the source is identical to what they released.
|
| |
- Verifying the signature as part of the build ensures that packagers don't forget to verify it.
|
| |
+ A signature by the upstream developers certifies
|
| |
+ that the source is identical to what they released.
|
| |
+ Verifying the signature as part of the build ensures
|
| |
+ that packagers don't forget to verify it.
|
| |
|
| |
=== Obtaining the Correct Keys
|
| |
|
| |
The verification method requires an OpenPGP keyring file
|
| |
with one or more public keys from the upstream project.
|
| |
- The keyring shall contain all the keys that are trusted to certify the authenticity of the sources,
|
| |
+ The keyring shall contain all the keys that are trusted
|
| |
+ to certify the authenticity of the sources,
|
| |
and *MUST NOT* contain any other keys.
|
| |
|
| |
Ideally the upstream project publishes such a keyring as a downloadable file.
|
| |
@@ -184,12 +301,15 @@
|
| |
Then you shall add it unmodified to the package SCM,
|
| |
and provide its URL in the spec file
|
| |
so that others can verify it.
|
| |
- The URL *MUST* use HTTPS or a similarly authenticated protocol if at all possible.
|
| |
+ The URL *MUST* use HTTPS
|
| |
+ or a similarly authenticated protocol if at all possible.
|
| |
|
| |
Even if you are unable to verify the key at the first addition,
|
| |
it still enhances security in a trust-on-first-use way.
|
| |
- It will ensure that future attacks will be detected if the key is the right one,
|
| |
- or that a current attack will be detected later if future releases are signed by the correct key.
|
| |
+ It will ensure that future attacks will be detected
|
| |
+ if the key is the right one,
|
| |
+ or that a current attack will be detected later
|
| |
+ if future releases are signed by the correct key.
|
| |
|
| |
=== Verifying Signatures
|
| |
|
| |
@@ -198,7 +318,8 @@
|
| |
before any potentially compromised code is executed.
|
| |
The verification *MUST* be done with the macro `+%{gpgverify}+`,
|
| |
which expands into a command
|
| |
- whose parameters shall be the pathnames of the keyring, the signature and the signed file.
|
| |
+ whose parameters shall be the pathnames of the keyring,
|
| |
+ the signature and the signed file.
|
| |
`BuildRequires: gnupg2` is necessary for the verification to work.
|
| |
|
| |
Any detached signature file
|
| |
@@ -227,24 +348,31 @@
|
| |
If the upstream tarball of a package needs to be modified,
|
| |
for example because it contains forbidden items,
|
| |
then the tarball cannot be verified as part of the build process.
|
| |
- In this case the upstream OpenPGP keyring must still be included in the package SCM
|
| |
- and the instructions/script used to build the stripped-down tarball needs to verify the upstream source.
|
| |
+ In this case
|
| |
+ the upstream OpenPGP keyring must still be included in the package SCM
|
| |
+ and the instructions/script used to build the stripped-down tarball
|
| |
+ needs to verify the upstream source.
|
| |
|
| |
If the upstream project does not publish a keyring file
|
| |
(for example if they publish only a fingerprint on their website
|
| |
and refer to a keyserver network for downloading the key),
|
| |
then you may need to create a keyring after you have verified the key.
|
| |
In this case there is no upstream URL to the keyring,
|
| |
- so instead you should document how you created the keyring in a comment in the spec file.
|
| |
- A minimal keyring with the key with the fingerprint `7D33D762FD6C35130481347FDB4B54CBA4826A18` can be created with the following command:
|
| |
+ so instead you should document how you created the keyring
|
| |
+ in a comment in the spec file.
|
| |
+ A minimal keyring with the key with the fingerprint
|
| |
+ `7D33D762FD6C35130481347FDB4B54CBA4826A18`
|
| |
+ can be created with the following command:
|
| |
|
| |
....
|
| |
gpg2 --export --export-options export-minimal 7D33D762FD6C35130481347FDB4B54CBA4826A18 > gpgkey-7D33D762FD6C35130481347FDB4B54CBA4826A18.gpg
|
| |
....
|
| |
|
| |
If upstream signed a tarball differently,
|
| |
- for example by signing only the uncompressed tarball but distributing a compressed version,
|
| |
- then the verification step must be adjusted accordingly, for example:
|
| |
+ for example by signing only the uncompressed tarball
|
| |
+ but distributing a compressed version,
|
| |
+ then the verification step must be adjusted accordingly,
|
| |
+ for example:
|
| |
|
| |
....
|
| |
Source0: ftp://ftp.example.com/pub/foo/%{name}-%{version}.tar.xz
|
| |
@@ -258,24 +386,47 @@
|
| |
....
|
| |
|
| |
Packages that are vital during bootstrapping of Fedora
|
| |
- may use a <<bootstrapping,bootstrap flag>> to skip the verification before GnuPG has been built.
|
| |
+ may use a <<bootstrapping,bootstrap flag>>
|
| |
+ to skip the verification before GnuPG has been built.
|
| |
|
| |
=== Help
|
| |
|
| |
If you need help getting your package compliant to this guideline,
|
| |
or if you do not know what to do if a build fails on a signature verification,
|
| |
- then you should seek help on the Fedora devel mailing list before circumventing the check,
|
| |
+ then you should seek help on the Fedora devel mailing list
|
| |
+ before circumventing the check,
|
| |
to make sure that you do not build compromised software.
|
| |
|
| |
== Architecture Support
|
| |
|
| |
- All Fedora packages must successfully compile and build into binary rpms on at least one supported primary architecture, except where the package is useful only on a secondary architecture (such as an architecture-specific boot utility, microcode loader, or hardware configuration tool). Fedora packagers should make every effort to support all https://fedoraproject.org/wiki/Architectures#Primary_Architectures[primary architectures].
|
| |
+ All Fedora packages must successfully compile and build
|
| |
+ into binary rpms on at least one supported primary architecture,
|
| |
+ except where the package is useful only on a secondary architecture
|
| |
+ (such as an architecture-specific boot utility, microcode loader,
|
| |
+ or hardware configuration tool).
|
| |
+ Fedora packagers should make every effort to support all
|
| |
+ https://fedoraproject.org/wiki/Architectures#Primary_Architectures[primary architectures].
|
| |
|
| |
- Content, code which does not need to compile or build, and architecture independent code (noarch) are notable exceptions.
|
| |
+ Content, code which does not need to compile or build,
|
| |
+ and architecture independent code (noarch) are notable exceptions.
|
| |
|
| |
=== Architecture Build Failures
|
| |
|
| |
- If a Fedora package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` needs to have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number should then be placed in a comment, next to the corresponding `+ExcludeArch+` line. New packages will not have bugzilla entries during the review process, so they should put this description in the comment until the package is approved, then file the bugzilla entry, and replace the long explanation with the bug number. The bug should be marked as blocking one (or more) of the following bugs to simplify tracking such issues:
|
| |
+ If a Fedora package does not successfully compile, build or work on an architecture,
|
| |
+ then those architectures should be listed in the spec in `+ExcludeArch+`.
|
| |
+ Each architecture listed in `+ExcludeArch+`
|
| |
+ needs to have a bug filed in bugzilla,
|
| |
+ describing the reason that the package does not
|
| |
+ compile/build/work on that architecture.
|
| |
+ The bug number should then be placed in a comment,
|
| |
+ next to the corresponding `+ExcludeArch+` line.
|
| |
+ New packages will not have bugzilla entries during the review process,
|
| |
+ so they should put this description in the comment
|
| |
+ until the package is approved,
|
| |
+ then file the bugzilla entry,
|
| |
+ and replace the long explanation with the bug number.
|
| |
+ The bug should be marked as blocking one (or more)
|
| |
+ of the following bugs to simplify tracking such issues:
|
| |
|
| |
* https://bugzilla.redhat.com/show_bug.cgi?id=F-ExcludeArch-x86[F-ExcludeArch-x86]
|
| |
* https://bugzilla.redhat.com/show_bug.cgi?id=F-ExcludeArch-x64[F-ExcludeArch-x64]
|
| |
@@ -286,11 +437,22 @@
|
| |
|
| |
=== Noarch with Unported Dependencies
|
| |
|
| |
- Sometimes you are working on a noarch package that can only run in locations that a different, arched package builds on. This is common for packages written in a scripting language which depend on the language's interpreter package, for instance. If the arched package that your package deps on isn't available on all architectures Fedora (or EPEL) targets you run into a situation where you may need to exclude your package from certain architectures' package repositories or prevent it from building on certain architectures in the buildsystem.
|
| |
+ Sometimes you are working on a noarch package
|
| |
+ that can only run in locations that a different,
|
| |
+ arched package builds on.
|
| |
+ This is common for packages written in a scripting language
|
| |
+ which depend on the language's interpreter package, for instance.
|
| |
+ If the arched package that your package deps on isn't available
|
| |
+ on all architectures Fedora (or EPEL) targets
|
| |
+ you run into a situation where you may need to exclude your package
|
| |
+ from certain architectures' package repositories
|
| |
+ or prevent it from building on certain architectures in the buildsystem.
|
| |
|
| |
==== Arch-Specific Runtime and Build-Time Dependencies
|
| |
|
| |
- You can limit both the architectures used to build a noarch package, and the repositories to which the built noarch package will be added, by using either the `+ExcludeArch:+` or `+ExclusiveArch:+` tags:
|
| |
+ You can limit both the architectures used to build a noarch package,
|
| |
+ and the repositories to which the built noarch package will be added,
|
| |
+ by using either the `+ExcludeArch:+` or `+ExclusiveArch:+` tags:
|
| |
|
| |
....
|
| |
BuildArch: noarch
|
| |
@@ -298,7 +460,14 @@
|
| |
ExclusiveArch: %{ix86} %{arm} x86_64 noarch
|
| |
....
|
| |
|
| |
- Sometimes a language runtime you are packaging for will provide a macro for the arches it's available on, for instance, `+%{nodejs_arches}+`. If it does exist, then you can use something like `+ExclusiveArch: %{nodejs_arches} noarch+` in your spec file. Take a look at the guidelines for the language to see if such a macro exists.
|
| |
+ Sometimes a language runtime you are packaging for will provide a macro
|
| |
+ for the arches it's available on, for instance,
|
| |
+ `+%{nodejs_arches}+`.
|
| |
+ If it does exist, then you can use something like
|
| |
+ `+ExclusiveArch: %{nodejs_arches} noarch+`
|
| |
+ in your spec file.
|
| |
+ Take a look at the guidelines for the language
|
| |
+ to see if such a macro exists.
|
| |
|
| |
=== No Arch-Specific Sources or Patches ===
|
| |
|
| |
@@ -379,11 +548,23 @@
|
| |
|
| |
=== Multilib Exempt Locations
|
| |
|
| |
- If a package is exempt from multilib, it may use `+%{_prefix}/lib+` instead of `+%{_libdir}+`. Packages that contain architecture specific files that would ordinarily be installed into `+%{_libexecdir}+` are always considered ineligible for multilib. However, you should be sure that the (sub)package that they are in does not have other content that would be considered eligible for multilib. If this is not the case for the files you wish to do this in for your package or you are just unsure, ask FESCo for an explicit multilib exemption.
|
| |
+ If a package is exempt from multilib,
|
| |
+ it may use `+%{_prefix}/lib+` instead of `+%{_libdir}+`.
|
| |
+ Packages that contain architecture specific files
|
| |
+ that would ordinarily be installed into `+%{_libexecdir}+`
|
| |
+ are always considered ineligible for multilib.
|
| |
+ However, you should be sure that the (sub)package that they are in
|
| |
+ does not have other content that would be considered eligible for multilib.
|
| |
+ If this is not the case for the files you wish to do this in for your package
|
| |
+ or you are just unsure, ask FESCo for an explicit multilib exemption.
|
| |
|
| |
=== `+/run+`
|
| |
|
| |
- System services should store small volatile run-time data in `+/run+`. This is a tmpfs backed directory that is mounted in very early boot, before any services are started (and before `+/var+` is available). `+/var/run+` is a legacy symlink to `+/run+`.
|
| |
+ System services should store small volatile run-time data in `+/run+`.
|
| |
+ This is a tmpfs backed directory that is mounted in very early boot,
|
| |
+ before any services are started
|
| |
+ (and before `+/var+` is available).
|
| |
+ `+/var/run+` is a legacy symlink to `+/run+`.
|
| |
|
| |
=== No Files or Directories under /srv, /usr/local, or /home/$USER
|
| |
|
| |
@@ -398,26 +579,67 @@
|
| |
directories without administrator permission."
|
| |
....
|
| |
|
| |
- The FHS is explicitly handing control of the directory structure under `+/srv+` to the system administrator rather than the distribution. Therefore, no Fedora packages can have any files or directories under `+/srv+`, come preconfigured to use specific files or directories under `+/srv+`, to remove files there, or to modify the files there in any way.
|
| |
-
|
| |
- In addition, no Fedora package can contain files or directories or modify files under:
|
| |
-
|
| |
- * `+/usr/local+` as these directories are not permitted to be used by Distributions in the FHS
|
| |
- * `+/home/$USER+` as users can arbitrarily modify the files in their home directories and rpm packages that modify those files run the risk of destroying user data. Additionally, sites may be nfs mounting `+/home+` on many different types of systems or even network automounting them on demand. Modifying files in home directories that are thus configured will have negative effects in both of these situations.
|
| |
-
|
| |
- It is important to note that the software in a Fedora package, once installed and configured by a user, can use `+/srv+` as a location for data. The package simply must not do this out of the box
|
| |
+ The FHS is explicitly handing control of the directory structure
|
| |
+ under `+/srv+` to the system administrator rather than the distribution.
|
| |
+ Therefore, no Fedora packages can have any files or directories under `+/srv+`,
|
| |
+ come preconfigured to use specific files or directories under `+/srv+`,
|
| |
+ to remove files there, or to modify the files there in any way.
|
| |
+
|
| |
+ In addition, no Fedora package can
|
| |
+ contain files or directories or modify files under:
|
| |
+
|
| |
+ * `+/usr/local+`
|
| |
+ as these directories are not permitted to be used
|
| |
+ by Distributions in the FHS
|
| |
+ * `+/home/$USER+`
|
| |
+ as users can arbitrarily modify the files in their home directories
|
| |
+ and rpm packages that modify those files run the risk of destroying user data.
|
| |
+ Additionally, sites may be nfs mounting `+/home+`
|
| |
+ on many different types of systems
|
| |
+ or even network automounting them on demand.
|
| |
+ Modifying files in home directories that are thus configured
|
| |
+ will have negative effects in both of these situations.
|
| |
+
|
| |
+ It is important to note that the software in a Fedora package,
|
| |
+ once installed and configured by a user,
|
| |
+ can use `+/srv+` as a location for data.
|
| |
+ The package simply must not do this out of the box
|
| |
|
| |
=== Limited usage of /opt, /etc/opt, and /var/opt
|
| |
|
| |
- `+/opt+` and its related directories (`+/etc/opt+` and `+/var/opt+`) is reserved for the use of vendors in the FHS. We have reserved the `+fedora+` name with http://www.lanana.org/lsbreg/providers/providers.txt[LANANA] for our use. If a package installs files into `+/opt+` it may only use directories in the `+/opt/fedora+` hierarchy. Fedora attempts to organize this directory by allocating a subdirectory of our `+/opt/fedora+` directory for specific subsystems. If you think you need to use `+/opt/fedora+` please file an FPC ticket to decide whether it's a valid use of `+/opt+` and what subdirectory should be allocated for your use.
|
| |
-
|
| |
- Currently, we have allocated `+/opt/fedora/scls+`, `+/etc/opt/fedora/scls+`, and `+/var/opt/fedora/scls+` for use by {scl-guidelines}.
|
| |
-
|
| |
- Because the Google-supplied Chrome packaging has chosen a specific file location for extension-specific files which, if used, would conflicts with the above guidelines, the Packaging Committee has approved the following exception: A package MAY install files into the `+/etc/opt/chrome/native-messaging-hosts+` directory, and may create that directory hierarchy, as long as package as a whole also supports Chromium. (The Chromium support MAY be in a different subpackage.) If Chrome in the future allows a more standard directory to be used for this purpose, this exception will be removed.
|
| |
+ `+/opt+` and its related directories (`+/etc/opt+` and `+/var/opt+`)
|
| |
+ is reserved for the use of vendors in the FHS.
|
| |
+ We have reserved the `+fedora+` name with
|
| |
+ http://www.lanana.org/lsbreg/providers/providers.txt[LANANA]
|
| |
+ for our use.
|
| |
+ If a package installs files into `+/opt+`
|
| |
+ it may only use directories in the `+/opt/fedora+` hierarchy.
|
| |
+ Fedora attempts to organize this directory by allocating a subdirectory
|
| |
+ of our `+/opt/fedora+` directory for specific subsystems.
|
| |
+ If you think you need to use `+/opt/fedora+`
|
| |
+ please file an FPC ticket to decide whether it's a valid use of `+/opt+`
|
| |
+ and what subdirectory should be allocated for your use.
|
| |
+
|
| |
+ Currently, we have allocated
|
| |
+ `+/opt/fedora/scls+`, `+/etc/opt/fedora/scls+`, and `+/var/opt/fedora/scls+`
|
| |
+ for use by {scl-guidelines}.
|
| |
+
|
| |
+ Because the Google-supplied Chrome packaging has chosen
|
| |
+ a specific file location for extension-specific files which,
|
| |
+ if used, would conflicts with the above guidelines,
|
| |
+ the Packaging Committee has approved the following exception:
|
| |
+ A package MAY install files into the
|
| |
+ `+/etc/opt/chrome/native-messaging-hosts+` directory,
|
| |
+ and may create that directory hierarchy,
|
| |
+ as long as package as a whole also supports Chromium.
|
| |
+ (The Chromium support MAY be in a different subpackage.)
|
| |
+ If Chrome in the future allows a more standard directory
|
| |
+ to be used for this purpose, this exception will be removed.
|
| |
|
| |
=== Effect of the UsrMove Fedora Feature
|
| |
|
| |
- Fedora has merged several directories in `+/+` with their counterparts in `+/usr/+`.
|
| |
+ Fedora has merged several directories in `+/+`
|
| |
+ with their counterparts in `+/usr/+`.
|
| |
|
| |
/bin
|
| |
|
| |
@@ -435,16 +657,34 @@
|
| |
|
| |
/usr/lib aka %\{_prefix}/lib
|
| |
|
| |
- For example, end users will find that `+/bin/sh+` is the same file as `+/usr/bin/sh+`.
|
| |
+ For example, end users will find that `+/bin/sh+`
|
| |
+ is the same file as `+/usr/bin/sh+`.
|
| |
|
| |
- However, rpm file dependencies don't work according to what's on the filesystem, they work according to the path specified in the rpm `+%files+` section. So an rpm which specified:
|
| |
+ However,
|
| |
+ rpm file dependencies don't work according to what's on the filesystem,
|
| |
+ they work according to the path specified in the rpm `+%files+` section.
|
| |
+ So an rpm which specified:
|
| |
|
| |
....
|
| |
%files
|
| |
/bin/sh
|
| |
....
|
| |
|
| |
- would be able to satisfy a file dependency for `+/bin/sh+` but not for `+/usr/bin/sh+`. As a packager you may need to pay attention to where other packages expect to find your files. Things that history has placed into `+/bin+`, `+/sbin+`, `+/lib+`, or `+/lib64+` should be listed in the `+%files+` section as being in those directories. Things that history placed in `+/usr/bin+`, `+/usr/sbin+`, etc, should be listed in the `+%files+` section as being in `+%{_bindir}+`, `+%{_sbindir}+`, etc. If you feel that there is some historical confusion as to which directory a program is placed in, you can use a Virtual Provides to list the alternate path. For instance:
|
| |
+ would be able to satisfy a file dependency for `+/bin/sh+`
|
| |
+ but not for `+/usr/bin/sh+`.
|
| |
+ As a packager you may need to pay attention
|
| |
+ to where other packages expect to find your files.
|
| |
+ Things that history has placed into
|
| |
+ `+/bin+`, `+/sbin+`, `+/lib+`, or `+/lib64+`
|
| |
+ should be listed in the `+%files+` section as being in those directories.
|
| |
+ Things that history placed in
|
| |
+ `+/usr/bin+`, `+/usr/sbin+`, etc,
|
| |
+ should be listed in the `+%files+` section as being in
|
| |
+ `+%{_bindir}+`, `+%{_sbindir}+`, etc.
|
| |
+ If you feel that there is some historical confusion
|
| |
+ as to which directory a program is placed in,
|
| |
+ you can use a Virtual Provides to list the alternate path.
|
| |
+ For instance:
|
| |
|
| |
....
|
| |
Provides: %{_sbindir}/ifconfig
|
| |
@@ -453,7 +693,11 @@
|
| |
/sbin/ifconfig
|
| |
....
|
| |
|
| |
- If you are a packager who uses file dependencies to Require the proper dependencies then you may need to make sure that the file dependencies are pointing to the location that the packager of that file specified to rpm. Here's an example of doing this:
|
| |
+ If you are a packager who uses file dependencies
|
| |
+ to Require the proper dependencies
|
| |
+ then you may need to make sure that the file dependencies
|
| |
+ are pointing to the location that the packager of that file specified to rpm.
|
| |
+ Here's an example of doing this:
|
| |
|
| |
....
|
| |
$ rpm -ql $(rpm -qf /usr/sbin/ifconfig)|grep sbin/ifconfig
|
| |
@@ -464,23 +708,49 @@
|
| |
|
| |
== Use rpmlint
|
| |
|
| |
- Run rpmlint on binary and source rpms to examine them for common errors, and fix them (unless rpmlint is wrong, which can happen, too). If you find rpmlint's output cryptic, the `+-i+` switch to it can be used to get more verbose descriptions of most errors and warnings. Note that rpmlint will perform additional checks if given the name of an installed package. For example, `+dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint foo+` will perform a set of tests on the foo package that `+rpmlint foo-1.0-1.f20.x86_64.rpm+` cannot. A community-maintained page on rpmlint issues can be found https://fedoraproject.org/wiki/Common_Rpmlint_issues[here].
|
| |
+ Run rpmlint on binary and source rpms to examine them for common errors,
|
| |
+ and fix them (unless rpmlint is wrong, which can happen, too).
|
| |
+ If you find rpmlint's output cryptic,
|
| |
+ the `+-i+` switch to it can be used
|
| |
+ to get more verbose descriptions of most errors and warnings.
|
| |
+ Note that rpmlint will perform additional checks
|
| |
+ if given the name of an installed package.
|
| |
+ For example,
|
| |
+ `+dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint foo+`
|
| |
+ will perform a set of tests on the foo package that
|
| |
+ `+rpmlint foo-1.0-1.f20.x86_64.rpm+` cannot.
|
| |
+ A community-maintained page on rpmlint issues can be found
|
| |
+ https://fedoraproject.org/wiki/Common_Rpmlint_issues[here].
|
| |
|
| |
== Tags and Sections
|
| |
|
| |
- * The `+Copyright:+`, `+Packager:+`, `+Vendor:+` and `+PreReq:+` tags MUST NOT be used.
|
| |
- * The `+BuildRoot:+` tag, `+Group:+` tag, and `+%clean+` section SHOULD NOT be used.
|
| |
- * The contents of the buildroot SHOULD NOT be removed in the first line of `+%install+`.
|
| |
+ * The `+Copyright:+`, `+Packager:+`, `+Vendor:+` and `+PreReq:+` tags
|
| |
+ MUST NOT be used.
|
| |
+ * The `+BuildRoot:+` tag, `+Group:+` tag, and `+%clean+` section
|
| |
+ SHOULD NOT be used.
|
| |
+ * The contents of the buildroot SHOULD NOT be removed
|
| |
+ in the first line of `+%install+`.
|
| |
* The `+Summary:+` tag value SHOULD NOT end in a period.
|
| |
- * The `+Source:+` tags document where to find the upstream sources for the package. In most cases this SHOULD be a complete URL to the upstream tarball. For special cases, please see the xref:SourceURL.adoc[SourceURL Guidelines].
|
| |
+ * The `+Source:+` tags document where to find
|
| |
+ the upstream sources for the package.
|
| |
+ In most cases this SHOULD be a complete URL to the upstream tarball.
|
| |
+ For special cases, please see the
|
| |
+ xref:SourceURL.adoc[SourceURL Guidelines].
|
| |
|
| |
== Package Dependencies
|
| |
|
| |
- All package dependencies (build-time or runtime, regular, weak or otherwise) MUST ALWAYS be satisfiable within the official Fedora repositories.
|
| |
+ All package dependencies
|
| |
+ (build-time or runtime, regular, weak or otherwise)
|
| |
+ MUST ALWAYS be satisfiable within the official Fedora repositories.
|
| |
|
| |
- RPM can automatically determine dependencies for most compiled libraries and for some scripting languages such as Perl. Automatically determined dependencies MUST NOT be duplicated by manual dependencies.
|
| |
+ RPM can automatically determine dependencies for most compiled libraries
|
| |
+ and for some scripting languages such as Perl.
|
| |
+ Automatically determined dependencies MUST NOT be duplicated
|
| |
+ by manual dependencies.
|
| |
|
| |
- Build dependencies, however, cannot be automatically determined and MUST be explicitly listed. Refer to the <<buildrequires>>.
|
| |
+ Build dependencies, however,
|
| |
+ cannot be automatically determined and MUST be explicitly listed.
|
| |
+ Refer to the <<buildrequires>>.
|
| |
|
| |
Versioned dependencies (build-time or runtime) SHOULD ONLY be used
|
| |
when actually necessary to guarantee
|
| |
@@ -490,21 +760,31 @@
|
| |
then a versioned dependency is not needed
|
| |
and a regular unversioned dependency SHOULD be used instead.
|
| |
|
| |
- A versioned dependency on a package with a defined Epoch MUST be included in that dependency. Otherwise the dependency will not function as expected.
|
| |
+ A versioned dependency on a package with a defined Epoch
|
| |
+ MUST be included in that dependency.
|
| |
+ Otherwise the dependency will not function as expected.
|
| |
|
| |
=== Dependency types
|
| |
|
| |
- `Requires` MUST be used if the dependency is required for the software to function correctly.
|
| |
+ `Requires` MUST be used if the dependency is required
|
| |
+ for the software to function correctly.
|
| |
|
| |
- If the package functions correctly but in diminished capacity, then
|
| |
- `Recommends` or `Suggests` SHOULD be used.
|
| |
- If the functionality should be available by default for users, `Recommends` SHOULD be used, and `Suggests` otherwise.
|
| |
- Alternatively, the reverse dependencies `Supplements` or `Enhances` may be used in the other package.
|
| |
- See xref:WeakDependencies.adoc[Packaging:WeakDependencies] for guidelines on using those dependency types.
|
| |
+ If the package functions correctly but in diminished capacity,
|
| |
+ then `Recommends` or `Suggests` SHOULD be used.
|
| |
+ If the functionality should be available by default for users,
|
| |
+ `Recommends` SHOULD be used,
|
| |
+ and `Suggests` otherwise.
|
| |
+ Alternatively, the reverse dependencies
|
| |
+ `Supplements` or `Enhances
|
| |
+ may be used in the other package.
|
| |
+ See xref:WeakDependencies.adoc[Packaging:WeakDependencies]
|
| |
+ for guidelines on using those dependency types.
|
| |
|
| |
=== Architecture-specific Dependencies
|
| |
|
| |
- A dependency is made arch-specific by appending the macro `+%{?_isa}+` to the package name. For example:
|
| |
+ A dependency is made arch-specific by appending the macro `+%{?_isa}+`
|
| |
+ to the package name.
|
| |
+ For example:
|
| |
|
| |
....
|
| |
Requires: foo
|
| |
@@ -516,7 +796,10 @@
|
| |
Requires: foo%{?_isa}
|
| |
....
|
| |
|
| |
- If the foo-devel package has a foo-config script, you can try doing a foo-config --libs and foo-config --cflags to get strong hints what packages should be marked as foo's requirements. For example:
|
| |
+ If the foo-devel package has a foo-config script,
|
| |
+ you can try doing a foo-config --libs and foo-config --cflags
|
| |
+ to get strong hints what packages should be marked as foo's requirements.
|
| |
+ For example:
|
| |
|
| |
....
|
| |
$ gtk-config --cflags
|
| |
@@ -531,27 +814,75 @@
|
| |
|
| |
=== Rich/Boolean dependencies
|
| |
|
| |
- Packages MAY make full use of the https://rpm-software-management.github.io/rpm/manual/boolean_dependencies.html[rich (or Boolean) dependency feature] supported in RPM.
|
| |
+ Packages MAY make full use of the
|
| |
+ https://rpm-software-management.github.io/rpm/manual/boolean_dependencies.html[rich (or Boolean) dependency feature]
|
| |
+ supported in RPM.
|
| |
|
| |
=== File and Directory Dependencies
|
| |
|
| |
- RPM gives you the ability to depend on arbitrary files or directories instead of packages. Packages SHOULD NOT include file dependencies outside of the following directories:
|
| |
+ RPM gives you the ability to depend on arbitrary files or directories
|
| |
+ instead of packages.
|
| |
+ Packages SHOULD NOT include file dependencies
|
| |
+ outside of the following directories:
|
| |
|
| |
* /usr/bin
|
| |
* /usr/sbin
|
| |
* /etc
|
| |
|
| |
- Please also note that it is not uncommon for multiple packages to provide the same directory. Directory dependencies SHOULD ONLY be used to express the dependency on that directory existing, not on any other functionality of any other package that might provide that directory.
|
| |
+ Please also note that it is not uncommon
|
| |
+ for multiple packages to provide the same directory.
|
| |
+ Directory dependencies SHOULD ONLY be used
|
| |
+ to express the dependency on that directory existing,
|
| |
+ not on any other functionality of any other package
|
| |
+ that might provide that directory.
|
| |
|
| |
=== Explicit Requires
|
| |
|
| |
- Explicit Requires are Requires added manually by the packager in the spec file. Packages must not contain unnecessary explicit Requires on libraries. We generally rely on rpmbuild to automatically add dependencies on library SONAMEs. Modern package management tools are capable of resolving such dependencies to determine the required packages in many cases. However, present versions of rpmbuild only add deps on library SONAMES, not the library's full version. This can be a problem if a library has added features over the course of time without backwards incompatibilities that would cause SONAMES to be changed. This can lead to a case where the user has an old version of a library installed, the new version of the library with new ABI is built in Fedora and an application using that ABI is built. If the user just attempts to install or update that one application without also updating the library, the application will install fine (because the SONAME dependency is satisfied) but will fail when run because the library installed on the system is missing features it needs.
|
| |
-
|
| |
- Although you do need to add explicit library dependencies to keep this from occurring, there are drawbacks to manually specifying this in all your packages. History has shown that such dependencies add confusion when library/files are moved from one package to another, when packages get renamed, when one out of multiple alternative packages would suffice, and when versioned explicit dependencies become out-of-date and inaccurate. Additionally, in some cases, old explicit dependencies on package names require unnecessary updates/rebuilds. For example, Fedora packages are only required to retain historical provides for two full release cycles.
|
| |
-
|
| |
- Because of this and because we hope to have this fixed in rpmbuild, this is something to be aware of but it's not required that you explicitly specify the libraries you require with their version information.
|
| |
-
|
| |
- When explicit library Requires are necessary, explicit library dependencies should typically be arch-specific (unless the packages involved are noarch) and there should be a spec file comment justifying it:
|
| |
+ Explicit Requires are Requires added manually by the packager in the spec file.
|
| |
+ Packages must not contain unnecessary explicit Requires on libraries.
|
| |
+ We generally rely on rpmbuild to automatically add dependencies
|
| |
+ on library SONAMEs.
|
| |
+ Modern package management tools are capable of resolving such dependencies
|
| |
+ to determine the required packages in many cases.
|
| |
+ However, present versions of rpmbuild only add deps on library SONAMES,
|
| |
+ not the library's full version.
|
| |
+ This can be a problem if a library has added features over the course of time
|
| |
+ without backwards incompatibilities that would cause SONAMES to be changed.
|
| |
+ This can lead to a case where the user has an old version
|
| |
+ of a library installed,
|
| |
+ the new version of the library with new ABI is built in Fedora
|
| |
+ and an application using that ABI is built.
|
| |
+ If the user just attempts to install or update that one application
|
| |
+ without also updating the library,
|
| |
+ the application will install fine
|
| |
+ (because the SONAME dependency is satisfied)
|
| |
+ but will fail when run because the library installed
|
| |
+ on the system is missing features it needs.
|
| |
+
|
| |
+ Although you do need to add explicit library dependencies
|
| |
+ to keep this from occurring,
|
| |
+ there are drawbacks to manually specifying this in all your packages.
|
| |
+ History has shown that such dependencies add confusion
|
| |
+ when library/files are moved from one package to another,
|
| |
+ when packages get renamed,
|
| |
+ when one out of multiple alternative packages would suffice,
|
| |
+ and when versioned explicit dependencies become out-of-date and inaccurate.
|
| |
+ Additionally, in some cases,
|
| |
+ old explicit dependencies on package names
|
| |
+ require unnecessary updates/rebuilds.
|
| |
+ For example,
|
| |
+ Fedora packages are only required to retain historical provides
|
| |
+ for two full release cycles.
|
| |
+
|
| |
+ Because of this and because we hope to have this fixed in rpmbuild,
|
| |
+ this is something to be aware of
|
| |
+ but it's not required that you explicitly specify the libraries you require
|
| |
+ with their version information.
|
| |
+
|
| |
+ When explicit library Requires are necessary,
|
| |
+ explicit library dependencies should typically be arch-specific
|
| |
+ (unless the packages involved are noarch)
|
| |
+ and there should be a spec file comment justifying it:
|
| |
|
| |
....
|
| |
# The automatic dependency on libfubar.so.1 is insufficient,
|
| |
@@ -559,7 +890,11 @@
|
| |
Requires: libfubar%{?_isa} >= 0:1.2.3-7
|
| |
....
|
| |
|
| |
- Packagers should revisit an explicit dependency as appropriate to avoid it becoming inaccurate and superfluous. For instance in the example above, when no current Fedora release shipped with libfubar < 1.2.3-7, it is no longer necessary to list the explicit, versioned requirement.
|
| |
+ Packagers should revisit an explicit dependency
|
| |
+ as appropriate to avoid it becoming inaccurate and superfluous.
|
| |
+ For instance in the example above,
|
| |
+ when no current Fedora release shipped with libfubar < 1.2.3-7,
|
| |
+ it is no longer necessary to list the explicit, versioned requirement.
|
| |
|
| |
=== Filtering Auto-Generated Requires
|
| |
|
| |
tibbs
commented 2 years ago
This is an ongoing effort to apply semantic line breaks to the main guidelines page.
These initial 23 commits convert about 20% of the document.
I've made one commit per section/subsection
so I can just drop and redo a commit if it happens to conflict,
but I can squash if that's preferable.
I've held off on doing this for a while
because it invalidates existing PRs against the main guidelines,
but I took care of a number of those so I figure it's a good time.