.TH "alpm-package-relation" 7

.SH "NAME"
.PP
package relation \- package relationships for ALPM based packages\.

.SH "DESCRIPTION"
.PP
\fBPackage relations\fP describe relationships between ALPM based packages for various scenarios\.
They are used in build scripts or file formats for package metadata (e\.g\. in \fBPKGBUILD\fP, \fBPKGINFO\fP or \fBSRCINFO\fP) to describe relationships of packages to other packages\.
Software such as package managers or package build software rely on \fBpackage relations\fP to resolve dependency graphs, e\.g\. when installing or uninstalling packages\.

.SS "Packages and virtual components"
.PP
Any \fBpackage relation\fP may contain an \fBalpm\-package\-name\fP, which may be used to refer to an existing package or a \fIvirtual component\fP\.
\fIVirtual components\fP do not represent the names of existing packages, but instead a component that is implicitly defined by package metadata\.
With the help of \fBpackage relations\fP, \fIvirtual components\fP are defined and used similarly to names of existing packages (see \fBEXAMPLES\fP for further information)\.

.SS "Sonames"
.PP
A \fBpackage relation\fP of type \fBprovision\fP or \fBrun\-time dependency\fP may contain an \fBalpm\-soname\fP that represents a hard dependency based on a specific \fIshared object\fP in a package\.
They are used to encode compatibility guarantees between \fBELF\fP[1] and \fIshared object\fP files with the help of \fBsoname\fP[2] data (see \fBEXAMPLES\fP for further information)\.

.SS "Architecture specific use"
.PP
\fBPackage relations\fP may be used in contexts that can describe multiple \fBalpm\-architectures\fP at the same time\.
For these situations, architecture\-specific identifiers are available and may be used\.

.SS "Types of package relations"
.PP
The definition of a \fBpackage relation\fP is bound to a set of types\.
Which keywords and what data structures are used for each type depends on the context they are used in\.

.SB "Run-time dependency"
.PP
A run\-time dependency of a package\.
This \fBpackage relation\fP specifies a hard requirement (another package, optionally in a specific version), that must be present when using a given package\.
.PP
The value for a run\-time dependency is either an \fBalpm\-package\-name\fP, an \fBalpm\-comparison\fP or an \fBalpm\-soname\fP (e\.g\. `\f[CR]example\fP`, `\f[CR]example>=1\.0\.0\fP`, or `\f[CR]lib:libexample\.so\.1\fP`, respectively)\.
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more run\-time dependencies of a package are specified using the \fBdepends\fP array\.
Architecture\-specific run\-time dependencies may be specified using an array named 'depends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]depends_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBdepend\fP keyword is used to specify a run\-time dependency\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBdepends\fP keyword is used to specify a run\-time dependency\.
An architecture\-specific run\-time dependency may be specified using a keyword consisting of 'depends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]depends_aarch64\fP`\.
.El
.RE

.SB "Build dependency"
.PP
A build\-time dependency of a package\.
This \fBpackage relation\fP specifies a build requirement (another package, optionally in a specific version), that must be present when building a given package\.
.PP
The value for a build dependency is either an \fBalpm\-package\-name\fP or an \fBalpm\-comparison\fP (e\.g\. `\f[CR]example\fP` or `\f[CR]example>=1\.0\.0\fP`)\.
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more build\-time dependencies of a package are specified using the \fBmakedepends\fP array\.
Architecture\-specific build dependencies may be specified using an array named 'makedepends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]makedepends_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBmakedepend\fP keyword is used to specify a build\-time dependency\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBmakedepends\fP keyword is used to specify a build\-time dependency\.
An architecture\-specific build dependency may be specified using a keyword consisting of 'makedepends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]makedepends_aarch64\fP`\.
.El
.RE

.SB "Test dependency"
.PP
A package dependency, that is only required when running the tests of the package\.
This \fBpackage relation\fP specifies a test requirement (another package, optionally in a specific version), that must be present when running the tests of a given package\.
.PP
The value for a test dependency is either an \fBalpm\-package\-name\fP or an \fBalpm\-comparison\fP (e\.g\. `\f[CR]example\fP` or `\f[CR]example>=1\.0\.0\fP`)\.
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more test dependencies of a package are specified using the \fBcheckdepends\fP array\.
Architecture\-specific test dependencies may be specified using an array named 'makedepends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]checkdepends_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBcheckdepend\fP keyword is used to specify a test dependency\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBcheckdepends\fP keyword is used to specify a test dependency\.
An architecture\-specific test dependency may be specified using a keyword consisting of 'checkdepends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]checkdepends_aarch64\fP`\.
.El
.RE

