Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

clarify info.clear() behavior #3485

Merged
merged 3 commits into from
Dec 19, 2023
Merged

clarify info.clear() behavior #3485

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aadb25b
clarify info.clear() behavior
memsharded Dec 18, 2023
d462447
fixes to implements docs
memsharded Dec 18, 2023
a1fa277
Update reference/conanfile/methods/package_id.rst
memsharded Dec 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions reference/conanfile/attributes/binary_model.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 9 additions & 10 deletions reference/conanfile/methods/package_id.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change a little bit these lines:

Then, if no ``package_id()`` method is specified in the recipe, Conan
will automatically call ``self.info.clear()`` in the ``package_id()``
to make the ``package_id`` value 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:
memsharded marked this conversation as resolved.
Show resolved Hide resolved

.. 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
Expand Down
3 changes: 2 additions & 1 deletion tutorial/creating_packages/configure_options_settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,14 +258,15 @@ 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

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<reference_conanfile_methods>` if you want to know how this method works in
Expand Down
5 changes: 3 additions & 2 deletions tutorial/creating_packages/other_types_of_packages/header_only_packages.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down