Add documentation for import std.

2 files changed, 20 insertions, 0 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index 5b4da125b..bccf85f02 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -314,6 +314,7 @@ or compiler being used:
 | cpp_rtti         | true          | true, false                              | Whether to enable RTTI (runtime type identification) |
 | cpp_thread_count | 4             | integer value ≥ 0                        | Number of threads to use with emcc when using threads |
 | cpp_winlibs      | see below     | free-form comma-separated list           | Standard Windows libs to link against |
+| cpp_importstd    | false         | true or false                            | Whether to use `import std` |
 | fortran_std      | none          | [none, legacy, f95, f2003, f2008, f2018] | Fortran language standard to use |
 | rust_dynamic_std | false         | true, false                              | Whether to link dynamically to the Rust standard library *(Added in 1.9.0)* |
 | rust_nightly     | auto          | enabled, disabled, auto                  | Nightly Rust compiler (enabled=required, disabled=don't use nightly feature, auto=use nightly feature if available) *(Added in 1.10.0)* |
diff --git a/docs/markdown/snippets/istd.md b/docs/markdown/snippets/istd.md
new file mode 100644
index 000000000..6b92d114a
--- /dev/null
+++ b/docs/markdown/snippets/istd.md
@@ -0,0 +1,19 @@
+## Experimental C++ import std support
+
+**Note**: this feature is experimental and not guaranteed to be
+  backwards compatible or even exist at all in future Meson releases.
+
+Meson now supports `import std`, a new, modular way of using the C++
+standard library. This support is enabled with the new `cpp_importstd`
+option. It defaults to `false`, but you can set it to `true` either
+globally or per-target using `override_options` in the usual way.
+
+The implementation has many limitations. The biggest one is that the
+same module file is used on _all_ targets. That means you can not mix
+multiple different C++ standards versions as the compiled module file
+can only be used with the same compiler options as were used to build
+it. This feature only works with the Ninja backend.
+
+As `import std` is a major new feature in compilers, expect to
+encounter toolchain issues when using it. For an example [see
+here](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=122614).