.SB "Optional dependency"
.PP
A package dependency, that provides optional functionality for a package but is otherwise not required during run\-time\.
This \fBpackage relation\fP specifies a requirement (another package with optional version constraints and an optional description) that is only needed to enable optional functionality of a given package\.
.PP
The value for an optional dependency can be one of the following:
.RS
.Bl
.IP 1. 4
An \fBalpm\-package\-name\fP (e\.g\., `\f[CR]example\fP`) or an \fBalpm\-comparison\fP (e\.g\., `\f[CR]example>=1\.2\.3\fP`)
.El
.Bl
.IP 2. 4
An \fBalpm\-package\-name\fP or \fBalpm\-comparison\fP followed by a `\f[CR]:\fP` sign, a whitespace, and a UTF\-8\-formatted description string that specifies the reason for the optional dependency (e\.g\., `\f[CR]example: for feature X\fP` or `\f[CR]example>=1\.2\.3: for feature X\fP`)
.El
.RE
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more optional dependencies of a package are specified using the \fBoptdepends\fP array\.
Architecture\-specific optional dependencies may be specified using an array named 'optdepends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]optdepends_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBoptdepend\fP keyword is used to specify an optional dependency\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBoptdepends\fP keyword is used to specify an optional dependency\.
An architecture\-specific optional dependency may be specified using a keyword consisting of 'optdepends', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]optdepends_aarch64\fP`\.
.El
.RE

.SB "Provision"
.PP
This \fBpackage relation\fP specifies a component name (an \fBalpm\-package\-name\fP, a \fIvirtual component\fP, or an \fBalpm\-soname\fP) that is provided by a given package\.
The use of a provision allows for scenarios in which e\.g\. several packages provide the same component, allowing package managers to provide a choice\.
.PP
The value for a \fBprovision\fP is either an \fBalpm\-package\-name\fP, an \fBalpm\-comparison\fP, or an \fBalpm\-soname\fP (e\.g\. `\f[CR]example\fP`, `\f[CR]example>=1\.0\.0\fP`, or `\f[CR]lib:libexample\.so\.1\fP`, respectively)\.
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more provisions are specified using the \fBprovides\fP array\.
Architecture\-specific provisions may be specified using an array named 'provides', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]provides_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBprovides\fP keyword is used to specify a provision\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBprovides\fP keyword is used to specify a provision\.
An architecture\-specific provision may be specified using a keyword consisting of 'provides', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]provides_aarch64\fP`\.
.El
.RE

