expand on the system type in hacking guide

1 files changed, 47 insertions, 16 deletions

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 7b2440971..c7cb0d980 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -110,41 +110,72 @@ You can also build Nix for one of the [supported platforms](#platforms).
 
 ## Platforms
 
-As specified in [`flake.nix`], Nix can be built for various platforms:
-
-- `aarch64-linux`
-- `i686-linux`
-- `x86_64-darwin`
-- `x86_64-linux`
+Nix can be built for various platforms, as specified in [`flake.nix`]:
 
 [`flake.nix`]: https://github.com/nixos/nix/blob/master/flake.nix
 
+- `x86_64-linux`
+- `x86_64-darwin`
+- `i686-linux`
+- `aarch64-linux`
+- `aarch64-darwin`
+- `armv6l-linux`
+- `armv7l-linux`
+
 In order to build Nix for a different platform than the one you're currently
-on, you need to have some way for your system Nix to build code for that
-platform. Common solutions include [remote builders] and [binfmt emulation]
+on, you need a way for your current Nix installation to build code for that
+platform. Common solutions include [remote builders] and [binary format emulation]
 (only supported on NixOS).
 
 [remote builders]: ../advanced-topics/distributed-builds.md
 [binfmt emulation]: https://nixos.org/manual/nixos/stable/options.html#opt-boot.binfmt.emulatedSystems
 
-These solutions let Nix perform builds as if you're on the native platform, so
-executing the build is as simple as
+Given such a setup, executing the build only requires selecting the respective output attribute.
+For example, to compile for `aarch64-linux`:
 
 ```console
-$ nix build .#packages.aarch64-linux.default
+$ nix-build --attr packages.aarch64-linux.default
 ```
 
-for flake-enabled Nix, or
+or for Nix with the [`flakes`] and [`nix-command`] experimental features enabled:
 
 ```console
-$ nix-build --attr packages.aarch64-linux.default
+$ nix build .#packages.aarch64-linux.default
 ```
 
-for classic Nix.
+Cross-compiled builds are available for ARMv6 (`armv6l-linux`) and ARMv7 (`armv7l-linux`).
+Add more [system types](#system-type) to `crossSystems` in `flake.nix` to bootstrap Nix on unsupported platforms.
+
+## System type
+
+Nix uses a string with he following format to identify the *system type* or *platform* it runs on:
+
+```
+<cpu>-<os>[-<abi>]
+```
+
+It is set when Nix is compiled for the given system, and based on the output of [`config.guess`](https://github.com/nixos/nix/blob/master/config/config.guess) ([upstream](https://git.savannah.gnu.org/cgit/config.git/tree/config.guess)):
+
+```
+<cpu>-<vendor>-<os>[<version>][-<abi>]
+```
+
+When Nix is built such that `./configure` is passed any of the `--host`, `--build`, `--target` options, the value is based on the output of [`config.sub`](https://github.com/nixos/nix/blob/master/config/config.sub) ([upstream](https://git.savannah.gnu.org/cgit/config.git/tree/config.sub)):
+
+```
+<cpu>-<vendor>[-<kernel>]-<os>
+```
 
-You can use any of the other supported platforms in place of `aarch64-linux`.
+For historic reasons and backward-compatibility, some CPU and OS identifiers are transformed as follows in [`configure.ac`](https://github.com/nixos/nix/blob/master/config/config.sub):
 
-Cross-compiled builds are available for ARMv6 and ARMv7, and Nix on unsupported platforms can be bootstrapped by adding more `crossSystems` in `flake.nix`.
+| `config.guess`             | Nix                 |
+|----------------------------|---------------------|
+| `amd64`                    | `x86_64`            |
+| `i*86`                     | `i686`              |
+| `arm6`                     | `arm6l`             |
+| `arm7`                     | `arm7l`             |
+| `linux-gnu*`               | `linux`             |
+| `linux-musl*`              | `linux`             |
 
 ## Compilation environments