From 36678863a948acf18d179d4fd844f249530d19ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rub=C3=A9n=20Rinc=C3=B3n=20Blanco?= Date: Fri, 19 Jan 2024 13:12:56 +0100 Subject: [PATCH] A few notes on using the new -cc CLI arg --- devops/versioning/resolve_prereleases.rst | 7 ++++--- reference/config_files/global_conf.rst | 16 ++++++++-------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/devops/versioning/resolve_prereleases.rst b/devops/versioning/resolve_prereleases.rst index 04cd834310ab..a5366c094914 100644 --- a/devops/versioning/resolve_prereleases.rst +++ b/devops/versioning/resolve_prereleases.rst @@ -11,7 +11,7 @@ At first glance, it could be expected that the new version matches our range if but :ref:`as described in the version ranges tutorial`, by default Conan does not match pre-release versions to ranges that don't specify it. Conan provides the :ref:`global.conf` ``core.version_ranges:resolve_prereleases``, -which when set to ``True``, enable pre-release matching in version ranges. +which when set to ``True``, enables pre-release matching in version ranges. This avoids having to modify and export the recipes of your dependency graph, which would become unfeasible for large ones. This conf has the added benefit of affecting the whole dependency graph, so that if any of our dependencies also define @@ -32,8 +32,9 @@ in which we depend on ``libpng`` and ``libmysqlclient``, both of which depend on } If ``zlib/1.3-pre`` is now published, using it is as easy as modifying your :ref:`global.conf` -file and adding the line ``core.version_ranges:resolve_prereleases=True``, after which, -running ``conan create`` will now output the expected prerelease version of ``zlib`` being used: +file and adding the line ``core.version_ranges:resolve_prereleases=True`` +(or adding the ``--core-conf core.version_ranges:resolve_prereleases=True`` CLI argument to your command invocations), +after which, running ``conan create`` will now output the expected prerelease version of ``zlib`` being used: .. code-block:: text diff --git a/reference/config_files/global_conf.rst b/reference/config_files/global_conf.rst index 37cfb25e40ab..3d45a3cc9e6c 100644 --- a/reference/config_files/global_conf.rst +++ b/reference/config_files/global_conf.rst @@ -58,12 +58,12 @@ Tools and user configurations can be defined in both the *global.conf* file and These are some hints about configuration items scope and naming: - ``core.xxx`` and ``tools.yyy`` are Conan built-ins, users cannot define their own ones in these scopes. -- ``core.xxx`` can be defined in ``global.conf`` only, but not in profiles. -- ``tools.yyy`` can be defined in ``global.conf``, in profiles ``[conf]`` section and cli ``-c`` arguments +- ``core.xxx`` can be defined in ``global.conf`` or via the ``--core-conf`` CLI argument only, but not in profiles. +- ``tools.yyy`` can be defined in ``global.conf``, in profiles ``[conf]`` section and as CLI ``-c`` arguments - ``user.zzz`` can be defined everywhere, and they are totally at the user discretion, no established naming convention. However this would be more or less expected: - - For open source libraries, specially those in conancenter, ``user.packagename:conf`` might be expected, like the ``boost`` recipe defining ``user.boost:conf`` conf - - For private usage, the recommendation could be to use something like ``user.orgname:conf`` for global org configuration across all projects, ``user.orgname.project:conf`` for project or package configuration, though ``user.project:conf`` might be also good if the project name is unique enough. - + - For open source libraries, specially those in conancenter, ``user.packagename:conf`` might be expected, like the ``boost`` recipe defining ``user.boost:conf`` conf + - For private usage, the recommendation could be to use something like ``user.orgname:conf`` for global org configuration across all projects, ``user.orgname.project:conf`` for project or package configuration, though ``user.project:conf`` might be also good if the project name is unique enough. + - They _must_ have one ``:`` separator, like ``user.myorg:conf``, but not ``user.myorg.conf`` or ``user.myorg``. This is to disambiguate from patterns, which are discussed below. Configuration file template --------------------------- @@ -156,8 +156,8 @@ You can use package patterns to apply the configuration in those dependencies wh *:tools.cmake.cmaketoolchain:generator=Ninja zlib:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019 -This example shows you how to specify a general ``generator`` for all your packages except for `zlib` which is defining -`Visual Studio 16 2019` as its generator. +This example shows you how to specify a general ``generator`` for all your packages except for ``zlib`` which is defining +``Visual Studio 16 2019`` as its generator. Besides that, it's quite relevant to say that **the order matters**. So, if we change the order of the configuration lines above: @@ -167,7 +167,7 @@ configuration lines above: zlib:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019 *:tools.cmake.cmaketoolchain:generator=Ninja -The result is that you're specifying a general `generator` for all your packages, and that's it. The `zlib` line has no +The result is that you're specifying a general ``generator`` for all your packages, and that's it. The ``zlib`` line has no effect because it's the first one evaluated, and after that, Conan is overriding that specific pattern with the most general one, so it deserves to pay special attention to the order.