On Sun, 20 Sep 2026 10:13:04 -0600
Ian Darwin <[email protected]> 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
