git: 681ef79f8f - main - handbook/cutting-edge/: Document building FreeBSD on macOS and Linux

The branch main has been updated by 0mp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=681ef79f8f0bf080592fe3ebc196b5a2e4f5feaa

commit 681ef79f8f0bf080592fe3ebc196b5a2e4f5feaa
Author:     Mateusz Piotrowski <[email protected]>
AuthorDate: 2023-10-02 15:54:52 +0000
Commit:     Mateusz Piotrowski <[email protected]>
CommitDate: 2023-10-02 15:54:52 +0000

     handbook/cutting-edge/: Document building FreeBSD on macOS and Linux
    
     Based on https://wiki.freebsd.org/BuildingOnNonFreeBSD.
---
 .../en/books/handbook/cutting-edge/_index.adoc     | 45 ++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
index cf06f6df60..07e97a396f 100644
--- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc
+++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
@@ -1141,3 +1141,48 @@ set `DISTDIR` to a common shared directory that is writable by whichever user `r
 Each machine should set `WRKDIRPREFIX` to a local build directory, if ports are to be built locally.
 Alternately, if the build system is to build and distribute packages to the machines in the build set,
 set `PACKAGES` on the build system to a directory similar to `DISTDIR`.
+
+[[building-on-non-freebsd-hosts]]
+== Building on non-FreeBSD Hosts
+
+Historically, building FreeBSD required a FreeBSD host.
+Nowadays, the FreeBSD can be build on Linux distributions and macOS.
+
+To build FreeBSD on non-FreeBSD hosts, the recommendation is to use the `tools/build/make.py` script.
+This script acts as a wrapper around `bmake`, which is the make implementation used by FreeBSD.
+It ensures that the necessary tooling, including the actual FreeBSD's man:make[1], is bootstrapped and that the build environment is properly configured.
+In particular, it sets the external toolchain variables, such as `XCC`, `XLD`, and others.
+Additionally, the script can pass any additional command arguments, such as `-j 4` for parallel builds or specific make targets, to `bmake`.
+
+[NOTE]
+====
+A recent version of `bmake` can be ued instead of the `tools/build/make.py` script as well.
+In that case, however, required environment variables need to be set manually (the easiest way to obtain a list of them is by running `tools/build/make.py --debug`).
+====
+
+Otherwise, the list of prerequisites for building FreeBSD is rather short.
+In fact, it boils down to installing a couple of dependencies.
+
+On macOS, the only dependency LLVM.
+The necessary dependencies can be installed with package manager (e.g., link:https://brew.sh/[Homebrew]):
+
+[source,shell]
+....
+brew install llvm
+....
+
+On a Linux distributions, install link:https://clang.llvm.org/[Clang] version 10.0 or newer and the headers for libarchive and libbz2 (often packaged as libarchive-dev and libbz2-dev).
+
+Once the dependencies are installed, the host should be able to build FreeBSD.
+
+For example, the following `tools/build/make.py` invocation builds the world:
+
+[source,shell]
+....
+MAKEOBJDIRPREFIX=/tmp tools/build/make.py -j 8 TARGET=arm64 TARGET_ARCH=aarch64 buildworld
+....
+
+It builds the world for target `aarch64:arm64` on 8 CPUs and uses [.filename]#/tmp# for object files.
+Note that the variables `MAKEOBJDIRPREFIX`, `TARGET`, and `TARGET_ARCH` are mandatory when building on non-FreeBSD hosts.
+
+Refer to man:arch[7] and man:build[7] for more details.