Skip to content

Commit

Permalink
Docs for implements (#3303)
Browse files Browse the repository at this point in the history 
* docs for implements

* Update reference/conanfile/attributes.rst

Co-authored-by: James <james@conan.io>

* Update reference/conanfile/methods/config_options.rst

Co-authored-by: James <james@conan.io>

* Update reference/conanfile/attributes.rst

Co-authored-by: James <james@conan.io>

* Update reference/conanfile/methods/configure.rst

Co-authored-by: James <james@conan.io>

* remove opt-out

* warn

* Update reference/conanfile/methods/package_id.rst

* fix format

---------

Co-authored-by: James <james@conan.io>
  • Loading branch information
@czoido @memsharded
czoido and memsharded authored Jul 19, 2023
1 parent 74f24c7 commit 09146c9
Show file tree
Hide file tree
Showing 5 changed files with 132 additions and 138 deletions.
34 changes: 34 additions & 0 deletions reference/conanfile/attributes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,3 +128,37 @@ 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", ...]
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<reference_conanfile_methods_configure_implementations>` and
:ref:`config_options<reference_conanfile_methods_config_options_implementations>` steps
when those methods are not explicitly defined in the recipe.

- ``"auto_header_only"``: automatically manages the package ID clearing settings. Adding this
implementation will have effect in the
:ref:`package_id<reference_conanfile_methods_package_id_implementations>` 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
41 changes: 31 additions & 10 deletions reference/conanfile/methods/config_options.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,33 +18,54 @@ 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()<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<conan_conanfile_attributes_implements>` ConanFile attribute:

auto_shared_fpic
----------------

Options automatically managed:

- ``fPIC`` (True, False).

To opt-out from this behavior, the method can be empty-defined:
It can be added to the recipe like this:

.. code-block:: python
from conan import ConanFile
class Pkg(ConanFile):
implements = ["auto_shared_fpic"]
...
def config_options(self):
pass
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<reference_conanfile_methods_configure_implementations>` step.

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
Expand Down
47 changes: 37 additions & 10 deletions reference/conanfile/methods/configure.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,35 +43,62 @@ 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()<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<conan_conanfile_attributes_implements>` ConanFile attribute:

auto_shared_fpic
----------------

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:
It can be added to the recipe like this:

.. code-block:: python
from conan import ConanFile
class Pkg(ConanFile):
implements = ["auto_shared_fpic"]
...
def configure(self):
pass
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<reference_conanfile_methods_config_options_implementations>` step.

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")
Expand Down
42 changes: 30 additions & 12 deletions reference/conanfile/methods/package_id.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,30 +12,48 @@ 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()<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<conan_conanfile_attributes_implements>` ConanFile
attribute:

To opt-out from this behavior, the method can be empty-defined:
auto_header_only
----------------

.. code-block:: python
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:

def package_id(self):
pass
.. code-block:: python
from conan import ConanFile
class Pkg(ConanFile):
implements = ["auto_header_only"]
...
To manage the package ID info further, the tool has to be explicitly called:
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
from conan.tools import default_package_id
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:

.. code-block:: python
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")
Expand Down
106 changes: 0 additions & 106 deletions reference/tools/cpp_info.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

0 comments on commit 09146c9

Please sign in to comment.