porters-handbook: Document USE_FORGEJO helper variables

Sponsored by:	The FreeBSD Foundation
Reviewed by:	carlavilla, diizzy
Pull Request:	https://ron-dev.freebsd.org/FreeBSD/doc/pulls/1

1 files changed, 271 insertions, 0 deletions

diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index 38b747c226..c88f83416d 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -2089,6 +2089,271 @@ Grouping was used in the previous example with `bar:icons,contrib`.
 Some redundant information is present with `GL_TUPLE` because grouping is not possible.
 ====
 
+[[makefile-master_sites-forgejo]]
+=== `USE_FORGEJO`
+
+https://forgejo.org/[Forgejo] is a fork of https://about.gitea.com/[Gitea], and both are self-hosted Git forges.
+https://codeberg.org/[Codeberg] is the most prominent public Forgejo instance, but the same archive URL format is used by all Forgejo and Gitea instances.
+The `USE_FORGEJO` helper variables make it straightforward to fetch distribution files that these forges generate on demand for specific tags or commits.
+
+[WARNING]
+====
+The checksums of archives generated on demand for tags or commits have changed in the past.
+When upstream publishes release archives, fetch those instead by setting `MASTER_SITES` directly rather than setting `USE_FORGEJO`.
+====
+
+[[makefile-master_sites-forgejo-description]]
+.`USE_FORGEJO` Description
+[cols="1,1,1", options="header"]
+|===
+| Variable
+| Description
+| Default
+
+|`FJ_SITE`
+|Base URL of the Forgejo instance, including the scheme and any port or path prefix the instance is served under, but excluding the organization or account.
+|`https://codeberg.org`
+
+|`FJ_ACCOUNT`
+|Account name of the Forgejo user hosting the project.
+|`${PORTNAME}`
+
+|`FJ_PROJECT`
+|Name of the project on Forgejo.
+|`${PORTNAME}`
+
+|`FJ_TAGNAME`
+|Tag name or full 40-character commit hash to download. Must not be `main` or `master`.
+|`${DISTVERSIONFULL}`
+
+|`FJ_SUBDIR`
+|When the software needs an additional distribution file to be extracted within
+`${WRKSRC}`, this variable can be used. See the examples in
+crossref:makefiles[makefile-master_sites-forgejo-multiple, Fetching Multiple Files from Forgejo] for more information.
+|(none)
+
+|`FJ_TUPLE`
+|`FJ_TUPLE` allows putting `FJ_SITE`, `FJ_ACCOUNT`, `FJ_PROJECT`, `FJ_TAGNAME`, and `FJ_SUBDIR` into a single variable.
+The format is:
+
+`[site[:port][/webroot]:]account:project:tagname[:group][/subdir]`
+
+The fields shown in `[]` are optional.
+When a site is given, it must be a full URL including the scheme, such as `https://forgejo.example.com`.
+|
+|===
+
+[NOTE]
+====
+`WRKSRC` is automatically set to `${WRKDIR}/${FJ_PROJECT}`.
+Unlike GitHub and GitLab archives, Forgejo archives extract into a directory named after the project only, without any tag or commit hash appended.
+Because of this, every group, including the default, must use a distinct `FJ_PROJECT`.
+The framework reports an error when a project name is reused.
+====
+
+[[makefile-master_sites-forgejo-ex1]]
+.Simple Use of `USE_FORGEJO`
+[example]
+====
+Here is a [.filename]#Makefile# snippet to fetch the distribution files for version `0.7.0` of forgejo-cli from the `forgejo-contrib` account on codeberg.org:
+
+[.programlisting]
+....
+PORTNAME=	forgejo-cli
+DISTVERSIONPREFIX=	v
+DISTVERSION=	0.7.0
+
+USE_FORGEJO=	yes
+FJ_ACCOUNT=	forgejo-contrib
+....
+
+It will cause `MASTER_SITES` to be set to https://codeberg.org/[codeberg.org] and `WRKSRC` to be set to `${WRKDIR}/forgejo-cli`.
+The distribution file will be named [.filename]#forgejo-contrib-forgejo-cli-v0.7.0_FJ0.tar.gz#.
+====
+
+[[makefile-master_sites-forgejo-ex2]]
+.Use of `USE_FORGEJO` Without a Version
+[example]
+====
+If the port has no upstream version and is identified by a commit hash, the [.filename]#Makefile# looks like this:
+
+[.programlisting]
+....
+PORTNAME=	foobar
+DISTVERSION=	g20261031
+
+USE_FORGEJO=	yes
+FJ_ACCOUNT=	someuser
+FJ_TAGNAME=	a3f1b2c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
+....
+
+[TIP]
+======
+`20261031` is the date of the commit referenced in `FJ_TAGNAME`, not the date the [.filename]#Makefile# is edited, or the date the commit to the FreeBSD ports tree is made.
+======
+
+====
+
+[[makefile-master_sites-forgejo-ex3]]
+.Use of `USE_FORGEJO` with a Self-Hosted Instance
+[example]
+====
+For a project hosted on a self-hosted Forgejo instance rather than codeberg.org, set `FJ_SITE`:
+
+[.programlisting]
+....
+PORTNAME=	myapp
+DISTVERSION=	1.2.3
+
+USE_FORGEJO=	yes
+FJ_SITE=	https://forgejo.example.com
+FJ_ACCOUNT=	myorg
+....
+
+When a self-hosted site appears in `FJ_TUPLE`, include the URL scheme in the tuple so the framework can distinguish it from the account.
+
+[.programlisting]
+....
+FJ_TUPLE=	https://forgejo.example.com:myorg:plugins:v2.0:plugins
+....
+
+====
+
+[[makefile-master_sites-forgejo-multiple]]
+==== Fetching Multiple Files from Forgejo
+
+The `USE_FORGEJO` framework also supports fetching multiple distribution files from different Forgejo projects.
+It works in a way very similar to crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations].
+
+Multiple values are added to `FJ_SITE`, `FJ_ACCOUNT`, `FJ_PROJECT`, and `FJ_TAGNAME`, and each value is assigned a group.
+Alternatively, `FJ_TUPLE` can be used to keep the account, project, tagname, and group information together.
+
+For each group, a `${WRKSRC_group}` helper variable is created, containing the group's work source directory.
+
+[CAUTION]
+====
+The `:__group__` _must be unique for each distribution file_.
+It is used as a unique key and using it more than once will overwrite the previous values.
+====
+
+[NOTE]
+====
+As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group
+names must adhere to the restrictions on group names outlined in
+crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations]
+====
+
+[[makefile-master_sites-forgejo-multi]]
+.Use of `USE_FORGEJO` with Multiple Distribution Files
+[example]
+====
+When a port requires multiple repositories, groups in the `FJ_*` variables can be used:
+
+[.programlisting]
+....
+PORTNAME=	foo
+DISTVERSIONPREFIX=	v
+DISTVERSION=	1.0.2
+
+USE_FORGEJO=	yes
+FJ_ACCOUNT=	bar:icons,contrib
+FJ_PROJECT=	foo-icons:icons foo-contrib:contrib
+FJ_TAGNAME=	ae7368c0b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6:icons \
+		9e4dd76f1e2d3c4b5a69788776655443322110aa:contrib
+FJ_SUBDIR=	ext/icons:icons
+
+CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}
+....
+
+.`USE_FORGEJO`: Groups and Variables for Fetching Multiple Distribution Files from codeberg.org
+[cols="1,1,1,1", options="header"]
+|===
+| Group
+| Account
+| Project
+| Tagname
+
+| default
+| `foo`
+| `foo`
+| `v1.0.2`
+
+| icons
+| `bar`
+| `foo-icons`
+| `ae7368c0b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6`
+
+| contrib
+| `bar`
+| `foo-contrib`
+| `9e4dd76f1e2d3c4b5a69788776655443322110aa`
+|===
+
+The distribution files are named [.filename]#foo-foo-v1.0.2_FJ0.tar.gz#, [.filename]#bar-foo-icons-ae7368c0b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6_FJ0.tar.gz#, and [.filename]#bar-foo-contrib-9e4dd76f1e2d3c4b5a69788776655443322110aa_FJ0.tar.gz#.
+The default distribution file comes from [.filename]#https://codeberg.org/foo/foo# at tag `v1.0.2`.
+The second, for the `icons` group, comes from [.filename]#https://codeberg.org/bar/foo-icons# at commit `ae7368c0b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6`.
+The third, for the contrib group, comes from [.filename]#https://codeberg.org/bar/foo-contrib# at commit `9e4dd76f1e2d3c4b5a69788776655443322110aa`.
+
+All the distribution files are extracted in `${WRKDIR}` in their respective subdirectories.
+The default file is extracted in `${WRKSRC}`, which is `${WRKDIR}/foo`.
+Each additional distribution file is extracted in `${WRKSRC_group}`:
+`${WRKSRC_icons}` contains `${WRKDIR}/foo-icons` and `${WRKSRC_contrib}` contains `${WRKDIR}/foo-contrib`.
+
+The software's build system expects to find the icons in a [.filename]#ext/icons# subdirectory in its sources, so `FJ_SUBDIR` is used.
+`FJ_SUBDIR` makes sure that [.filename]#ext# exists, but that [.filename]#ext/icons# does not already exist.
+Then it does this:
+
+[.programlisting]
+....
+post-extract:
+        @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons
+....
+
+====
+
+[[makefile-master_sites-forgejo-multi2]]
+.Use of `USE_FORGEJO` with Multiple Distribution Files Using `FJ_TUPLE`
+[example]
+====
+This is functionally equivalent to
+crossref:makefiles[makefile-master_sites-forgejo-multi,Use of `USE_FORGEJO` with Multiple Distribution Files], but using `FJ_TUPLE`:
+
+[.programlisting]
+....
+PORTNAME=	foo
+DISTVERSIONPREFIX=	v
+DISTVERSION=	1.0.2
+
+USE_FORGEJO=	yes
+FJ_TUPLE=	bar:foo-icons:ae7368c0b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6:icons/ext/icons \
+		bar:foo-contrib:9e4dd76f1e2d3c4b5a69788776655443322110aa:contrib
+
+CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}
+....
+
+Some redundant information is present with `FJ_TUPLE` because grouping is not possible.
+====
+
+When fetching multiple files using Forgejo, sometimes the default distribution file is not fetched from a Forgejo-hosted project.
+To disable fetching the default distribution, set:
+
+[.programlisting]
+....
+USE_FORGEJO=   nodefault
+....
+
+[IMPORTANT]
+====
+When using `USE_FORGEJO=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its crossref:order[porting-order-portname,top block].
+The definition should be:
+
+[.programlisting]
+....
+DISTFILES=    ${DISTNAME}${EXTRACT_SUFX}
+....
+
+====
+
 [[makefile-extract_sufx]]
 === `EXTRACT_SUFX`
 
@@ -4873,6 +5138,12 @@ For any of these variables:
 * `DISTFILES`
 * `EXTRACT_ONLY`
 * `EXTRA_PATCHES`
+* `FJ_ACCOUNT`
+* `FJ_PROJECT`
+* `FJ_SITE`
+* `FJ_SUBDIR`
+* `FJ_TAGNAME`
+* `FJ_TUPLE`
 * `GH_ACCOUNT`
 * `GH_PROJECT`
 * `GH_SUBDIR`