From 1d80ef324d8933bbd5bec454cc18a62c4fecce04 Mon Sep 17 00:00:00 2001 From: memsharded Date: Wed, 5 Nov 2025 13:54:51 +0100 Subject: [PATCH 01/34] warnings for local-recipes-index --- devops/devops_local_recipes_index.rst | 25 +++++++++++++++++-- .../setup_local_recipes_index.rst | 9 +++++++ 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/devops/devops_local_recipes_index.rst b/devops/devops_local_recipes_index.rst index ed551db0988a..34723f0195c2 100644 --- a/devops/devops_local_recipes_index.rst +++ b/devops/devops_local_recipes_index.rst @@ -18,6 +18,26 @@ This setup is particularly useful for: :ref:`setup_local_recipes_index`. +.. warning:: + + Using the ``local-recipes-index`` feature from a fork of ``conan-center-index`` Github repository, + without using a package server or relying on the ConanCenter package server can easily result in + missing dependencies due to old versions being removed by upstream ``conan-center-index``. The + recommendations are: + + - Use a package server to store your recipes and binaries built from your fork, and use it to resolve + dependencies. + - If not using a package server, at least consider adding ``conancenter`` as remote besides your + ``local-recipes-index``, possibly with the ``recipes-only`` argument enabled, to be able to fetch + those older versions removed from the source from it. + - If you are not using a server, then it becomes necessary to move forward with the ``local-recipes-index`` + source repository. If a version is removed, the requirements to that old version must be updated to + existing versions. + - Another alternative is managing your fork accordingly, to avoid removals, not merging from upstream, + applying only selective patches. + + + Building Binaries from a private `conan-center-index` fork ---------------------------------------------------------- @@ -229,8 +249,9 @@ Several important points should be considered when using this new feature: packages for regular use. - Also, note that a server remote can retain a history of changes storing multiple recipe - revisions. In contrast, a `local-recipes-index` remote can only represent a single - snapshot at any given time. + versions and revisions. In contrast, a `local-recipes-index` remote can only represent a single + snapshot at any given time. That means that it will be impossible to use or resolve to older + recipe revisions or to old versions that have been removed from the source repository. - ConanCenter does not use ``python-requires``, as this is a mechanism more intended for first-party packages. Using ``python-requires`` in a ``local-recipes-index`` repository diff --git a/tutorial/conan_repositories/setup_local_recipes_index.rst b/tutorial/conan_repositories/setup_local_recipes_index.rst index b572b600d5db..37d9adaa9527 100644 --- a/tutorial/conan_repositories/setup_local_recipes_index.rst +++ b/tutorial/conan_repositories/setup_local_recipes_index.rst @@ -15,6 +15,15 @@ upload packages or store binaries. The purpose of this remote is: For detailed setup and usage instructions, see the dedicated section in the Conan DevOps Guide :ref:`devops_local_recipes_index`. + +.. warning:: + + Recall that the ``local-recipes-index`` is a "source" repository, and as such it has + several limitations with respect to full package servers. Please read carefully the + instructions and warnings in :ref:`devops_local_recipes_index` before using this + type of remote. + + Setup ----- From 4f76b76f605303d29bbd1e297dffbf6aa98cc5c5 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 21 Jul 2026 14:46:29 +0200 Subject: [PATCH 02/34] fix options shadows (#4490) --- .../conanfile/attributes/binary_model.inc | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/reference/conanfile/attributes/binary_model.inc b/reference/conanfile/attributes/binary_model.inc index 71b920f44e3b..b4284980bbbf 100644 --- a/reference/conanfile/attributes/binary_model.inc +++ b/reference/conanfile/attributes/binary_model.inc @@ -214,6 +214,27 @@ would be: if self.settings.os == "Windows": self.options.rm_safe("fPIC") +.. warning:: + + Some names are not allowed as option names because they conflict with existing ``Options`` class + methods. Some of them are already documented or available methods: + + - ``update``: used by ``self.options.update()`` to extend options from a ``python_requires`` base + class. See the :ref:`init() method`. + - ``clear``: used internally to clear all options, e.g. for header-only packages. + - ``items``: used to iterate over option name/value pairs. + - The ``get_safe`` and ``rm_safe`` operations. + + But there can be also other private methods that could eventually collide (Conan will try to reduce + them, but at the moment they are still there and could shadow user definitions): + + - Some verbs related to storage and serialization: ``loads``, ``dumps`` and ``serialize``. + - The ``possible_values`` access + - Anything that is private (starts with ``_`` underscore, or starts with ``conan``) + + Using any of these names as option keys will cause the option value to be shadowed by the + corresponding method, leading to unexpected behavior. + .. seealso:: - Read the :ref:`Getting started, creating packages` to know how to declare and how to From 89402c6f5c16f16aacac2be3f1d021206cd29c36 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 21 Jul 2026 14:46:57 +0200 Subject: [PATCH 03/34] Docs/20102 micro mode (#4491) * Add micro_mode to package_id modes documentation Documents the new micro_mode added in conan-io/conan#20102 that factors the 4th MICRO digit of a MAJOR.MINOR.PATCH.MICRO version into the package_id computation. * review --- reference/conanfile/attributes/binary_model.inc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/reference/conanfile/attributes/binary_model.inc b/reference/conanfile/attributes/binary_model.inc index b4284980bbbf..4da5ae4022ed 100644 --- a/reference/conanfile/attributes/binary_model.inc +++ b/reference/conanfile/attributes/binary_model.inc @@ -456,9 +456,10 @@ The ``build_mode`` (experimental) is a class attribute that affects the package In general, the Conan defaults are good ones, and allow providing users good control over when the consumers need to be re-built from source or not. Also, the Conan defaults can be changed globally in the ``global.conf`` file (they should be changed globally for all users, CI, etc.) via the ``core.package_id:xxxx`` configurations. The in-recipe attribute definition is useful to define behavior that deviates from the defaults. -Possible values are (following the semver definition of MAJOR.MINOR.PATCH): +Possible values are (following the semver definition of MAJOR.MINOR.PATCH, with an extra MICRO digit for versioning schemes with 4 digits): - ``patch_mode``: New patches, minors, and major releases of the package will require a new binary (new ``package_id``) of the consumers. New recipe revisions will not require new binaries of the consumers. For example if we create a new ``pkg/1.0.1`` version and some consumer has ``requires = "pkg/[>=1.0 <2.0]"``, such a consumer will build a new binary against this specific new ``1.0.1`` version. But if we just change the recipe, producing a new ``recipe_revision``, the consumers will not require building a new binary. +- ``micro_mode``: (Available since Conan 2.31). Similar to ``patch_mode`` but factoring in a 4th ``MICRO`` digit for versioning schemes that use ``MAJOR.MINOR.PATCH.MICRO``. New micro, patch, minor and major releases will require a new binary of the consumers, but new recipe revisions will not. Any additional digits beyond the 4th are ignored. Missing digits default to ``0`` (a dependency version ``1.2.3`` will be represented as ``1.2.3.0``). - ``minor_mode``: New minor and major releases of this package will require a new binary of the consumers. New patches and new revisions will not require new binaries of the consumers. This is the default for the "non-embed-mode", as it allows fine control by the users to decide when to rebuild things or not. - ``major_mode``: Only new major releases will require new binaries. Any other modifications and new versions will not require new binaries from the consumers. - ``full_mode``: The full identifier of this package, including ``pkgname/version@user/channel#recipe_revision:package_id`` will be used in the consumers ``package_id``, then requiring to build a new binary of the consumer for every change of this package (as any change either in source or configuration will produce a different ``recipe_revision`` or ``package_id`` respectively). This is the default for the "embed-mode". From ef370bcd912fe671ac16b0c2d9e3e3e6e81f087c Mon Sep 17 00:00:00 2001 From: James Date: Tue, 21 Jul 2026 14:47:41 +0200 Subject: [PATCH 04/34] Document warning when mixing conan config install with install-pkg (#4493) Documents the new warning added in conan-io/conan#20188. Running 'conan config install' when a 'config_version.json' file already exists (from a previous 'conan config install-pkg') will warn the user, since the plain install is not tracked in config_version.json and may lead to inconsistent configuration state. --- reference/commands/config.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/reference/commands/config.rst b/reference/commands/config.rst index afc1c7078c59..9eec8adc7441 100644 --- a/reference/commands/config.rst +++ b/reference/commands/config.rst @@ -128,6 +128,17 @@ You can force certain files to be copied over by using the ``!`` negation syntax $ conan config install /path/to/some/config.zip +.. note:: + + Since Conan 2.31, ``conan config install`` will warn if a ``config_version.json`` file + already exists in the Conan home (which is created by ``conan config install-pkg`` to + track installed configuration package versions). Mixing ``conan config install`` with + ``conan config install-pkg`` is not recommended, as the plain ``conan config install`` + is not tracked in ``config_version.json`` and may result in a configuration that is + inconsistent with the tracked versions. In that case, consider running + ``conan config clean`` first, or avoid mixing the two commands. + + .. _reference_commands_conan_config_install_pkg: conan config install-pkg From fca043630b099d9c743ac986ed0a5a5d74e8b19c Mon Sep 17 00:00:00 2001 From: James Date: Tue, 21 Jul 2026 14:48:16 +0200 Subject: [PATCH 05/34] Document nosoname property in CMakeConfigDeps (#4492) Documents the new nosoname property support in CMakeConfigDeps added in conan-io/conan#20168. Equivalent to the CMakeDeps nosoname property, it emits IMPORTED_NO_SONAME_ for shared library targets so CMake skips the SONAME check when linking. --- reference/tools/cmake/cmakeconfigdeps.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/reference/tools/cmake/cmakeconfigdeps.rst b/reference/tools/cmake/cmakeconfigdeps.rst index e9a13d7b6164..ce794018cad2 100644 --- a/reference/tools/cmake/cmakeconfigdeps.rst +++ b/reference/tools/cmake/cmakeconfigdeps.rst @@ -201,6 +201,11 @@ The following properties affect the ``CMakeConfigDeps`` generator: (Possibly using the **cmake_extra_variables** property). Supported when using CMake 3.24 or newer. This property performs **no** checks on the given feature, it is up to the recipe author to ensure that the feature is usable. +- **nosoname**: boolean value that should be used only by dependencies that are defined as ``SHARED`` and + represent a library built without the ``soname`` flag option. When set to ``True``, the generated + target will have the ``IMPORTED_NO_SONAME_`` CMake property set to ``TRUE``, so CMake skips + the SONAME check when linking. Can be set at the package level or per-component. Ignored for non-shared + library types. Available since Conan 2.31. Example: From be8c9f633dfbef01cdc43305f14c647d004bddf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20S=C3=A1nchez=20Falero?= Date: Tue, 21 Jul 2026 17:21:21 +0200 Subject: [PATCH 06/34] Document VirtualRunEnv win_copy_folder support (#4494) --- reference/tools/env/virtualrunenv.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/reference/tools/env/virtualrunenv.rst b/reference/tools/env/virtualrunenv.rst index fd6b5bd7c0b1..c3f5d0155951 100644 --- a/reference/tools/env/virtualrunenv.rst +++ b/reference/tools/env/virtualrunenv.rst @@ -82,6 +82,20 @@ current active configuration, like ``deactivate_conanrunenv-release-x86_64.bat`` For disabling the automatic generation of environment files, check :ref:`reference_tools_env_virtualbuildenv_disable` +On Windows, ``VirtualRunEnv`` can also copy the runtime binaries of dependencies into a single folder and point ``PATH`` to that folder instead of to every dependency ``bindirs`` location. This can help avoid ``PATH`` overflow limits for large dependency graphs. Use the ``win_copy_folder`` argument with a relative path when instantiating the generator: + +.. code-block:: python + + from conan import ConanFile + from conan.tools.env import VirtualRunEnv + + class Pkg(ConanFile): + settings = "os", "compiler", "arch", "build_type" + + def generate(self): + runenv = VirtualRunEnv(self, win_copy_folder="imported-bin") + runenv.generate() + Reference --------- From c17d7287215a4b6d5f89e85c63e681a754c2ada2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20S=C3=A1nchez=20Falero?= Date: Wed, 22 Jul 2026 13:01:01 +0200 Subject: [PATCH 07/34] document AutotoolsDeps Windows msvc LINK env fix (#4495) * document AutotoolsDeps Windows msvc LINK env fix * wip --- reference/tools/gnu/autotoolsdeps.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reference/tools/gnu/autotoolsdeps.rst b/reference/tools/gnu/autotoolsdeps.rst index 7542faec0e80..7cc714bfdf03 100644 --- a/reference/tools/gnu/autotoolsdeps.rst +++ b/reference/tools/gnu/autotoolsdeps.rst @@ -50,6 +50,9 @@ It will generate the file ``conanautotoolsdeps.sh`` or ``conanautotoolsdeps.bat` These launchers will define aggregated variables ``CPPFLAGS``, ``LIBS``, ``LDFLAGS``, ``CXXFLAGS``, ``CFLAGS`` that accumulate all dependencies information, including transitive dependencies, with flags like ``-I``, ``-L``, etc. +.. important:: + On Windows with ``msvc``, ``AutotoolsDeps`` emits linker flags in ``_LINK_`` rather than ``LDFLAGS``, so the Autotools wrapper can process the flags correctly. ``_LINK_`` is used instead of ``LINK`` to avoid a conflict with the ``LINK`` variable that Automake defines for C targets. + At this moment, only the ``requires`` information is generated, the ``tool_requires`` one is not managed by this generator yet. From f1159cbd2c3caef1c5c4ae26b707b4009cbfd666 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20S=C3=A1nchez=20Falero?= Date: Thu, 23 Jul 2026 12:00:17 +0200 Subject: [PATCH 08/34] Document cpp_info.ignored_requires attribute (#4496) * Document cpp_info.ignored_requires attribute * wip * wip --- reference/conanfile/methods/package_info.rst | 23 ++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/reference/conanfile/methods/package_info.rst b/reference/conanfile/methods/package_info.rst index 84ab419703be..fa5255838179 100644 --- a/reference/conanfile/methods/package_info.rst +++ b/reference/conanfile/methods/package_info.rst @@ -162,6 +162,29 @@ If your package is composed by more than one library, it is possible to declare Dependencies among components and to components of other requirements can be defined using the ``requires`` attribute and the name of the component. The dependency graph for components will be calculated and values will be aggregated in the correct order for each field. +Conan validates that every direct dependency of a recipe is used in some ``(cpp_info/components).requires``, raising an error otherwise. + +If a dependency really has no relationship at all with the current package artifacts (not linked, not embedded, not exposing any of +its headers), it can be added to ``self.cpp_info.ignored_requires`` to silence the validation: + +.. code-block:: python + + def requirements(self): + self.requires("other/1.0") + self.requires("another/1.0") # not linked or embedded in this package in any way + + def package_info(self): + self.cpp_info.components["cmp1"].requires = ["other::other"] + self.cpp_info.ignored_requires = ["another"] + +The definition of ``ignored_requires`` should not be necessary in most cases, as Conan already avoids propagating information that is +not needed (for example, it doesn't propagate headers downstream unless ``transitive_headers=True``). + +If there is some relationship between the dependency and the package, even if it looks like a build-time only one (for example, a +static library linked into the current shared library), it is recommended to still declare it via ``requires`` instead. Otherwise, +changes in that dependency, like building it with a different ``shared`` value, could break the package without Conan being able to +detect it. + .. _reference_conanfile_methods_package_info_buildenv_info: .. _reference_conanfile_methods_package_info_runenv_info: From 79a072818b0d0b7bdcb03fb163fc7c24c1eb892a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20S=C3=A1nchez=20Falero?= Date: Thu, 23 Jul 2026 14:22:45 +0200 Subject: [PATCH 09/34] Document conanws.py get_ref() and updated python_requires discovery behavior (#4497) --- reference/workspace_files.rst | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/reference/workspace_files.rst b/reference/workspace_files.rst index 75420eacffd9..6b26cbe4e885 100644 --- a/reference/workspace_files.rst +++ b/reference/workspace_files.rst @@ -38,11 +38,13 @@ Moreover, it could not have the ``ref`` field, and let Conan read the *name/vers Support for ``python_requires`` in a workspace is limited and highly **experimental** (the whole feature is still incubating, so no guarantees about ``python_requires`` either). - In case of having ``python_requires`` in the workspace, they should be declared first, before other packages that use - them, the order is important. They also must declare the proper ``package_type = "python-require"``. + Discovering the workspace packages does not resolve ``python_requires``, as remotes and the Conan cache are not + necessarily available at that point. If a package's ``name``/``version`` is declared directly (or via its own + ``set_name()``/``set_version()``), it works out of the box. If it is inherited from a ``python_requires``, it cannot + be deduced automatically, and a ``get_ref()`` method must be defined in ``conanws.py`` (see below). - Also, it will only work when using ``conanws.yml``, but not with a dynamic definition using ``conanws.py`` ``packages()`` - method. + Python-requires are also expected to declare ``package_type = "python-require"`` directly as a class attribute, not + inherited, so they can be filtered out from the workspace packages. conanws.py @@ -91,6 +93,28 @@ methods, using the ``Workspace.load_conanfile()`` helper: return result +get_ref() ++++++++++ + +If a package's ``name``/``version`` cannot be deduced because it is inherited from a ``python_requires`` (which is not +resolved while discovering the workspace packages), ``conanws.py`` can define a ``get_ref(folder)`` method to provide +the reference explicitly: + +.. code-block:: python + :caption: conanws.py + + from conan import Workspace + + class MyWorkspace(Workspace): + def get_ref(self, folder): + return {"pkga": "pkga/1.0", "pkgb": "pkgb/2.0"}.get(folder) + +``get_ref()`` can return a ``name/version[@user/channel]`` string, a ``RecipeReference``, or ``None`` if it doesn't +apply to that ``folder``. When the reference for a package cannot be deduced by any of these means (``ref`` in +``conanws.yml``, ``name``/``version`` attributes, ``set_name()``/``set_version()``, or ``get_ref()``), Conan raises an +error listing all the available alternatives. + + conanws.py super-build ``ConanFile`` ++++++++++++++++++++++++++++++++++++ From 40480a97fb1c72c251dc27bb55ac7e2ad14b53b2 Mon Sep 17 00:00:00 2001 From: Ernesto de Gracia Herranz Date: Thu, 23 Jul 2026 15:54:58 +0200 Subject: [PATCH 10/34] replace_in file with regex (#4498) --- examples/tools/files/patches/patch_sources.rst | 9 +++++++++ reference/tools/files/basic.rst | 6 ++++++ 2 files changed, 15 insertions(+) diff --git a/examples/tools/files/patches/patch_sources.rst b/examples/tools/files/patches/patch_sources.rst index 88bccef45cf6..6e04b24f048a 100644 --- a/examples/tools/files/patches/patch_sources.rst +++ b/examples/tools/files/patches/patch_sources.rst @@ -65,6 +65,15 @@ We can run ``conan create .`` and verify that if the replace was done: hello/1.0: Hello Friends! Release! ... + +Regular expressions and backreferences are also supported by enabling ``regex``. For example, the following call +captures the numeric part of ``version=123`` with ``(\d+)`` and reuses it in the replacement with ``\1``, producing +``version=v123``: + +.. code-block:: python + + replace_in_file(self, "file.txt", r"version=(\d+)", r"version=v\1", regex=True) + in build() method ^^^^^^^^^^^^^^^^^ diff --git a/reference/tools/files/basic.rst b/reference/tools/files/basic.rst index 269aa00dabb3..65204eb0eaaf 100644 --- a/reference/tools/files/basic.rst +++ b/reference/tools/files/basic.rst @@ -102,6 +102,12 @@ Usage: replace_in_file(self, os.path.join(self.source_folder, "folder", "file.txt"), "foo", "bar") +Regular expressions and backreferences can be used by enabling ``regex``: + +.. code-block:: python + + replace_in_file(self, "file.txt", r"version=(\d+)", r"version=v\1", regex=True) + conan.tools.files.chmod() ----------------------------------- From 1128eed408a133f30ad7af579ee467c0c56de471 Mon Sep 17 00:00:00 2001 From: James Date: Thu, 23 Jul 2026 16:50:06 +0200 Subject: [PATCH 11/34] example for PKG_CONFIG_PATH for package_info() (#4500) * example for PKG_CONFIG_PATH for package_info() * review --- examples/tools.rst | 1 + examples/tools/gnu/gnu.rst | 12 ++ examples/tools/gnu/pkg_config_sysroot.rst | 128 ++++++++++++++++++ .../system/system_package/package_manager.rst | 4 + reference/tools/cpp_info.rst | 12 ++ reference/tools/gnu/pkgconfig.rst | 5 + 6 files changed, 162 insertions(+) create mode 100644 examples/tools/gnu/gnu.rst create mode 100644 examples/tools/gnu/pkg_config_sysroot.rst diff --git a/examples/tools.rst b/examples/tools.rst index 28b8aadc70eb..d77dfcf67ad1 100644 --- a/examples/tools.rst +++ b/examples/tools.rst @@ -11,6 +11,7 @@ Conan recipe tools examples tools/meson/meson tools/google/bazel tools/autotools/autotools + tools/gnu/gnu tools/scm/git/capture_scm/git_capture_scm tools/microsoft/msbuild tools/system/system diff --git a/examples/tools/gnu/gnu.rst b/examples/tools/gnu/gnu.rst new file mode 100644 index 000000000000..eab3e16f5cf4 --- /dev/null +++ b/examples/tools/gnu/gnu.rst @@ -0,0 +1,12 @@ +.. _examples_tools_gnu: + + +GNU +=== + + +.. toctree:: + :maxdepth: 2 + + + pkg_config_sysroot diff --git a/examples/tools/gnu/pkg_config_sysroot.rst b/examples/tools/gnu/pkg_config_sysroot.rst new file mode 100644 index 000000000000..ad9dbdfc4f53 --- /dev/null +++ b/examples/tools/gnu/pkg_config_sysroot.rst @@ -0,0 +1,128 @@ +.. _examples_tools_gnu_pkg_config_sysroot: + +Using PkgConfig.fill_cpp_info with PKG_CONFIG_PATH from a profile +================================================================= + +The :ref:`PkgConfig` helper can read a ``.pc`` file and use +its contents to fill a ``cpp_info`` object with ``fill_cpp_info()``. When +``pkg_config_path`` is not passed explicitly, ``pkg-config`` locates the ``.pc`` file +via the ``PKG_CONFIG_PATH`` environment variable, which can be defined in the profile +``[buildenv]`` section. + +A common scenario is cross-compilation with an external toolchain: the toolchain provides +a sysroot that already ships ``.pc`` files describing its libraries (``gl.pc``, ``EGL.pc``, +``zlib.pc``, ...), and the host profile points ``PKG_CONFIG_PATH`` at the sysroot's +``pkgconfig`` folder. A wrapper recipe can then read those ``.pc`` files at ``package()`` +time and expose the information to consumers without hard-coding include and library paths. + +The challenge comes when users try to define ``PKG_CONFIG_PATH`` in the ``[buildenv]`` section +of a profile, because that is not available in the ``package_info()`` method of the recipes, +as the package information cannot rely on the "build environment", as the build environment +is only available when the package is being built, but not necessarily when the package is +being consumed. + +The example below uses a fabricated ``mylibastral.pc`` next to the profile to keep it +self-contained, but the mechanism is exactly the same as pointing to a real sysroot folder, +to illustrate how this could be implemented if necessary. + + +.. important:: + + This strategy is valid only for "system" packages, that is, recipes that act as a wrapper + around a system or sysroot dependency (typical in cross-compilation with an external + toolchain). Regular Conan packages that build and package their own artifacts should + not use this. + + +The **profile** below adds a folder containing ``.pc`` files to ``PKG_CONFIG_PATH``. The +``profile_dir`` Jinja variable resolves to the folder that contains the profile itself, +so a ``mypcs/`` folder next to the profile can be used directly: + +.. code-block:: ini + :caption: *myprofile* + + [settings] + os=Linux + arch=armv8 + + [buildenv] + PKG_CONFIG_PATH+=(path){{ profile_dir }}/mypcs + +In a real cross-compilation setup, that path would typically point to the sysroot +folder shipped by the toolchain, for example ``{{ sysroot }}/usr/lib/pkgconfig``. + +The ``.pc`` file located in the ``mypcs`` folder besides the profile describes the library +(include folders, library folders, libs, defines, link flags, ...): + +.. code-block:: text + :caption: *mypcs/mylibastral.pc* + + prefix=/usr/local + exec_prefix=${prefix} + libdir=${exec_prefix}/lib + includedir=${prefix}/include + + Name: mylibastral + Description: Interface library for Astral data flows + Version: 6.6.6 + Libs: -L${libdir}/libastral -lastral -lm -Wl,--whole-archive + Cflags: -I${includedir}/libastral -D_USE_LIBASTRAL + + +The ``conanfile.py`` recipe uses ``PkgConfig`` to read ``mylibastral.pc`` and populate a ``CppInfo`` +object. It does it at ``package()`` time, when the package is being built (the policies are added so the +package is automatically build when necessary in the current machine, and binaries are never uploaded, as +the information from that .pc file will only be valid in the current machine). +Notice that ``pkg_config_path`` is not passed: it is picked up from +``PKG_CONFIG_PATH`` defined in the profile. The resulting ``CppInfo`` is serialized to +the package folder in ``package()``, and reloaded in ``package_info()``: + +.. code-block:: python + :caption: *conanfile.py* + + import os + from conan import ConanFile + from conan.tools.gnu import PkgConfig + from conan.tools import CppInfo + + + class Pkg(ConanFile): + name = "mypkg" + version = "0.1" + build_policy = "missing" + upload_policy = "skip" + + def package(self): + # This method executes at package build time, it has + # available the build environment "buildenv" + pkg_config = PkgConfig(self, "mylibastral") + cpp_info = CppInfo(self) + pkg_config.fill_cpp_info(cpp_info, is_system=False, system_libs=["m"]) + cpp_info.save(os.path.join(self.package_folder, "cpp_info.json")) + + def package_info(self): + # This method executes at package consumption time, it will + # NOT have available the build environment, but it can load a file + # generated at build/package time + self.cpp_info = CppInfo(self).load("cpp_info.json") + + +Let's now create and consume the package: + +.. code-block:: bash + + $ conan create . -pr=myprofile + $ conan install --requires=mypkg/0.1 -pr=myprofile -g CMakeDeps + +The generated ``mypkg-none-armv8-data.cmake`` will contain the include/lib folders, +libs, defines and link flags read from ``mylibastral.pc``, something like: + +.. code-block:: cmake + + set(mypkg_INCLUDE_DIRS_NONE "/usr/local/include/libastral") + set(mypkg_LIB_DIRS_NONE "/usr/local/lib/libastral") + set(mypkg_LIBS_NONE astral) + set(mypkg_SYSTEM_LIBS_NONE m) + set(mypkg_DEFINITIONS_NONE "-D_USE_LIBASTRAL") + set(mypkg_COMPILE_DEFINITIONS_NONE "_USE_LIBASTRAL") + set(mypkg_SHARED_LINK_FLAGS_NONE "-Wl,--whole-archive") diff --git a/examples/tools/system/system_package/package_manager.rst b/examples/tools/system/system_package/package_manager.rst index 67eac57ba238..97a4d21c1eab 100644 --- a/examples/tools/system/system_package/package_manager.rst +++ b/examples/tools/system/system_package/package_manager.rst @@ -118,6 +118,10 @@ Another important detail is the **package_info** method. In this method, we are :ref:`PkgConfig` tool to fill the **cpp_info** data, based on the file ``ncurses.pc`` installed by the system package manager. +See :ref:`examples_tools_gnu_pkg_config_sysroot` for a variant of this pattern in a +cross-compilation scenario, where the ``.pc`` files are provided by a sysroot pointed to +by ``PKG_CONFIG_PATH`` in the profile ``[buildenv]``. + Now, let's install the ncurses library using the **conanfile.py** file: .. code-block:: bash diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst index 53bf0844642f..e985638acd4b 100644 --- a/reference/tools/cpp_info.rst +++ b/reference/tools/cpp_info.rst @@ -43,6 +43,9 @@ Some generators, like the built-in ``NMakeDeps``, contains the equivalent to thi 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. +CppInfo interface +----------------- + The public documented interface (besides the defined one in :ref:`the package_info()`) is: - ``CppInfo(conanfile)``: Constructor. Receives a ``conanfile`` as argument, typically ``self`` @@ -51,3 +54,12 @@ The public documented interface (besides the defined one in :ref:`the package_in with fewer dependencies within the same package. Returns an ``OrderedDict`` of sorted components in the format ``{component_name: component}``. - ``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. +- ``save(path)`` serializes the ``CppInfo`` object into json and saves it to the ``path``. +- ``CppInfo.load(path)`` static method returns a ``CppInfo`` object result of loading the ``path`` file and deserializing its json contents (result of a ``cpp_info.save(path)``) + +.. note:: + + **Best practices** + + Regular recipes should not use these special ``CppInfo`` methods in most cases. Most of them are intended for custom generators only, not recipes. + The ``save()/load()`` operations shouldn't be needed in recipes in most cases either, only for some exceptional circumstances like the :ref:`PkgConfig fill_cpp_info example`. diff --git a/reference/tools/gnu/pkgconfig.rst b/reference/tools/gnu/pkgconfig.rst index 046693614894..d31e05540791 100644 --- a/reference/tools/gnu/pkgconfig.rst +++ b/reference/tools/gnu/pkgconfig.rst @@ -37,6 +37,11 @@ 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"]) +If ``pkg_config_path`` is not provided, ``PkgConfig`` relies on the ``PKG_CONFIG_PATH`` environment +variable to locate the ``.pc`` files. This variable can be defined in the profile ``[buildenv]`` +section, a common approach for cross-compilation with a sysroot that already provides ``.pc`` files. +See :ref:`examples_tools_gnu_pkg_config_sysroot` for a full example. + Reference --------- From 1f4b57da073aa059091a1650cc9e0defa2128fa9 Mon Sep 17 00:00:00 2001 From: James Date: Thu, 23 Jul 2026 17:04:19 +0200 Subject: [PATCH 12/34] Feature/workspace out incubating (#4501) * wip * review --- incubating.rst | 4 ++- reference.rst | 2 +- reference/commands.rst | 2 +- reference/commands/workspace.rst | 2 +- reference/tools/cmake/cmaketoolchain.rst | 2 +- .../{workspace_files.rst => workspace.rst} | 27 ++++++++++++++----- tutorial/developing_packages/workspaces.rst | 11 ++------ 7 files changed, 30 insertions(+), 20 deletions(-) rename reference/{workspace_files.rst => workspace.rst} (91%) diff --git a/incubating.rst b/incubating.rst index 81b820d39ef8..9a68ed4e57cf 100644 --- a/incubating.rst +++ b/incubating.rst @@ -19,12 +19,14 @@ See :ref:`CMakeConfigDeps generator` Workspaces ---------- +Workspaces are not incubating anymore, but generally available as experimental. + Moved to :ref:`tutorial_workspaces` Workspace files syntax ++++++++++++++++++++++ -Moved to :ref:`reference_workspace_files` +Moved to :ref:`reference_workspace` Workspace commands diff --git a/reference.rst b/reference.rst index 8f1cd61c6741..b4dc409a0881 100644 --- a/reference.rst +++ b/reference.rst @@ -19,4 +19,4 @@ Reference reference/policies reference/tools reference/runners - reference/workspace_files + reference/workspace diff --git a/reference/commands.rst b/reference/commands.rst index 9b64d53df9c7..8d22fd55df6a 100644 --- a/reference/commands.rst +++ b/reference/commands.rst @@ -46,7 +46,7 @@ and these :ref:`custom command examples ` - :doc:`conan remote `: Add, remove, login/logout and manage remote server - :doc:`conan search `: Search packages matching a name - :doc:`conan version `: Give information about the Conan client version -- :doc:`conan workspace (incubating) `: Manage Conan workspaces +- :doc:`conan workspace `: Manage Conan workspaces - :doc:`conan run `: Execute binaries with automatic environment activation - :doc:`conan require `: Adds/removes requirements to/from your local conanfile diff --git a/reference/commands/workspace.rst b/reference/commands/workspace.rst index c2493897fb75..ab8088bd39d1 100644 --- a/reference/commands/workspace.rst +++ b/reference/commands/workspace.rst @@ -3,7 +3,7 @@ conan workspace =============== -.. include:: ../../common/incubating_warning.inc +.. include:: ../../common/experimental_warning.inc The ``conan workspace`` command allows to open, add, and remove packages from the current workspace. Check the diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst index f63eaf7d2b26..ea7f62c54e51 100644 --- a/reference/tools/cmake/cmaketoolchain.rst +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -663,7 +663,7 @@ The generated ``conan_toolchain.cmake`` contains information in its ``find_paths ``find_program()``, ``find_file()`` and other special "finder" routines that find artifacts without a explicit package and targets definition via the overall recommended ``find_package()``. -With the new incubating ``CMakeConfigDeps``, the ``conan_toolchain.cmake`` block ``find_paths`` no longer +With the new ``CMakeConfigDeps`` generator, the ``conan_toolchain.cmake`` block ``find_paths`` no longer defines the information itself, but it just loads a new file generated by the ``CMakeConfigDeps`` generator, the ``conan_cmakedeps_paths.cmake`` file. This way, the responsibility for creating information about dependencies is the ``CMakeConfigDeps`` generator, and that new file can be used in some scenarios in which passing a toolchain diff --git a/reference/workspace_files.rst b/reference/workspace.rst similarity index 91% rename from reference/workspace_files.rst rename to reference/workspace.rst index 6b26cbe4e885..3e107def3359 100644 --- a/reference/workspace_files.rst +++ b/reference/workspace.rst @@ -1,9 +1,9 @@ -.. _reference_workspace_files: +.. _reference_workspace: -Workspace files -=============== +Workspace +========= -.. include:: ../common/incubating_warning.inc +.. include:: ../common/experimental_warning.inc Workspaces are defined by the ``conanws.yml`` and/or ``conanws.py`` files that will define the "root" workspace folder. @@ -35,8 +35,7 @@ Moreover, it could not have the ``ref`` field, and let Conan read the *name/vers .. warning:: - Support for ``python_requires`` in a workspace is limited and highly **experimental** (the whole feature is still incubating, so - no guarantees about ``python_requires`` either). + Support for ``python_requires`` in a workspace is limited and highly **experimental**. Discovering the workspace packages does not resolve ``python_requires``, as remotes and the Conan cache are not necessarily available at that point. If a package's ``name``/``version`` is declared directly (or via its own @@ -46,6 +45,22 @@ Moreover, it could not have the ``ref`` field, and let Conan read the *name/vers Python-requires are also expected to declare ``package_type = "python-require"`` directly as a class attribute, not inherited, so they can be filtered out from the workspace packages. +.. note:: + + **Best practices** + + Workspaces are in general not expected to contain ``python-require`` recipes. The purpose of a workspace is to be + able to develop the C/C++ code of several packages simultaneously in a convenient way. The recipes should be rarely + modified in this flow, and it is not expected that the common Python code that lives in a ``python-require`` needs + to be modified by developers in a Workspace together with the C/C++ code. + + By the time a developer is putting several different packages into a Workspace to work on them, the common recipe + logic living in a ``python-require`` is expected to be read-only, not editable, and managed as an external dependency, + not an editable one within the workspace. + + A ``python-require`` might still be added to a workspace, with some limitations and caveats, but still the intention + is that this is a very exceptional scenario, and not something that regular developers would do. + conanws.py ---------- diff --git a/tutorial/developing_packages/workspaces.rst b/tutorial/developing_packages/workspaces.rst index 94dec8a8b31c..8dfdc5e19b0d 100644 --- a/tutorial/developing_packages/workspaces.rst +++ b/tutorial/developing_packages/workspaces.rst @@ -3,7 +3,7 @@ Workspaces ========== -.. include:: ../../common/incubating_warning.inc +.. include:: ../../common/experimental_warning.inc In the previous section, we worked with *editable packages* and how to define a custom layout. Let's introduce the concept @@ -12,13 +12,6 @@ of *workspace* and how to use it. Introduction ------------ -.. important:: - - The workspace feature can be enabled defining the environment variable ``CONAN_WORKSPACE_ENABLE=will_break_next``. - The value ``will_break_next`` is used to emphasize that it will change in next releases, and this feature is for testing only, - it cannot be used in production. - - A Conan *workspace* gives you the chance to manage several packages as ``editable`` mode in an *orchestrated* or *monolithic* (also called *super-build*) way: @@ -41,7 +34,7 @@ Through the ``conan workspace`` command, we can open, add, and/or remove ``packa .. seealso:: - Read the :ref:`workspace files` section. + Read the :ref:`workspace ` section. Read the :ref:`conan workspace command` section. .. _tutorial_workspaces_monolithic: From 00c77cefa29e36c41c15e3e4fb566dc941dc1f1b Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Thu, 23 Jul 2026 17:12:18 +0200 Subject: [PATCH 13/34] Conan 2.31.0 docs --- changelog.rst | 33 +++++++++++++++++++++++++++++++++ conf.py | 4 ++-- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/changelog.rst b/changelog.rst index 11943f9fae4f..7a40ee721b51 100644 --- a/changelog.rst +++ b/changelog.rst @@ -3,6 +3,39 @@ Changelog This page lists the changes made to Conan in each version, with links to each pull request for more details. +2.31.0 (23-Jul-2026) +-------------------- + +- Feature: Get Workspace feature out of incubating. `#20202 `_ . Docs `here `__ +- Feature: `replace_in_file` now supports regex patterns. `#20194 `_ . Docs `here `__ +- Feature: Warn when `conan config install` is used after `conan config install-pkg`. `#20188 `_ . Docs `here `__ +- Feature: Support GCC 14.4 and 15.3 in ``settings.yml``. `#20184 `_ +- Feature: Support intel-cc 2025.2, 2025.3 and 2026.1 in ``settings.yml``. `#20184 `_ +- Feature: Change the ``Workspace`` approach to not process ``python_requires`` just to derive ``name/version``. Proposed a new ``get_ref(folder)`` method in the ``conanws.py`` file to be able to define versions dynamically. `#20176 `_ . Docs `here `__ +- Feature: Define new `cpp_info.not_required` attribute to avoid downstream propagation of dependencies. `#20171 `_ . Docs `here `__ +- Feature: Add `NO_SONAME` support to `CMakeConfigDeps` to skip SONAME generation. `#20168 `_ . Docs `here `__ +- Feature: Assert invalid parameters in `ConanFile.run()` method. `#20156 `_ +- Feature: Add `.tar.zst` (Zstandard) archive support to the `unzip()` tool function. `#20140 `_ +- Feature: Reduce verbose terminal output produced during the `package()` step. `#20134 `_ +- Feature: Add `tools.build:asmflags` config and `CMakeToolchain.extra_asmflags` to populate `CMAKE_ASM_FLAGS`. `#20127 `_ +- Feature: Add ``micro`` modes to ``package_id_modes`` to model changes over MAJOR.MINOR.PATCH.MICRO ``micro`` digit. `#20102 `_ . Docs `here `__ +- Feature: New ``win_runtime_copy`` capability of ``VirtualRunEnv``, so it can copy on Windows the runtime files of dependencies (the ``cpp_info.bindirs`` directories contents) to a single location and point to it, avoiding path overflows (like in Windows) for large graphs. `#18638 `_ . Docs `here `__ +- Fix: Update remaining `audit.conan.io/` links to `conan.io/audit/`. `#20203 `_ +- Fix: Fix upload with empty uploads from pattern, to make it equal to package lists behavior `#20197 `_ +- Fix: Avoid conflict with Automake's `LINK` var when using `AutotoolsDeps` with MSVC by using `_LINK_` for linker flags. `#20192 `_ . Docs `here `__ +- Fix: Add support for VS 2026 in the `Premake` generator (requires Premake 5.0 beta 8). `#20189 `_ +- Fix: Fix rpath flags from `AutotoolsDeps` being dropped by Libtool on macOS, causing missing `LC_RPATH` in executables. `#20179 `_ +- Fix: Avoid option names shadowing internal `Options` implementation methods. `#20172 `_ . Docs `here `__ +- Fix: Fix deprecation warning for emcc/em++ >= 6.0.1, changing ``-sMEMORY64`` flag with the modern ``-m64`` one. `#20152 `_ +- Fix: Avoid a corner-case in component requires when `replace_requires` creates diamond divergent requirements. `#20139 `_ +- Fix: Fix Artifactory search patterns not matching `*@user/channel`, now requiring explicit `*/*@user/channel`. `#20136 `_ +- Fix: Use `LINK` env-var in Windows for AutotoolsDeps ``msvc`` compiler. `#20130 `_ . Docs `here `__ +- Bugfix: Require `default_components`, or all existing components, in `PkgConfigDeps` when root `pkg_config_name="none"`. `#20169 `_ +- Bugfix: Apply sorting to ``include()`` profiles settings patterns. `#20164 `_ +- Bugfix: Raise an exception when `layout()` fails in the Docker runner. `#20154 `_ +- Bugfix: Fix early return in `workspace complete` that could skip necessary packages. `#20150 `_ +- Bugfix: Fix crash in `replace_requires` when the graph had an override to a replaced requirement that did not apply. `#20146 `_ + 2.30.0 (29-Jun-2026) -------------------- diff --git a/conf.py b/conf.py index 96085393dec7..a87666b10287 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # The short X.Y version. -version = "2.30" +version = "2.31" # The full version, including alpha/beta/rc tags. -release = u'2.30.0' +release = u'2.31.0' dir_path = os.path.dirname(os.path.realpath(__file__)) if not os.path.exists(os.path.join(dir_path, "versions.json")): From 55fac32444449e3e9b6e850d5d89c8c159eba48e Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Fri, 24 Jul 2026 07:33:59 +0200 Subject: [PATCH 14/34] fix changelog --- changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.rst b/changelog.rst index 7a40ee721b51..989e8c3f665d 100644 --- a/changelog.rst +++ b/changelog.rst @@ -12,7 +12,7 @@ This page lists the changes made to Conan in each version, with links to each pu - Feature: Support GCC 14.4 and 15.3 in ``settings.yml``. `#20184 `_ - Feature: Support intel-cc 2025.2, 2025.3 and 2026.1 in ``settings.yml``. `#20184 `_ - Feature: Change the ``Workspace`` approach to not process ``python_requires`` just to derive ``name/version``. Proposed a new ``get_ref(folder)`` method in the ``conanws.py`` file to be able to define versions dynamically. `#20176 `_ . Docs `here `__ -- Feature: Define new `cpp_info.not_required` attribute to avoid downstream propagation of dependencies. `#20171 `_ . Docs `here `__ +- Feature: Define new `cpp_info.ignored_requires` attribute to avoid downstream propagation of dependencies. `#20171 `_ . Docs `here `__ - Feature: Add `NO_SONAME` support to `CMakeConfigDeps` to skip SONAME generation. `#20168 `_ . Docs `here `__ - Feature: Assert invalid parameters in `ConanFile.run()` method. `#20156 `_ - Feature: Add `.tar.zst` (Zstandard) archive support to the `unzip()` tool function. `#20140 `_ From 5215cc13f43ab5b81a87d38c4f4d1bf18cf87742 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Fri, 24 Jul 2026 12:51:06 +0200 Subject: [PATCH 15/34] Conan 2.31.1 docs --- changelog.rst | 5 +++++ conf.py | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/changelog.rst b/changelog.rst index 989e8c3f665d..89085dfe0a36 100644 --- a/changelog.rst +++ b/changelog.rst @@ -3,6 +3,11 @@ Changelog This page lists the changes made to Conan in each version, with links to each pull request for more details. +2.31.1 (24-Jul-2026) +-------------------- + +- Fix: Fixed `replace_in_file()` raising a false "pattern not found" error when the replacement produced the same content as the original (no-op replace). `#20211 `_ + 2.31.0 (23-Jul-2026) -------------------- diff --git a/conf.py b/conf.py index a87666b10287..2ca22f1f351f 100644 --- a/conf.py +++ b/conf.py @@ -69,7 +69,7 @@ # The short X.Y version. version = "2.31" # The full version, including alpha/beta/rc tags. -release = u'2.31.0' +release = u'2.31.1' dir_path = os.path.dirname(os.path.realpath(__file__)) if not os.path.exists(os.path.join(dir_path, "versions.json")): From 4afb9fcb99713a5e6d52ed21d81c3a15446ba482 Mon Sep 17 00:00:00 2001 From: James Date: Wed, 29 Jul 2026 13:32:12 +0200 Subject: [PATCH 16/34] layout order details (#4506) --- reference/conanfile/methods/layout.rst | 47 ++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/reference/conanfile/methods/layout.rst b/reference/conanfile/methods/layout.rst index 840815808b80..9d90e5f62884 100644 --- a/reference/conanfile/methods/layout.rst +++ b/reference/conanfile/methods/layout.rst @@ -114,6 +114,53 @@ package's build or source directory: - :ref:`here`. +.. _reference_conanfile_methods_layout_conan_source: + +Ordering and ``conan source`` compatibility +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``layout()`` method is also called by the :command:`conan source` command, which +runs without a host profile. This has two implications for how ``layout()`` should be +written: + +- **Order matters**: define the inputs, source-related parts first + (``self.folders.source``, ``self.folders.root``, ``self.folders.subproject``). These are + independent of settings and options, so they will always be correctly defined even + when :command:`conan source` is invoked. + +- **Do not fail when settings/options are not defined**: the build-related parts + (``self.folders.build``, ``self.folders.generators``, ``self.cpp.build``...) typically + depend on ``self.settings`` or ``self.options``, which are empty during + :command:`conan source`. The ``layout()`` method must not raise in that case. There + are two common approaches: + + - Use ``self.settings.get_safe(...)`` / ``self.options.get_safe(...)``, which return + ``None`` when the value is not defined instead of raising. This is the approach + used by the built-in ``cmake_layout()``, which produces a build folder like + ``build/None`` when :command:`conan source` is invoked. That value is not used by + :command:`conan source`, so it is harmless. + - Early-return from ``layout()`` after defining the source parts when settings are + not available, for example ``if not self.settings.get_safe(): return``. + +.. code-block:: python + + def layout(self): + # 1) Source parts: independent of settings/options, define them first + self.folders.source = "src" + + # 2) Build parts: may depend on settings/options, use get_safe to avoid + # failing during `conan source` when settings are empty + build_type = self.settings.get_safe("build_type") + # might be "build/None", but won't really be used in "conan source" commands + self.folders.build = f"build/{build_type}" + self.folders.generators = f"build/{build_type}/generators" + self.cpp.build.libdirs = [f"build/{build_type}"] + + # The "cpp_info" editable information needs also configuration, goes + # together with the build parts + self.cpp.source.includedirs = ["include"] + + Environment variables and configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From eae6a7177d7e8705fb8f4fd8127c79d195d6b3c7 Mon Sep 17 00:00:00 2001 From: James Date: Wed, 29 Jul 2026 13:40:04 +0200 Subject: [PATCH 17/34] conf eval float warning (#4507) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * conf eval float warning * Update reference/config_files/global_conf.rst Co-authored-by: Abril Rincón Blanco <5364255+AbrilRBS@users.noreply.github.com> --------- Co-authored-by: Abril Rincón Blanco <5364255+AbrilRBS@users.noreply.github.com> --- reference/config_files/global_conf.rst | 35 ++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/reference/config_files/global_conf.rst b/reference/config_files/global_conf.rst index 9377b959a38b..c378db6b6054 100644 --- a/reference/config_files/global_conf.rst +++ b/reference/config_files/global_conf.rst @@ -126,6 +126,41 @@ All the values will be interpreted by Conan as the result of the python built-in tools.microsoft.msbuildtoolchain:compile_options={"ExceptionHandling": "Async"} +.. warning:: + + Because the value is passed through ``eval()``, an input that looks like a numeric + literal will be evaluated as such. For example, a version string like ``1.10`` will + be evaluated to the float ``1.1``, silently losing the trailing zero: + + .. code-block:: text + + # This becomes the float 1.1, NOT the string "1.10" + user.myorg:docker_image_tag=1.10 + + Note that this mostly affects ``user.*`` confs, since built-in ``core.*`` and + ``tools.*`` confs internally declare their type and would not convert + a float. For ``user.*`` confs no type is enforced by default, so the evaluated + value is passed through as-is. + + The recommended workaround is to prefix the value with a non-numeric character + (for example ``v``) so ``eval()`` cannot turn it into a number, and then strip + that character in the recipe: + + .. code-block:: text + + # In the profile / global.conf / -c CLI argument + user.myorg:docker_image_tag=v1.10 + + .. code-block:: python + + # In the recipe + tag = self.conf.get("user.myorg:docker_image_tag", check_type=str).lstrip("v") + + Wrapping the value in quotes (``"1.10"``) also works from a *global.conf* or profile + ``[conf]`` section (``eval()`` will return the string ``1.10``), but this typically + does not survive shell quoting when passed on the command line with ``-c``. + + .. _configuration_data_operators: Configuration data operators From f0d140661a349160760e791c9c1d581643e1927a Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Mon, 27 Jul 2026 12:43:25 +0300 Subject: [PATCH 18/34] Merge pull request #4505 from czoido/fix-backend-example Remove passing Python3_EXECUTABLE from recipe for conan-py-build example --- .../build_python_extension_with_conan.rst | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/examples/extensions/python/build_backend/build_python_extension_with_conan.rst b/examples/extensions/python/build_backend/build_python_extension_with_conan.rst index 6bf9cdc45afd..6d35653f4d98 100644 --- a/examples/extensions/python/build_backend/build_python_extension_with_conan.rst +++ b/examples/extensions/python/build_backend/build_python_extension_with_conan.rst @@ -72,15 +72,14 @@ create a C++ package: .. code-block:: python :caption: **conanfile.py** - import sys - from conan import ConanFile - from conan.tools.cmake import CMake, CMakeDeps, CMakeToolchain, cmake_layout + from conan.tools.cmake import CMake, cmake_layout class MyAdderConan(ConanFile): name = "myadder" settings = "os", "compiler", "build_type", "arch" + generators = "CMakeToolchain", "CMakeDeps" def layout(self): cmake_layout(self) @@ -89,13 +88,6 @@ create a C++ package: self.requires("pybind11/3.0.1") self.requires("fmt/12.1.0") - def generate(self): - tc = CMakeToolchain(self) - tc.cache_variables["Python3_EXECUTABLE"] = sys.executable - tc.generate() - deps = CMakeDeps(self) - deps.generate() - def build(self): cmake = CMake(self) cmake.configure() @@ -112,8 +104,10 @@ to configure and build the extension with CMake. .. important:: - Setting ``Python3_EXECUTABLE`` to ``sys.executable`` keeps CMake on the - same interpreter ``pip`` uses, avoiding a wrong ABI build. + ``conan-py-build`` automatically points ``CMakeToolchain`` at the same Python + interpreter driving the build (``Python3_EXECUTABLE``/``Python_EXECUTABLE``), + so the recipe doesn't need to set it and CMake can't pick up a different, + ABI-incompatible Python. .. important:: From 1e2c3380fbee63fe48ba30da3b3edad1e3c6e51a Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Tue, 4 Aug 2026 20:13:06 +0200 Subject: [PATCH 19/34] Conan 2.31.2 docs --- changelog.rst | 5 +++++ conf.py | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/changelog.rst b/changelog.rst index 89085dfe0a36..39fd25592dd1 100644 --- a/changelog.rst +++ b/changelog.rst @@ -3,6 +3,11 @@ Changelog This page lists the changes made to Conan in each version, with links to each pull request for more details. +2.31.2 (04-Aug-2026) +-------------------- + +- Bugfix: ``conan upload .. --dry-run -f=json > to_upload.json`` now allows round-trip for ``conan upload -l=to_upload.json`` without re-preparing the artifacts. `#20237 `_ + 2.31.1 (24-Jul-2026) -------------------- diff --git a/conf.py b/conf.py index 2ca22f1f351f..5470f7953c60 100644 --- a/conf.py +++ b/conf.py @@ -69,7 +69,7 @@ # The short X.Y version. version = "2.31" # The full version, including alpha/beta/rc tags. -release = u'2.31.1' +release = u'2.31.2' dir_path = os.path.dirname(os.path.realpath(__file__)) if not os.path.exists(os.path.join(dir_path, "versions.json")): From 2293f3be7fb5796c910e776fc82871d70de3b95b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Abril=20Rinc=C3=B3n=20Blanco?= <5364255+AbrilRBS@users.noreply.github.com> Date: Thu, 6 Aug 2026 16:45:26 +0200 Subject: [PATCH 20/34] Merge pull request #4509 from AbrilRBS/ar/upload-two-step Documentation on conan upload --dry-run roundtrip usage --- reference/commands/upload.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/reference/commands/upload.rst b/reference/commands/upload.rst index 999f7109c505..818879594e0b 100644 --- a/reference/commands/upload.rst +++ b/reference/commands/upload.rst @@ -23,6 +23,19 @@ If the ``--format=json`` formatter is specified, the result will be a "PackageLi The ``--dry-run`` argument will prepare the packages for upload, zip files if necessary, check in the server to see what needs to be uploaded and what is already in the server, but it will not execute the actual upload. +.. note:: + The ``--dry-run`` flag is useful as the resulting package list json can be used to feed a ``conan upload --list=`` call, + allowing for the split of the preparation of artifacts step and the actual upload step, which can be useful in CI pipelines. + + .. code-block:: bash + + # Recipes are loaded and artifacts prepared, but no upload is performed + $ conan upload --dry-run -r=myremote -f=json > pkglist.json + # Nothing is re-prepared, only the actual upload is performed + $ conan upload --list=pkglist.json -r=myremote + + + Upload policies and efficient uploads ------------------------------------- From 99abbbe2f64a3d8c79022684d43b81823a88da29 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Mon, 10 Aug 2026 15:01:59 +0200 Subject: [PATCH 21/34] add docs (#4515) --- reference/tools/cmake/cmaketoolchain.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst index ea7f62c54e51..608fc4cfe052 100644 --- a/reference/tools/cmake/cmaketoolchain.rst +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -470,7 +470,10 @@ and added in this order: - **compilers**: Defines ``CMAKE__COMPILER`` for different languages, as defined by ``tools.build:compiler_executables`` configuration. - **android_system**: Defines ``ANDROID_PLATFORM``, ``ANDROID_STL``, ``ANDROID_ABI`` and includes ``ANDROID_NDK_PATH/build/cmake/android.toolchain.cmake`` where ``ANDROID_NDK_PATH`` comes defined in ``tools.android:ndk_path`` configuration value. -- **apple_system**: Defines ``CMAKE_OSX_ARCHITECTURES`` (see the :ref:`universal binaries section`), ``CMAKE_OSX_SYSROOT`` for Apple systems. +- **apple_system**: Defines ``CMAKE_OSX_ARCHITECTURES`` (see the :ref:`universal binaries section`), ``CMAKE_OSX_SYSROOT`` for Apple systems. It also + defines a default for ``CMAKE_Swift_COMPILER_TARGET`` from the Apple settings, so Swift code can be cross-built for iOS, watchOS, + tvOS, visionOS and Mac Catalyst. This only takes effect with the ``Ninja`` generator, as the Xcode generator ignores this + variable, so ``Ninja`` is the recommended generator for Swift. - **fpic**: Defines the ``CMAKE_POSITION_INDEPENDENT_CODE`` when there is a ``options.fPIC`` - **arch_flags**: Defines C/C++ flags like ``-m32, -m64`` when necessary. - **linker_scripts**: Defines the flags for any provided linker scripts. From ac92d2dd6e946f63e6acbadd20b4a4c4edf854bc Mon Sep 17 00:00:00 2001 From: James Date: Mon, 10 Aug 2026 15:02:42 +0200 Subject: [PATCH 22/34] add notes to cmake_file_name (#4503) --- .../cmake_toolchain/use_package_config_cmake.rst | 10 ++++++++++ .../creating_packages/define_package_information.rst | 12 +++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/examples/tools/cmake/cmake_toolchain/use_package_config_cmake.rst b/examples/tools/cmake/cmake_toolchain/use_package_config_cmake.rst index 9984f8b3e653..0e39e5ba3841 100644 --- a/examples/tools/cmake/cmake_toolchain/use_package_config_cmake.rst +++ b/examples/tools/cmake/cmake_toolchain/use_package_config_cmake.rst @@ -51,6 +51,16 @@ This is a very typical recipe, the main difference is the ``package_info()`` met - It is defining that it will contain the build scripts (like the ``xxx-config.cmake`` package) inside that folder, to be located by consumers. +.. note:: + + If the in-package ``xxx-config.cmake`` file has a different name than the Conan + package name, set the ``cmake_file_name`` property with the right value, so that + ``find_package()`` can locate it: + + .. code-block:: python + + self.cpp_info.set_property("cmake_file_name", "MyPkg") + So the responsibility of defining the package details has been transferred to the ``CMakeLists.txt`` that contains: .. code-block:: cmake diff --git a/tutorial/creating_packages/define_package_information.rst b/tutorial/creating_packages/define_package_information.rst index 7c6002e561d9..374b3c8fbbb4 100644 --- a/tutorial/creating_packages/define_package_information.rst +++ b/tutorial/creating_packages/define_package_information.rst @@ -301,9 +301,19 @@ And re-create the package: You can see how Conan now declares the target ``hello::myhello`` instead of the default ``hello::hello`` and the *test_package* builds successfully. +Similarly, if the CMake config file name differs from the Conan package name, set the +``cmake_file_name`` property so consumers can call ``find_package()`` with the right name, +for example if the consumers are expected to do ``find_package(MyHello CONFIG REQUIRED)`` + +.. code-block:: python + :caption: *conanfile.py* + + def package_info(self): + self.cpp_info.set_property("cmake_file_name", "MyHello") + The target name is not the only property you can set in the ``CMakeDeps`` generator. For a complete list of properties that affect the ``CMakeDeps`` generator behaviour, please check -the :ref:`reference`. +the :ref:`reference`. Propagating environment or configuration information to consumers ----------------------------------------------------------------- From 6bde63152770ccde1738912a134bc0ead2a4701b Mon Sep 17 00:00:00 2001 From: James Date: Mon, 10 Aug 2026 15:03:35 +0200 Subject: [PATCH 23/34] docs: PR 20208 - conan lock upgrade-config path is conanconfig.yml folder (#4510) --- reference/commands/lock/upgrade_config.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/reference/commands/lock/upgrade_config.rst b/reference/commands/lock/upgrade_config.rst index 9fc99818e5b3..9d77e2a36985 100644 --- a/reference/commands/lock/upgrade_config.rst +++ b/reference/commands/lock/upgrade_config.rst @@ -19,18 +19,26 @@ The upgrade can be done over individual requirements passed on the command line: $ conan lock upgrade-config --requires=config/[*] --update-config-requires=config/* -Note that it is important to specify which packages are to be updated with ``--update-config-requires``, because +Note that it is important to specify which packages are to be updated with ``--update-config-requires``, because it is possible that the lockfile contains more than one configuration package. Also note that the upgrade of the lockfile doesn't change yet or install the configuration. Until a ``conan config install-pkg`` happens, the active and current configuration will not be updated. -It is also possible use a ``conanconfig.yml`` file as an input to the command: +It is also possible to use a ``conanconfig.yml`` file as an input to the command, by passing the path to +its containing folder: .. code-block:: bash $ conan lock upgrade-config . --update-config-requires=config/1.0 +.. important:: + + The ``path`` argument must point to a folder containing a ``conanconfig.yml`` file + (typically the folder where ``conan config install-pkg`` is executed), not to a ``conanfile.py`` + or ``conanfile.txt`` recipe. Use ``--requires`` or ``--tool-requires`` to define recipe references + directly on the command line. + .. seealso:: From 8ada76ed4d5762ec8084e47f27a91430bc5431ea Mon Sep 17 00:00:00 2001 From: James Date: Mon, 10 Aug 2026 15:16:52 +0200 Subject: [PATCH 24/34] docs: PR 20217 - copy() accepts a list of patterns for a single scan (#4512) --- reference/tools/files/basic.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/reference/tools/files/basic.rst b/reference/tools/files/basic.rst index 65204eb0eaaf..9bcc445c8538 100644 --- a/reference/tools/files/basic.rst +++ b/reference/tools/files/basic.rst @@ -19,6 +19,17 @@ Usage: copy(self, "*.lib", self.build_folder, os.path.join(self.package_folder, "lib")) +Since Conan 2.32, the ``pattern`` argument also accepts a list or tuple of patterns. When a list +is provided, the source folder is walked only once and every file matching any of the patterns +is copied, which can be significantly faster than calling ``copy()`` several times for large trees: + +.. code-block:: python + + def package(self): + copy(self, ["*.h", "*.hpp"], self.source_folder, + os.path.join(self.package_folder, "include")) + + .. note:: The files that are **symlinks to files** or **symlinks to folders** with be treated like any other file, so they will only From 8a79b4d6346730cc12c5cacb1efc67357ebf3366 Mon Sep 17 00:00:00 2001 From: James Date: Mon, 10 Aug 2026 15:17:29 +0200 Subject: [PATCH 25/34] Docs/pr20219 compiler executables ux (#4513) * docs: PR 20219 - compiler_executables UX: warn on unknown keys, add objc/objcpp/asm for Autotools * review --- reference/tools/cmake/cmaketoolchain.rst | 5 ++++- reference/tools/gnu/autotoolstoolchain.rst | 5 +++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst index 608fc4cfe052..2894a4b1d5e0 100644 --- a/reference/tools/cmake/cmaketoolchain.rst +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -814,7 +814,7 @@ This block injects ``$`` which will be expanded later. It also defines a cache v * ``c``: will set ``CMAKE_C_COMPILER`` in *conan_toolchain.cmake*. * ``cpp``: will set ``CMAKE_CXX_COMPILER`` in *conan_toolchain.cmake*. - * ``RC``: will set ``CMAKE_RC_COMPILER`` in *conan_toolchain.cmake*. + * ``rc``: will set ``CMAKE_RC_COMPILER`` in *conan_toolchain.cmake*. * ``objc``: will set ``CMAKE_OBJC_COMPILER`` in *conan_toolchain.cmake*. * ``objcpp``: will set ``CMAKE_OBJCXX_COMPILER`` in *conan_toolchain.cmake*. * ``cuda``: will set ``CMAKE_CUDA_COMPILER`` in *conan_toolchain.cmake*. @@ -822,3 +822,6 @@ This block injects ``$`` which will be expanded later. It also defines a cache v * ``asm``: will set ``CMAKE_ASM_COMPILER`` in *conan_toolchain.cmake*. * ``hip``: will set ``CMAKE_HIP_COMPILER`` in *conan_toolchain.cmake*. * ``ispc``: will set ``CMAKE_ISPC_COMPILER`` in *conan_toolchain.cmake*. + + Since Conan 2.32, keys not listed above (including uppercase variants such as ``RC``) + are reported with a ``risk`` warning. diff --git a/reference/tools/gnu/autotoolstoolchain.rst b/reference/tools/gnu/autotoolstoolchain.rst index 1579f5548c7f..943029ad3ddc 100644 --- a/reference/tools/gnu/autotoolstoolchain.rst +++ b/reference/tools/gnu/autotoolstoolchain.rst @@ -320,6 +320,11 @@ conf * ``rc``: will set ``RC`` in *conanautotoolstoolchain.sh|bat* script. * ``cuda``: will set ``NVCC`` in *conanautotoolstoolchain.sh|bat* script. * ``fortran``: will set ``FC`` in *conanautotoolstoolchain.sh|bat* script. + * ``objc`` *(since Conan 2.32)*: will set ``OBJC`` in *conanautotoolstoolchain.sh|bat* script. + * ``objcpp`` *(since Conan 2.32)*: will set ``OBJCXX`` in *conanautotoolstoolchain.sh|bat* script. + * ``asm`` *(since Conan 2.32)*: will set ``AS`` in *conanautotoolstoolchain.sh|bat* script. + + Since Conan 2.32, keys not listed above are reported with a ``risk`` warning. .. note:: From 6dd4e006a742e4c06967400010c7ac2dd9baa830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Abril=20Rinc=C3=B3n=20Blanco?= <5364255+AbrilRBS@users.noreply.github.com> Date: Tue, 11 Aug 2026 07:07:45 +0200 Subject: [PATCH 26/34] Remove documentation of removed deprecated features/policies (#4517) --- reference/policies.rst | 52 +----------------------------------------- 1 file changed, 1 insertion(+), 51 deletions(-) diff --git a/reference/policies.rst b/reference/policies.rst index b4231bde9c04..5f1327c64092 100644 --- a/reference/policies.rst +++ b/reference/policies.rst @@ -10,7 +10,7 @@ which is a list of strings, where each string is the name of a policy to be enab .. code-block:: :caption: ``global.conf`` - core:policies = ["required_conan_version>=2.28", "deprecated_build_order_args"] + core:policies = ["required_conan_version>=2.28"] List of current policies ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -53,53 +53,3 @@ If both the policy and the recipe attribute are defined, the behavior will be en .. note:: This policy is independent of the ``core:required_conan_version`` conf, which is exclusively used to define the minimum required Conan version. - -deprecated_build_order_args ---------------------------- -*Introduced in Conan 2.28* - -If the policy is defined, the old behaviour for ``conan graph build-order`` is kept where the -``--order-by`` argument is not required, and the output is ordered by recipe by default. -Note that when the argument is provided, the output format is different, such that the order is -returned inside the ``order`` key of the json output, instead of being the top-level list. - -With ``core:policies=["deprecated_build_order_args"]``, the following command will work without the ``--order-by`` argument: - -.. code-block:: shell - - $ conan graph build-order ... -f=json - - [ - [{...}, {...}], - [{...}] - ] - -Without the policy, the ``--order-by`` argument is mandatory, and the output will be: - -.. code-block:: shell - - $ conan graph build-order ... -f=json --order-by=recipe - - { - "order": [ - [{...}, {...}], - [{...}] - ], - "order_by": "recipe", - ... - } - - - -.. warning:: - **Will be removed in Conan 2.32**, where the ``--order-by`` argument will be mandatory and the old behavior will be removed. - -deprecated_empty_version_range ------------------------------- -*Introduced in Conan 2.28* - -If the policy is enabled, Conan will accept empty version ranges (e.g., ``pkg/[]``) as valid, -and they will be treated as "any version" (equivalent to ``pkg/[*]``). - -.. warning:: - **Will be removed in Conan 2.32**, where empty version ranges will be considered invalid and treated as a syntax error. From 3450b6f715d4c3ba9f50edd5a049c320e67d930e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Abril=20Rinc=C3=B3n=20Blanco?= <5364255+AbrilRBS@users.noreply.github.com> Date: Tue, 11 Aug 2026 09:40:17 +0200 Subject: [PATCH 27/34] Populate download cache on upload (#4518) --- reference/config_files/global_conf.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/reference/config_files/global_conf.rst b/reference/config_files/global_conf.rst index c378db6b6054..257ed41fa68f 100644 --- a/reference/config_files/global_conf.rst +++ b/reference/config_files/global_conf.rst @@ -512,6 +512,11 @@ This is useful to avoid recurrent downloads of the same packages, especially in **Default value:** Not defined. +.. note:: + + When this conf is defined and an artifact is uploaded to a remote, + Conan will also populate the download cache of the client with the same artifact. + UX confs -------- From a1522b43cf8e024a251a69d5de9697180c7cea64 Mon Sep 17 00:00:00 2001 From: Luis Caro Campos <3535649+jcar87@users.noreply.github.com> Date: Wed, 12 Aug 2026 11:01:47 +0100 Subject: [PATCH 28/34] pyenv docs: call methods on the same object (#4519) --- reference/tools/system/pyenv.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/reference/tools/system/pyenv.rst b/reference/tools/system/pyenv.rst index 8cb5cfb9771c..4f99dc3eb40b 100644 --- a/reference/tools/system/pyenv.rst +++ b/reference/tools/system/pyenv.rst @@ -58,8 +58,9 @@ In this case, in the build step, which is where we will use the installed tool. basic_layout(self) def generate(self): - PyEnv(self).install(["meson==1.9.1"]) - PyEnv(self).generate() + pyenv = PyEnv(self) + pyenv.install(["meson==1.9.1"]) + pyenv.generate() def build(self): self.run("meson --version") From 02854ee96afda10a5564e6f377097577859aa11a Mon Sep 17 00:00:00 2001 From: James Date: Fri, 14 Aug 2026 11:03:04 +0200 Subject: [PATCH 29/34] Docs/pr20214 run profile tool requires (#4511) * docs: PR 20214 - conan run can use profile [tool_requires] without conanfile * review --- reference/commands/run.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/reference/commands/run.rst b/reference/commands/run.rst index 44c948078097..f6e7d097e80f 100644 --- a/reference/commands/run.rst +++ b/reference/commands/run.rst @@ -29,3 +29,24 @@ This command is useful when you want to execute some specific binary from any pa .. note:: This command activates both the ``host`` and ``build`` contexts, so that both contexts binaries are made available at once. In case that a package exists in both contexts, the ``host`` context binaries take precedence. + + +Running executables from profile ``[tool_requires]`` +---------------------------------------------------- + +.. include:: ../../common/experimental_warning.inc + +Starting in Conan 2.32, ``conan run`` can be invoked without a ``conanfile`` and without +``--requires`` / ``--tool-requires`` arguments. In that case, executables provided by the +``[tool_requires]`` section of the active profile can be executed directly: + +.. code-block:: text + :caption: *myprofile* + + include(default) + [tool_requires] + cmake/3.29.3 + +.. code-block:: bash + + $ conan run "cmake --version" -pr:h=myprofile From 8aa0d8fb421407a26beccfc23c5d8288586e462d Mon Sep 17 00:00:00 2001 From: Uilian Ries Date: Fri, 14 Aug 2026 12:58:44 +0200 Subject: [PATCH 30/34] Add conan.tools.build.architecture_bits in tools reference (#4522) Signed-off-by: Uilian Ries --- reference/tools/build.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/reference/tools/build.rst b/reference/tools/build.rst index 69baca9e0d92..15e8ed8d7336 100644 --- a/reference/tools/build.rst +++ b/reference/tools/build.rst @@ -34,6 +34,13 @@ conan.tools.build.can_run() .. autofunction:: can_run +conan.tools.build.architecture_bits() +""""""""""""""""""""""""""""""""""""" + +.. currentmodule:: conan.tools.build.flags + +.. autofunction:: architecture_bits + Cppstd ^^^^^^ @@ -163,4 +170,3 @@ conan.tools.build.check_min_compiler_version() .. currentmodule:: conan.tools.build.compiler .. autofunction:: check_min_compiler_version - From 8ef9a742adb99329f043fcc2e767173dd784b3fe Mon Sep 17 00:00:00 2001 From: Ivan Komissarov Date: Mon, 17 Aug 2026 08:05:58 +0300 Subject: [PATCH 31/34] qbs: document qbs_file_name property (#4520) --- reference/conanfile/methods/package_info.rst | 2 +- reference/tools/qbs/qbsdeps.rst | 27 +++++++++++++++++++- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/reference/conanfile/methods/package_info.rst b/reference/conanfile/methods/package_info.rst index fa5255838179..b40c852222fd 100644 --- a/reference/conanfile/methods/package_info.rst +++ b/reference/conanfile/methods/package_info.rst @@ -82,7 +82,7 @@ Flags: Properties: -- **set_property()** allows to define some built-in and user general properties to be propagated with the ``cpp_info`` model for consumers. They might contain build-system specific information. Some built-in properties are ``cmake_file_name``, ``cmake_target_name``, ``pkg_config_name``, that can define specific behavior for ``CMakeDeps`` or ``PkgConfigDeps`` generators. For more information about these, read the specific build system integration documentation. +- **set_property()** allows to define some built-in and user general properties to be propagated with the ``cpp_info`` model for consumers. They might contain build-system specific information. Some built-in properties are ``cmake_file_name``, ``cmake_target_name``, ``pkg_config_name``, ``qbs_file_name``, that can define specific behavior for ``CMakeDeps``, ``PkgConfigDeps`` or ``QbsDeps`` generators. For more information about these, read the specific build system integration documentation. Structure: diff --git a/reference/tools/qbs/qbsdeps.rst b/reference/tools/qbs/qbsdeps.rst index 781653b01de4..42730ef08c74 100644 --- a/reference/tools/qbs/qbsdeps.rst +++ b/reference/tools/qbs/qbsdeps.rst @@ -46,6 +46,8 @@ The dependency to the application can be added using the ``Depends`` item: moduleProviders.conan.installDirectory: "build" } +By default, for a ``hello`` requires, you need to use ``Depends { name: "hello" }``. + Note that we are setting the ``qbsModuleProviders`` property to ``"conan"`` in order to tell Qbs that dependencies are generated by Conan. We also set the ``installDirectory`` property of the ``conan`` module provider to ``"build"`` to tell the provider to look for generated files @@ -71,10 +73,33 @@ generator is used. - Check the :ref:`Qbs helper ` for details. + +.. _QbsDeps Properties: + +Properties +---------- + +The following properties affect the ``QbsDeps`` generator: + +- **qbs_file_name**: Name of the generated Qbs module for the current package. The generator + creates a ``.json`` file, and consumers use ``Depends { name: "" }``. + By default this is the package name, or ``pkg_config_name`` if that property is set. + Use ``qbs_file_name`` to override the module name. + +Example: + +.. code-block:: python + + def package_info(self): + ... + # Generates MyFirstLib.json, consumed as: Depends { name: "MyFirstLib" } + self.cpp_info.set_property("qbs_file_name", "MyFirstLib") + + Reference --------- .. currentmodule:: conan.tools.qbs.qbsdeps .. autoclass:: QbsDeps - :members: \ No newline at end of file + :members: From 16d907601ea6d79e6b237920786a227b361c377a Mon Sep 17 00:00:00 2001 From: James Date: Mon, 17 Aug 2026 07:07:10 +0200 Subject: [PATCH 32/34] docs: PR 20240 - DownloadAPI methods to fetch metadata into an arbitrary folder (#4514) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: PR 20240 - DownloadAPI methods to fetch metadata into an arbitrary folder * Link the package --------- Co-authored-by: Abril Rincón Blanco --- devops/metadata.rst | 46 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/devops/metadata.rst b/devops/metadata.rst index 8c6612aea121..500d57567dd2 100644 --- a/devops/metadata.rst +++ b/devops/metadata.rst @@ -266,6 +266,52 @@ Note that the "package-list" will only contain associated to the "remote" origin There are other possibilities, like a custom command that can automatically collect and download dependencies metadata from the servers. +Downloading metadata to an arbitrary folder ++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../common/experimental_warning.inc + +Since Conan 2.32, the Python API provides two methods to fetch only the metadata of a +recipe or package revision into an arbitrary folder, bypassing the Conan cache. This is +useful for custom commands and CI workflows that need to inspect metadata (build logs, +test outputs...) without changing the local cache state: + +- :meth:`DownloadAPI.recipe_metadata ` +- :meth:`DownloadAPI.package_metadata ` + +Both methods require a fully resolved reference (with recipe revision, and package +revision for the package case), the target ``Remote``, the metadata patterns to fetch, +and the destination folder. The metadata files are written under ``/metadata/``. +This can be wrapped in a custom command as follows: + +.. code-block:: python + + import os + from conan.api.model import PkgReference, RecipeReference + from conan.cli.command import conan_command + + + @conan_command(group="custom commands") + def metadata_download(conan_api, parser, *args): + """Download the metadata of a recipe/package revision into cwd (no cache).""" + parser.add_argument("reference") + parser.add_argument("-r", "--remote", required=True) + a = parser.parse_args(*args) + remote = conan_api.remotes.get(a.remote) + if ":" in a.reference: + pref = PkgReference.loads(a.reference) + if pref.ref.revision is None: + pref.ref = conan_api.list.latest_recipe_revision(pref.ref, remote) + if pref.revision is None: + pref = conan_api.list.latest_package_revision(pref, remote) + conan_api.download.package_metadata(pref, remote, ["*"], os.getcwd()) + else: + ref = RecipeReference.loads(a.reference) + if ref.revision is None: + ref = conan_api.list.latest_recipe_revision(ref, remote) + conan_api.download.recipe_metadata(ref, remote, ["*"], os.getcwd()) + + Removing metadata ----------------- At the moment it is not possible to remove metadata from the server side using Conan, as the metadata are "additive", it is possible to add new data, but not to remove it (otherwise it would not be possible to add new metadata without downloading first all the previous metadata, and that can be quite inefficient and more error prone, specially sensitive to possible race conditions). From 57727f122dca316eff79a743ec7c7e76e83bac42 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Mon, 17 Aug 2026 12:51:23 +0200 Subject: [PATCH 33/34] add docs (#4523) --- reference/tools/apple/xcodetoolchain.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/reference/tools/apple/xcodetoolchain.rst b/reference/tools/apple/xcodetoolchain.rst index 3cc142c4b0a7..559f13e34757 100644 --- a/reference/tools/apple/xcodetoolchain.rst +++ b/reference/tools/apple/xcodetoolchain.rst @@ -67,15 +67,20 @@ Those files are: variables with conditional logic depending on the build configuration, architecture and sdk set. - *conantoolchain.xcconfig*: aggregates all the *conantoolchain__.xcconfig* files for the different installed configurations. -- *conan_global_flags.xcconfig*: this file will only be generated in case of any - configuration variables related to compiler or linker flags are set. Check :ref:`the - configuration section` below for more details. - +- *conan_global_flags__.xcconfig*: declares ``GCC_PREPROCESSOR_DEFINITIONS``, + ``OTHER_CFLAGS``, ``OTHER_CPLUSPLUSFLAGS`` and ``OTHER_LDFLAGS`` variables with conditional + logic depending on the build configuration, architecture and sdk set. This file will only + be generated in case any configuration variables related to compiler or linker flags are + set. Check :ref:`the configuration section` below for more details. +- *conan_global_flags.xcconfig*: aggregates all the + *conan_global_flags__.xcconfig* files for the different installed + configurations (*since Conan 2.32*). Every invocation to ``conan install`` with different configuration will create a new -*conantoolchain__.xcconfig* file that is aggregated in the -*conantoolchain.xcconfig*, so you can have different configurations included in your Xcode -project. +*conantoolchain__.xcconfig* and, if any compiler or linker flags are set, a new +*conan_global_flags__.xcconfig* file. Both are aggregated in +*conantoolchain.xcconfig* and *conan_global_flags.xcconfig* respectively, so you can have +different configurations included in your Xcode project. The XcodeToolchain files can declare the following Xcode build settings based on Conan settings values: From bfdc34af37d7ea52ab0b165a26172007fbbb3d1a Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Mon, 17 Aug 2026 12:58:15 +0200 Subject: [PATCH 34/34] wip (#4524) --- reference/tools/apple/xcodetoolchain.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/reference/tools/apple/xcodetoolchain.rst b/reference/tools/apple/xcodetoolchain.rst index 559f13e34757..5f7801833b86 100644 --- a/reference/tools/apple/xcodetoolchain.rst +++ b/reference/tools/apple/xcodetoolchain.rst @@ -112,3 +112,21 @@ This toolchain is also affected by these **[conf]** variables: If you set any of these variables, the toolchain will use them to generate the ``conan_global_flags.xcconfig`` file that will be included from the ``conan_config.xcconfig`` file. + +build_settings +++++++++++++++ + +The ``build_settings`` attribute lets a recipe set any Xcode build setting +directly. Settings already covered by a **[conf]** variable, such as +``OTHER_CFLAGS``, ``OTHER_CPLUSPLUSFLAGS``, ``OTHER_LDFLAGS`` and +``GCC_PREPROCESSOR_DEFINITIONS``, should instead be set with the +``tools.build:*`` variables from the :ref:`conf section` +above: + +.. code:: python + + def generate(self): + tc = XcodeToolchain(self) + tc.build_settings["OTHER_SWIFT_FLAGS"] = "$(inherited) -cxx-interoperability-mode=default" + tc.build_settings["GCC_WARN_UNUSED_VARIABLE"] = "YES" + tc.generate()