From: Ian Darwin <ian@darwinsys.com>
Subject: Start to document DIST_TUPLE
To: ports <ports@openbsd.org>
Date: Sun, 20 Sep 2026 10:13:04 -0600

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?

Index: guide.html
===================================================================
RCS file: /cvs/www/faq/ports/guide.html,v
diff -u -p -r1.115 guide.html
--- guide.html    2 Jul 2026 11:51:57 -0000    1.115
+++ guide.html    20 Sep 2026 16:08:13 -0000
@@ -181,6 +181,51 @@ You can check to see if you have filled
  </ul>

  <p>
+An alternative way of specifying downloads is <code>DIST_TUPLE</code>.
+This is useful in setting up downloads from the git code repositories
+listed under "sitecode" below.
+
+<p>
+The format of a <code>DIST_TUPLE</code> is five tab-separated fields:
+<p>
+<code>sitecode account repository version-or-hash target-dir</code>
+</p>
+<ul>
+<li><code>sitecode</code> is one of
+github, gitlab, codelab, codeberg, fdo, srht, kde, or gnome.
+/li>
+<li><code>account</code> is the repository owner's account name on that 
site</li>
+<li><code>repository</code> is the name of the repository within that 
user's account</li>
+<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>
+</ul>
+<p>
+For example:
+<p>
+<code>DIST_TUPLE =        github    someuser    greatlib v4.0.4    .</code>
+</p>
+
+<p>
+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.
+
+<p>
+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.
+
+<p>
  For more complex ports, you have more options and tools available to you:

  <ul><li>
@@ -366,11 +411,11 @@ Try building the port with <code>make bu
  If you're lucky, the port will go all the way through without errors.

  <li>
-If it exits with an error, you will need to generate patches for your port.
+If it exits with an error, you will likely need to generate patches for 
your port.
  Figure out what needs to be changed and make a patch for it.

  <li>
-the sequence to make a patch for a file is usually:
+The sequence to make a patch for a file is usually:

  <ul><li>
  <code>cd `make show=WRKSRC` ; cp foo/bar.c{,.orig.port}</code>