[PR PATCH] Manual.md: expand description of virtual packages

[PR PATCH] Manual.md: expand description of virtual packages

[ahesford]

[-- Attachment #1: Type: text/plain, Size: 458 bytes --]

There is a new pull request by ahesford against master on the void-packages repository

https://github.com/ahesford/void-packages docs
https://github.com/void-linux/void-packages/pull/21990

Manual.md: expand description of virtual packages
Please check my expanded description of virtual packages for correctness. I thought the concept could use a bit more clarity.

A patch file from https://github.com/void-linux/void-packages/pull/21990.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-docs-21990.patch --]
[-- Type: text/x-diff, Size: 2000 bytes --]

From 021a15a92d167afdf0e593b217dc06d3d4d89890 Mon Sep 17 00:00:00 2001
From: "Andrew J. Hesford" <ajh@sideband.org>
Date: Fri, 15 May 2020 13:19:26 -0400
Subject: [PATCH] Manual.md: expand description of virtual packages

---
 Manual.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Manual.md b/Manual.md
index 576b3d2032e..3da8ac4d4c9 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1162,10 +1162,16 @@ Dependencies declared via `${depends}` are not installed to the master directory
 only checked if they exist as binary packages, and are built automatically by `xbps-src` if
 the specified version is not in the local repository.
 
-There's a special variant of how `virtual` dependencies can be specified as `runtime dependencies`
-and is by using the `virtual?` keyword, i.e `depends="virtual?vpkg-0.1_1"`. This declares
-a `runtime` virtual dependency to `vpkg-0.1_1`; this `virtual` dependency will be simply ignored
-when the package is being built with `xbps-src`.
+As a special case, `virtual` dependencies may be specified as runtime dependencies in the
+`${depends}` template variable. Several conflicting packages can provide common functionality by
+declaring a virtual name and version in the `${provides}` template variable (e.g.,
+`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the
+specific provider can declare a dependency on the virtual package name with the prefix `virtual?`
+(e.g., `depends="virtual?vpkg-0.1_1"`). Virtual dependencies will generally be ignored when the
+package is being built with `xbps-src`, except to ensure the availability of a virtual provider
+during the build. A map from virtual packages to their default providers is defined in
+`etc/default.virtual`. Individual mappings can be overridden by local preferences in `etc/virtual`.
+Comments in `etc/default.virtual` provide more information on this map.
 
 <a id="install_remove_files"></a>
 ### INSTALL and REMOVE files

Re: [PR PATCH] [Updated] Manual.md: expand description of virtual packages

[ahesford]

[-- Attachment #1: Type: text/plain, Size: 463 bytes --]

There is an updated pull request by ahesford against master on the void-packages repository

https://github.com/ahesford/void-packages docs
https://github.com/void-linux/void-packages/pull/21990

Manual.md: expand description of virtual packages
Please check my expanded description of virtual packages for correctness. I thought the concept could use a bit more clarity.

A patch file from https://github.com/void-linux/void-packages/pull/21990.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-docs-21990.patch --]
[-- Type: text/x-diff, Size: 1963 bytes --]

From b3b0ba5d96461c7beda3e1248acc031ba3c98bdd Mon Sep 17 00:00:00 2001
From: "Andrew J. Hesford" <ajh@sideband.org>
Date: Fri, 15 May 2020 13:19:26 -0400
Subject: [PATCH] Manual.md: expand description of virtual packages

---
 Manual.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Manual.md b/Manual.md
index 576b3d2032e..33d56ba1781 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1162,10 +1162,16 @@ Dependencies declared via `${depends}` are not installed to the master directory
 only checked if they exist as binary packages, and are built automatically by `xbps-src` if
 the specified version is not in the local repository.
 
-There's a special variant of how `virtual` dependencies can be specified as `runtime dependencies`
-and is by using the `virtual?` keyword, i.e `depends="virtual?vpkg-0.1_1"`. This declares
-a `runtime` virtual dependency to `vpkg-0.1_1`; this `virtual` dependency will be simply ignored
-when the package is being built with `xbps-src`.
+As a special case, `virtual` dependencies may be specified as runtime dependencies in the
+`${depends}` template variable. Several conflicting packages can provide common functionality by
+declaring a virtual name and version in the `${provides}` template variable (e.g.,
+`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the
+specific provider can declare a dependency on the virtual package name with the prefix `virtual?`
+(e.g., `depends="virtual?vpkg-0.1_1"`). When a package is built by `xbps-src`, providers for any
+virtual packages will be confirmed to exist and will be built if necessary. A map from virtual
+packages to their default providers is defined in `etc/default.virtual`. Individual mappings can be
+overridden by local preferences in `etc/virtual`. Comments in `etc/default.virtual` provide more
+information on this map.
 
 <a id="install_remove_files"></a>
 ### INSTALL and REMOVE files

Re: [PR PATCH] [Updated] Manual.md: expand description of virtual packages

[ahesford]

[-- Attachment #1: Type: text/plain, Size: 463 bytes --]

There is an updated pull request by ahesford against master on the void-packages repository

https://github.com/ahesford/void-packages docs
https://github.com/void-linux/void-packages/pull/21990

Manual.md: expand description of virtual packages
Please check my expanded description of virtual packages for correctness. I thought the concept could use a bit more clarity.

A patch file from https://github.com/void-linux/void-packages/pull/21990.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-docs-21990.patch --]
[-- Type: text/x-diff, Size: 1961 bytes --]

From 89ac5e5debe8cea02b8af384fa41f8c649710531 Mon Sep 17 00:00:00 2001
From: "Andrew J. Hesford" <ajh@sideband.org>
Date: Fri, 15 May 2020 13:19:26 -0400
Subject: [PATCH] Manual.md: expand description of virtual packages

---
 Manual.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Manual.md b/Manual.md
index 576b3d2032e..f6c6f457451 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1162,10 +1162,16 @@ Dependencies declared via `${depends}` are not installed to the master directory
 only checked if they exist as binary packages, and are built automatically by `xbps-src` if
 the specified version is not in the local repository.
 
-There's a special variant of how `virtual` dependencies can be specified as `runtime dependencies`
-and is by using the `virtual?` keyword, i.e `depends="virtual?vpkg-0.1_1"`. This declares
-a `runtime` virtual dependency to `vpkg-0.1_1`; this `virtual` dependency will be simply ignored
-when the package is being built with `xbps-src`.
+As a special case, `virtual` dependencies may be specified as runtime dependencies in the
+`${depends}` template variable. Several different packages can provide common functionality by
+declaring a virtual name and version in the `${provides}` template variable (e.g.,
+`provides="vpkg-0.1_1"`). Packages that rely on the common functionality without concern for the
+specific provider can declare a dependency on the virtual package name with the prefix `virtual?`
+(e.g., `depends="virtual?vpkg-0.1_1"`). When a package is built by `xbps-src`, providers for any
+virtual packages will be confirmed to exist and will be built if necessary. A map from virtual
+packages to their default providers is defined in `etc/default.virtual`. Individual mappings can be
+overridden by local preferences in `etc/virtual`. Comments in `etc/default.virtual` provide more
+information on this map.
 
 <a id="install_remove_files"></a>
 ### INSTALL and REMOVE files

Re: [PR PATCH] [Merged]: Manual.md: expand description of virtual packages

[pullmoll]

[-- Attachment #1: Type: text/plain, Size: 308 bytes --]

There's a merged pull request on the void-packages repository

Manual.md: expand description of virtual packages
https://github.com/void-linux/void-packages/pull/21990

Description:
Please check my expanded description of virtual packages for correctness. I thought the concept could use a bit more clarity.