Add tools.cppstd_minimum_required

howtos/manage_cpp_standard.rst

@@ -94,3 +94,10 @@ new packages, because it was already the default of your compiler.
 
    Conan 1.x will also generate the same packages as the ones generated with the deprecated
    setting ``cppstd`` for the default value of the standard.
+
+
+Required version
+----------------
+
+When the package to be built requires a minimal C++ standard support (e.g. 17), it can be done by
+comparing the ``cppstd``. For such condition, there is the helper :ref:`check_min_cppstd <tools.check_min_cppstd>`.

reference/tools.rst

@@ -473,7 +473,7 @@ Parameters:
     - **replace** (Required): String to replace the searched string.
     - **strict** (Optional, Defaulted to ``True``): If ``True``, it raises an error if the searched string is not found, so nothing is
       actually replaced.
-    - **encoding** (Optional, Defaulted to ``None``): Specifies the input and output files text encoding. The ``None`` value has a special 
+    - **encoding** (Optional, Defaulted to ``None``): Specifies the input and output files text encoding. The ``None`` value has a special
       meaning - perform the encoding detection by checking the BOM (byte order mask), if no BOM is present tries to use: ``utf-8``, ``cp1252``.
       In case of ``None``, the output file is saved to the ``utf-8``
 
@@ -484,7 +484,7 @@ tools.replace_path_in_file()
 
 .. code-block:: python
 
-    def replace_path_in_file(file_path, search, replace, strict=True, windows_paths=None, 
+    def replace_path_in_file(file_path, search, replace, strict=True, windows_paths=None,
                              encoding=None)
 
 Replace a path in a file with another string. In Windows, it will match the path even if the casing and the path separator doesn't match.
@@ -509,7 +509,7 @@ Parameters:
       - ``False``: Deactivated, it will match exact patterns (like :ref:`tools_replace_in_file`).
       - ``True``: Always activated, irrespective of the detected operating system.
 
-    - **encoding** (Optional, Defaulted to ``None``): Specifies the input and output files text encoding. The ``None`` value has a special 
+    - **encoding** (Optional, Defaulted to ``None``): Specifies the input and output files text encoding. The ``None`` value has a special
       meaning - perform the encoding detection by checking the BOM (byte order mask), if no BOM is present tries to use: ``utf-8``, ``cp1252``.
       In case of ``None``, the output file is saved to the ``utf-8``
 
@@ -790,8 +790,8 @@ Parameters:
     - **settings** (Required): Conanfile settings. Use ``self.settings``.
     - **self_os** (Optional, Defaulted to ``None``): Current operating system where the build is being done.
     - **self_arch** (Optional, Defaulted to ``None``): Current architecture where the build is being done.
-    - **skip_x64_x86** (Optional, Defaulted to ``False``): Do not consider building for ``x86`` host from ``x86_64`` build machine 
-      as cross building, in case of host and build machine use the same operating system. Normally, in such case build machine may 
+    - **skip_x64_x86** (Optional, Defaulted to ``False``): Do not consider building for ``x86`` host from ``x86_64`` build machine
+      as cross building, in case of host and build machine use the same operating system. Normally, in such case build machine may
       execute binaries produced for the target machine, and special cross-building handling may not be needed.
 
 .. _tools_get_gnu_triplet:
@@ -1007,8 +1007,8 @@ the file.
 Parameters:
     - **path** (Required): Path to the file.
     - **binary** (Optional, Defaulted to ``False``): If ``True``, it reads the the file as binary code.
-    - **encoding** (Optional, Defaulted to ``auto``): Specifies the input file text encoding. The ``auto`` value has a special 
-      meaning - perform the encoding detection by checking the BOM (byte order mask), if no BOM is present tries to use: ``utf-8``, ``cp1252``. 
+    - **encoding** (Optional, Defaulted to ``auto``): Specifies the input file text encoding. The ``auto`` value has a special
+      meaning - perform the encoding detection by checking the BOM (byte order mask), if no BOM is present tries to use: ``utf-8``, ``cp1252``.
       The value is ignored in case of ``binary`` set to the ``True``.
 
 .. _tools_mkdir_rmdir:
@@ -1622,3 +1622,73 @@ Converts Conan style architecture into Android NDK style architecture.
 
 Parameters:
     - **arch** (Required): Arch to perform the conversion. Usually this would be ``self.settings.arch``.
+
+.. _tools.check_min_cppstd:
+
+tools.check_min_cppstd()
+-------------------------------
+
+.. code-block:: python
+
+    def check_min_cppstd(conanfile, cppstd, gnu_extensions=False)
+
+Validate the current cppstd from settings or compiler, if it is supported by the required cppstd version.
+It raises a ``InvalidConfiguration`` when is not supported.
+
+.. code-block:: python
+
+    from conans import tools, ConanFile
+
+    class Recipe(ConanFile):
+        ...
+
+        def configure(self):
+            tools.check_min_cppstd(self, "17")
+
+* If the current cppstd does not support C++17, ``check_min_cppstd`` will raise an ``InvalidConfiguration`` error.
+* When there is no cppstd declared or is ``None``, the current compiler version listed in the profile will be used to detect
+  the compatibility with the required C++ standard.
+* If ``gnu_extensions`` is True and your current OS is Linux, the settings and/or compiler must support/offer GNU extensions
+  (e.g. gnu17), otherwise, an ``InvalidConfiguration`` will be raised. The ``gnu_extensions`` is only checked on Linux, for
+  any other OS it will be skipped.
+
+Parameters:
+    - **conanfile** (Required): ConanFile instance. Usually ``self``.
+    - **cppstd** (Required): C++ standard version which must be supported.
+    - **gnu_extensions** (Optional): GNU extension is required (only for Linux).
+
+.. _tools.valid_min_cppstd:
+
+tools.valid_min_cppstd()
+-------------------------------
+
+.. code-block:: python
+
+    def valid_min_cppstd(conanfile, cppstd, gnu_extensions=False)
+
+Validate the current cppstd from settings or compiler, if it is supported by the required cppstd version.
+It returns ``True`` when is valid, otherwise, ``False``.
+
+.. code-block:: python
+
+    from conans import tools, ConanFile
+
+    class Recipe(ConanFile):
+        ...
+
+        def configure(self):
+            if not tools.valid_min_cppstd(self, "17"):
+                self.output.error("C++17 is required.")
+
+* The ``valid_min_cppstd`` works exactly like ``check_min_cppstd``, however, it does not raise ``InvalidConfiguration`` error.
+* If the current cppstd does not support C++17, ``valid_min_cppstd`` returns ``False``.
+* When there is no cppstd declared or is ``None``, the current compiler version listed in the profile will be used to detect
+  the compatibility with the required C++ standard.
+* If ``gnu_extensions`` is True and your current OS is Linux, the settings and/or compiler must support/offer GNU extensions
+  (e.g. gnu17), otherwise, it will return ``False``. The ``gnu_extensions`` is only checked on Linux, for
+  any other OS it will be skipped.
+
+Parameters:
+    - **conanfile** (Required): ConanFile instance. Usually ``self``.
+    - **cppstd** (Required): C++ standard version which must be supported.
+    - **gnu_extensions** (Optional): GNU extension is required (only for Linux).