document the new DISTFILES.sufx infrastructure

1 files changed, 71 insertions, 33 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index 29c154dd8e6..97313337165 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.579 2023/08/08 12:46:56 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.580 2023/08/21 10:12:23 espie Exp $
 .\"
 .\" Copyright (c) 2000-2008 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 8 2023 $
+.Dd $Mdocdate: August 21 2023 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -153,7 +153,7 @@ Check that patches would apply cleanly, but do not modify anything.
 Compute a
 .Xr sha256 1
 digest
-of ${CHECKSUMFILES} (files listed in DISTFILES and PATCHFILES) and
+of ${CHECKSUMFILES} (files listed in DISTFILES* and PATCHFILES*) and
 check it against ${CHECKSUM_FILE}, normally
 .Pa distinfo .
 In case of a mismatch, running
@@ -286,12 +286,12 @@ See
 .Cm print-package-args .
 .It Cm fetch
 Fetch the list of files in
-.Ev DISTFILES
+.Ev DISTFILES*
 and
-.Ev PATCHFILES
+.Ev PATCHFILES*
 using ${FETCH_CMD}.
 Files are normally retrieved from the list of sites in
-.Ev MASTER_SITES .
+.Ev MASTER_SITES* .
 .Pp
 Appending
 .Sq :0
@@ -303,6 +303,19 @@ ${FETCH_CMD} retrieve from
 to
 .Ev MASTER_SITES9
 instead.
+.Pp
+Preferably, adding a suffix to
+.Ev DISTFILES ,
+.Ev PATCHFILES ,
+.Ev SUPDISTFILES
+will switch the site entry to the corresponding
+.Ev MASTER_SITES
+variable, e.g.,
+.Bd -literal -offset indent
+DISTFILES.go = ...
+MASTER_SITES.go = ...
+.Ed
+.Pp
 If the rest of the entry parses as
 .Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx
 ${FETCH_CMD} will fetch
@@ -332,24 +345,23 @@ hooks is forbidden, as this would make mirroring of distfiles very complicated.
 See
 .Ev CHECKSUMFILES ,
 .Ev DISTDIR ,
-.Ev DISTFILES ,
+.Ev DISTFILES* ,
 .Ev DIST_SUBDIR ,
 .Ev FETCH_CMD ,
 .Ev FETCH_MANUALLY ,
-.Ev FETCH_SYMLINK_DISTFILES ,
 .Ev FULLDISTDIR ,
 .Ev MAKESUMFILES ,
-.Ev MASTER_SITES ,
+.Ev MASTER_SITES* ,
 .Ev MASTER_SITES0 , ... ,
 .Ev MASTER_SITES9 ,
-.Ev PATCHFILES ,
-.Ev SUPDISTFILES ,
+.Ev PATCHFILES* ,
+.Ev SUPDISTFILES* ,
 .Ev REFETCH .
 .It Cm fetch-all
 Like
 .Cm fetch ,
 but also fetches
-.Ev SUPDISTFILES ,
+.Ev SUPDISTFILES* ,
 for use with e.g.,
 .Cm makesum .
 .It Cm fix-permissions
@@ -458,7 +470,7 @@ for details.
 Run
 .Xr sha256 1
 on ${MAKESUMFILES}
-that is, files listed in ${DISTFILES}, ${SUPDISTFILES} and ${PATCHFILES},
+that is, files listed in ${DISTFILES*}, ${SUPDISTFILES*} and ${PATCHFILES*},
 and store the result in ${CHECKSUM_FILE}, normally
 .Pa distinfo .
 Also store the lengths of all files for a quick check during
@@ -1547,10 +1559,10 @@ Always use
 to refer to ports' distribution files location, as it takes an eventual
 .Ev DIST_SUBDIR
 into account.
-.It Ev DISTFILES
+.It Ev DISTFILES*
 The main port's distribution files (the actual software source, except
 for binary-only ports).
