Merge pull request #10332 from xclaesse/std-opt

c_std, cpp_std: Change to a list of desired versions in preference order

2 files changed, 33 insertions, 0 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index ca4fd14..f3cbcea 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -296,6 +296,21 @@ is inherited from the main project. This is useful, for example, when the main
 project requires C++11, but a subproject requires C++14. The `cpp_std` value
 from the subproject's `default_options` is now respected.
 
+Since *1.3.0* `c_std` and `cpp_std` options now accept a list of values.
+Projects that prefer GNU C, but can fallback to ISO C, can now set, for
+example, `default_options: 'c_std=gnu11,c11'`, and it will use `gnu11` when
+available, but fallback to c11 otherwise. It is an error only if none of the
+values are supported by the current compiler.
+Likewise, a project that can take benefit of `c++17` but can still build with
+`c++11` can set `default_options: 'cpp_std=c++17,c++11'`.
+This allows us to deprecate `gnuXX` values from the MSVC compiler. That means
+that `default_options: 'c_std=gnu11'` will now print a warning with MSVC
+but fallback to `c11`. No warning is printed if at least one
+of the values is valid, i.e. `default_options: 'c_std=gnu11,c11'`.
+In the future that deprecation warning will become an hard error because
+`c_std=gnu11` should mean GNU is required, for projects that cannot be
+built with MSVC for example.
+
 ## Specifying options per machine
 
 Since *0.51.0*, some options are specified per machine rather than
diff --git a/docs/markdown/snippets/cstd.md b/docs/markdown/snippets/cstd.md
new file mode 100644
index 0000000..cc1f083
--- /dev/null
+++ b/docs/markdown/snippets/cstd.md
@@ -0,0 +1,18 @@
+## `c_std` and `cpp_std` options now accepts a list of values
+
+Projects that prefer GNU C, but can fallback to ISO C, can now set, for
+example, `default_options: 'c_std=gnu11,c11'`, and it will use `gnu11` when
+available, but fallback to `c11` otherwise. It is an error only if none of the
+values are supported by the current compiler.
+
+Likewise, a project that can take benefit of `c++17` but can still build with
+`c++11` can set `default_options: 'cpp_std=c++17,c++11'`.
+
+This allows us to deprecate `gnuXX` values from the MSVC compiler. That means
+that `default_options: 'c_std=gnu11'` will now print a warning with MSVC
+but fallback to `c11`. No warning is printed if at least one
+of the values is valid, i.e. `default_options: 'c_std=gnu11,c11'`.
+
+In the future that deprecation warning will become an hard error because
+`c_std=gnu11` should mean GNU is required, for projects that cannot be
+built with MSVC for example.