From 7efd839708f99aa64bd34b092ac37c766109bd2f Mon Sep 17 00:00:00 2001 From: Daniel Date: Thu, 13 Jul 2023 11:04:37 +0200 Subject: [PATCH] Document options managed automatically (#3296) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Document options managed automatically Apply suggestions from code review Update reference/tools/cpp_info.rst Update reference/tools/cpp_info.rst Co-authored-by: Francisco Ramírez Update reference/tools/cpp_info.rst Co-authored-by: Francisco Ramírez Update reference/tools/cpp_info.rst Co-authored-by: Francisco Ramírez Update reference/tools/cpp_info.rst Co-authored-by: Francisco Ramírez Update reference/tools/cpp_info.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/configure.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/config_options.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/config_options.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/config_options.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/configure.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/package_id.rst Co-authored-by: Francisco Ramírez Update reference/conanfile/methods/package_id.rst Co-authored-by: Francisco Ramírez Update reference/tools/cpp_info.rst Co-authored-by: Francisco Ramírez * include suggestion --------- Co-authored-by: Francisco Ramírez --- .../conanfile/methods/config_options.rst | 45 +++++++- reference/conanfile/methods/configure.rst | 32 ++++++ reference/conanfile/methods/package_id.rst | 27 +++++ reference/tools/cpp_info.rst | 106 ++++++++++++++++++ 4 files changed, 204 insertions(+), 6 deletions(-) diff --git a/reference/conanfile/methods/config_options.rst b/reference/conanfile/methods/config_options.rst index c232a42082e1..95ff071ed635 100644 --- a/reference/conanfile/methods/config_options.rst +++ b/reference/conanfile/methods/config_options.rst @@ -3,17 +3,50 @@ config_options() ================ -The ``config_options()`` method -is used to configure or constraint the available options in a package, **before** they are given a value. A typical use case is to remove an option in a given platform. For example, -the ``fPIC`` flag doesn't exist in Windows, so it should be removed in this method like so: +The ``config_options()`` method is used to configure or constrain the available options in a package **before** assigning them a value. +A typical use case is to remove an option in a given platform. +For example, the ``SSE2`` flag doesn't exist in architectures different than 32 bits, so it should be removed in this method like so: .. code-block:: python def config_options(self): - if self.settings.os == "Windows": - del self.options.fPIC + if self.settings.arch != "x86_64": + del self.options.with_sse2 -The ``config_options()`` method executes before the ``configure()`` method, and before the actual assignment of the ``options`` values, but after settings are already defined. +The ``config_options()`` method executes: +* Before calling the ``configure()`` method. +* Before assigning the ``options`` values. +* After ``settings`` are already defined. + +Default behavior +++++++++++++++++ + +.. 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. + +Options automatically managed: + +- ``fPIC`` (True, False). + +To opt-out from this behavior, the method can be empty-defined: + +.. code-block:: python + + def config_options(self): + pass + +To manage extra options apart from the ones automatically handled, the tool has to be explicitly called: + +.. code-block:: python + + from conan.tools import default_config_options + + def config_options(self): + default_config_options(self) + if self.settings.arch != "x86_64": + del self.options.with_sse2 .. seealso:: diff --git a/reference/conanfile/methods/configure.rst b/reference/conanfile/methods/configure.rst index acc3c345af67..40340aa63fe1 100644 --- a/reference/conanfile/methods/configure.rst +++ b/reference/conanfile/methods/configure.rst @@ -43,6 +43,38 @@ 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 +++++++++++++++++ + +.. 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. + +Options automatically managed: + +- ``fPIC`` (True, False). +- ``shared`` (True, False). +- ``header_only`` (True, False). + +To opt-out from this behavior, the method can be empty-defined: + +.. code-block:: python + + def configure(self): + pass + +To manage extra options apart from the ones automatically handled, the tool has to be explicitly called: + +.. code-block:: python + + from conan.tools import default_configure + + def configure(self): + default_configure(self) + self.settings.rm_safe("compiler.libcxx") + self.settings.rm_safe("compiler.cppstd") + Recipes can suggest values for their dependencies options as ``default_options = {"*:shared": True}``, but it is not possible to do that conditionally. For this purpose, it is also possible to use the diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index dcb714a5084d..0b1ed25d8bc1 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -12,6 +12,33 @@ 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 +++++++++++++++++ + +.. 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. + +To opt-out from this behavior, the method can be empty-defined: + +.. code-block:: python + + def package_id(self): + pass + +To manage the package ID info further, the tool has to be explicitly called: + +.. code-block:: python + + from conan.tools import default_package_id + + def package_id(self): + default_package_id(self) + self.info.settings.rm_safe("compiler.libcxx") + self.info.settings.rm_safe("compiler.cppstd") + Information erasure ------------------- diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst index 7daa65515d4e..f7e98ade0e29 100644 --- a/reference/tools/cpp_info.rst +++ b/reference/tools/cpp_info.rst @@ -48,3 +48,109 @@ 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)