doc: Update reference with better description of target_env

The definition of this value recently changed slightly. It no
longer corresponds directly to the target triple.

Also shuffled things around to make the order of cfg descriptions more
logical and added text related them to the target triple.

cc #33403

1 files changed, 26 insertions, 18 deletions

diff --git a/src/doc/reference.md b/src/doc/reference.md
index fcf9aefaba8..397abfe563c 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -2063,33 +2063,41 @@ arbitrarily complex configurations through nesting.
 
 The following configurations must be defined by the implementation:
 
-* `debug_assertions` - Enabled by default when compiling without optimizations.
-  This can be used to enable extra debugging code in development but not in
-  production.  For example, it controls the behavior of the standard library's
-  `debug_assert!` macro.
-* `target_arch = "..."` - Target CPU architecture, such as `"x86"`, `"x86_64"`
-  `"mips"`, `"powerpc"`, `"powerpc64"`, `"arm"`, or `"aarch64"`.
-* `target_endian = "..."` - Endianness of the target CPU, either `"little"` or
-  `"big"`.
-* `target_env = ".."` - An option provided by the compiler by default
-  describing the runtime environment of the target platform. Some examples of
-  this are `musl` for builds targeting the MUSL libc implementation, `msvc` for
-  Windows builds targeting MSVC, and `gnu` frequently the rest of the time. This
-  option may also be blank on some platforms.
+* `target_arch = "..."` - Target CPU architecture, such as `"x86"`,
+  `"x86_64"` `"mips"`, `"powerpc"`, `"powerpc64"`, `"arm"`, or
+  `"aarch64"`. This value is closely related to the first element of
+  the platform target triple, though it is not identical.
+* `target_os = "..."` - Operating system of the target, examples
+  include `"windows"`, `"macos"`, `"ios"`, `"linux"`, `"android"`,
+  `"freebsd"`, `"dragonfly"`, `"bitrig"` , `"openbsd"` or
+  `"netbsd"`. This value is closely related to the second and third
+  element of the platform target triple, though it is not identical.
 * `target_family = "..."` - Operating system family of the target, e. g.
   `"unix"` or `"windows"`. The value of this configuration option is defined
   as a configuration itself, like `unix` or `windows`.
-* `target_os = "..."` - Operating system of the target, examples include
-  `"windows"`, `"macos"`, `"ios"`, `"linux"`, `"android"`, `"freebsd"`, `"dragonfly"`,
-  `"bitrig"` , `"openbsd"` or `"netbsd"`.
+* `unix` - See `target_family`.
+* `windows` - See `target_family`.
+* `target_env = ".."` - Further disambiguates the target platform with
+  information about the ABI/libc. Presently this value is either
+  `"gnu"`, `"msvc"`, `"musl"`, or the empty string. For historical
+  reasons this value has only been defined as non-empty when needed
+  for disambiguation. Thus on many GNU platforms this value will be
+  empty. This value is closely related to the fourth element of the
+  platform target triple, though it is not identical. For example,
+  embedded ABIs such as `gnueabihf` will simply define `target_env` as
+  `"gnu"`.
+* `target_endian = "..."` - Endianness of the target CPU, either `"little"` or
+  `"big"`.
 * `target_pointer_width = "..."` - Target pointer width in bits. This is set
   to `"32"` for targets with 32-bit pointers, and likewise set to `"64"` for
   64-bit pointers.
 * `target_vendor = "..."` - Vendor of the target, for example `apple`, `pc`, or
   simply `"unknown"`.
 * `test` - Enabled when compiling the test harness (using the `--test` flag).
-* `unix` - See `target_family`.
-* `windows` - See `target_family`.
+* `debug_assertions` - Enabled by default when compiling without optimizations.
+  This can be used to enable extra debugging code in development but not in
+  production.  For example, it controls the behavior of the standard library's
+  `debug_assert!` macro.
 
 You can also set another attribute based on a `cfg` variable with `cfg_attr`: