(New guideline; writeup of https://fedorahosted.org/fpc/ticket/531) |
m (Grammar cleanup.) |
||
| Line 3: | Line 3: | ||
== Introduction == | == Introduction == | ||
Weak dependencies are basically | Weak dependencies are basically variants of the <code>Requires:</code> tag and | ||
They come in two strengths: "weak" and "hint" and two directions "forward" ( | are matched against (virtual) <code>Provides:</code> and package names using | ||
<code>Epoch-Version-Release</code> range comparisons, just like regular | |||
<code>Requires:</code>. They come in two strengths: "weak" and "hint" and two | |||
directions "forward" (analogous to <code>Requires:</code>) and "backwards" | |||
(which has no analog in the previous dependency system). | |||
{| | {| | ||
| Line 20: | Line 24: | ||
|} | |} | ||
Weak dependencies allow smaller minimal installations while keeping the default installation feature rich. They also allow packages to specify | Weak dependencies allow smaller minimal installations while keeping the default | ||
installation feature rich. They also allow packages to specify preferences for | |||
specific providers while maintaining the flexibility of virtual provides, for | |||
example, preferring ruby vs jruby or community-mysql vs mariadb. | |||
== Weak dependencies == | == Weak dependencies == | ||
Weak dependencies are by default treated similarly to regular Requires:. Matching packages are added to the transaction. If adding the package would lead to an error dnf will ignore the dependency. This allows users to exclude packages that would be added by weak dependencies or remove them later. (Future versions of dnf might also allow to switch weak deps off on the command line) | Weak dependencies are by default treated similarly to regular | ||
Weak dependencies | <code>Requires:</code>. Matching packages are added to the dnf transaction. If | ||
adding the package would lead to an error dnf will by default ignore the | |||
dependency. This allows users to exclude packages that would be added by weak | |||
dependencies or remove them later. (Future versions of dnf might also allow to | |||
switch weak deps off on the command line.) | |||
Weak dependencies may only be used in a package if the package still functions | |||
without the dependency present. It is acceptable, however, to create packages | |||
that have very limited functionality without adding any of its weak | |||
requirements. Weak dependencies should be used where possible to minimize the | |||
installation for reasonable use cases, especially for building virtual machines | |||
or containers that have a single purpose only and do not require the full | |||
feature set of the package. | |||
Typical use cases for weak dependencies are: | Typical use cases for weak dependencies are: | ||
* Documentation | * Documentation | ||
** Documentation viewers if missing them is handled gracefully | ** Documentation viewers if missing them is handled gracefully | ||
| Line 39: | Line 57: | ||
== Hints == | == Hints == | ||
Hints are by default ignored by dnf. They may be used by GUI tools to offer add-on packages that are not installed by default but might be useful in combination with the installed packages. The requirements of the main use cases of a | Hints are by default ignored by dnf. They may be used by GUI tools to offer | ||
add-on packages that are not installed by default but might be useful in | |||
combination with the installed packages. The requirements of the main use cases | |||
of a package should not merely be referenced by hints but included by strong or | |||
weak dependencies. | |||
== Package Preference == | == Package Preference == | ||
dnf (or more precisely libsolv) will use weak dependencies and hints to decide | |||
which package to use if there is a choice between multiple equally valid | |||
packages. In these cases packages that are pointed at by dependencies from | |||
installed or to be installed packages are preferred. Note, that this does not | |||
alter the normal rules of dependency resolution. For example, weak | |||
dependencies cannot enforce a older version of a package to be chosen. | |||
If there are multiple (typically virtual) providers for a | If there are multiple (typically virtual) providers for a dependency the | ||
requiring package may add a Suggests: to provide a hint to the dependency | |||
resolver as to which poption is preferred. <code>Enhances:</code> should only | |||
be used for the rare occasion when the main package and other providers agree | |||
that adding the hint to the required package is for some reason the cleaner | |||
solution. | |||
=== Real life example === | === Real life example === | ||
<code> | <code> | ||
Package A: | |||
Requires: mysql | Requires: mysql | ||
Package mariadb: | |||
Provides: mysql | Provides: mysql | ||
Package community-mysql: | |||
Provides: mysql | Provides: mysql | ||
</code> | </code> | ||
If you want to prefer mariadb | If you want to prefer mariadb over community-mysql -> add <code>Suggests: | ||
mariadb</code> to Package A. | |||
== Forward vs Backward Dependencies == | == Forward vs Backward Dependencies == | ||
Forward dependencies are | Forward dependencies are, as Requires, evaluated for packages that are being | ||
installed. The best of the matching (fulfilling) packages are also installed. | |||
For reverse dependencies the packages containing the dependency are installed if | |||
a matching package is getting installed also. | |||
In general forward dependencies should be used. Add the dependency to the package getting the other package added to the system. | In general forward dependencies should be used. Add the dependency to the | ||
package getting the other package added to the system. | |||
Reverse dependencies are mainly designed for 3rd party vendors | Reverse dependencies are mainly designed for 3rd party vendors who can attach | ||
their plug-ins/add-ons/extensions to distribution or other 3rd party packages. | |||
Within Fedora the control over which packages a package requires should stay | |||
with the package maintainer. There are, however, cases when it is easier for | |||
the requiring package not needing to care about all add-ons. In this cases | |||
reverse dependencies may be used with the agreement of the package maintainer of | |||
the targeted package. | |||
Note, that EPEL or other third party repositories may have (and are encouraged to have) a different policy. | Note, that EPEL or other third party repositories may have (and are encouraged | ||
to have) a different policy. | |||
== Compatibility == | == Compatibility == | ||
Weak dependencies are not supported and | Weak dependencies are not supported and are completely ignored by yum. Therefore | ||
packages must not rely on weak dependencies up to Fedora 22 where yum is still | |||
supported. While hints can still be used Requires: must not be replaced by | |||
Recommends: until Fedora 23. | |||
Revision as of 15:45, 18 June 2015
Weak Dependencies Policy
Introduction
Weak dependencies are basically variants of the Requires: tag and
are matched against (virtual) Provides: and package names using
Epoch-Version-Release range comparisons, just like regular
Requires:. They come in two strengths: "weak" and "hint" and two
directions "forward" (analogous to Requires:) and "backwards"
(which has no analog in the previous dependency system).
| Forward | Backward | |
| Weak | Recommends: | Supplements: |
| Hint | Suggests: | Enhances: |
Weak dependencies allow smaller minimal installations while keeping the default installation feature rich. They also allow packages to specify preferences for specific providers while maintaining the flexibility of virtual provides, for example, preferring ruby vs jruby or community-mysql vs mariadb.
Weak dependencies
Weak dependencies are by default treated similarly to regular
Requires:. Matching packages are added to the dnf transaction. If
adding the package would lead to an error dnf will by default ignore the
dependency. This allows users to exclude packages that would be added by weak
dependencies or remove them later. (Future versions of dnf might also allow to
switch weak deps off on the command line.)
Weak dependencies may only be used in a package if the package still functions without the dependency present. It is acceptable, however, to create packages that have very limited functionality without adding any of its weak requirements. Weak dependencies should be used where possible to minimize the installation for reasonable use cases, especially for building virtual machines or containers that have a single purpose only and do not require the full feature set of the package.
Typical use cases for weak dependencies are:
- Documentation
- Documentation viewers if missing them is handled gracefully
- Examples
- Plug-ins or add-ons
- Support for file formats
- Support for protocols
- ...
Hints
Hints are by default ignored by dnf. They may be used by GUI tools to offer add-on packages that are not installed by default but might be useful in combination with the installed packages. The requirements of the main use cases of a package should not merely be referenced by hints but included by strong or weak dependencies.
Package Preference
dnf (or more precisely libsolv) will use weak dependencies and hints to decide which package to use if there is a choice between multiple equally valid packages. In these cases packages that are pointed at by dependencies from installed or to be installed packages are preferred. Note, that this does not alter the normal rules of dependency resolution. For example, weak dependencies cannot enforce a older version of a package to be chosen.
If there are multiple (typically virtual) providers for a dependency the
requiring package may add a Suggests: to provide a hint to the dependency
resolver as to which poption is preferred. Enhances: should only
be used for the rare occasion when the main package and other providers agree
that adding the hint to the required package is for some reason the cleaner
solution.
Real life example
Package A:
Requires: mysql
Package mariadb:
Provides: mysql
Package community-mysql:
Provides: mysql
If you want to prefer mariadb over community-mysql -> add Suggests:
mariadb to Package A.
Forward vs Backward Dependencies
Forward dependencies are, as Requires, evaluated for packages that are being installed. The best of the matching (fulfilling) packages are also installed. For reverse dependencies the packages containing the dependency are installed if a matching package is getting installed also.
In general forward dependencies should be used. Add the dependency to the package getting the other package added to the system.
Reverse dependencies are mainly designed for 3rd party vendors who can attach their plug-ins/add-ons/extensions to distribution or other 3rd party packages. Within Fedora the control over which packages a package requires should stay with the package maintainer. There are, however, cases when it is easier for the requiring package not needing to care about all add-ons. In this cases reverse dependencies may be used with the agreement of the package maintainer of the targeted package.
Note, that EPEL or other third party repositories may have (and are encouraged to have) a different policy.
Compatibility
Weak dependencies are not supported and are completely ignored by yum. Therefore packages must not rely on weak dependencies up to Fedora 22 where yum is still supported. While hints can still be used Requires: must not be replaced by Recommends: until Fedora 23.