diff --git a/reference/commands/create.rst b/reference/commands/create.rst index 73eb093f3c8..e8ed3398f0b 100644 --- a/reference/commands/create.rst +++ b/reference/commands/create.rst @@ -140,6 +140,31 @@ The functions with *(test package)* belong to the *conanfile.py* in the *test_pa already installed. Typically, it should be installed just as it was installed in the previous "install packages" step. +Build modes +----------- + +The ``conan create --build=`` build modes are very similar to the ``conan install`` ones documented in :ref:`Build Modes`, +with some differences. + +By default, ``conan create`` defines the ``--build=current_pkg/current_version`` to force the build +from source for the current revision. This assumes that the source code (recipe, C/C++ code) was +changed and it will create a new revision. If that is not the case, then the ``--build=missing:current_pkg/current_version`` +would be recommended to avoid rebuilding from source an already existing binary. + +When a ``--build=xxx`` argument is defined in the command line, then the automatically defined +``--build=current_pkg/current_version`` is no longer passed, and it should be passed as a explicit argument too. + +.. note:: + + **Best practices** + + Having more than a ``package_revision`` for a given ``recipe_revision`` and ``package_id`` is discouraged + in most cases, as it implies unnecessarily rebuilding from sources binaries that were already existing. For that + reason, using ``conan create`` repeatedly over the same recipe without any source changes that would cause a + new ``recipe_revision`` is discouraged, and using ``conan create . --build=missing:[pattern]`` would be the + recommended approach. + + .. seealso:: - Read more about creating packages in the :ref:`dedicated diff --git a/reference/commands/install.rst b/reference/commands/install.rst index 21a486e0f04..2bfc0caa4bc 100644 --- a/reference/commands/install.rst +++ b/reference/commands/install.rst @@ -232,3 +232,63 @@ to only update those packages, which avoids the re-evaluation of the whole graph Note that the ``--update`` argument will look into all the remotes specified in the command for possible newer versions, and won't stop at the first newer one found. + + +.. _reference_commands_build_modes: + +Build modes +----------- + +The ``conan install --build=`` argument controls the behavior regarding building packages from source. +The default behavior is failing if there are no existing binaries, with the "missing binary" error message, +except for packages that define a ``build_policy = "missing"`` policy, but this can be changed with the +``--build`` argument. + +The possible values are: + +.. code-block:: bash + + --build=never Disallow build for all packages, use binary packages or fail if a binary + package is not found, it cannot be combined with other '--build' options. + --build=missing Build packages from source whose binary package is not found. + --build=cascade Build packages from source that have at least one dependency being built from + source. + --build=[pattern] Build packages from source whose package reference matches the pattern. The + pattern uses 'fnmatch' style wildcards, so '--build="*"' will build everything + from source. + --build=~[pattern] Excluded packages, which will not be built from the source, whose package + reference matches the pattern. The pattern uses 'fnmatch' style wildcards. + --build=missing:[pattern] Build from source if a compatible binary does not exist, only for + packages matching pattern. + --build=compatible:[pattern] (Experimental) Build from source if a compatible binary does not + exist, and the requested package is invalid, the closest package + binary following the defined compatibility policies (method and + compatibility.py) + + +The ``--build=never`` policy can be used to force never building from source, even for package recipes +that define the ``build_policy = "missing"`` policy. + +The ``--build=compatible:[pattern]`` is an **experimental** new mode that allows building missing binaries +with a configuration different than the current one. For example if the current profile has +``compiler.cppstd=14``, but some package raises an "invalid" configuration error, because it needs at +least ``compiler.cppstd=17``, and the binary compatibiliy (defined for example in ``compatibility.py`` plugin) +allows that as a compatible binary, then, Conan will build from source that dependency package applying +``compiler.cppstd=17``. + +The ``--build=[pattern]`` uses a pattern, so it should use something like ``--build="zlib/*"`` to match any +version of the ``zlib`` package, as doing ``--build=zlib`` will not work. + +.. note:: + + **Best practices** + + Forcing the rebuild of existing binaries with ``--build="*"`` or any other ``--build="pkg/*"`` or + similar pattern is not a recommended practice. If a binary is already existing there is no reason + to rebuild it from source. CI pipelines should be specially careful to not do this, and in general + the ``--build=missing`` and ``--build=missing:[pattern]`` are more recommended. + + The ``--build=cascade`` mode is partly legacy, and shouldn't be used in most cases. The ``package_id`` + computation should be the driver to decide what needs to be built. This mode has been left in Conan 2 + only for exceptional cases, like recovering from broken systems, but it is not recommended for normal + production usage.