diff --git a/reference/conanfile/attributes/binary_model.inc b/reference/conanfile/attributes/binary_model.inc index ff585b8c8075..6a9d067ef0c8 100644 --- a/reference/conanfile/attributes/binary_model.inc +++ b/reference/conanfile/attributes/binary_model.inc @@ -295,6 +295,11 @@ Object used exclusively in ``package_id()`` method: self.info.clear() +The ``self.info.clear()`` method removes all the settings, options, requirements (``requires``, ``tool_requires``, ``python_requires``) +and configuration (``conf``) from the ``package_id`` computation, so the ``package_id`` will always result in the same binary, irrespective +of all those things. This would be the typical case of a header-only library, in which the packaged artifacts (files) are always identical. + + .. _reference_conanfile_attributes_package_id_modes: package_id_{embed,non_embed,unknown}_mode diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index 93713fd8ba9a..33e6e2acc7d7 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -39,23 +39,22 @@ recipe declares an option ``header_only=True`` or when ``package_type`` is ... 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: +automatically manage it and call ``self.info.clear()`` in the ``package_id()`` automatically, +to make the ``package_id`` independent of settings, options, configuration and requirements. -.. code-block:: python - - if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER: - conanfile.info.clear() If you need to implement custom behaviors in your recipes but also need this logic, it -must be explicitly declared: +must be explicitly declared, for example, something like this: .. code-block:: python def 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") + def package_id(self): + if self.package_type == "header-library": + self.info.clear() + else: + self.info.settings.rm_safe("compiler.libcxx") + self.info.settings.rm_safe("compiler.cppstd") Information erasure diff --git a/tutorial/creating_packages/configure_options_settings.rst b/tutorial/creating_packages/configure_options_settings.rst index e6a2dbc2f5d1..bf8ef57bd8a8 100644 --- a/tutorial/creating_packages/configure_options_settings.rst +++ b/tutorial/creating_packages/configure_options_settings.rst @@ -258,7 +258,7 @@ there's no binary code we need to link with, but just some header files to add t project. In this cases the package ID of the Conan package should not be affected by settings or options. For that case, there's a simplified way of declaring that the generated package ID should not take into account settings, options or any information -from the requirement which is using the ``self.info.clear()`` method inside another recipe +from the requirements, which is using the ``self.info.clear()`` method inside another recipe method called ``package_id()``: .. code-block:: python @@ -266,6 +266,7 @@ method called ``package_id()``: def package_id(self): self.info.clear() + We will explain the ``package_id()`` method later and explain how you can customize the way the package ID for the package is calculated. You can also check the :ref:`Conanfile's methods reference` if you want to know how this method works in diff --git a/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst b/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst index 2267b5a27f78..819c855f8f34 100644 --- a/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst +++ b/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst @@ -196,8 +196,9 @@ These are the changes introduced in the recipe: - We have a ``build()`` method, building the tests, but only when the standard conf ``tools.build:skip_test`` is not True. Use that conf as a standard way to enable/disable the testing. It is used by the helpers like ``CMake`` to skip the ``cmake.test()`` in case we implement the tests in CMake. - - We have a ``package_id()`` method calling ``self.info.clear()``. This is internally removing the settings - from the package ID calculation so we generate only one configuration for our header-only library. + - We have a ``package_id()`` method calling ``self.info.clear()``. This is internally removing all the information + (settings, options, requirements) from the package_id calculation so we generate only one configuration for our + header-only library. We can call ``conan create`` to build and test our package.