Improve reference for the build_id() method (#4158)

* Improve reference for the build_id() method

* fix

* Update reference/conanfile/methods/build_id.rst

Co-authored-by: Abril Rincón Blanco <[email protected]>

* Update reference/conanfile/methods/build_id.rst

Co-authored-by: Abril Rincón Blanco <[email protected]>

* Update reference/conanfile/methods/build_id.rst

---------

Co-authored-by: Abril Rincón Blanco <[email protected]>

Author: danimtb

reference/conanfile/methods/build_id.rst

@@ -3,56 +3,101 @@
 build_id()
 ==========
 
-The ``build_id()`` method allows to re-use the same build to create different binary packages in the cache,
-potentially saving build time as it can avoid some unnecessary re-builds. It is therefore an optimization method.
+The ``build_id()`` method allows you to **reuse a single build** to create multiple binary packages in the Conan cache,
+saving time by avoiding unnecessary rebuilds.
 
-In the general case, there is one build folder for each binary package, with the exact same ``package_id`` of the package. However this behavior
-can be changed, there are a couple of scenarios that this might be useful:
+It is primarily an optimization tool for situations where **building each configuration separately isn't feasible**.
 
-- The package build scripts generate several different configurations at once (like both debug and release artifacts) in the same run, without the possibility of building each configuration separately.
-- The package build scripts generate one binary configuration, but different artifacts that can be packaged separately. For example if there are some test executables, you might want to create two packages: one just containing the library for general usage, and another one also containing the tests (for compliance, later reproducibility, debugging, etc).
+There are a couple of scenarios where this could be useful, for example, when a package build:
 
-In the first case, we could for example write:
+* **Generates multiple configurations in a single build run**:
+  Some build scripts always produce both Debug and Release artifacts together, without a way to build them separately.
 
-..  code-block:: python
+
+* **Produces one configuration but different sets of artifacts**:
+  The build could generate the main library plus some test executables, and you want to create:
+
+  * one package with just the library (for general use), and
+  * another package that includes both the library and the test binaries (for compliance, debugging, or reproducibility).
+
+In these scenarios, **reusing the same build folder avoids recompiling the same sources multiple times** just because you need slightly different packaging.
+
+How does the build folder relate to the package ID and the build ID?
+--------------------------------------------------------------------
+
+By default, Conan creates **one build folder per unique package ID**, where:
+
+* Generally, the **package ID** depends on the combination of `settings`, `options`, and dependencies.
+* Each different **package ID** triggers a separate ``build()`` execution and generates a separate build folder.
+
+When you define the ``build_id()`` method, you can **force different package IDs to share the same build folder** by customizing `self.info_build`:
+
+* ``self.info_build`` is like ``self.info``, but it only affects the computation of the **build ID**, not the final package ID.
+* Any package IDs with the same build ID will reuse the same build folder and the same build step.
+
+
+Example: sharing the build for Debug and Release
+++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. code-block:: python
 
     settings = "os", "compiler", "arch", "build_type"
 
     def build_id(self):
         self.info_build.settings.build_type = "Any"
 
-This recipe will generate a final different package with a different ``package_id`` for debug and release configurations. But as the ``build_id()`` will generate the
-same ``build_id`` for any ``build_type``, then just one folder and one ``build()`` will be done, building both debug and release artifacts,
-and then the ``package()`` method will be called for each configuration, and it should package the artifacts conditionally to the ``self.settings.build_type`` value. Different builds will still be
-executed if using different compilers or architectures.
+* With this recipe, Debug and Release will each produce their own package IDs (and thus their own binary packages),
+  but they will **share the same build folder**, because the build ID ignores the ``build_type`` setting.
+* **However, you still need to run one** :command:`conan create` **command per configuration** (e.g., once for Debug, once for Release).
+  Conan will check if the build folder already exists (based on the shared build ID) and skip the actual compilation
+  if it's already been built, only executing `package()` to create the corresponding package.
 
-Other information like custom package options can also be changed:
+Example workflow:
 
-..  code-block:: python
+.. code-block:: bash
 
-    def build_id(self):
-        self.info_build.options.myoption = 'MyValue' # any value possible
-        self.info_build.options.fullsource = 'Always'
+    # First build: creates the build folder + packages the Debug package
+    $ conan create . -s build_type=Debug
+
+    # Second build: reuses the previous build folder + packages the Release package without rebuilding
+    $ conan create . -s build_type=Release
+
+This way, although we called :command:`conan create` twice (once per package ID), the actual build will only happen once.
+
+.. note::
+
+    You can also customize ``build_id()`` based on options:
+
+    .. code-block:: python
+
+        def build_id(self):
+            self.info_build.options.myoption = "MyValue"
+            self.info_build.options.fullsource = "Always"
+
+Conditional usage of the build ID
+---------------------------------
 
-If the ``build_id()`` method does not modify the ``info_build`` data, and it still produces a different id than
-the ``package_id``, then the standard behavior will be applied. Consider the following:
+If the ``build_id()`` method does not modify the ``self.info_build`` data, and produces the same build ID as the package ID,
+then the standard behavior will be applied. For example:
 
-..  code-block:: python
+.. code-block:: python
 
     settings = "os", "compiler", "arch", "build_type"
 
     def build_id(self):
         if self.settings.os == "Windows":
             self.info_build.settings.build_type = "Any"
 
-This will only produce a different ``build_id`` if the package is for Windows, thus running ``build()`` just
-once for all ``build_type`` values. The behavior
-in any other OS will be the standard one, as if the ``build_id()`` method was not defined, running
-one different ``build()`` for each ``build_type``.
+This will only produce a different **build ID** if the package is for Windows, so it will only run the ``build()`` method once
+for all the ``build_type`` values.
 
+For any other OS, Conan will behave as usual (as if the ``build_id()`` method was not defined), running the ``build()`` method
+for every ``build_type`` configuration.
 
 .. note::
 
     **Best practices**
 
-    Conan strongly recommends to use one package binary with its own ``package_id`` for each different configuration. The goal of the ``build_id()`` method is to deal with legacy build scripts that cannot easily be changed to do the build of one configuration each time.
+    The goal of the ``build_id()`` method is to deal with legacy build scripts that cannot easily be changed
+    to compile one configuration at a time. We strongly recommend to just package **one package binary per package ID**
+    for each different configuration.