Help: Document language standard meta-features

2 files changed, 34 insertions, 0 deletions

diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst
index 9862d4a..13f7d16 100644
--- a/Help/manual/cmake-compile-features.7.rst
+++ b/Help/manual/cmake-compile-features.7.rst
@@ -84,6 +84,33 @@ Feature requirements are evaluated transitively by consuming the link
 implementation.  See :manual:`cmake-buildsystem(7)` for more on
 transitive behavior of build properties and usage requirements.
 
+Requiring Language Standards
+----------------------------
+
+In projects that use a large number of commonly available features from
+a particular language standard (e.g. C++ 11) one may specify a
+meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode
+aware of that standard.  This is simpler than specifying all the
+features individually, but does not guarantee the existence of any
+particular feature.  Diagnosis of use of unsupported features will be
+delayed until compile time.
+
+For example, if C++ 11 features are used extensively in a project's
+header files, then clients must use a compiler mode aware of C++ 11
+or above.  This can be requested with the code:
+
+.. code-block:: cmake
+
+  target_compile_features(mylib PUBLIC cxx_std_11)
+
+In this example, CMake will ensure the compiler is invoked in a mode
+that is aware of C++ 11 (or above), adding flags such as
+``-std=gnu++11`` if necessary.  This applies to sources within ``mylib``
+as well as any dependents (that may include headers from ``mylib``).
+
+Availability of Compiler Extensions
+-----------------------------------
+
 Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default,
 CMake uses extended variants of language dialects by default, such as
 ``-std=gnu++11`` instead of ``-std=c++11``.  That target property may be
diff --git a/Help/release/dev/compile-features-for-language-standards.rst b/Help/release/dev/compile-features-for-language-standards.rst
new file mode 100644
index 0000000..20473b7
--- /dev/null
+++ b/Help/release/dev/compile-features-for-language-standards.rst
@@ -0,0 +1,7 @@
+compile-features-for-language-standards
+---------------------------------------
+
+* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
+  now offers meta-features that request compiler modes for specific language
+  standard levels.  See :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and
+  :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`.