Add win_subsystem kwarg. Closes #7765.

2 files changed, 31 insertions, 2 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 8bff428..c1e509e 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -599,8 +599,9 @@ be passed to [shared and static libraries](#library).
 - `extra_files`: not used for the build itself but are shown as
   source files in IDEs that group files by targets (such as Visual
   Studio)
-- `gui_app`: when set to true flags this target as a GUI application on
-  platforms where this makes a difference (e.g. Windows).
+- `gui_app`: when set to true flags this target as a GUI application
+  on platforms where this makes a differerence, **deprecated** since
+  0.56.0, use `win_subsystem` instead.
 - `link_args`: flags to use during linking. You can use UNIX-style
   flags here for all platforms.
 - `link_depends`: strings, files, or custom targets the link step
@@ -677,6 +678,12 @@ be passed to [shared and static libraries](#library).
 - `pie` *(since 0.49.0)*: build a position-independent executable
 - `native`: is a boolean controlling whether the target is compiled for the
   build or host machines. Defaults to false, building for the host machine.
+- `win_subsystem` *(since 0.56.0)* specifies the subsystem type to use
+  on the Windows platform. Typical values include `console` for text
+  mode programs and `windows` for gui apps. The value can also contain
+  version specification such as `windows,6.0'. See [MSDN
+  documentation](https://docs.microsoft.com/en-us/cpp/build/reference/subsystem-specify-subsystem)
+  for the full list. The default value is `console`.
 
 The list of `sources`, `objects`, and `dependencies` is always
 flattened, which means you can freely nest and add lists while
diff --git a/docs/markdown/snippets/winsubsystem.md b/docs/markdown/snippets/winsubsystem.md
new file mode 100644
index 0000000..a7d589f
--- /dev/null
+++ b/docs/markdown/snippets/winsubsystem.md
@@ -0,0 +1,22 @@
+## Add support for all Windows subsystem types
+
+It is now possible to build things like Windows kernel drivers with
+the new `win_subsystem` keyword argument. This replaces the old
+`gui_app` keyword argument, which is now deprecated. You should update
+your project to use the new style like this:
+
+```meson
+# Old way
+executable(..., gui_app: 'true')
+# New way
+executable(..., win_subsystem: 'windows')
+```
+
+The argument supports versioning [as described on MSDN
+documentation](https://docs.microsoft.com/en-us/cpp/build/reference/subsystem-specify-subsystem).
+Thus to build a Windows kernel driver with a specific version you'd
+write something like this:
+
+```meson
+executable(..., win_subsystem: 'native,6.02')
+```