.SB "Conflict"
.PP
This \fBpackage relation\fP specifies a component name (which may also be a package name), that a given package conflicts with\.
A conflict is usually used to ensure that package managers are not able to install two packages, that provide the same files\.
.PP
The value for a conflict is either an \fBalpm\-package\-name\fP or an \fBalpm\-comparison\fP (e\.g\. `\f[CR]example\fP` or `\f[CR]example>=1\.0\.0\fP`)\.
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more conflicts are specified using the \fBconflicts\fP array\.
Architecture\-specific conflicts may be specified using an array named 'conflicts', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]conflicts_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBconflict\fP keyword is used to specify a conflict\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBconflicts\fP keyword is used to specify a conflict\.
An architecture\-specific conflict may be specified using a keyword consisting of 'conflicts', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]conflicts_aarch64\fP`\.
.El
.RE

.SB "Replacement"
.PP
A \fBpackage relation\fP that specifies which other component or package a given package replaces upon installation\.
The feature is used e\.g\. by package managers to replace existing packages or virtual components if they are e\.g\. renamed or superseded by another project offering the same functionality\.
.PP
The value for a replacement is either an \fBalpm\-package\-name\fP or an \fBalpm\-comparison\fP (e\.g\. `\f[CR]example\fP` or `\f[CR]example>=1\.0\.0\fP`)\.
.RS
.Bl
.IP \(bu 4
In \fBPKGBUILD\fP files zero or more replacements are specified using the \fBreplaces\fP array\.
Architecture\-specific replacements may be specified using an array named 'replaces', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]replaces_aarch64\fP`\.
.El
.Bl
.IP \(bu 4
In \fBPKGINFO\fP files the \fBreplaces\fP keyword is used to specify a conflict\.
.El
.Bl
.IP \(bu 4
In \fBSRCINFO\fP files the \fBreplaces\fP keyword is used to specify a conflict\.
An architecture\-specific replacement may be specified using a keyword consisting of 'replaces', directly followed by an '_' sign, directly followed by an \fBalpm\-architecture\fP (all \fBalpm\-architectures\fP except `\f[CR]any\fP` can be used), e\.g\. `\f[CR]replaces_aarch64\fP`\.
.El
.RE

.SH "EXAMPLES"

.SS "Provisions as virtual components"
.PP
Mail servers working with the SMTP protocol can usually be used in several scenarios (e\.g\. as SMTP forwarder or server)\.
It is commonplace to have packages that only require one of these scenarios\.
Given the mail server package `\f[CR]my\-mailserver\fP`, which represents a full mail server solution, it is therefore useful to define \fBprovisions\fP for it (e\.g\. introducing the \fIvirtual components\fP `\f[CR]smtp\-forwarder\fP` and `\f[CR]smtp\-server\fP`)\.
Another mail server package \- `\f[CR]minimal\-mailserver\fP` \- can only be used as SMTP forwarder, so defining only one \fBprovision\fP (i\.e\. introducing the \fIvirtual component\fP `\f[CR]smtp\-forwarder\fP`) is possible\.
.PP
Other packages may now depend on these \fIvirtual components\fP, instead of one specific mail server:
Given the monitoring package `\f[CR]my\-monitoring\fP`, which allows sending out monitoring mails using a local SMTP forwarder, a \fBrun\-time dependency\fP can be defined for it to depend on the \fIvirtual component\fP `\f[CR]smtp\-forwarder\fP`\.
.PP
This scenario enables a package manager to provide the user with the choice to rely on one of the providers of `\f[CR]smtp\-forwarder\fP` (i\.e\. `\f[CR]my\-mailserver\fP` or `\f[CR]minimal\-mailserver\fP`)\.

.SS "Dependencies using sonames"
.PP
Some packages provide \fIshared object\fP files that \fBELF\fP[1] files in other packages may dynamically link against\.
.PP
For example, the package `\f[CR]example\fP` may contain the following files:
.RS
.PP
.nf
/usr/lib/libexample\.so \-> libexample\.so\.1
/usr/lib/libexample\.so\.1 \-> libexample\.so\.1\.0\.0
/usr/lib/libexample\.so\.1\.0\.0
.fi
.RE
.PP
Here, the shared object file `\f[CR]/usr/lib/libexample\.so\.1\.0\.0\fP` encodes the \fBsoname\fP[2] `\f[CR]libexample\.so\.1\fP`\.
.PP
Following the \fBalpm\-soname\fP specification, `\f[CR]lib:libexample\.so\.1\fP` can be added as a \fBprovision\fP to the \fBPKGINFO\fP file of the `\f[CR]example\fP` package, if the library \fIlookup directory\fP `\f[CR]/usr/lib\fP` is represented by the \fIprefix\fP `\f[CR]lib\fP`\.
.PP
Afterwards, another example package called `\f[CR]application\fP` may contain the \fBELF\fP[1] file `\f[CR]/usr/bin/application\fP`, which dynamically links against the \fIshared object\fP `\f[CR]/usr/lib/libexample\.so\.1\fP` contained in the `\f[CR]example\fP` package\.
The \fBELF\fP[1] file encodes this requirement by relying on the \fBsoname\fP[2] `\f[CR]libexample\.so\.1\fP`\.
.PP
Following the \fBalpm\-soname\fP specification, `\f[CR]lib:libexample\.so\.1\fP` can be added as a \fBrun\-time dependency\fP to the \fBPKGINFO\fP file of the `\f[CR]application\fP` package, if the library \fIlookup directory\fP `\f[CR]/usr/lib\fP` is represented by the \fIprefix\fP `\f[CR]lib\fP` and the \fIshared object\fP encoding the `\f[CR]libexample\.so\.1\fP` \fBsoname\fP[2] (here `\f[CR]/usr/lib/libexample\.so\.1\.0\.0\fP`) is present in the \fIlookup directory\fP\.
.PP
\fBNote\fP: For legacy behavior of \fBalpm\-soname\fP refer to \fBalpm\-sonamev1\fP\.

.SH "SEE ALSO"
.PP
\fBBUILDINFO\fP(5), \fBPKGBUILD\fP(5), \fBPKGINFO\fP(5), \fBSRCINFO\fP(5), \fBalpm\-architecture\fP(7), \fBalpm\-comparison\fP(7), \fBalpm\-package\-name\fP(7), \fBalpm\-package\-version\fP(7), \fBalpm\-soname\fP(7)

.SH "NOTES"
.RS
.Bl
.IP 1. 4
\fBELF\fP
.sp
https://en\.wikipedia\.org/wiki/Executable_and_Linkable_Format
.El
.Bl
.IP 2. 4
\fBsoname\fP
.sp
https://en\.wikipedia\.org/wiki/Soname
.El
.RE