new --build-require argument for create/install

changelog.rst

@@ -37,7 +37,7 @@ Check https://github.com/conan-io/conan for issues and more details about develo
 - Feature: Update urlib3 Conan dependency setting version `>=1.25.8` to avoid CVE-2020-7212. `#8914 <https://github.com/conan-io/conan/pull/8914>`_
 - Feature: Build-requires can define [conf] for its consumers. `#8895 <https://github.com/conan-io/conan/pull/8895>`_ . Docs `here <https://github.com/conan-io/docs/pull/2107>`__
 - Feature: support M1 Catalyst. `#8818 <https://github.com/conan-io/conan/pull/8818>`_
-- Feature: New ``conan install <ref> --build-require`` and ``conan create <path> --build-require``  (when not using ``test_package``) arguments to explicitly define that the installed or created package has to be a ``build-require``, receiving the build profile instead of the host one. `#8627 <https://github.com/conan-io/conan/pull/8627>`_
+- Feature: New ``conan install <ref> --build-require`` and ``conan create <path> --build-require``  (when not using ``test_package``) arguments to explicitly define that the installed or created package has to be a ``build-require``, receiving the build profile instead of the host one. `#8627 <https://github.com/conan-io/conan/pull/8627>`_ . Docs `here <https://github.com/conan-io/docs/pull/2113>`__
 - Feature: Introduced the `layout()` method to the recipe to be able to declare the folder structure both for the local development methods (conan source, conan build...) and in the cache. Also, associated to the folders, cppinfo objects to be used in editable packages and file pattern descriptions to enable "auto packaging". `#8554 <https://github.com/conan-io/conan/pull/8554>`_ . Docs `here <https://github.com/conan-io/docs/pull/2092>`__
 - Fix: **CMakeDeps** generator: The transitive requirements for a build_require are not included in the `xxx-config.cmake` files generated. `#9015 <https://github.com/conan-io/conan/pull/9015>`_
 - Fix: The `CMakeToolchain` now supports Apple M1 cross-building with a profile without environment declared pointing to the system toolchain. `#9011 <https://github.com/conan-io/conan/pull/9011>`_

reference/commands/consumer/install.rst

@@ -7,16 +7,17 @@ conan install
 .. code-block:: bash
 
     $ conan install [-h] [-g GENERATOR] [-if INSTALL_FOLDER] [-m [MANIFESTS]]
-                    [-mi [MANIFESTS_INTERACTIVE]] [-v [VERIFY]]
-                    [--no-imports] [-j JSON] [-b [BUILD]] [-r REMOTE] [-u]
-                    [-l LOCKFILE] [--lockfile-out LOCKFILE_OUT] [-e ENV_HOST]
-                    [-e:b ENV_BUILD] [-e:h ENV_HOST] [-o OPTIONS_HOST]
-                    [-o:b OPTIONS_BUILD] [-o:h OPTIONS_HOST]
-                    [-pr PROFILE_HOST] [-pr:b PROFILE_BUILD]
-                    [-pr:h PROFILE_HOST] [-s SETTINGS_HOST]
-                    [-s:b SETTINGS_BUILD] [-s:h SETTINGS_HOST]
-                    [--lockfile-node-id LOCKFILE_NODE_ID]
-                    path_or_reference [reference]
+                     [-mi [MANIFESTS_INTERACTIVE]] [-v [VERIFY]]
+                     [--no-imports] [--build-require] [-j JSON] [-b [BUILD]]
+                     [-r REMOTE] [-u] [-l LOCKFILE]
+                     [--lockfile-out LOCKFILE_OUT] [-e ENV_HOST]
+                     [-e:b ENV_BUILD] [-e:h ENV_HOST] [-o OPTIONS_HOST]
+                     [-o:b OPTIONS_BUILD] [-o:h OPTIONS_HOST]
+                     [-pr PROFILE_HOST] [-pr:b PROFILE_BUILD]
+                     [-pr:h PROFILE_HOST] [-s SETTINGS_HOST]
+                     [-s:b SETTINGS_BUILD] [-s:h SETTINGS_HOST]
+                     [--lockfile-node-id LOCKFILE_NODE_ID]
+                     path_or_reference [reference]
 
 Installs the requirements specified in a recipe (conanfile.py or conanfile.txt).
 
@@ -60,6 +61,7 @@ generators.
       -v [VERIFY], --verify [VERIFY]
                             Verify dependencies manifests against stored ones
       --no-imports          Install specified packages but avoid running imports
+      --build-require       The provided reference is a build-require
       -j JSON, --json JSON  Path to a json file where the install information will
                             be written
       -b [BUILD], --build [BUILD]
