From 4c59f4414c50d634197fa8b195c73cd7c48bf2af Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Sun, 3 Jul 2022 11:07:11 -0700 Subject: [PATCH 1/9] doc/stdenv/cross-compilation.chapter.md: explain tuples This commit adjusts the documentation for the `config` field of `{host,build,target}Platform` in the following ways: 1. It clarifieds that stdenv uses multiarch tuples, which are the same thing as autoconf tuples except for two cases involving 32-bit architectures where autoconf tuples are ambiguous. 2. It mentions and gives examples of the 5-field form for tuples, which include both a `libc` and an `abi`. 3. It documents that this field should be canonicalized, and explains where to find the canonicalization rules. --- doc/stdenv/cross-compilation.chapter.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 7b8f2b4ce6cdb..60bfdf712e8be 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -44,7 +44,14 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv `config` -: This is a 3- or 4- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnu` and `aarch64-apple-darwin14`. This is a standard format called the "LLVM target triple", as they are pioneered by LLVM. In the 4-part form, this corresponds to `[cpu]-[vendor]-[os]-[abi]`. This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. This needs a better name than `config`! +: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format called the "[multiarch tuple](https://wiki.debian.org/Multiarch/Tuples)", as [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type), [disambiguated to create multiarch](https://wiki.debian.org/Multiarch/Tuples#Used_solution), and adopted by LLVM. In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. This needs a better name than `config`! + +"Multiarch tuple" means exactly the same thing as "autoconf tuple" except in [two specific cases](https://wiki.debian.org/Multiarch/Tuples) dealing with 32-bit architectures: + +1. Autoconf has multiple `[cpu]` fields for 32-bit x86 systems (`i386-`, `i486-`, `i586-`, and `i686-`). Multiarch uses `i386-` for all of them. +2. The 32-bit ARM ABI for systems with hardware floating point is incompatible with the ABI for systems without floating point. Autoconf tuples use the same tuples (`arm-*-*eabi`) for both of these ABIs; multiarch distinguishes between them as `arm-*-*eabi` and `arm-*-*eabihf`. + +This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.guess` file in the source code for `autoconf`. `parsed` From 35475b81b8f8c1603a3e3b544bb8e7f527d9a83b Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Mon, 4 Jul 2022 01:33:33 +0000 Subject: [PATCH 2/9] Update doc/stdenv/cross-compilation.chapter.md Co-authored-by: sternenseemann --- doc/stdenv/cross-compilation.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 60bfdf712e8be..86bce11a0a6a7 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -51,7 +51,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv 1. Autoconf has multiple `[cpu]` fields for 32-bit x86 systems (`i386-`, `i486-`, `i586-`, and `i686-`). Multiarch uses `i386-` for all of them. 2. The 32-bit ARM ABI for systems with hardware floating point is incompatible with the ABI for systems without floating point. Autoconf tuples use the same tuples (`arm-*-*eabi`) for both of these ABIs; multiarch distinguishes between them as `arm-*-*eabi` and `arm-*-*eabihf`. -This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.guess` file in the source code for `autoconf`. +This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.sub` file in the source code for `autoconf`. The script is also available via the `gnu-config` package in nixpkgs. `parsed` From 1e2886658ab11568ef543f1ceb631f2145ccb1cc Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Sun, 3 Jul 2022 19:05:20 -0700 Subject: [PATCH 3/9] minimize reference to multiarch, mentioning it only in the case where it is relevant (arm32) --- doc/stdenv/cross-compilation.chapter.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 86bce11a0a6a7..8cb4b15fe6da2 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -44,12 +44,9 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv `config` -: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format called the "[multiarch tuple](https://wiki.debian.org/Multiarch/Tuples)", as [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type), [disambiguated to create multiarch](https://wiki.debian.org/Multiarch/Tuples#Used_solution), and adopted by LLVM. In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. This needs a better name than `config`! +: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and adopted by LLVM. For 32-bit arm, nixpkgs adopts the [multiarch solution](https://wiki.debian.org/Multiarch/Tuples#Used_solution) to the problem of distinguishing between `arm-*-*-*` and `armhf-*-*-*`, which are linker-incompatible due to having different calling conventions. -"Multiarch tuple" means exactly the same thing as "autoconf tuple" except in [two specific cases](https://wiki.debian.org/Multiarch/Tuples) dealing with 32-bit architectures: - -1. Autoconf has multiple `[cpu]` fields for 32-bit x86 systems (`i386-`, `i486-`, `i586-`, and `i686-`). Multiarch uses `i386-` for all of them. -2. The 32-bit ARM ABI for systems with hardware floating point is incompatible with the ABI for systems without floating point. Autoconf tuples use the same tuples (`arm-*-*eabi`) for both of these ABIs; multiarch distinguishes between them as `arm-*-*eabi` and `arm-*-*eabihf`. +In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. This needs a better name than `config`! This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.sub` file in the source code for `autoconf`. The script is also available via the `gnu-config` package in nixpkgs. From a0b3adf23bf9d5ffe152904548f7ae9e025d7d7c Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Sun, 3 Jul 2022 19:07:40 -0700 Subject: [PATCH 4/9] "Nix host double" -> "Nix system double", "the previous format" -> "the format used by the nix interpreter" --- doc/stdenv/cross-compilation.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 8cb4b15fe6da2..2d8337fa07fd9 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -46,7 +46,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv : This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and adopted by LLVM. For 32-bit arm, nixpkgs adopts the [multiarch solution](https://wiki.debian.org/Multiarch/Tuples#Used_solution) to the problem of distinguishing between `arm-*-*-*` and `armhf-*-*-*`, which are linker-incompatible due to having different calling conventions. -In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. This needs a better name than `config`! +In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix system double", the format used by the nix interpreter. This needs a better name than `config`! This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.sub` file in the source code for `autoconf`. The script is also available via the `gnu-config` package in nixpkgs. From dd6235b334274cad7170548616a2191304494f92 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Sun, 3 Jul 2022 19:39:11 -0700 Subject: [PATCH 5/9] remove mention of multiarch --- doc/stdenv/cross-compilation.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 2d8337fa07fd9..49385c53258bb 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -44,7 +44,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv `config` -: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and adopted by LLVM. For 32-bit arm, nixpkgs adopts the [multiarch solution](https://wiki.debian.org/Multiarch/Tuples#Used_solution) to the problem of distinguishing between `arm-*-*-*` and `armhf-*-*-*`, which are linker-incompatible due to having different calling conventions. +: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and adopted by LLVM. In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix system double", the format used by the nix interpreter. This needs a better name than `config`! From f34b04ec11c981948015ed4ffdc31d298aab5349 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Sun, 3 Jul 2022 20:14:15 -0700 Subject: [PATCH 6/9] add link to LLVM triples documentation --- doc/stdenv/cross-compilation.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 49385c53258bb..a47c5209614ec 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -44,7 +44,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv `config` -: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and adopted by LLVM. +: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and [adopted by LLVM](https://clang.llvm.org/docs/CrossCompilation.html#target-triple). In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix system double", the format used by the nix interpreter. This needs a better name than `config`! From 494a1fdec44ebcdfc916673c326e525e45218172 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Mon, 1 Aug 2022 15:22:35 -0700 Subject: [PATCH 7/9] cross-compilation.md: correct the authoritative source of config.sub Implements https://github.com/NixOS/nixpkgs/pull/180030/files#r934931579 --- doc/stdenv/cross-compilation.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index a47c5209614ec..af94a98668143 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -48,7 +48,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix system double", the format used by the nix interpreter. This needs a better name than `config`! -This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.sub` file in the source code for `autoconf`. The script is also available via the `gnu-config` package in nixpkgs. +This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.sub` file in the source code for `gnu-config`. `parsed` From c3d8109a7cbb71d74124bf64e60ada439d189183 Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Mon, 24 Apr 2023 05:29:02 +0000 Subject: [PATCH 8/9] Update doc/stdenv/cross-compilation.chapter.md Co-authored-by: Valentin Gagarin --- doc/stdenv/cross-compilation.chapter.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index af94a98668143..2d03f876b112d 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -44,9 +44,27 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv `config` -: This is a 3-, 4-, or 5- component shorthand for the platform. Examples of this would be `x86_64-unknown-linux-gnux32`, `aarch64-apple-darwin14`, and `mips64el-unknown-linux-muslabin32`. This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and [adopted by LLVM](https://clang.llvm.org/docs/CrossCompilation.html#target-triple). - -In the 5-part form, this corresponds to `[cpu]-[vendor]-[os]-[libc][abi]`; note that there is no hyphen separating the `[libc]` field from the `[abi]` field. This format is strictly more informative than the "Nix system double", the format used by the nix interpreter. This needs a better name than `config`! +: This is a 3-, 4-, or 5-component shorthand for the platform. + + Format: + + - `[cpu]-[vendor]-[os]` + - `[cpu]-[vendor]-[os]-[abi]` + - `[cpu]-[vendor]-[os]-[libc][abi]` + + :::{.note} + There is no hyphen separating the `[libc]` field from the `[abi]` field. + ::: + + Examples: + + - `aarch64-apple-darwin14` + - `x86_64-unknown-linux-gnux32` + - `mips64el-unknown-linux-muslabin32` + + This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and [adopted by LLVM](https://clang.llvm.org/docs/CrossCompilation.html#target-triple). + It is strictly more informative than the platform string `[cpu]-[os]` used by Nix. + This field should be *canonicalized*. The rules for canonicalizing a tuple are kept in the `config.sub` file in the source code for `gnu-config`. From d1100977673b8af12d1bffd0cc4b4b822d559565 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Sun, 23 Apr 2023 22:26:53 -0700 Subject: [PATCH 9/9] fix trailing whitespace --- doc/stdenv/cross-compilation.chapter.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index 2d03f876b112d..3cef3a92ed51d 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -45,23 +45,23 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv `config` : This is a 3-, 4-, or 5-component shorthand for the platform. - + Format: - + - `[cpu]-[vendor]-[os]` - `[cpu]-[vendor]-[os]-[abi]` - `[cpu]-[vendor]-[os]-[libc][abi]` :::{.note} There is no hyphen separating the `[libc]` field from the `[abi]` field. - ::: + ::: Examples: - + - `aarch64-apple-darwin14` - `x86_64-unknown-linux-gnux32` - `mips64el-unknown-linux-muslabin32` - + This is a standard format [pioneered by autoconf](https://www.gnu.org/software/autoconf/manual/autoconf-2.65/html_node/System-Type.html#System-Type) and [adopted by LLVM](https://clang.llvm.org/docs/CrossCompilation.html#target-triple). It is strictly more informative than the platform string `[cpu]-[os]` used by Nix.