From 68b7bb1a062c6471b678d5488a71324e0486d405 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 11 May 2023 15:51:48 +0200 Subject: [PATCH 01/11] add information on the system type string --- configure.ac | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/configure.ac b/configure.ac index bb3f92e4d..26df39d54 100644 --- a/configure.ac +++ b/configure.ac @@ -5,7 +5,12 @@ AC_CONFIG_AUX_DIR(config) AC_PROG_SED -# Construct a Nix system name (like "i686-linux"). +# Construct a Nix system name (like "i686-linux"): +# https://www.gnu.org/software/autoconf/manual/html_node/Canonicalizing.html#index-AC_005fCANONICAL_005fHOST-1 +# The inital value is produced by the `config.guess` script: +# https://git.savannah.gnu.org/cgit/config.git/tree/config.guess +# It has the following form, which is not documented anywhere: +# --[][-] AC_CANONICAL_HOST AC_MSG_CHECKING([for the canonical Nix system name]) From 0751c1bfc6375ffbe94e90cfcfdb987e8b286f2e Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 31 May 2023 03:21:11 +0200 Subject: [PATCH 02/11] one line per sentence for easier review --- src/libstore/globals.hh | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index d4b8fb1f9..76afeb5f5 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -193,18 +193,12 @@ public: Setting thisSystem{ this, SYSTEM, "system", R"( - This option specifies the canonical Nix system name of the current - installation, such as `i686-linux` or `x86_64-darwin`. Nix can only - build derivations whose `system` attribute equals the value - specified here. In general, it never makes sense to modify this - value from its default, since you can use it to ‘lie’ about the - platform you are building on (e.g., perform a Mac OS build on a - Linux machine; the result would obviously be wrong). It only makes - sense if the Nix binaries can run on multiple platforms, e.g., - ‘universal binaries’ that run on `x86_64-linux` and `i686-linux`. + This option specifies the canonical Nix system name of the current installation, such as `i686-linux` or `x86_64-darwin`. + Nix can only build derivations whose `system` attribute equals the value specified here. + In general, it never makes sense to modify this value from its default, since you can use it to ‘lie’ about the platform you are building on (e.g., perform a Mac OS build on a Linux machine; the result would obviously be wrong). + It only makes sense if the Nix binaries can run on multiple platforms, e.g., ‘universal binaries’ that run on `x86_64-linux` and `i686-linux`. - It defaults to the canonical Nix system name detected by `configure` - at build time. + It defaults to the canonical Nix system name detected by `configure` at build time. )"}; Setting maxSilentTime{ From c8a42039eae4c046297517b67a3ce43685d3e756 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 31 May 2023 03:48:05 +0200 Subject: [PATCH 03/11] move docs of the current system to the system setting add information what happens when Nix itself is cross-compiled --- configure.ac | 2 ++ src/libstore/globals.hh | 45 +++++++++++++++++++++++++++++++++++++---- 2 files changed, 43 insertions(+), 4 deletions(-) diff --git a/configure.ac b/configure.ac index 26df39d54..cc7009859 100644 --- a/configure.ac +++ b/configure.ac @@ -11,6 +11,8 @@ AC_PROG_SED # https://git.savannah.gnu.org/cgit/config.git/tree/config.guess # It has the following form, which is not documented anywhere: # --[][-] +# If `./configure` is passed any of the `--host`, `--build`, `--target` options, the value comes from `config.sub` instead: +# https://git.savannah.gnu.org/cgit/config.git/tree/config.sub AC_CANONICAL_HOST AC_MSG_CHECKING([for the canonical Nix system name]) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index 76afeb5f5..1fb5927d0 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -193,12 +193,49 @@ public: Setting thisSystem{ this, SYSTEM, "system", R"( - This option specifies the canonical Nix system name of the current installation, such as `i686-linux` or `x86_64-darwin`. - Nix can only build derivations whose `system` attribute equals the value specified here. - In general, it never makes sense to modify this value from its default, since you can use it to ‘lie’ about the platform you are building on (e.g., perform a Mac OS build on a Linux machine; the result would obviously be wrong). + The system type of the current Nix installation. + + Nix can only build [derivations](@docroot@/language/derivations.md) whose `system` attribute equals the value specified here. + In general, it never makes sense to modify this value, since you can use it to ‘lie’ about the system you are building on (e.g., perform a macOS build on a Linux machine; the result would obviously be wrong). It only makes sense if the Nix binaries can run on multiple platforms, e.g., ‘universal binaries’ that run on `x86_64-linux` and `i686-linux`. - It defaults to the canonical Nix system name detected by `configure` at build time. + The default value is set when Nix itself is compiled for the system it will run on. + The following system types are widely used, as Nix is actively supported on these platforms: + + - `x86_64-linux` + - `x86_64-darwin` + - `i686-linux` + - `aarch64-linux` + - `aarch64-darwin` + + The concrete value is based on the output of [`config.guess`](https://git.savannah.gnu.org/cgit/config.git/tree/config.guess): + + ``` + --[][-] + ``` + + 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://git.savannah.gnu.org/cgit/config.git/tree/config.sub): + + ``` + -[-]- + ``` + + Nix only uses the CPU and OS identifiers: + + ``` + -[-] + ``` + + For historic reasons and backwards-compatibility, some CPU and OS identifiers are transformed as follows: + + | `config.guess` | Nix | + |----------------------------|---------------------| + | `amd64` | `x86_64` | + | `i*86` | `i686` | + | `arm6` | `arm6l` | + | `arm7` | `arm7l` | + | `linux-gnu*` | `linux` | + | `linux-musl*` | `linux` | )"}; Setting maxSilentTime{ From 3763c7bb5ef5a7a1ddcf47169c9733edb7989e98 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Jun 2023 13:42:23 +0200 Subject: [PATCH 04/11] shorten `system` setting description --- src/libstore/globals.hh | 38 ++++++-------------------------------- 1 file changed, 6 insertions(+), 32 deletions(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index 1fb5927d0..442d72911 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -194,12 +194,12 @@ public: this, SYSTEM, "system", R"( The system type of the current Nix installation. - - Nix can only build [derivations](@docroot@/language/derivations.md) whose `system` attribute equals the value specified here. - In general, it never makes sense to modify this value, since you can use it to ‘lie’ about the system you are building on (e.g., perform a macOS build on a Linux machine; the result would obviously be wrong). - It only makes sense if the Nix binaries can run on multiple platforms, e.g., ‘universal binaries’ that run on `x86_64-linux` and `i686-linux`. + Nix will only build [derivations](@docroot@/language/derivations.md) whose `system` attribute equals the value specified here. The default value is set when Nix itself is compiled for the system it will run on. + In general, it never makes sense to modify this value. + While you can force Nix to run a Darwin-specific `builder` executable on a Linux machine, the result would obviously be wrong. + The following system types are widely used, as Nix is actively supported on these platforms: - `x86_64-linux` @@ -207,35 +207,9 @@ public: - `i686-linux` - `aarch64-linux` - `aarch64-darwin` + - `armv6l-linux` + - `armv7l-linux` - The concrete value is based on the output of [`config.guess`](https://git.savannah.gnu.org/cgit/config.git/tree/config.guess): - - ``` - --[][-] - ``` - - 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://git.savannah.gnu.org/cgit/config.git/tree/config.sub): - - ``` - -[-]- - ``` - - Nix only uses the CPU and OS identifiers: - - ``` - -[-] - ``` - - For historic reasons and backwards-compatibility, some CPU and OS identifiers are transformed as follows: - - | `config.guess` | Nix | - |----------------------------|---------------------| - | `amd64` | `x86_64` | - | `i*86` | `i686` | - | `arm6` | `arm6l` | - | `arm7` | `arm7l` | - | `linux-gnu*` | `linux` | - | `linux-musl*` | `linux` | )"}; Setting maxSilentTime{ From 4944e37ec04cc8c62f35aa9b1f4e97ee8f233eb8 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Jun 2023 14:10:30 +0200 Subject: [PATCH 05/11] expand on the system type in hacking guide --- configure.ac | 8 +-- doc/manual/src/contributing/hacking.md | 69 +++++++++++++++++++------- 2 files changed, 54 insertions(+), 23 deletions(-) diff --git a/configure.ac b/configure.ac index cc7009859..6d78237f0 100644 --- a/configure.ac +++ b/configure.ac @@ -7,12 +7,12 @@ AC_PROG_SED # Construct a Nix system name (like "i686-linux"): # https://www.gnu.org/software/autoconf/manual/html_node/Canonicalizing.html#index-AC_005fCANONICAL_005fHOST-1 -# The inital value is produced by the `config.guess` script: -# https://git.savannah.gnu.org/cgit/config.git/tree/config.guess +# The inital value is produced by the `config/config.guess` script: +# upstream: https://git.savannah.gnu.org/cgit/config.git/tree/config.guess # It has the following form, which is not documented anywhere: # --[][-] -# If `./configure` is passed any of the `--host`, `--build`, `--target` options, the value comes from `config.sub` instead: -# https://git.savannah.gnu.org/cgit/config.git/tree/config.sub +# If `./configure` is passed any of the `--host`, `--build`, `--target` options, the value comes from `config/config.sub` instead: +# upstream: https://git.savannah.gnu.org/cgit/config.git/tree/config.sub AC_CANONICAL_HOST AC_MSG_CHECKING([for the canonical Nix system name]) 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 - -```console -$ nix build .#packages.aarch64-linux.default -``` - -for flake-enabled Nix, or +Given such a setup, executing the build only requires selecting the respective output attribute. +For example, to compile for `aarch64-linux`: ```console $ nix-build --attr packages.aarch64-linux.default ``` -for classic Nix. +or for Nix with the [`flakes`] and [`nix-command`] experimental features enabled: -You can use any of the other supported platforms in place of `aarch64-linux`. +```console +$ nix build .#packages.aarch64-linux.default +``` -Cross-compiled builds are available for ARMv6 and ARMv7, and Nix on unsupported platforms can be bootstrapped by adding more `crossSystems` in `flake.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: + +``` +-[-] +``` + +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)): + +``` +--[][-] +``` + +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)): + +``` +-[-]- +``` + +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): + +| `config.guess` | Nix | +|----------------------------|---------------------| +| `amd64` | `x86_64` | +| `i*86` | `i686` | +| `arm6` | `arm6l` | +| `arm7` | `arm7l` | +| `linux-gnu*` | `linux` | +| `linux-musl*` | `linux` | ## Compilation environments From 32de11923e932b5bbda8ce4877542fb299de9b03 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 22 Jun 2023 13:50:00 +0200 Subject: [PATCH 06/11] add cross-links --- src/libstore/globals.hh | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index 442d72911..760655302 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -197,10 +197,7 @@ public: Nix will only build [derivations](@docroot@/language/derivations.md) whose `system` attribute equals the value specified here. The default value is set when Nix itself is compiled for the system it will run on. - In general, it never makes sense to modify this value. - While you can force Nix to run a Darwin-specific `builder` executable on a Linux machine, the result would obviously be wrong. - - The following system types are widely used, as Nix is actively supported on these platforms: + The following system types are widely used, as [Nix is actively supported on these platforms](@docroot@/contributing/hacking.md#platforms): - `x86_64-linux` - `x86_64-darwin` @@ -210,6 +207,10 @@ public: - `armv6l-linux` - `armv7l-linux` + In general, it never makes sense to modify this value when building derivations. + While you can force Nix to run a Darwin-specific `builder` executable on a Linux machine, the result would obviously be wrong. + + This value is available in the Nix language as [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem). )"}; Setting maxSilentTime{ From c8f04e2024d3e66f620ae38258fa86eb6103ce05 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 13 Jul 2023 22:00:16 +0200 Subject: [PATCH 07/11] note that naming convention is from Autotools Co-authored-by: Robert Hensing --- doc/manual/src/contributing/hacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index c7cb0d980..ff4690f1e 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -166,7 +166,7 @@ When Nix is built such that `./configure` is passed any of the `--host`, `--buil -[-]- ``` -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): +For historic reasons and backward-compatibility, some CPU and OS identifiers are translated from the GNU Autotools naming convention in [`configure.ac`](https://github.com/nixos/nix/blob/master/config/config.sub) as follows: | `config.guess` | Nix | |----------------------------|---------------------| From 1a220bed9361be2c360f83eb42025f9765c96f34 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 18 Jul 2023 23:21:43 +0200 Subject: [PATCH 08/11] do not mention output attributes Co-authored-by: Robert Hensing --- doc/manual/src/contributing/hacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index ff4690f1e..b8ea977d7 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -130,7 +130,7 @@ platform. Common solutions include [remote builders] and [binary format emulatio [remote builders]: ../advanced-topics/distributed-builds.md [binfmt emulation]: https://nixos.org/manual/nixos/stable/options.html#opt-boot.binfmt.emulatedSystems -Given such a setup, executing the build only requires selecting the respective output attribute. +Given such a setup, executing the build only requires selecting the respective attribute. For example, to compile for `aarch64-linux`: ```console From aba32def7390432855401b815ff21915aba3eb81 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 18 Jul 2023 23:26:36 +0200 Subject: [PATCH 09/11] fix wording Co-authored-by: Robert Hensing --- src/libstore/globals.hh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index 760655302..63ac54e97 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -207,7 +207,7 @@ public: - `armv6l-linux` - `armv7l-linux` - In general, it never makes sense to modify this value when building derivations. + In general, you do not have to modify this setting. While you can force Nix to run a Darwin-specific `builder` executable on a Linux machine, the result would obviously be wrong. This value is available in the Nix language as [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem). From fcadac0a02b30d1d876c804edf7f2745d880a10c Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jul 2023 10:33:41 +0200 Subject: [PATCH 10/11] mention `extra-platforms` --- src/libstore/globals.hh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index 63ac54e97..ad02bfb42 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -194,7 +194,7 @@ public: this, SYSTEM, "system", R"( The system type of the current Nix installation. - Nix will only build [derivations](@docroot@/language/derivations.md) whose `system` attribute equals the value specified here. + Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals the value specified here or in [`extra-platforms`](@docroot@/command-ref/conf-file.html#conf-extra-platforms). The default value is set when Nix itself is compiled for the system it will run on. The following system types are widely used, as [Nix is actively supported on these platforms](@docroot@/contributing/hacking.md#platforms): From 0779005f4945d373b81c933a6b7390c8bc7ad6cb Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jul 2023 10:57:37 +0200 Subject: [PATCH 11/11] expand on the `extra-platforms` option --- src/libstore/globals.hh | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index ad02bfb42..723d18d74 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -194,7 +194,7 @@ public: this, SYSTEM, "system", R"( The system type of the current Nix installation. - Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals the value specified here or in [`extra-platforms`](@docroot@/command-ref/conf-file.html#conf-extra-platforms). + Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in [`extra-platforms`](#conf-extra-platforms). The default value is set when Nix itself is compiled for the system it will run on. The following system types are widely used, as [Nix is actively supported on these platforms](@docroot@/contributing/hacking.md#platforms): @@ -676,18 +676,20 @@ public: getDefaultExtraPlatforms(), "extra-platforms", R"( - Platforms other than the native one which this machine is capable of - building for. This can be useful for supporting additional - architectures on compatible machines: i686-linux can be built on - x86\_64-linux machines (and the default for this setting reflects - this); armv7 is backwards-compatible with armv6 and armv5tel; some - aarch64 machines can also natively run 32-bit ARM code; and - qemu-user may be used to support non-native platforms (though this - may be slow and buggy). Most values for this are not enabled by - default because build systems will often misdetect the target - platform and generate incompatible code, so you may wish to - cross-check the results of using this option against proper - natively-built versions of your derivations. + System types of executables that can be run on this machine. + + Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in the [`system` option](#conf-system). + + Setting this can be useful to build derivations locally on compatible machines: + - `i686-linux` executables can be run on `x86_64-linux` machines (set by default) + - `x86_64-darwin` executables can be run on macOS `aarch64-darwin` with Rosetta 2 (set by default where applicable) + - `armv6` and `armv5tel` executables can be run on `armv7` + - some `aarch64` machines can also natively run 32-bit ARM code + - `qemu-user` may be used to support non-native platforms (though this + may be slow and buggy) + + Build systems will usually detect the target platform to be the current physical system and therefore produce machine code incompatible with what may be intended in the derivation. + You should design your derivation's `builder` accordingly and cross-check the results when using this option against natively-built versions of your derivation. )", {}, false}; Setting systemFeatures{