Document options managed automatically (#3296)

* 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 <franchuti688@gmail.com>

Update reference/tools/cpp_info.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/tools/cpp_info.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/tools/cpp_info.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/tools/cpp_info.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/configure.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/config_options.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/config_options.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/config_options.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/configure.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/package_id.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/conanfile/methods/package_id.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

Update reference/tools/cpp_info.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

* include suggestion

---------

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

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()<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::
 

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()<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

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()<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
 -------------------

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)