Merge pull request #3989 from conan-io/release/2.12

Sync develop2 with Release/2.12

Author: czoido

changelog.rst

@@ -3,6 +3,13 @@ Changelog
 
 For a more detailed description of the major changes that Conan 2 brings, compared with Conan 1.X, please read :ref:`whatsnew`
 
+2.12.2 (12-Feb-2025)
+--------------------
+
+- Fix: Fix default name and let cycloneDX define a custom name. `#17760 <https://github.com/conan-io/conan/pull/17760>`_ . Docs `here <https://github.com/conan-io/docs/pull/3983>`__
+- Fix: Add cycloneDX `add_tests` and `add_build` parameters. `#17760 <https://github.com/conan-io/conan/pull/17760>`_ . Docs `here <https://github.com/conan-io/docs/pull/3983>`__
+- Bugfix: Fix cycloneDX tool parameters. `#17760 <https://github.com/conan-io/conan/pull/17760>`_ . Docs `here <https://github.com/conan-io/docs/pull/3983>`__
+
 2.12.1 (28-Jan-2025)
 --------------------
 

conf.py

@@ -67,7 +67,7 @@
 # The short X.Y version.
 version = "2.12"
 # The full version, including alpha/beta/rc tags.
-release = u'2.12.1'
+release = u'2.12.2'
 
 dir_path = os.path.dirname(os.path.realpath(__file__))
 if not os.path.exists(os.path.join(dir_path, "versions.json")):

examples/tools.rst

@@ -13,4 +13,4 @@ Conan recipe tools examples
    tools/autotools/autotools
    tools/scm/git/capture_scm/git_capture_scm
    tools/microsoft/msbuild
-   tools/system/package_manager
+   tools/system/system

examples/tools/system/system.rst

@@ -0,0 +1,13 @@
+.. _examples_system:
+
+
+System Packages
+===============
+
+
+.. toctree::
+   :maxdepth: 2
+
+
+   system_package/package_manager
+   system_package/consuming_system_packages

examples/tools/system/system_package/consuming_system_packages.rst

@@ -0,0 +1,65 @@
+.. _examples_tools_system_consuming_system_packages:
+
+Consuming system requirements only when building a package
+==========================================================
+
+In some cases, you may want to consume system requirements only when building a package, but not when installing it.
+It can be useful when you want to build a package in a CI/CD pipeline, but you don't want to run the system package
+manager when installing the Conan package in a different environment.
+For those cases, there are few approaches that can be used to achieve this goal.
+
+
+Consume a Conan package wrapper for a system package as build requirement
+-------------------------------------------------------------------------
+
+In this approach, you can use a Conan package for a :ref:`wrapped system package<examples_tools_system_package_manager>`.
+Then, the package can be consumed regularly by the method
+:ref:`build_requirements()<reference_conanfile_methods_build_requirements>`.
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class MyPackage(ConanFile):
+        name = "mypackage"
+        settings = "os", "compiler", "build_type", "arch"
+
+        def build_requirements(self):
+            self.tool_requires("ncurses/system")
+
+        ...
+
+This ensures that downstream consumers of the package *mypackage* will not directly invoke the system
+package manager (e.g., apt-get). Only the direct package consumer of the system wrap package for ``ncurses``
+will execute the system package manager when building the package.
+
+Centralizing and wrapping ``ncurses`` in a separated recipe makes it reusable across multiple cases and is
+good practice to avoid code duplication.
+
+
+Consume the system package directly in the build() method
+---------------------------------------------------------
+
+In case wanting to run the system package manager only when building the package, but not having a Conan package to
+wrap the system library information, it's possible to run the system package manager in the **build()** method:
+
+.. code-block:: python
+
+    from conan import ConanFile
+    from conan.tools.system import package_manager
+
+    class MyPackage(ConanFile):
+        settings = "os", "compiler", "build_type", "arch"
+        ...
+
+        def build(self):
+            if self.settings.os == "Linux":
+                apt = package_manager.Apt(self)
+                apt.install(["libncurses-dev"], update=True, check=True)
+
+This way, the system package manager will be called only when building the package, not when installing it.
+There is the advantage of not needed to create a separated Conan package to wrap the system library information,
+this is a much simpler case, when only a single recipe need to install the system package.
+
+Still, this approach may lead to code duplication if multiple recipes consume the same system package.
+It is recommended to use this method sparingly and only for well-contained cases.

examples/tools/system/package_manager.rst examples/tools/system/system_package/package_manager.rst

@@ -103,11 +103,14 @@ The ``core.package_id:default_xxx`` configurations defined in ``global.conf`` ca
     core.package_id:default_python_mode: By default, 'minor_mode'
     core.package_id:default_unknown_mode: By default, 'semver_mode'
 
