Add kernel and userland properties to machine objects.sysprops

3 files changed, 57 insertions, 3 deletions

diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md
index fb222220e..159d0ab49 100644
--- a/docs/markdown/Cross-compilation.md
+++ b/docs/markdown/Cross-compilation.md
@@ -212,6 +212,8 @@ target machines look the same. Here is a sample for host machine.
 ```ini
 [host_machine]
 system = 'windows'
+userland = 'windows'
+kernel = 'windows'
 cpu_family = 'x86'
 cpu = 'i686'
 endian = 'little'
@@ -221,9 +223,13 @@ These values define the machines sufficiently for cross compilation
 purposes. The corresponding target definition would look the same but
 have `target_machine` in the header. These values are available in
 your Meson scripts. There are three predefined variables called,
-surprisingly, [[@build_machine]], [[@host_machine]] and [[@target_machine]].
-Determining the operating system of your host machine is simply a
-matter of calling `host_machine.system()`.
+surprisingly, [[@build_machine]], [[@host_machine]] and
+[[@target_machine]]. Determining the operating system of your host
+machine is simply a matter of calling `host_machine.system()`.
+Starting from version 1.2.0 you can get more fine grained information
+using the `.userland()` and `.kernel()` methods. The return values of
+these functions are documented in [the reference table
+page](Reference-tables.md).
 
 There are two different values for the CPU. The first one is
 `cpu_family`. It is a general type of the CPU. This should have a
diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md
index fb7deda8a..dbbb92dac 100644
--- a/docs/markdown/Reference-tables.md
+++ b/docs/markdown/Reference-tables.md
@@ -161,6 +161,42 @@ These are provided by the `.system()` method call.
 Any string not listed above is not guaranteed to remain stable in
 future releases.
 
+## Kernel names (since 1.2.0)
+
+Native names as returned by the `.kernel()` method.
+
+| Value               | Comment                         |
+| -----               | -------                         |
+| linux   | |
+| freebsd | |
+| openbsd | |
+| windows | |
+| xnu                 | Kernel of various Apple OSes    |
+
+
+## Userland names (since 1.2.0)
+
+Native names as returned by the `.userland()` method.
+
+| Value               | Comment                          |
+| -----               | -------                          |
+| gnu                 | Linux or Hurd                    |
+| musl                | Linux using Musl libc            |
+| macos               | The OS formerly known as Mac OSX |
+| freebsd | |
+| openbsd | |
+| windows | |
+
+Recommended cross build names for systems that can not run Meson
+natively.
+
+| Value               | Comment                         |
+| -----               | -------                         |
+| ios                 | Apple iOS                       |
+| tvos                | Apple tvOS                      |
+| watchos             | Apple watchOS                   |
+| ipados              | Apple iPadOS                    |
+
 ## Language arguments parameter names
 
 These are the parameter names for passing language specific arguments to your build target.
diff --git a/docs/markdown/snippets/moremachinedata.md b/docs/markdown/snippets/moremachinedata.md
new file mode 100644
index 000000000..27d9a7eb2
--- /dev/null
+++ b/docs/markdown/snippets/moremachinedata.md
@@ -0,0 +1,12 @@
+## Machine objects get `kernel` and `userland` properties
+
+Meson has traditionally provided a `system` property to detect the
+system being run on. However this is not enough to reliably
+differentiate between e.g. an iOS platform from a watchOS one. Two new
+properties, namely `kernel` and `userland` have been added to make
+this configuration doable.
+
+These new properties are not necessary in cross files for now, but if
+they are not defined and a build file tries to access them, Meson will
+exit with a hard error. It is expected that at some point in the
+future defining the new properties will become mandatory.