From fb9683a2303ebe702fbb533f33e9f4cfa2f0acc2 Mon Sep 17 00:00:00 2001 From: Francisco Ramirez de Anton Date: Thu, 18 May 2023 13:01:12 +0200 Subject: [PATCH 1/6] explained host_version --- .../conanfile/methods/build_requirements.rst | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index b494f725dfed..8837d1562c72 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -27,6 +27,45 @@ The ``tool_requires`` is equivalent to ``requires()`` with the following traits: - ``headers=False`` A tool requirement does not have headers. - ``libs=False``: A tool requirement does not have libraries to be linked by the consumer (if it had libraries they would be in the "build" context and could be incompatible with the "host" context of the consumer package). + +************** + +.. include:: ../../../common/experimental_warning.inc + +This syntax is useful when you're using the same package recipe as a *requires* and as a *tool_requires* and you want to avoid +conflicting downstream if any user decides to override the original *requires* version, i.e., the user could end up with +two different versions in host and build context of the same dependency. + +For instance, let's show a simple recipe using *protobuf*: + +.. code-block:: python + + from conan import ConanFile + + class mylibRecipe(ConanFile): + name = "mylib" + version = "0.1" + def requirements(self): + self.requires("protobuf/3.18.1") + def build_requirements(self): + self.tool_requires("protobuf/") + +Then, if any user wants to use my *mylib/0.1*, but another version of protobuf, there shouldn't be any problem overriding it: + +.. code-block:: python + + from conan import ConanFile + + class myappRecipe(ConanFile): + name = "myapp" + version = "0.1" + def requirements(self): + self.requires("mylib/0.1") + self.requires("protobuf/3.21.9", override=True) + +The ```` defined upstream is ensuring that the host and build context are using the same version of that requirement. + + test_requires ------------- From 4398067303076aaef184a2262f22abba46f30649 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ram=C3=ADrez?= Date: Thu, 18 May 2023 13:15:11 +0200 Subject: [PATCH 2/6] Update reference/conanfile/methods/build_requirements.rst Co-authored-by: Luis Caro Campos <3535649+jcar87@users.noreply.github.com> --- reference/conanfile/methods/build_requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index 8837d1562c72..caacbe24986b 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -33,7 +33,7 @@ The ``tool_requires`` is equivalent to ``requires()`` with the following traits: .. include:: ../../../common/experimental_warning.inc This syntax is useful when you're using the same package recipe as a *requires* and as a *tool_requires* and you want to avoid -conflicting downstream if any user decides to override the original *requires* version, i.e., the user could end up with +conflicting downstream if any user decides to override the original *requires* version in the *host* context, i.e., the user could end up with two different versions in host and build context of the same dependency. For instance, let's show a simple recipe using *protobuf*: From 42759f4faada6b0ee2d29a3ebb9cfd149ee7f62f Mon Sep 17 00:00:00 2001 From: Francisco Ramirez de Anton Date: Thu, 18 May 2023 13:18:03 +0200 Subject: [PATCH 3/6] Suggestions --- reference/conanfile/methods/build_requirements.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index caacbe24986b..9313de1d33f5 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -36,6 +36,9 @@ This syntax is useful when you're using the same package recipe as a *requires* conflicting downstream if any user decides to override the original *requires* version in the *host* context, i.e., the user could end up with two different versions in host and build context of the same dependency. +In a nutshell, the ```` specifier allows us to ensure that the version resolved for the *tool_requires* +always matches the one for the host requirement. + For instance, let's show a simple recipe using *protobuf*: .. code-block:: python From 9c8c492e5cd25d0cf6e35084461f7a1aa70186b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ram=C3=ADrez?= Date: Thu, 18 May 2023 13:20:14 +0200 Subject: [PATCH 4/6] Update reference/conanfile/methods/build_requirements.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rubén Rincón Blanco --- reference/conanfile/methods/build_requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index 9313de1d33f5..2d684d1e69ae 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -34,7 +34,7 @@ The ``tool_requires`` is equivalent to ``requires()`` with the following traits: This syntax is useful when you're using the same package recipe as a *requires* and as a *tool_requires* and you want to avoid conflicting downstream if any user decides to override the original *requires* version in the *host* context, i.e., the user could end up with -two different versions in host and build context of the same dependency. +two different versions in the host and build contexts of the same dependency. In a nutshell, the ```` specifier allows us to ensure that the version resolved for the *tool_requires* always matches the one for the host requirement. From 384fc1355e407711186d6d5038c05594edcdf8c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ram=C3=ADrez?= Date: Thu, 18 May 2023 13:20:25 +0200 Subject: [PATCH 5/6] Update reference/conanfile/methods/build_requirements.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rubén Rincón Blanco --- reference/conanfile/methods/build_requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index 2d684d1e69ae..00925b7e63a9 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -53,7 +53,7 @@ For instance, let's show a simple recipe using *protobuf*: def build_requirements(self): self.tool_requires("protobuf/") -Then, if any user wants to use my *mylib/0.1*, but another version of protobuf, there shouldn't be any problem overriding it: +Then, if any user wants to use *mylib/0.1*, but another version of *protobuf*, there shouldn't be any problems overriding it: .. code-block:: python From 8d4ae7d33c548cb7a88ed9d77efd0ae005cfcbff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ram=C3=ADrez?= Date: Thu, 18 May 2023 13:20:32 +0200 Subject: [PATCH 6/6] Update reference/conanfile/methods/build_requirements.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rubén Rincón Blanco --- reference/conanfile/methods/build_requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index 00925b7e63a9..624073a6d90d 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -66,7 +66,7 @@ Then, if any user wants to use *mylib/0.1*, but another version of *protobuf*, t self.requires("mylib/0.1") self.requires("protobuf/3.21.9", override=True) -The ```` defined upstream is ensuring that the host and build context are using the same version of that requirement. +The ```` defined upstream is ensuring that the host and build contexts are using the same version of that requirement. test_requires