|author||Mateusz Piotrowski <0mp@FreeBSD.org>||2023-10-02 15:54:52 +0000|
|committer||Mateusz Piotrowski <0mp@FreeBSD.org>||2023-10-02 15:54:52 +0000|
handbook/cutting-edge/: Document building FreeBSD on macOS and Linux
1 files changed, 45 insertions, 0 deletions
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
@@ -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
+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, 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`.
+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]):
+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:
+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 and man:build for more details.