+These confs affect how :ref:`the package id<reference_binary_model_package_id>` is calculated, so changing them will affect
+your generated binaries. It's thus recommended that they stay consistent across your organization.
+
 .. note::
 
     **Best practices**
 
-    It is strongly recommended that the ``core.package_id:default_xxx`` should be global, consistent and immutable accross organizations. It can be confusing to change these defaults for different projects or teams, because it will result in missing binaries.
+    It is strongly recommended that the ``core.package_id:default_xxx`` should be global, consistent and immutable across organizations. It can be confusing to change these defaults for different projects or teams, because it will result in missing binaries.
 
     It should also be consistent and shared with the consumers of generated packages if those packages are
     shared outside the organization, in that case sharing the ``global.conf`` file via ``conan config install``

reference/binary_model/custom_compatibility.rst

@@ -148,7 +148,9 @@ It is possible to also invoke the package recipes ``deploy()`` method with the `
     # Execute deploy() method only for "pkg" (any version) recipes
     $ conan install --requires=pkg/0.1 --deployer-package=pkg/*
 
-The ``--deployer-package`` argument is a pattern and accept multiple values, all package references matching any of the defined patterns will execute its ``deploy()`` method. The ``--deployer-folder`` argument will also affect the output location of this deployment. See the :ref:`deploy() method<reference_conanfile_methods_deploy>`.
+The ``--deployer-package`` argument is a pattern and accepts multiple values, all package references matching any of the defined patterns will execute its ``deploy()`` method.
+This includes negated patterns, where for example ``--deployer-package=~pkg/*`` will execute the ``deploy()`` method for all packages except for that of the ``pkg`` recipe.
+The ``--deployer-folder`` argument will also affect the output location of this deployment. See the :ref:`deploy() method<reference_conanfile_methods_deploy>`.
 
 If multiple deployed packages deploy to the same location, it is their responsibility to not mutually overwrite their binaries if they have the same filenames. For example if multiple packages ``deploy()`` a file called "License.txt", each recipe is responsible for creating an intermediate folder with the package name and/or version that makes it unique, so other recipes ``deploy()`` method do not overwrite previously deployed "License.txt" files.
 

reference/commands/install.rst

@@ -25,8 +25,8 @@ CycloneDX
 Conan supports `CycloneDX <https://cyclonedx.org/>`_ out-of-the-box, which is one of the most widely used standards for SBOMs.
 
 The CycloneDX tool is available in the ``conan.tools.sbom.cyclonedx`` module.
-It provides the ``cyclonedx_1_4`` function which receives a Conan dependency graph
-(usually a :ref:`conanfile.subgraph <conan_conanfile_attribute_other_subgraph>`) and returns a dictionary with the SBOM data in the CycloneDX 1.4 format.
+It provides the ``cyclonedx_1_4`` function which receives a ``conanfile`` and returns a dictionary with the SBOM data in
+the CycloneDX 1.4 JSON format.
 
 .. currentmodule:: conan.tools.sbom.cyclonedx
 .. autofunction:: cyclonedx_1_4
@@ -35,7 +35,7 @@ Using this feature is as simple as implementing a :ref:`hook <reference_extensio
 which uses this tool to create the SBOM and stores it in the appropriate location.
 
 Usage examples
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 Let's look at two examples:
 
@@ -52,7 +52,7 @@ In the example, we save the generated sbom in the package metadata folder to kee
     from conan.tools.sbom.cyclonedx import cyclonedx_1_4
 
     def post_package(conanfile, **kwargs):
-        sbom_cyclonedx_1_4 = cyclonedx_1_4(conanfile.subgraph)
+        sbom_cyclonedx_1_4 = cyclonedx_1_4(conanfile)
         metadata_folder = conanfile.package_metadata_folder
         file_name = "sbom.cdx.json"
         with open(os.path.join(metadata_folder, file_name), 'w') as f:
@@ -77,7 +77,7 @@ has easy access to the SBOM.
     from conan.tools.sbom.cyclonedx import cyclonedx_1_4
 
     def post_generate(conanfile, **kwargs):
-        sbom_cyclonedx_1_4 = cyclonedx_1_4(conanfile.subgraph)
+        sbom_cyclonedx_1_4 = cyclonedx_1_4(conanfile)
         generators_folder = conanfile.generators_folder
         file_name = "sbom.cdx.json"
         os.mkdir(os.path.join(generators_folder, "sbom"))
@@ -89,8 +89,8 @@ has easy access to the SBOM.
 Both hooks can coexist in such a way that we can generate the SBOMs for our application and our dependencies separately.
 This can greatly assist us in conducting continuous analysis of our development process and ensuring software quality.
 
-Conan
-^^^^^
+Generating a Conan-based SBOM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Instead of using a standard, we can take a "Conan-based approach". Thanks to the ``conanfile.subgraph.serialize()``
 function, we can directly obtain information about the dependencies of our package.