From c3dd6c2c591047ef32517623423425188361df84 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 29 Oct 2019 11:34:41 -0300 Subject: [PATCH 01/11] Add tools.cppstd_minimum_required Signed-off-by: Uilian Ries --- howtos/manage_cpp_standard.rst | 7 ++++++ reference/tools.rst | 43 ++++++++++++++++++++++++++++------ 2 files changed, 43 insertions(+), 7 deletions(-) diff --git a/howtos/manage_cpp_standard.rst b/howtos/manage_cpp_standard.rst index aa14f1793bc8..e14d12c7f31e 100644 --- a/howtos/manage_cpp_standard.rst +++ b/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:`cppstd_minimum_required `. \ No newline at end of file diff --git a/reference/tools.rst b/reference/tools.rst index c609f8833d77..de2fc6cb5455 100644 --- a/reference/tools.rst +++ b/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,32 @@ 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.cppstd_minimum_required: + +tools.cppstd_minimum_required() +------------------------------- + +.. code-block:: python + + def cppstd_minimum_required(conanfile, cppstd_version) + +Validate the current cppstd from settings or compiler, if it is supported by the required cppstd version. + +.. code-block:: python + + from conans import tools, ConanFile + + class Recipe(ConanFile): + ... + + def configure(self): + tools.cppstd_minimum_required(self, "17") + +* If the current cppstd does not support C++17, ``cppstd_minimum_required`` 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. + +Parameters: + - **conanfile** (Required): ConanFile instance. Usually ``self``. + - **cppstd_version** (Required): C++ standard version which must be supported. From eec6dbaabd430a53d2f938eea065d9860c1c9d7e Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 14 Nov 2019 09:51:46 -0300 Subject: [PATCH 02/11] Rename cppstd_minimum_required to check_min_cppstd Signed-off-by: Uilian Ries --- howtos/manage_cpp_standard.rst | 2 +- reference/tools.rst | 53 ++++++++++++++++++++++++++++++---- 2 files changed, 48 insertions(+), 7 deletions(-) diff --git a/howtos/manage_cpp_standard.rst b/howtos/manage_cpp_standard.rst index e14d12c7f31e..9ead2dabf0dd 100644 --- a/howtos/manage_cpp_standard.rst +++ b/howtos/manage_cpp_standard.rst @@ -100,4 +100,4 @@ 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:`cppstd_minimum_required `. \ No newline at end of file +comparing the ``cppstd``. For such condition, there is the helper :ref:`check_min_cppstd `. diff --git a/reference/tools.rst b/reference/tools.rst index de2fc6cb5455..fc6e3a05e5b3 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1623,16 +1623,17 @@ 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.cppstd_minimum_required: +.. _tools.check_min_cppstd: -tools.cppstd_minimum_required() +tools.check_min_cppstd() ------------------------------- .. code-block:: python - def cppstd_minimum_required(conanfile, cppstd_version) + 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 @@ -1642,12 +1643,52 @@ Validate the current cppstd from settings or compiler, if it is supported by the ... def configure(self): - tools.cppstd_minimum_required(self, "17") + tools.check_min_cppstd(self, "17") -* If the current cppstd does not support C++17, ``cppstd_minimum_required`` will raise an ``InvalidConfiguration`` error. +* 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_version** (Required): C++ standard version which must be supported. + - **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). From efa25f6672c0592ecf2e904b2d04967a417bd5cf Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 3 Dec 2019 10:05:48 -0300 Subject: [PATCH 03/11] Update check_min_cppstd and check_min_cppstd description Signed-off-by: Uilian Ries --- reference/tools.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/reference/tools.rst b/reference/tools.rst index fc6e3a05e5b3..9cf380617179 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1646,16 +1646,15 @@ It raises a ``InvalidConfiguration`` when is not supported. 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. +* When there is no cppstd declared in setttings or is ``None``, the current compiler version listed in the profile will be used to detect + the default standard C++ version supported. +* If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions + (e.g. gnu17), otherwise, an ``InvalidConfiguration`` will be raised. The ``gnu_extensions`` is checked in any OS. 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). + - **gnu_extensions** (Optional): GNU extension is required. .. _tools.valid_min_cppstd: @@ -1682,13 +1681,12 @@ It returns ``True`` when is valid, otherwise, ``False``. * 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. +* When there is no cppstd declared in settings or is ``None``, the current compiler version listed in the profile will be used to detect + the default standard C++ version supported. +* If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions + (e.g. gnu17), otherwise, it will return ``False``. The ``gnu_extensions`` is checked in any OS. 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). + - **gnu_extensions** (Optional): GNU extension is required. From dd1c778955f6f1fd5fcc35c1755698a9faaefd25 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 3 Dec 2019 10:29:31 -0300 Subject: [PATCH 04/11] Apply review changes Signed-off-by: Uilian Ries --- reference/tools.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/reference/tools.rst b/reference/tools.rst index 9cf380617179..7d023b9b47ac 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1626,14 +1626,14 @@ Parameters: .. _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. +It raises a ``ConanInvalidConfiguration`` when is not supported. .. code-block:: python @@ -1645,11 +1645,11 @@ It raises a ``InvalidConfiguration`` when is not supported. 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. +* If the current cppstd does not support C++17, ``check_min_cppstd`` will raise an ``ConanInvalidConfiguration`` error. * When there is no cppstd declared in setttings or is ``None``, the current compiler version listed in the profile will be used to detect the default standard C++ version supported. * If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions - (e.g. gnu17), otherwise, an ``InvalidConfiguration`` will be raised. The ``gnu_extensions`` is checked in any OS. + (e.g. gnu17), otherwise, an :ref:`ConanInvalidConfiguration` will be raised. The ``gnu_extensions`` is checked in any OS. Parameters: - **conanfile** (Required): ConanFile instance. Usually ``self``. @@ -1659,7 +1659,7 @@ Parameters: .. _tools.valid_min_cppstd: tools.valid_min_cppstd() -------------------------------- +------------------------ .. code-block:: python @@ -1679,10 +1679,8 @@ It returns ``True`` when is valid, otherwise, ``False``. 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. +* The ``valid_min_cppstd`` works exactly like ``check_min_cppstd``, however, it does not raise ``ConanInvalidConfiguration`` error. * If the current cppstd does not support C++17, ``valid_min_cppstd`` returns ``False``. -* When there is no cppstd declared in settings or is ``None``, the current compiler version listed in the profile will be used to detect - the default standard C++ version supported. * If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions (e.g. gnu17), otherwise, it will return ``False``. The ``gnu_extensions`` is checked in any OS. From 85d9b7d94515c9c34432e6621e8dff96fdb4d419 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:07:27 -0300 Subject: [PATCH 05/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index 7d023b9b47ac..f0166d4cc2ee 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1682,7 +1682,6 @@ It returns ``True`` when is valid, otherwise, ``False``. * The ``valid_min_cppstd`` works exactly like ``check_min_cppstd``, however, it does not raise ``ConanInvalidConfiguration`` error. * If the current cppstd does not support C++17, ``valid_min_cppstd`` returns ``False``. * If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions - (e.g. gnu17), otherwise, it will return ``False``. The ``gnu_extensions`` is checked in any OS. Parameters: - **conanfile** (Required): ConanFile instance. Usually ``self``. From 3c0ad2ec5b2c6c6728e4da415ab8c252ecb4ba23 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:07:34 -0300 Subject: [PATCH 06/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index f0166d4cc2ee..887184d5a476 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1648,7 +1648,7 @@ It raises a ``ConanInvalidConfiguration`` when is not supported. * If the current cppstd does not support C++17, ``check_min_cppstd`` will raise an ``ConanInvalidConfiguration`` error. * When there is no cppstd declared in setttings or is ``None``, the current compiler version listed in the profile will be used to detect the default standard C++ version supported. -* If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions +* If ``gnu_extensions`` is True, it is required that the applied ``cppstd`` supports the gnu extensions. (e.g. gnu17), otherwise, an :ref:`ConanInvalidConfiguration` will be raised. The ``gnu_extensions`` is checked in any OS. Parameters: From ddce6b187058dc2cbad759fc69d1e7f107292494 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:07:40 -0300 Subject: [PATCH 07/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index 887184d5a476..f947be74eae7 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1647,7 +1647,6 @@ It raises a ``ConanInvalidConfiguration`` when is not supported. * If the current cppstd does not support C++17, ``check_min_cppstd`` will raise an ``ConanInvalidConfiguration`` error. * When there is no cppstd declared in setttings or is ``None``, the current compiler version listed in the profile will be used to detect - the default standard C++ version supported. * If ``gnu_extensions`` is True, it is required that the applied ``cppstd`` supports the gnu extensions. (e.g. gnu17), otherwise, an :ref:`ConanInvalidConfiguration` will be raised. The ``gnu_extensions`` is checked in any OS. From 265b6f9bbd42c2b19ab1e031a6392bd37aa92584 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:07:47 -0300 Subject: [PATCH 08/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index f947be74eae7..f5818dc4aa6e 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1646,7 +1646,6 @@ It raises a ``ConanInvalidConfiguration`` when is not supported. tools.check_min_cppstd(self, "17") * If the current cppstd does not support C++17, ``check_min_cppstd`` will raise an ``ConanInvalidConfiguration`` error. -* When there is no cppstd declared in setttings or is ``None``, the current compiler version listed in the profile will be used to detect * If ``gnu_extensions`` is True, it is required that the applied ``cppstd`` supports the gnu extensions. (e.g. gnu17), otherwise, an :ref:`ConanInvalidConfiguration` will be raised. The ``gnu_extensions`` is checked in any OS. From 454694668358ac3f1b46f850857ee904c49b35c2 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:07:52 -0300 Subject: [PATCH 09/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index f5818dc4aa6e..c9774cfff039 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1632,7 +1632,7 @@ tools.check_min_cppstd() 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. +Validates if the applied cppstd setting (from `compiler.cppstd` settings or deducing the default from `compiler` and `compiler.version`) is at least the value specified in the `cppstd` argument. It raises a ``ConanInvalidConfiguration`` when is not supported. .. code-block:: python From 844ab25d5979f97b8685c85f0c8c49026ab7c5e4 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:08:00 -0300 Subject: [PATCH 10/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index c9774cfff039..76c1a2b84651 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1678,7 +1678,6 @@ It returns ``True`` when is valid, otherwise, ``False``. self.output.error("C++17 is required.") * The ``valid_min_cppstd`` works exactly like ``check_min_cppstd``, however, it does not raise ``ConanInvalidConfiguration`` error. -* If the current cppstd does not support C++17, ``valid_min_cppstd`` returns ``False``. * If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions Parameters: From f2ce0508f10d3c02f8fa603f213e85aa8f592962 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Thu, 5 Dec 2019 13:08:07 -0300 Subject: [PATCH 11/11] Update reference/tools.rst Co-Authored-By: Luis Martinez de Bartolome Izquierdo --- reference/tools.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/tools.rst b/reference/tools.rst index 76c1a2b84651..6bc0d2a82df2 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -1678,7 +1678,6 @@ It returns ``True`` when is valid, otherwise, ``False``. self.output.error("C++17 is required.") * The ``valid_min_cppstd`` works exactly like ``check_min_cppstd``, however, it does not raise ``ConanInvalidConfiguration`` error. -* If ``gnu_extensions`` is True, the settings and/or compiler must support/offer GNU extensions Parameters: - **conanfile** (Required): ConanFile instance. Usually ``self``.