On Sun, 20 Sep 2026 10:13:04 -0600
Ian Darwin <ian@darwinsys.com> wrote:

> Following a discussion with kirill and sthen, the latter sent some
> text along the lines of "DIST_TUPLE probably should be documented
> there..." and some text, which I bent, folded, spindled and mutilated
> into the following. OKs or comments?

Hi,

Proposing a diff on top of the committed one with 1 nit and one
additional example. 

[...]
> +<li><code>target_dir</code> is usually "." for the current work
> directory, +but may also be used to download the file into a
> subdirectory.</li> +</ul>

Nit: the distfiles are always download into /usr/ports/distfiles. This
is about where the files are extracted to.

There might also be a better expression than "current work directory"
which can be misunderstood. It's actually the default directory for the
extracted distfiles, aka WRKDIST.

[...]
> +Some projects require more than one distfile.
> +If you need more than one entry in <code>DIST_TUPLE</code>,
> +enter one per line with "+=" on all but the first.
> +For GitHub, the use of the <code>GH_*</code> parameters is preferred
> +over <code>DIST_TUPLE</code> for the "main" distfile;
> +<code>DIST_TUPLE</code> can be used with any secondary distfiles.
> +For the other sites listed, <code>DIST_TUPLE</code> can be used
> +for all distfiles.

I feel this could use an example to make it less confusing how these
can be combined; see diff below.

> +With some of the sites, <code>DIST_TUPLE</code> doesn't set
> +<code>WRKDIST</code> properly.
> +In this case <code>WRKDIST</code> needs to be overridden.
> +A common example is gitlab when using commit hashes instead of
> version numbers.
> +Some sites may need the hash added to the dirname even for a tagged 
> release.
> +Some trial and error, as well as examining working ports, may be
> needed. +

Another common example is that codeberg needs ${WRKDIR}/${_project}
withtout hash or version identifier.

FYI I'm working on a solution for this; hopefully some improvements
soon.

Index: guide.html
===================================================================
RCS file: /cvs/www/faq/ports/guide.html,v
diff -u -p -r1.116 guide.html
--- guide.html	20 Sep 2026 19:10:30 -0000	1.116
+++ guide.html	20 Sep 2026 22:04:38 -0000
@@ -198,7 +198,7 @@ github, gitlab, codelab, codeberg, fdo, 
 <li><code>version-or-hash</code> is either a release or tag version number, or else a
 full (40-character) git commit hash.</li>
 <li><code>target_dir</code> is usually "." for the current work directory,
-but may also be used to download the file into a subdirectory.</li>
+but may also be used to extract the distfile into a subdirectory.</li>
 </ul>
 <p>
 For example:
@@ -215,6 +215,16 @@ over <code>DIST_TUPLE</code> for the "ma
 <code>DIST_TUPLE</code> can be used with any secondary distfiles.
 For the other sites listed, <code>DIST_TUPLE</code> can be used
 for all distfiles.
+</p>
+<p>
+For example:
+<p>
+<code>GH_ACCOUNT =	someuser<br>
+GH_PROJECT =	greatproject<br>
+GH_TAGNAME =	v4.0.4<br>
+DIST_TUPLE =	gitlab	otheruser	otherproject	v0.1.2	extern/otherproject<br>
+DIST_TUPLE +=	github	randomstranger	anotherproject	v3.4.5	extern/anotherproject</code>
+</p>
 
 <p>
 With some of the sites, <code>DIST_TUPLE</code> doesn't set