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

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, fallback to c11 otherwise. It is an error only if none of the
values are supported by the current compiler.

This allows to deprecate gnuXX values from MSVC compiler, that means
that `default_options: 'c_std=gnu11'` will now print warning with MSVC
but still fallback to 'c11' value. 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.

2 files changed, 33 insertions, 0 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index fed893e..cd86e22 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.