fedora-llm-docs/Documents/pages/WeakDependencies.txt

= 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).

[cols=",,",]
|===============================
| |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. To skip installing weak dependencies, pass
`--setopt=install_weak_deps=False` to `dnf`.

As with regular dependencies, weak dependencies MUST be satisfiable within the official Fedora repositories.

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