From c6c8f72873e8847e63991a14298bca81d9e8e2b4 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 13 Aug 2024 12:05:07 +0200 Subject: [PATCH 1/6] Document pkg-config running from package Signed-off-by: Uilian Ries --- reference/tools/gnu/pkgconfig.rst | 44 ++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index 147aaf9d27f..54db77215ad 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -25,8 +25,11 @@ Read a ``pc`` file and access the information: print(pkg_config.variables['prefix']) # something like'/usr/local' -Use the ``pc`` file information to fill a ``cpp_info`` object: +Using PkgConfig to fill a ``cpp_info`` object +--------------------------------------------- +The ``PkgConfig`` class can be used to fill a ``CppInfo`` object with the information that will be consumed by ``PkgConfigDeps`` generator later. +This is a useful feature when packaging a system library that provides a ``.pc`` file, or when a proprietary package has a build system that only outputs ``.pc`` files. .. code-block:: python @@ -35,6 +38,45 @@ Use the ``pc`` file information to fill a ``cpp_info`` object: pkg_config.fill_cpp_info(self.cpp_info, is_system=False, system_libs=["m", "rt"]) +However, ``PkgConfig`` will invoke the ``pkg-config`` executable to extract the information from the ``.pc`` file. +The ``pkg-config`` executable must be available in the system path for this case, otherwise, it will fail when installing the consumed package. + + +Using pkg-config from Conan package instead of system +----------------------------------------------------- + +.. include:: ../../../common/experimental_warning.inc + +In case not having ``pkg-config`` available in the system, it is possible to use the ``pkg-config`` executable provided by a Conan package: + +.. code-block:: python + + import os + from conan import ConanFile + from conan.tools.gnu import PkgConfig + from conan.tools import CppInfo + + class Pkg(ConanFile): + + def tool_requires(self): + self.requires("pkgconf/[*]") + + ... + + def package(self): + pkg_config = PkgConfig(self, "libastral", pkg_config_path=".") + cpp_info = CppInfo(self) + pkg_config.fill_cpp_info(cpp_info, is_system=False, system_libs=["m", "rt"]) + cpp_info.save(os.path.join(self.package_folder, "cpp_info.json")) + + def package_info(self): + self.cpp_info = CppInfo(self).load(os.path.join(self.package_folder, "cpp_info.json")) + + +The ``pkg-config`` executable provided by the Conan package ``pkgconf`` will be invoked only when creating the Conan binary package. +The ``.pc`` information will be extracted from the ``cpp_info.json`` file located in the package folder, it will fill the ``self.cpp_info`` object. +This way, the ``PkgConfig`` will not need to invoke the ``pkg-config`` executable again to extract the information from the ``.pc`` file, +when consuming the package. Reference --------- From 31b19ec066191ca475aa8121b3457f32fc29f85b Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 13 Aug 2024 14:35:20 +0200 Subject: [PATCH 2/6] Grammar fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Abril Rincón Blanco --- reference/tools/gnu/pkgconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index 54db77215ad..ff170efd212 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -47,7 +47,7 @@ Using pkg-config from Conan package instead of system .. include:: ../../../common/experimental_warning.inc -In case not having ``pkg-config`` available in the system, it is possible to use the ``pkg-config`` executable provided by a Conan package: +In case of not having ``pkg-config`` available in the system, it is possible to use the ``pkg-config`` executable provided by a Conan package: .. code-block:: python From 95bb6e5d18f32c8084c355adeab1054e2673ec1b Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 13 Aug 2024 14:35:30 +0200 Subject: [PATCH 3/6] Grammar fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Abril Rincón Blanco --- reference/tools/gnu/pkgconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index ff170efd212..974b568282e 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -28,7 +28,7 @@ Read a ``pc`` file and access the information: Using PkgConfig to fill a ``cpp_info`` object --------------------------------------------- -The ``PkgConfig`` class can be used to fill a ``CppInfo`` object with the information that will be consumed by ``PkgConfigDeps`` generator later. +The ``PkgConfig`` class can be used to fill a ``CppInfo`` object with the information that will be consumed by the ``PkgConfigDeps`` generator later. This is a useful feature when packaging a system library that provides a ``.pc`` file, or when a proprietary package has a build system that only outputs ``.pc`` files. .. code-block:: python From 9b1f9eff405b2003d21b670d379a5551b157d570 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Tue, 13 Aug 2024 14:35:57 +0200 Subject: [PATCH 4/6] Fix example code using tool_requires MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Abril Rincón Blanco --- reference/tools/gnu/pkgconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index 974b568282e..ab6d723e075 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -58,8 +58,8 @@ In case of not having ``pkg-config`` available in the system, it is possible to class Pkg(ConanFile): - def tool_requires(self): - self.requires("pkgconf/[*]") + def build_requirements(self): + self.tool_requires("pkgconf/[*]") ... From e23b7c217dd462e992e392d53ce1b2aa2b8c5a18 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Wed, 14 Aug 2024 08:18:45 +0200 Subject: [PATCH 5/6] Do not recommend system package usage Signed-off-by: Uilian Ries --- reference/tools/gnu/pkgconfig.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index ab6d723e075..f21c877f052 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -29,7 +29,7 @@ Using PkgConfig to fill a ``cpp_info`` object --------------------------------------------- The ``PkgConfig`` class can be used to fill a ``CppInfo`` object with the information that will be consumed by the ``PkgConfigDeps`` generator later. -This is a useful feature when packaging a system library that provides a ``.pc`` file, or when a proprietary package has a build system that only outputs ``.pc`` files. +This is a useful feature when packaging a proprietary package has a build system that only outputs ``.pc`` files for a known environment. .. code-block:: python @@ -78,6 +78,11 @@ The ``.pc`` information will be extracted from the ``cpp_info.json`` file locate This way, the ``PkgConfig`` will not need to invoke the ``pkg-config`` executable again to extract the information from the ``.pc`` file, when consuming the package. +.. warning:: + + It's not recommended to use this approach when creating a "system" package recipe, as the packaged information may not be compatible with the host system, + resulting in errors when consuming the package. + Reference --------- From c3139187527d33139748bc9dda08c6ba74a2acb1 Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Wed, 14 Aug 2024 12:46:51 +0200 Subject: [PATCH 6/6] Update pkg-config recommendation Signed-off-by: Uilian Ries --- reference/conanfile/attributes.rst | 1 + reference/tools/gnu/pkgconfig.rst | 11 +++++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index fd3e1994324..d05a626b43b 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -126,6 +126,7 @@ recipe or the package, then it is possible to exclude them from the check with t configuration, which is a list of patterns (fnmatch) to exclude. +.. _upload_policy_attribute: upload_policy ------------- diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index f21c877f052..43bcdb35072 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -42,12 +42,12 @@ However, ``PkgConfig`` will invoke the ``pkg-config`` executable to extract the The ``pkg-config`` executable must be available in the system path for this case, otherwise, it will fail when installing the consumed package. -Using pkg-config from Conan package instead of system ------------------------------------------------------ +Using pkg-config from Conan tool_requires instead of system +----------------------------------------------------------- .. include:: ../../../common/experimental_warning.inc -In case of not having ``pkg-config`` available in the system, it is possible to use the ``pkg-config`` executable provided by a Conan package: +In case of not having ``pkg-config`` available in the system, it is possible to use the ``pkg-config`` executable provided by Conan ``tool_requires`` instead.: .. code-block:: python @@ -80,9 +80,12 @@ when consuming the package. .. warning:: - It's not recommended to use this approach when creating a "system" package recipe, as the packaged information may not be compatible with the host system, + It's forbidden to upload or reuse this approach when creating a package, as the information may not be compatible with the host system, resulting in errors when consuming the package. + When using this approach for wrapping system packages, it is recommended to use ``upload_policy = "skip"`` + (see :ref:`upload_policy_attribute`) in the package recipe to avoid uploading the package. + Reference ---------