-Will be retrieved from the MASTER_SITES (see
+Will be retrieved from the corresponding MASTER_SITES* (see
 .Cm fetch ) ,
 checksummed and extracted (see
 .Cm checksum ,
@@ -1563,6 +1575,16 @@ to
 appended to select a different
 .Ev MASTER_SITES .
 .Pp
+Preferably, adding a suffix to
+.Ev DISTFILES ,
+will switch the site entry to the corresponding
+.Ev MASTER_SITES
+variable, e.g.,
+.Bd -literal -offset indent
+DISTFILES.go = ...
+MASTER_SITES.go = ...
+.Ed
+.Pp
 Each entry may optionally be of the form
 .Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx
 to deal with sites that only offer archives as weird urls, doing the transfer
@@ -1582,17 +1604,17 @@ will retrieve from url
 into
 .Sq minetest-${V}${EXTRACT_SUFX} .
 .Pp
-If ${DISTFILES} varies depending on
+If ${DISTFILES*} varies depending on
 .Ev FLAVORS
 or architecture, use
-.Ev SUPDISTFILES
+.Ev SUPDISTFILES*
 to ensure distfiles mirroring and
 .Cm makesum
 proper operation.
 .It Ev DISTNAME
 Name used to identify the port.
 See
-.Ev DISTFILES
+.Ev DISTFILES*
 and
 .Ev PKGNAME .
 .It Ev DISTORIG
@@ -1748,6 +1770,12 @@ Used to set DISTFILES default value to ${DISTNAME}${EXTRACT_SUFX}.
 The decompression tool needed will be automatically added as
 .Ev BUILD_DEPENDS .
 Default value is .tar.gz.
+.Pp
+Note that
+.Ev DISTFILES
+will only be set in the absence of
+.Ev DISTFILES.sufx
+as well.
 .It Ev EXTRACT_FILES
 Set to the list of files to actually extract from distfiles.
 Its content is subject to shell evaluation as part of
@@ -1912,8 +1940,8 @@ the
 target will also update installed packages even when the signature
 did not change.
 .It Ev FULLDISTDIR
-Complete path to directory where ${DISTFILES} and ${PATCHFILES} will be
-located, to be used in hand-crafted extraction targets.
+Complete path to directory where ${DISTFILES*} ${SUPDISTFILES*} and
+${PATCHFILES*} will be located, to be used in hand-crafted extraction targets.
 Read-only.
 .It Ev FULLPKGNAME
 Full name of the created package, taking flavors into account.
@@ -1944,7 +1972,7 @@ Set by
 .Nm
 to the generated name of the distribution file.
 This can be useful for ports listing multiple
-.Ev DISTFILES .
+.Ev DISTFILES* .
 .It Ev GH_PROJECT
 Name of the project on GitHub.
 .It Ev GH_TAGNAME
@@ -2205,6 +2233,16 @@ see
 See
 .Xr ports 7
 for user configuration.
+.It Ev MASTER_SITES*
+List of alternate locations from which ${DISTFILES*}, ${PATCHFILES*},
+${SUPDISTFILES*} are retrieved.
+See
+.Cm fetch
+for details.
+Suffix should start with
+.Sq \&.
+for consistency.
+.Pp
 .It Ev MASTER_SITES0 , ... , MASTER_SITES9
 Supplementary locations from which distribution files and patchfiles are
 retrieved.
@@ -2416,7 +2454,7 @@ to re-generate
 by looking for files using this suffix.
 Defaults to
 .Pa .orig.port .
-In the unlikely event that one of the ${DISTFILES} already contains
+In the unlikely event that one of the ${DISTFILES*} already contains
 .Pa .orig.port
 files, set this to something else, such as
 .Pa .orig.obsdport .
@@ -2427,7 +2465,7 @@ See also
 In the normal
 .Cm distpatch
 stage (when
-.Ev PATCHFILES
+.Ev PATCHFILES*
 is not empty), this is the contents of a case statement, used to apply
 distribution patches.
 Fragments are automatically appended to handle gzip'ed, bzip'ed and lzip'ed
@@ -2456,15 +2494,15 @@ Location for patches applied by the
 target.
 Default:
 .Pa patches .
-.It Ev PATCHFILES
+.It Ev PATCHFILES*
 Files to fetch from the master sites like
-.Ev DISTFILES ,
+.Ev DISTFILES* ,
 but serving a different purpose, as they hold distribution patches that
 will be applied at the
 .Cm patch
 stage.
 See also
-.Ev SUPDISTFILES .
+.Ev SUPDISTFILES* .
 .It Ev PATCH_ARGS
 Full list of options used while applying port's patches.
 .It Ev PATCH_CHECK_ONLY
@@ -3150,20 +3188,20 @@ in
 .Xr mk.conf 5 ,
 the ports tree will only invoke root's privileges for the parts that
 really require it.
-.It Ev SUPDISTFILES
+.It Ev SUPDISTFILES*
 Supplementary files that need to be retrieved under some specific
 circumstances.
 For instance, a port might need architecture-specific files.
-.Ev SUPDISTFILES
+.Ev SUPDISTFILES*
 should hold a list of all distribution files and patchfiles that are not
 always needed, so that a mirror will be able to grab all files, or that
 .Cm makesum
 will work.
 Having an overlap between
-.Ev SUPDISTFILES
+.Ev SUPDISTFILES*
 and
-.Ev DISTFILES ,
-.Ev PATCHFILES
+.Ev DISTFILES* ,
+.Ev PATCHFILES*
 is admissible, and in fact, expected, as it is much simpler to build
 an error-free list of files to retrieve in that way.
 See the xanim port for an example.
@@ -4084,7 +4122,7 @@ Holds the output of
 .Xr cksum 1 ,
 using
 .Xr sha256 1
-for the port's ${DISTFILES} and ${PATCHFILES},
+for the port's ${DISTFILES*}, ${SUPDISFILES*} and ${PATCHFILES*},
 as well as the sizes of these files.
 .It Pa ${DISTDIR}/${CHECKSUMFILES}
 Cache of normal distribution files for a given port.
@@ -4245,7 +4283,7 @@ resulting in a double inclusion.
 This would lead to weird results, such as
 .Ev PKG_ARGS
 being defined twice.
-.It "Fatal: MASTER_SITESn is not defined but referenced by <file> in <DISTFILES/PATCHFILES/SUPDISTFILES>"
+.It "Fatal: MASTER_SITES* is not defined but referenced by <file> in <DISTFILES*/PATCHFILES*/SUPDISTFILES*>"
 Pretty much self-explanatory.
 .It "Fatal: SUBPACKAGES should always begin with -: <offending list>"
 That is the only way to differentiate between