From e2227ee54b92f4bbe585beb2d4fd3a3b6a5ea739 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 19 Jul 2023 15:27:48 +0200 Subject: [PATCH 1/9] docs for implements --- reference/conanfile/attributes.rst | 30 +++++ .../conanfile/methods/config_options.rst | 41 ++++++- reference/conanfile/methods/configure.rst | 47 +++++++- reference/conanfile/methods/package_id.rst | 42 +++++-- reference/tools/cpp_info.rst | 106 ------------------ 5 files changed, 141 insertions(+), 125 deletions(-) diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index 224f2df6fb9d..eaef5db6f212 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -128,3 +128,33 @@ Version ranges as in ``requires`` are allowed. Also there is a ``global.conf`` file ``core:required_conan_version`` configuration that can define a global minimum, maximum or exact Conan version to run, which can be very convenient to maintain teams of developers and CI machines to use the desired range of versions. + +.. _conan_conanfile_attributes_implements: + +implements +---------- + +A list is used to define a series of option configurations that Conan will handle +automatically. This is especially handy for avoiding boilerplate code that tends to repeat +in most of the recipes. The syntax is as follows: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + implements = ["auto_shared_fpic", "auto_header_only_package", ...] + + +Currently these are the automatic implementations provided by Conan: + +- ``"auto_shared_fpic"``: automatically manages ``fPIC`` and ``shared`` options. Adding this + implementation will have both effect in the + :ref:`configure` and + :ref:`config_options` steps + when those methods are not explicitly defined in the recipe. + +- ``"auto_header_only_package"``: automatically manages the package ID clearing settings. Adding this + implementation will have effect in the + :ref:`package_id` step + when the method is not explicitly defined in the recipe. diff --git a/reference/conanfile/methods/config_options.rst b/reference/conanfile/methods/config_options.rst index 95ff071ed635..b2f291746aee 100644 --- a/reference/conanfile/methods/config_options.rst +++ b/reference/conanfile/methods/config_options.rst @@ -18,18 +18,45 @@ The ``config_options()`` method executes: * Before assigning the ``options`` values. * After ``settings`` are already defined. -Default behavior -++++++++++++++++ +.. _reference_conanfile_methods_config_options_implementations: + +Available automatic implementations ++++++++++++++++++++++++++++++++++++ .. include:: ../../../common/experimental_warning.inc -When the ``config_options()`` method is not defined, Conan automatically manages some conventional options using -the :ref:`conan.tools.default_config_options()` tool. +When the ``config_options()`` method is not defined, Conan can automatically manage some +conventional options if specified in the +:ref:`implements` ConanFile attribute: + +auto_shared_fpic +---------------- Options automatically managed: - ``fPIC`` (True, False). +It can be added to the recipe like this: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + implements = ["auto_shared_fpic"] + ... + +Then, if no ``config_options()`` method is specified in the recipe, Conan will +automatically manage the fPIC setting in the ``config_options`` step like this: + +.. code-block:: python + + if conanfile.settings.get_safe("os") == "Windows": + conanfile.options.rm_safe("fPIC") + +Be aware that adding this implementation to the recipe may also affect the +:ref:`configure` step. + To opt-out from this behavior, the method can be empty-defined: .. code-block:: python @@ -37,14 +64,16 @@ To opt-out from this behavior, the method can be empty-defined: def config_options(self): pass -To manage extra options apart from the ones automatically handled, the tool has to be explicitly called: +If you need to implement custom behaviors in your recipes but also need this logic, it +must be explicitly declared: .. code-block:: python from conan.tools import default_config_options def config_options(self): - default_config_options(self) + if conanfile.settings.get_safe("os") == "Windows": + conanfile.options.rm_safe("fPIC") if self.settings.arch != "x86_64": del self.options.with_sse2 diff --git a/reference/conanfile/methods/configure.rst b/reference/conanfile/methods/configure.rst index 40340aa63fe1..ec3609564413 100644 --- a/reference/conanfile/methods/configure.rst +++ b/reference/conanfile/methods/configure.rst @@ -43,13 +43,19 @@ so it should be removed: # fPIC might have been removed in config_options(), so we use rm_safe self.options.rm_safe("fPIC") -Default behavior -++++++++++++++++ +.. _reference_conanfile_methods_configure_implementations: + +Available automatic implementations ++++++++++++++++++++++++++++++++++++ .. include:: ../../../common/experimental_warning.inc -When the ``configure()`` method is not defined, Conan automatically manages some conventional options calling the -:ref:`conan.tools.default_configure()` tool. +When the ``configure()`` method is not defined, Conan can automatically manage some +conventional options if specified in the +:ref:`implements` ConanFile attribute: + +auto_shared_fpic +---------------- Options automatically managed: @@ -57,6 +63,30 @@ Options automatically managed: - ``shared`` (True, False). - ``header_only`` (True, False). +It can be added to the recipe like this: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + implements = ["auto_shared_fpic"] + ... + +Then, if no ``configure()`` method is specified in the recipe, Conan will +automatically manage the fPIC setting in the ``configure`` step like this: + +.. code-block:: python + + if conanfile.options.get_safe("header_only"): + conanfile.options.rm_safe("fPIC") + conanfile.options.rm_safe("shared") + elif conanfile.options.get_safe("shared"): + conanfile.options.rm_safe("fPIC") + +Be aware that adding this implementation to the recipe may also affect the +:ref:`configure` step. + To opt-out from this behavior, the method can be empty-defined: .. code-block:: python @@ -64,14 +94,19 @@ To opt-out from this behavior, the method can be empty-defined: def configure(self): pass -To manage extra options apart from the ones automatically handled, the tool has to be explicitly called: +If you need to implement custom behaviors in your recipes but also need this logic, it +must be explicitly declared: .. code-block:: python from conan.tools import default_configure def configure(self): - default_configure(self) + if conanfile.options.get_safe("header_only"): + conanfile.options.rm_safe("fPIC") + conanfile.options.rm_safe("shared") + elif conanfile.options.get_safe("shared"): + conanfile.options.rm_safe("fPIC") self.settings.rm_safe("compiler.libcxx") self.settings.rm_safe("compiler.cppstd") diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index 0b1ed25d8bc1..98fa121b78c6 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -12,14 +12,40 @@ The general rule is that every different value of ``settings`` and ``options`` c - A given package recipe can implement some partial erasure of information, for example to obtain the same ``package_id`` for a range of compiler versions. This type of binary compatibility is in general better addressed with the global ``compatibility`` plugin, or with the ``compatibility()`` method if the global plugin is not enough. - A package recipe can decide to inject extra variability in its computed ``package_id``, adding ``conf`` items or "target" settings. -Default behavior -++++++++++++++++ +.. _reference_conanfile_methods_package_id_implementations: + +Available automatic implementations ++++++++++++++++++++++++++++++++++++ .. include:: ../../../common/experimental_warning.inc -When the ``package_id()`` method is not defined, Conan automatically manages the package ID clearing settings and options when the recipe -declares an option ``header_only=True`` or when ``package_type`` is ``"header-library"``. -This is achived by calling the :ref:`conan.tools.default_package_id()` tool. +When the ``package_id()`` method is not defined, the following automatic implementation +can be specified in the :ref:`implements` ConanFile +attribute: + +auto_header_only +---------------- + +Conan will automatically manage the package ID clearing settings and options when the +recipe declares an option ``header_only=True`` or when ``package_type`` is +``"header-library"``. It can be added to the recipe like this: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + implements = ["auto_header_only"] + ... + +Then, if no ``package_id()`` method is specified in the recipe, Conan will +automatically manage the fPIC setting in the ``package_id`` step like this: + +.. code-block:: python + + if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER: + conanfile.info.clear() + To opt-out from this behavior, the method can be empty-defined: @@ -28,14 +54,16 @@ To opt-out from this behavior, the method can be empty-defined: def package_id(self): pass -To manage the package ID info further, the tool has to be explicitly called: +If you need to implement custom behaviors in your recipes but also need this logic, it +must be explicitly declared: .. code-block:: python from conan.tools import default_package_id def package_id(self): - default_package_id(self) + if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER: + conanfile.info.clear() self.info.settings.rm_safe("compiler.libcxx") self.info.settings.rm_safe("compiler.cppstd") diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst index f7e98ade0e29..7daa65515d4e 100644 --- a/reference/tools/cpp_info.rst +++ b/reference/tools/cpp_info.rst @@ -48,109 +48,3 @@ The public documented interface (besides the defined one in :ref:`the package_in - ``CppInfo(conanfile)``: Constructor. Receives a ``conanfile`` as argument, typically ``self`` - ``aggregated_components()``: return a new ``CppInfo`` object resulting from the aggregation of all the components - ``merge(other_cppinfo: CppInfo)``: modifies the current ``CppInfo`` object, updating it with the information of the parameter ``other_cppinfo``, allowing to aggregate information from multiple dependencies. - -.. _conan_tools_default_config_options: - -conan.tools.default_config_options -================================== - -.. include:: ../../common/experimental_warning.inc - -.. note:: - - This tool is automatically called **only** whenever a recipe does not declare a ``config_options()`` method explicitly. - -Manage options in `config_options()` method automatically. This tool manages the following options: - -- ``fPIC`` (True, False): Option set as a convention to designate "Position Independent Code" flag. - This option is not intended for Windows, so the tool automatically deletes it if the option is defined in the recipe. - -Implementation: - -.. code-block:: python - - def default_configure(conanfile): - if conanfile.options.get_safe("header_only"): - conanfile.options.rm_safe("fPIC") - conanfile.options.rm_safe("shared") - elif conanfile.options.get_safe("shared"): - conanfile.options.rm_safe("fPIC") - -Usage: - -.. code-block:: python - - from conan.tools import default_config_options - - def config_options(self): - default_config_options(self) - -.. _conan_tools_default_configure: - -conan.tools.default_configure -============================= - -.. include:: ../../common/experimental_warning.inc - -.. note:: - - This tool is automatically called **only** whenever a recipe does not declare a ``configure()`` method explicitly. - -Manage options in `configure()` method automatically. This tool manages the following options: - -- ``fPIC`` (True, False): Option set as a convention to designate "Position Independent Code" flag. - This option is removed when there is a ``header_only=True`` option or when ``shared=True``. -- ``shared`` (True, False): Option set as a convention to designate a dynamic library. - This option is removed when there is a ``header_only=True`` option. - -Implementation: - -.. code-block:: python - - def default_configure(conanfile): - if conanfile.options.get_safe("header_only"): - conanfile.options.rm_safe("fPIC") - conanfile.options.rm_safe("shared") - elif conanfile.options.get_safe("shared"): - conanfile.options.rm_safe("fPIC") - -Usage: - -.. code-block:: python - - from conan.tools import default_configure - - def configure(self): - default_configure(self) - -.. _conan_tools_default_package_id: - -conan.tools.default_package_id -============================== - -.. include:: ../../common/experimental_warning.inc - -.. note:: - - This tool is automatically called **only** whenever a recipe does not declare a ``package_id()`` method explicitly. - -Manages settings and options in `package_id()` method automatically. -This tool clears the defined settings and options from the package ID -when the recipe declares an option ``header_only=True`` or when ``package_type`` is ``"header-library"``. - -Implementation: - -.. code-block:: python - - def default_package_id(conanfile): - if conanfile.options.get_safe("header_only") or conanfile.package_type is "header-library": - conanfile.info.clear() - -Usage: - -.. code-block:: python - - from conan.tools import default_configure - - def package_id(self): - default_package_id(self) From 3b2a3e99cbac582031cb269d7fb720abd1419477 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 19 Jul 2023 16:15:21 +0200 Subject: [PATCH 2/9] Update reference/conanfile/attributes.rst Co-authored-by: James --- reference/conanfile/attributes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index eaef5db6f212..b3cadd67efdd 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -143,7 +143,7 @@ in most of the recipes. The syntax is as follows: from conan import ConanFile class Pkg(ConanFile): - implements = ["auto_shared_fpic", "auto_header_only_package", ...] + implements = ["auto_shared_fpic", "auto_header_only", ...] Currently these are the automatic implementations provided by Conan: From 735e609572c894316588ce4eeaaae879e48e2f7a Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 19 Jul 2023 16:15:39 +0200 Subject: [PATCH 3/9] Update reference/conanfile/methods/config_options.rst Co-authored-by: James --- reference/conanfile/methods/config_options.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/conanfile/methods/config_options.rst b/reference/conanfile/methods/config_options.rst index b2f291746aee..c6507a802021 100644 --- a/reference/conanfile/methods/config_options.rst +++ b/reference/conanfile/methods/config_options.rst @@ -69,7 +69,6 @@ must be explicitly declared: .. code-block:: python - from conan.tools import default_config_options def config_options(self): if conanfile.settings.get_safe("os") == "Windows": From ceae8bffce9d78cc5a5e4c2536d24d5cf756861e Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 19 Jul 2023 16:16:19 +0200 Subject: [PATCH 4/9] Update reference/conanfile/attributes.rst Co-authored-by: James --- reference/conanfile/attributes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index b3cadd67efdd..1c72b4d4023d 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -154,7 +154,7 @@ Currently these are the automatic implementations provided by Conan: :ref:`config_options` steps when those methods are not explicitly defined in the recipe. -- ``"auto_header_only_package"``: automatically manages the package ID clearing settings. Adding this +- ``"auto_header_only"``: automatically manages the package ID clearing settings. Adding this implementation will have effect in the :ref:`package_id` step when the method is not explicitly defined in the recipe. From ab274fe2d6dd8a9fecabd345d7dd857709827fd2 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 19 Jul 2023 16:16:45 +0200 Subject: [PATCH 5/9] Update reference/conanfile/methods/configure.rst Co-authored-by: James --- reference/conanfile/methods/configure.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/conanfile/methods/configure.rst b/reference/conanfile/methods/configure.rst index ec3609564413..a6e3bf798a2a 100644 --- a/reference/conanfile/methods/configure.rst +++ b/reference/conanfile/methods/configure.rst @@ -99,7 +99,6 @@ must be explicitly declared: .. code-block:: python - from conan.tools import default_configure def configure(self): if conanfile.options.get_safe("header_only"): From 37cef7ce5d4f4118c3ae045146c9bea22368e8c4 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 19 Jul 2023 16:18:50 +0200 Subject: [PATCH 6/9] remove opt-out --- reference/conanfile/methods/config_options.rst | 7 ------- reference/conanfile/methods/configure.rst | 7 ------- reference/conanfile/methods/package_id.rst | 8 -------- 3 files changed, 22 deletions(-) diff --git a/reference/conanfile/methods/config_options.rst b/reference/conanfile/methods/config_options.rst index c6507a802021..02164ee15832 100644 --- a/reference/conanfile/methods/config_options.rst +++ b/reference/conanfile/methods/config_options.rst @@ -57,13 +57,6 @@ automatically manage the fPIC setting in the ``config_options`` step like this: Be aware that adding this implementation to the recipe may also affect the :ref:`configure` step. -To opt-out from this behavior, the method can be empty-defined: - -.. code-block:: python - - def config_options(self): - pass - If you need to implement custom behaviors in your recipes but also need this logic, it must be explicitly declared: diff --git a/reference/conanfile/methods/configure.rst b/reference/conanfile/methods/configure.rst index a6e3bf798a2a..2330623e101b 100644 --- a/reference/conanfile/methods/configure.rst +++ b/reference/conanfile/methods/configure.rst @@ -87,13 +87,6 @@ automatically manage the fPIC setting in the ``configure`` step like this: Be aware that adding this implementation to the recipe may also affect the :ref:`configure` step. -To opt-out from this behavior, the method can be empty-defined: - -.. code-block:: python - - def configure(self): - pass - If you need to implement custom behaviors in your recipes but also need this logic, it must be explicitly declared: diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index 98fa121b78c6..05a49cc529a2 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -46,14 +46,6 @@ automatically manage the fPIC setting in the ``package_id`` step like this: if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER: conanfile.info.clear() - -To opt-out from this behavior, the method can be empty-defined: - -.. code-block:: python - - def package_id(self): - pass - If you need to implement custom behaviors in your recipes but also need this logic, it must be explicitly declared: From d18871be0191b54f9afe1db87e9975c12097f4f7 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 19 Jul 2023 16:21:20 +0200 Subject: [PATCH 7/9] warn --- reference/conanfile/attributes.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index 1c72b4d4023d..0ad2ffd76048 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -158,3 +158,7 @@ Currently these are the automatic implementations provided by Conan: implementation will have effect in the :ref:`package_id` step when the method is not explicitly defined in the recipe. + +.. warning:: + + This is a 2.0-only feature, and it will not work in 1.X From 97b1042d9ee8dd390a7597f9b68de17d6a5a41f3 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Wed, 19 Jul 2023 16:22:36 +0200 Subject: [PATCH 8/9] Update reference/conanfile/methods/package_id.rst --- reference/conanfile/methods/package_id.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index 05a49cc529a2..63e6475c02f0 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -51,7 +51,6 @@ must be explicitly declared: .. code-block:: python - from conan.tools import default_package_id def package_id(self): if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER: From b773e3da537b187037c7ff8056b244076c5983fd Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 19 Jul 2023 16:23:59 +0200 Subject: [PATCH 9/9] fix format --- reference/conanfile/methods/package_id.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index 63e6475c02f0..995611e2fbcf 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -51,7 +51,6 @@ must be explicitly declared: .. code-block:: python - def package_id(self): if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER: conanfile.info.clear()