From faceec913d31734185d6cde66b0a656b0bdde2f1 Mon Sep 17 00:00:00 2001 From: memsharded Date: Tue, 20 Jun 2023 11:58:29 +0200 Subject: [PATCH 1/3] CppInfo(self)/aggregate new public interface --- reference/tools.rst | 1 + reference/tools/cpp_info.rst | 46 ++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 reference/tools/cpp_info.rst diff --git a/reference/tools.rst b/reference/tools.rst index 34615be1a923..290666a51fc9 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -38,3 +38,4 @@ Contents: tools/layout tools/intel tools/android + tools/cpp_info diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst new file mode 100644 index 000000000000..e74985bdd6d9 --- /dev/null +++ b/reference/tools/cpp_info.rst @@ -0,0 +1,46 @@ +.. _conan_tools_cpp_info: + +conan.tools.CppInfo +=================== + +The ``CppInfo`` class represents the basic C++ usage information of a given package, like the ``includedirs``, ``libdirs``, library names, etc. It is the information that the consumers of the package needs in order to be able to find the headers and link correctly with the libraries. + +The ``self.cpp_info`` object in the ``package_info()`` is a ``CppInfo`` object, so in most cases it will not be necessary to explicitly instantiate it, and using it as explained in :ref:`the package_info()` section would be enough. + + +This section describes the other, advanced uses cases of the ``CppInfo``. + +Aggregating information in custom generators +-------------------------------------------- + +.. include:: ../../common/experimental_warning.inc + +Some generators, like the built-in ``NMakeDeps``, contains the equivalent to this code, that collapses all information from all dependencies into one single ``CppInfo`` object that aggregates all the information + +.. code-block:: python + + def generate(self): + aggregated_cpp_info = CppInfo(self) + deps = self.dependencies.host.topological_sort + deps = [dep for dep in reversed(deps.values())] + for dep in deps: + # We don't want independent components management, so we collapse + # the "dep" components into one CppInfo called "dep_cppinfo" + dep_cppinfo = dep.cpp_info.aggregated_components() + # Then we merge and aggregate this dependency "dep" into the final result + aggregated_cpp_info.merge(dep_cppinfo) + + aggregated_cpp_info.includedirs # All include dirs from all deps, all components + aggregated_cpp_info.libs # All library names from all deps, all components + aggregated_cpp_info.system_libs # All system-libs from all deps + .... + # Creates a file with this information that the build system will use + + +This aggregation could be useful in cases where the build system cannot easily use independent dependencies or components. For example ``NMake`` or ``Autotools`` mechanism to provide dependencies information would be via ``LIBS``, ``CXXFLAGS`` and similar variables. These variables are global, so passing all the information from all dependencies is the only possibility. + +The public documented interface (besides the defined one in :ref:`the package_info()`) is: + +- ``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. From 553d1b91233cadb993656a479052e75eb49c664a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rub=C3=A9n=20Rinc=C3=B3n=20Blanco?= Date: Tue, 20 Jun 2023 16:26:55 +0200 Subject: [PATCH 2/3] Update reference/tools/cpp_info.rst Co-authored-by: Carlos Zoido --- reference/tools/cpp_info.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst index e74985bdd6d9..d2c3e6839016 100644 --- a/reference/tools/cpp_info.rst +++ b/reference/tools/cpp_info.rst @@ -19,6 +19,10 @@ Some generators, like the built-in ``NMakeDeps``, contains the equivalent to thi .. code-block:: python + from conan.tools import CppInfo + + ... + def generate(self): aggregated_cpp_info = CppInfo(self) deps = self.dependencies.host.topological_sort From 7ced31af95aee607fdfc16a43f308606354f3940 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rub=C3=A9n=20Rinc=C3=B3n=20Blanco?= Date: Tue, 20 Jun 2023 16:27:01 +0200 Subject: [PATCH 3/3] Update reference/tools/cpp_info.rst --- reference/tools/cpp_info.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst index d2c3e6839016..7daa65515d4e 100644 --- a/reference/tools/cpp_info.rst +++ b/reference/tools/cpp_info.rst @@ -3,7 +3,7 @@ conan.tools.CppInfo =================== -The ``CppInfo`` class represents the basic C++ usage information of a given package, like the ``includedirs``, ``libdirs``, library names, etc. It is the information that the consumers of the package needs in order to be able to find the headers and link correctly with the libraries. +The ``CppInfo`` class represents the basic C++ usage information of a given package, like the ``includedirs``, ``libdirs``, library names, etc. It is the information that the consumers of the package need in order to be able to find the headers and link correctly with the libraries. The ``self.cpp_info`` object in the ``package_info()`` is a ``CppInfo`` object, so in most cases it will not be necessary to explicitly instantiate it, and using it as explained in :ref:`the package_info()` section would be enough.