On Sat, 17 Oct 2026 18:19:11 +0200
Marc Espie <[email protected]> wrote:
> Contrary to the comments in your patch, it does not say it actually
> sets WRKDIST, nor do you give examples, contrary to the other
> templates.
>
> It's also not really clear for me (again from your patch) what's the
> rationale behind the actual values for github and codeberg.
>
> Also, it puts two variables inside the DIST_TUPLE description
> (TEMPLATE_EXTRACT_DIR and ID_MOD), they should have independent
> entries. It's not clear at all how all these are related.
>
> At this point, I think that the DIST_TUPLE stuff would benefit from
> having its own subsection in bsd.port.mk(5).
>
> e.g., just say in the main body that DIST_TUPLE is used for various
> forges and reference the other variables in there (TEMPLATE*).
>
> Also put a one-liner for each template, and group everything together
> in a
> .Ss THE DIST_TUPLE FRAMEWORK
> subsection.
>
> You could in particular document each substitution pattern
> appropriately, and how all the variables relate to each other.
>
>
> e.g, the main document would have something like
>
> .Ev DIST_TUPLE
> Framework for fetching
> .Ev DISTFILES
> from one of the forges.
> May also use
> .Ev ID_MOD.* ,
> .Ev TEMPLATE_DISTFILES.* ,
> .Ev TEMPLATE_EXTRACT_DIR.* ,
> .Ev TEMPLATE_HOMEPAGE.*
> for proper behavior.
> See
> .Sx THE DIST_TUPLE FRAMEWORK
> section below.
>
> ...
>
> .Ev ID_MOD.*
> Part of
> .Sx THE DIST_TUPLE_FRAMEWORK
>
> ...
>
> Then you can document it properly in one single section.
New bsd.port.mk.5 diff below. If this or something building on it ends
up going in, I think we could remove the comments in dist-tuple.pattern
that are essentially stating the same thing. The duplication risks
being a source of future confusion otherwise.
ok? comments?
(ok would by necessity include the DIST_TUPLE diff itself from earlier
in the email thread; attached again for convenience)
Index: bsd.port.mk.5
===================================================================
RCS file: /cvs/src/share/man/man5/bsd.port.mk.5,v
diff -u -p -r1.658 bsd.port.mk.5
--- bsd.port.mk.5 21 Oct 2026 09:09:47 -0000 1.658
+++ bsd.port.mk.5 24 Oct 2026 03:59:06 -0000
@@ -1684,43 +1684,23 @@ directories and needs to be configured w
.Sq gnu dest ,
so that those few directories do not get in the way.
.It Ev DIST_TUPLE
-List of distfile templates to use, each consisting of five entries:
-.Ar name account project tagname/commithash targetdir .
-The template
-.Ar name
-should be one of
-.Sq codeberg ,
-.Sq fdo ,
-.Sq github ,
-.Sq gitlab ,
-.Sq gnome ,
-.Sq kde ,
-or
-.Sq srht
-at the moment
-.Po see
+Framework for fetching
+.Ev DISTFILES
+from one of the forges.
+The way to handle
+.Ev DISTFILES
+fetching and extraction is specific to each forge and usually set in
.Pa ${PORTSDIR}/infrastructure/db/dist-tuple.pattern ,
-additional
-.Ev TEMPLATE_DISTFILES.<name>
+with a combination of some or all of
+.Ev ID_MOD.* ,
+.Ev TEMPLATE_DISTFILES.* ,
+.Ev TEMPLATE_EXTRACT_DIR.* ,
+.Ev TEMPLATE_EXTRACT_SUFX.* ,
and
-.Ev TEMPLATE_HOMEPAGE.<name>
-entries can be added as needed
-.Pc .
-The components are used to build
-.Ev SITES.name
-.Ev DISTFILES.name
-and (optionally)
-.Ev HOMEPAGE .
-.Pp
-At the end of
-.Cm post-extract ,
-the files are moved to
-.Pa ${WRKDIST}/<targetdir> .
-Using
-.Sq \&.
-for
-.Ar targetdir
-will disable the move.
+.Ev TEMPLATE_HOMEPAGE.* .
+See
+.Sx THE DIST_TUPLE FRAMEWORK
+section below.
.It Ev DISTDIR
User settings.
Directory where all ports distribution files and patchfiles are stashed.
@@ -3493,47 +3473,6 @@ and module hooks
Used by introspection tools such as the
.Pa sqlports
package.
-.It Ev TEMPLATE_DISTFILES.<name>
-Template used to construct
-.Ev DISTFILES.name
-based on a
-.Ev DIST_TUPLE
-entry by filling in placeholder strings.
-For instance,
-.Ev TEMPLATE_DISTFILES.github
-defaults to
-.Bd -literal
-<account>-<project>-{<account>/<project>/archive/<subdir>}<id>.tar.gz
-.Ed
-.Pp
-with
-.Li DIST_TUPLE += github foo bar baz qux.
-We end up with the following
-.Ev DISTFILES.github
-entry:
-.Bd -literal -offset indent
-foo-bar-{foo/bar/archive/ref/tags}baz.tar.gz
-.Ed
-.Pp
-Placeholders
-.Sq account ,
-.Sq project ,
-.Sq id
-are self-explanatory.
-.Sq subdir
-is set automatically by figuring out whether
-.Ar id
-is a
-.Ar tagname
-or a
-.Ar hash .
-.It Ev TEMPLATE_HOMEPAGE.<name>
-Template for automatically generated
-.Ev HOMEPAGE
-when using
-.Ev DIST_TUPLE .
-Very similar to
-.Ev TEMPLATE_DISTFILES.<name> .
.It Ev TEST_DEPENDS
See
.Ev BUILD_DEPENDS
@@ -3961,6 +3900,170 @@ during
(see the
.Sx FILES
section above for details).
+.Sh THE DIST_TUPLE FRAMEWORK
+.Ev DIST_TUPLE is used for handling
+.Ev DISTFILES
+obtained from supported upstream code forges.
+It is invoked by defining it in a port's
+.Pa Makefile ,
+and consists of exactly 5 entries:
+.Ar name account project tagname/commithash targetdir .
+The
+.Ar name
+determines the template for generating the information to fetch and extract the
+.Ev DISTFILES
+correctly.
+It should be one of
+.Sq codeberg ,
+.Sq fdo ,
+.Sq github ,
+.Sq gitlab ,
+.Sq gnome ,
+.Sq kde ,
+or
+.Sq srht
+at the moment
+.Po see
+.Pa ${PORTSDIR}/infrastructure/db/dist-tuple.pattern
+.Pc .
+The other components are used to build
+.Ev SITES.name ,
+.Ev DISTFILES.name ,
+.Ev HOMEPAGE
+and the path of the extracted directory.
+The typical case is to use
+.Sq \&.
+for
+.Ar targetdir .
+This extracts
+.Ev DISTFILES.name
+in
+.Ev WRKDIR
+and by default sets the port's
+.Ev DISTNAME
+and
+.Ev WRKDIST .
+Setting
+.Ar targetdir
+to a
+.Em relative
+path will extract the files to said path under
+.Ev WRKDIST
+.Pq which must be otherwise defined .
+Multiple entries of
+.Ev DIST_TUPLE
+can be combined to arrange the files from different repositories in a tree.
+.Pp
+The flexibility to handle different forges comes from the variables set in
+.Pa ${PORTSDIR}/infrastructure/db/dist-tuple.pattern ,
+outlined as follows with
+.Sq *
+replaced by the forge's
+.Ar name:
+.Bl -tag -width Ds
+.It ID_MOD.*.hash
+Modfier for the
+.Sq <mod_id>
+portion of
+.Ev TEMPLATE_EXTRACT_DIR.*.hash ,
+see
+.Xr make 1
+for available modifiers.
+.It ID_MOD.*.tag
+Same for
+.Sq <mod_id>
+in
+.Ev TEMPLATE_EXTRACT_DIR.*.tag .
+.It SITES.*
+The primary location where
+.Ev DISTFILES.*
+are found for the specific forge.
+See
+.Ev SITES* .
+.It Ev TEMPLATE_DISTFILES.*
+Template used to construct
+.Ev DISTFILES.*
+based on a
+.Ev DIST_TUPLE
+entry by filling in placeholder strings.
+For instance,
+.Ev TEMPLATE_DISTFILES.github
+defaults to:
+.Bd -literal -offset indent
+<account>-<project>-{<account>/<project>/archive/<subdir>}<id>.tar.gz
+.Ed
+.Pp
+With
+.Li DIST_TUPLE += github foo bar baz qux ,
+we end up with the following
+.Ev DISTFILES.github
+entry:
+.Bd -literal -offset indent
+foo-bar-{foo/bar/archive/ref/tags}baz.tar.gz
+.Ed
+.Pp
+Placeholders
+.Sq account ,
+.Sq project ,
+.Sq id
+are self-explanatory.
+.Sq subdir
+is set automatically by figuring out whether
+.Ar id
+is a
+.Ar tagname
+or a
+.Ar commithash .
+.It TEMPLATE_EXTRACT_DIR.*.hash
+This pattern must match the directory that is extracted from
+.Ev DISTFILES.* .
+Uses the same substitutions as in
+.Ev TEMPLATE.DISTFILES.* .
+In addition,
+.Ql <mod_id>
+may be used.
+This is substituted like
+.Ql <id> ,
+but also modified by
+.Ev ID_MOD.*.hash .
+If
+.Ev TEMPLATE_DISTFILES.*.hash
+is not defined, it falls back to a heuristically modified version of
+.Ql <project>-<id> .
+If this is not done or relies on information that is not part of
+.Ev DIST_TUPLE ,
+then
+.Ev WRKDIST
+and potentially
+.Po
+if using a directory in
+.Ar targetdir
+.Pc
+also
+.Ev MODDIST-TUPLE_post-extract
+may need to be defined in the port.
+.It TEMPLATE_EXTRACT_DIR.*.tag
+Same as
+.Ev TEMPLATE_EXTRACT_DIR.*.hash ,
+except it applies when a
+.Ar tagname
+is used and modifies
+.Ql <mod_id>
+with
+.Ev ID_MOD.*.tag .
+.It TEMPLATE_EXTRACT_SUFX.*
+Sets
+.Ev EXTRACT_SUFX.* ;
+defaults to
+.Sq .tar.gz .
+.It TEMPLATE_HOMEPAGE.*
+Generates
+.Ev HOMEPAGE
+with the same substitutions as
+.Ev TEMPLATE_DISTFILES.* .
+Defaults to
+.Sq <site><account>/<project> .
+.El
.Sh THE DEBUG_PACKAGES INFRASTRUCTURE
If
.Ev DEBUG_PACKAGES
Index: db/dist-tuple.pattern
===================================================================
RCS file: /cvs/ports/infrastructure/db/dist-tuple.pattern,v
diff -u -p -r1.13 dist-tuple.pattern
--- db/dist-tuple.pattern 16 Jan 2026 06:12:28 -0000 1.13
+++ db/dist-tuple.pattern 15 Oct 2026 14:23:19 -0000
@@ -36,6 +36,20 @@ TEMPLATE_DISTFILES.kde ?= \
TEMPLATE_DISTFILES.srht ?= \
<account>-<project>-{~<account>/<project>/archive/}<id>${EXTRACT_SUFX.srht}
+# Template for the directory created upon extraction of the distfile.
+# This is used 1) for setting WRKDIST where needed, and 2) to use the
+# correct path for the post-extract target.
+# Format: TEMPLATE_EXTRACT_DIR.x.y, where x is the template and y is
+# either tag or hash
+# Defaults to a (heuristically modified) version of <project>-<id>.
+# Can use <mod_id>: the <id> string, modified with ID_MOD.x.y,
+# according to make(1) rules.
+TEMPLATE_EXTRACT_DIR.codeberg.tag ?= <project>
+TEMPLATE_EXTRACT_DIR.codeberg.hash ?= <project>
+
+TEMPLATE_EXTRACT_DIR.github.tag ?= <project>-<mod_id>
+ID_MOD.github.tag ?= :C/^(v|V)([0-9])/\2/
+
# template for HOMEPAGE; same substitutions as for DISTFILES.x
# Defaults to TEMPLATE_HOMEPAGE. Set TEMPLATE_HOMEPAGE.x to use different pattern.
# - <site> - substituted, may correspond to SITES.x
Index: mk/bsd.port.mk
===================================================================
RCS file: /cvs/ports/infrastructure/mk/bsd.port.mk,v
diff -u -p -r1.1652 bsd.port.mk
--- mk/bsd.port.mk 19 Sep 2026 23:17:29 -0000 1.1652
+++ mk/bsd.port.mk 15 Oct 2026 14:23:19 -0000
@@ -897,8 +897,6 @@ WRKDIST ?= ${WRKDIR}/${GH_PROJECT}-${GH_
WRKDIST ?= ${WRKDIR}/${GH_PROJECT}-${GH_COMMIT}
.elif defined(DISTNAME)
WRKDIST ?= ${WRKDIR}/${DISTNAME}
-.elif !empty(_DT_WRKDIST)
-WRKDIST ?= ${_DT_WRKDIST}
.else
WRKDIST ?= ${WRKDIR}
.endif
Index: mk/dist-tuple.port.mk
===================================================================
RCS file: /cvs/ports/infrastructure/mk/dist-tuple.port.mk,v
diff -u -p -r1.22 dist-tuple.port.mk
--- mk/dist-tuple.port.mk 1 Apr 2026 15:14:57 -0000 1.22
+++ mk/dist-tuple.port.mk 15 Oct 2026 14:23:19 -0000
@@ -1,14 +1,14 @@
# DIST_TUPLE: 5 elements
# use targetdir=. if you don't want to move files after extraction
# Syntax:
-# DIST_TUPLE += template account project id(commit/tag) targetdir # license
+# DIST_TUPLE += template account project id(commit/tag) targetdir
#
# Examples:
-# DIST_TUPLE += github vim vim v9.0.1677 . # VIM License / donation-ware
+# DIST_TUPLE += github vim vim v9.0.1677 .
# DIST_TUPLE += gitlab Mr_Goldberg goldberg_emulator \
-# 475342f0d8b2bd7eb0d93bd7cfdd61e3ae7cda24 . # LGPLv3
+# 475342f0d8b2bd7eb0d93bd7cfdd61e3ae7cda24 .
# DIST_TUPLE += github FNA-XNA FNA.NetStub ebff244074bb3c28aeeb8cf7b383b5a029d7e28d \
-# ../FNA.NetStub # Ms-PL
+# ../FNA.NetStub
DIST_TUPLE ?=
# Caveats:
@@ -18,40 +18,71 @@ DIST_TUPLE ?=
.include "${PORTSDIR}/infrastructure/db/dist-tuple.pattern"
.if !empty(DIST_TUPLE)
-. for _template _account _project _id _targetdir in ${DIST_TUPLE}
-. if empty(SITES.${_template})
+. for __template __account __project __id __targetdir in ${DIST_TUPLE}
+
+. for __id_type in tag hash
+# inert substitution by default; this can't be an empty element
+ID_MOD.${__template}.${__id_type} ?= :S///
+. endfor
+
+. for _template _account _project _id _id_mod_tag _id_mod_hash _targetdir in ${__template} ${__account} ${__project} ${__id} ${ID_MOD.${__template}.tag} ${ID_MOD.${__template}.hash} ${__targetdir}
+
+. if empty(SITES.${_template})
ERRORS += "Fatal: invalid choice for DIST_TUPLE: ${_template}"
-. endif
+. endif
-_subdir =
-. if "${_id}" == "HASH" || "${_id:C/^[0-9a-f]{10,40}$/HASH/}" != "HASH"
-# set DISTNAME if not done by the port and add refs/tags/ subdir
-_distname ?= ${_project}-${_id:C/^(v|V|ver|[Rr]el|[Rr]elease)[-._]?([0-9])/\2/:S,/,-,g}
-DISTNAME ?= ${_distname}
-_subdir = refs/tags/
-_DT_WRKDIST ?= ${WRKDIR}/${_distname}
-. else
-_DT_WRKDIST ?= ${WRKDIR}/${_project:C,^.*/,,}-${_id}
+# create _FULL_DIST_TUPLE with derived variables
+_FULL_DIST_TUPLE += ${_template} ${_account} ${_project} ${_id} ${_targetdir}
+
+. if "${_id}" == "HASH" || "${_id:C/^[0-9a-f]{10,40}$/HASH/}" != "HASH"
+# tag mode
+_FULL_DIST_TUPLE += tag
+_FULL_DIST_TUPLE += ${_project}-${_id:C/^(v|V|ver|[Rr]el|[Rr]elease)[-._]?([0-9])/\2/:S,/,-,g}
+. if !empty(TEMPLATE_EXTRACT_DIR.${_template}.tag)
+_FULL_DIST_TUPLE += ${TEMPLATE_EXTRACT_DIR.${_template}.tag}
+. else
+_FULL_DIST_TUPLE += <defaultname>
+. endif
+# XXX: refs/tags/ is only useful for template github
+_FULL_DIST_TUPLE += S,<account>,${_account},g:S,<project>,${_project},g:S,<id>,${_id},g:S,<subdir>,refs/tags/,g:S,<site>,${SITES.${_template}},g:S,<defaultname>,${_project}-${_id:C/^(v|V|ver|[Rr]el|[Rr]elease)[-._]?([0-9])/\2/:S,/,-,g},g:S,<mod_id>,${_id${_id_mod_tag}},g
+
+. else
+# hash mode
+_FULL_DIST_TUPLE += hash
+_FULL_DIST_TUPLE += ${_project}-${_id}
+. if !empty(TEMPLATE_EXTRACT_DIR.${_template}.hash)
+_FULL_DIST_TUPLE += ${TEMPLATE_EXTRACT_DIR.${_template}.hash}
+. else
+_FULL_DIST_TUPLE += <defaultname>
+. endif
+_FULL_DIST_TUPLE += S,<account>,${_account},g:S,<project>,${_project},g:S,<id>,${_id},g:S,<subdir>,,g:S,<site>,${SITES.${_template}},g:S,<defaultname>,${_project}-${_id},g:S,<mod_id>,${_id${_id_mod_hash}},g
+. endif
+. endfor
+. endfor
+
+. for _template _account _project _id _targetdir _mode _defaultname _extrdir_temp _subst in ${_FULL_DIST_TUPLE}
+
+. if "${_mode}" == "tag" && !defined(GH_TAGNAME)
+# Yield to GH_TAGNAME; it takes precedence and is set later in bsd.port.mk with ?=.
+# Only set DISTNAME for tag; commit hashes are not desired for this.
+DISTNAME ?= ${_defaultname}
. endif
-. for _subst in S,<account>,${_account},g:S,<project>,${_project},g:S,<id>,${_id},g:S,<subdir>,${_subdir},g:S,<site>,${SITES.${_template}},g
+. for _extrdir in ${_extrdir_temp:${_subst}}
DISTFILES.${_template} += ${TEMPLATE_DISTFILES.${_template}:${_subst}}
EXTRACT_SUFX.${_template} ?= ${TEMPLATE_EXTRACT_SUFX}
TEMPLATE_HOMEPAGE.${_template} ?= ${TEMPLATE_HOMEPAGE}
-HOMEPAGE ?= ${TEMPLATE_HOMEPAGE.${_template}:${_subst}}
+HOMEPAGE ?= ${TEMPLATE_HOMEPAGE.${_template}:${_subst}}
-. if "${_targetdir}" != "." && "${_template}" == "codeberg"
-MODDIST-TUPLE_post-extract += \
- t=${WRKDIST}/${_targetdir}; [[ -d $$t ]] && rmdir $$t \
- || mkdir -p `dirname $$t` ; \
- mv ${WRKDIR}/${_project:T} $$t;
-. elif "${_targetdir}" != "."
+. if "${_targetdir}" == "."
+WRKDIST ?= ${WRKDIR}/${_extrdir}
+. else
MODDIST-TUPLE_post-extract += \
t=${WRKDIST}/${_targetdir}; [[ -d $$t ]] && rmdir $$t \
|| mkdir -p `dirname $$t` ; \
- mv ${WRKDIR}/${_project:T}-${_id:S/refs\/tags\///:C/^v([0-9])/\1/} $$t;
+ mv ${WRKDIR}/${_extrdir} $$t;
. endif
. endfor