From 797e7a6c53a01c25dfaf5bd81c3f616dc8c8fe74 Mon Sep 17 00:00:00 2001 From: espie Date: Mon, 21 Aug 2023 10:12:23 +0000 Subject: [PATCH] document the new DISTFILES.sufx infrastructure --- share/man/man5/bsd.port.mk.5 | 104 ++++++++++++++++++++++++----------- 1 file 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 in " +.It "Fatal: MASTER_SITES* is not defined but referenced by in " Pretty much self-explanatory. .It "Fatal: SUBPACKAGES should always begin with -: " That is the only way to differentiate between -- 2.20.1