@@ -351,3 +353,26 @@ The ``install`` command accepts several arguments related to :ref:`lockfiles<ver
 
   Installation of binaries can be accelerated setting up parallel downloads with the ``general.parallel_download``
   **experimental** configuration in :ref:`conan_conf`.
+
+--build-require
+---------------
+
+The ``--build-require``, new in Conan 1.37, is experimental. It allows to install the package using the
+configuration and settings of the "build" context, as it was a ``build_require``. Lets see it with an example:
+
+We have a ``mycmake/1.0`` package, which bundles cmake executable, and we are cross-compiling from Windows
+to Linux, so all the usual install commands will use something like ``-pr:b=Windows -pr:h=Linux``.
+At some point we might want to install the ``build-require`` to test it, executing it directly in the
+terminal, with ``-build-require`` it is possible:
+
+.. code-block:: bash
+
+    $ conan install mycmake/1.0@ --build-require -g virtualenv -pr:b=Windows -pr:h=Linux
+    # Installs Windows package binary, not the Linux one.
+    $ source ./activate.sh && mycmake
+    # This will execute the "mycmake" from the Windows package.
+
+This also works when building a dependency graph, including build-requires, in CI. As the
+``conan lock build-order`` command will return a list including the build/host context, it is
+possible to use that to add the ``--build-require`` to the command, and build ``build-requires``
+as necessary without needing to change the profiles at all.

reference/commands/creator/create.rst

@@ -11,16 +11,16 @@ conan create
 .. code-block:: bash
 
     $ conan create [-h] [-j JSON] [-k] [-kb] [-ne] [-tbf TEST_BUILD_FOLDER]
-                   [-tf TEST_FOLDER] [--ignore-dirty] [-m [MANIFESTS]]
-                   [-mi [MANIFESTS_INTERACTIVE]] [-v [VERIFY]] [-b [BUILD]]
-                   [-r REMOTE] [-u] [-l LOCKFILE]
-                   [--lockfile-out LOCKFILE_OUT] [-e ENV_HOST]
-                   [-e:b ENV_BUILD] [-e:h ENV_HOST] [-o OPTIONS_HOST]
-                   [-o:b OPTIONS_BUILD] [-o:h OPTIONS_HOST]
-                   [-pr PROFILE_HOST] [-pr:b PROFILE_BUILD]
-                   [-pr:h PROFILE_HOST] [-s SETTINGS_HOST]
-                   [-s:b SETTINGS_BUILD] [-s:h SETTINGS_HOST]
-                   path [reference]
+                    [-tf TEST_FOLDER] [--ignore-dirty] [--build-require]
+                    [-m [MANIFESTS]] [-mi [MANIFESTS_INTERACTIVE]]
+                    [-v [VERIFY]] [-b [BUILD]] [-r REMOTE] [-u] [-l LOCKFILE]
+                    [--lockfile-out LOCKFILE_OUT] [-e ENV_HOST]
+                    [-e:b ENV_BUILD] [-e:h ENV_HOST] [-o OPTIONS_HOST]
+                    [-o:b OPTIONS_BUILD] [-o:h OPTIONS_HOST]
+                    [-pr PROFILE_HOST] [-pr:b PROFILE_BUILD]
+                    [-pr:h PROFILE_HOST] [-s SETTINGS_HOST]
+                    [-s:b SETTINGS_BUILD] [-s:h SETTINGS_HOST]
+                    path [reference]
 
 Builds a binary package for a recipe (conanfile.py).
 
@@ -58,6 +58,7 @@ to know more about 'test_folder' project.
       --ignore-dirty        When using the "scm" feature with "auto" values,
                             capture the revision and url even if there are
                             uncommitted changes
+       --build-require       The provided reference is a build-require
       -m [MANIFESTS], --manifests [MANIFESTS]
                             Install dependencies manifests in folder for later
                             verify. Default folder is .conan_manifests, but can be
@@ -187,4 +188,11 @@ In case of installing a pre-built binary, steps from 5 to 11 will be skipped. No
 .. note::
 
   Installation of binaries can be accelerated setting up parallel downloads with the ``general.parallel_download``
-  **experimental** configuration in :ref:`conan_conf`.
+  **experimental** configuration in :ref:`conan_conf`.
+
+
+The ``--build-require``, new in Conan 1.37, is experimental. It allows to create the package using the
+configuration and settings of the "build" context, as it was a ``build_require``. This feature allows
+to create packages in a way that is consistent to the way they will be used later. When there is a
+``test_package``, then it is possible to specify there the ``test_type`` directly, no need to provide it
+in the command line.