Skip to content

Commit

Permalink
Docs for replace_requires, replace_tool_requires, platform_requires a…
Browse files Browse the repository at this point in the history 
…nd platform_tool_requires profile sections (#3495)

* Docs for replace_requires and replace_tool_requires profile sections

* add platform_requires and platform_tool_requires

* add experimental

* some clarifications and examples

* add best practices section

* Update reference/config_files/profiles.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

* Update reference/config_files/profiles.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

* Update reference/config_files/profiles.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

---------

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>
  • Loading branch information
@danimtb @czoido
danimtb and czoido authored Dec 19, 2023
1 parent ab45a38 commit 6376205
Showing 1 changed file with 181 additions and 121 deletions.
302 changes: 181 additions & 121 deletions reference/config_files/profiles.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,30 @@ They have this structure:
[options]
MyLib:shared=True
[buildenv]
VAR1=value
[tool_requires]
tool1/0.1@user/channel
*: tool4/0.1@user/channel
[buildenv]
VAR1=value
[runenv]
EnvironmentVar1=My Value
[conf]
tools.build:jobs=2
[replace_requires]
zlib/1.2.123: zlib/*
[replace_tool_requires]
7zip/*: 7zip/system
[platform_requires]
dlib/1.3.22
[platform_tool_requires]
cmake/3.24.2
Profiles can be created with the ``detect`` option in :ref:`conan profile <reference_commands_profile>` command,
and edited later. If you don't specify a *name*, the command will create the ``default`` profile:
Expand Down Expand Up @@ -182,7 +196,7 @@ List of settings available from :ref:`reference_config_files_settings_yml`:
[options]
++++++++++
+++++++++

List of options available from your recipe and its dependencies:

Expand Down Expand Up @@ -214,117 +228,12 @@ List of ``tool_requires`` required by your recipe or its dependencies:

.. _reference_config_files_profiles_system_tools:

[system_tools]
+++++++++++++++

.. include:: ../../common/experimental_warning.inc

This section is similar to the previous one, **[tool_requires]**, but it's intended to list only the tool requires
that are already in your own system and you don't want Conan to search for, neither remotely nor locally.

For instance, you have already installed ``cmake==3.24.2`` in your system:

.. code-block:: bash
$ cmake --version
cmake version 3.24.2
CMake suite maintained and supported by Kitware (kitware.com/cmake).
Now, you have in your recipe (or the transitive dependencies) declared a **tool_requires**, i.e., something like this:

.. code-block:: python
:caption: **conanfile.py**
from conan import ConanFile
class PkgConan(ConanFile):
name = "pkg"
version = "2.0"
# ....
# Exact version
def build_requirements(self):
self.tool_requires("cmake/3.24.2")
# Or even version ranges
def build_requirements(self):
self.tool_requires("cmake/[>=3.20.0]")
Given this situation, it could make sense to want to use your already installed CMake version, so it's enough to declare
it as a ``system_tools`` in your profile (``default`` one or any other in use):

.. code-block:: text
:caption: *myprofile*
...
[system_tools]
cmake/3.24.2
Whenever you want to create the package, you'll see that build requirement is already satisfied because of the system tool
declaration:

.. code-block:: bash
:emphasize-lines: 9,18
$ conan create . -pr myprofile --build=missing
...
-------- Computing dependency graph --------
Graph root
virtual
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767 - Cache
Build requirements
cmake/3.24.2 - System tool
-------- Computing necessary packages --------
-------- Computing necessary packages --------
pkg/2.0: Forced build from source
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767:20496b332552131b67fb99bf425f95f64d0d0818 - Build
Build requirements
cmake/3.24.2 - System tool
Notice that if the ``system_tools`` declared does not make a strict match with the ``tool_requires`` one (version or
version range), then Conan will try to bring them remotely or locally as usual. Given the previous example, changing the
profile as follows:

.. code-block:: text
:caption: *myprofile*
...
[system_tools] (DEPRECATED)
+++++++++++++++++++++++++++

[system_tools]
cmake/3.20.0
The result will be different when calling the :command:`conan create`, because Conan will download remotely and build
from source if necessary:

.. code-block:: bash
:emphasize-lines: 9,18
$ conan create . -pr myprofile --build=missing
...
-------- Computing dependency graph --------
Graph root
virtual
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767 - Cache
Build requirements
cmake/3.24.2#e35bc44b3fcbcd661e0af0dc5b5b1ad4 - Downloaded (conancenter)
-------- Computing necessary packages --------
.. note::

-------- Computing necessary packages --------
pkg/2.0: Forced build from source
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767:20496b332552131b67fb99bf425f95f64d0d0818 - Build
Build requirements
cmake/3.24.2#e35bc44b3fcbcd661e0af0dc5b5b1ad4:d0599452a426a161e02a297c6e0c5070f99b4909 - Build
This section is **deprecated** and has been replaced by :ref:`reference_config_files_profiles_platform_requires` and :ref:`reference_config_files_profiles_platform_tool_requires` sections.


.. _reference_config_files_profiles_buildenv:
Expand All @@ -346,7 +255,6 @@ Another essential point to mention is the possibility of defining variables as `
the prefix of the variable. It is useful to automatically get the append/prepend of the `PATH` in different systems
(Windows uses ``;`` as separation, and UNIX ``:``).


.. code-block:: text
:caption: *myprofile*
Expand Down Expand Up @@ -376,16 +284,14 @@ Then, the result of applying this profile is:
* ``mypkg*:PATH``: ``None``



.. _reference_config_files_profiles_runenv:

[runenv]
++++++++++
++++++++

List of environment variables that will be injected to the environment every time the ConanFile
``run(cmd, env="conanrun")`` method is invoked (runtime context is automatically run by :ref:`conan_tools_env_virtualrunenv`).


All the operators/patterns explained for :ref:`reference_config_files_profiles_buildenv` applies to this one in the same way:

.. code-block:: text
Expand All @@ -398,6 +304,7 @@ All the operators/patterns explained for :ref:`reference_config_files_profiles_b
MyPath1=+(path)/other path/path12
MyPath1=!
.. _reference_config_files_profiles_conf:

[conf]
Expand Down Expand Up @@ -425,20 +332,17 @@ Recall some hints about configuration scope and naming:
- ``core.xxx`` configuration can only be defined in ``global.conf`` file, but not in profiles
- ``tools.yyy`` and ``user.zzz`` can be defined in ``global.conf`` and they will affect both the "build" and the "host" context. But configurations defined in a profile ``[conf]`` will only affect the respective "build" or "host" context of the profile, not both.


They can also be used in :ref:`reference_config_files_global_conf`,
but **profiles values will have priority over globally defined ones in global.conf**, so let's see an example that is a bit more complex,
trying different configurations coming from the *global.conf* and another profile *myprofile*:


.. code-block:: text
:caption: *global.conf*
# Defining several lists
user.myconf.build:ldflags=["--flag1 value1"]
user.myconf.build:cflags=["--flag1 value1"]
.. code-block:: text
:caption: *myprofile*
Expand All @@ -455,7 +359,6 @@ trying different configurations coming from the *global.conf* and another profil
# Prepending values into the existing list
user.myconf.build:ldflags=+["--prefix prefix-value"]
Running, for instance, :command:`conan install . -pr myprofile`, the configuration output will be something like:

.. code-block:: bash
Expand All @@ -471,6 +374,163 @@ Running, for instance, :command:`conan install . -pr myprofile`, the configurati
...
.. _reference_config_files_profiles_replace_requires:

[replace_requires]
++++++++++++++++++

.. include:: ../../common/experimental_warning.inc

This section allows the user to redefine requires of recipes. This can be useful when a package can be changed by a similar one like `zlib` and `zlibng`.
It is also useful to solve conflicts, or to replace some dependencies by system alternatives wrapped in another Conan package recipe.

References listed under this section work as a **literal replacement of requires in recipes**, and is done as the very first step before any other processing
of recipe requirements, without processing them or checking for conflicts.

As an example, we could define `zlibng` as a replacement for the typical `zlib`:abbr:

.. code-block:: text
:caption: *myprofile*
[replace_requires]
zlib/*: zlibng/*
Using the ``*`` pattern for the ``zlibng`` reference means that ``zlib`` will be replaced by the exact same version of ``zlibng``.

Other examples are:

.. code-block:: text
:caption: *myprofile*
[replace_requires]
dep/*: dep/1.1 # To override dep/[>=1.0 <2] in recipes to a specific version dep/1.1)
dep/*: dep/*@system # To override a dep/1.3 in recipes to dep/1.3@system
dep/*@*/*: dep/*@system/* # To override "dep/1.3@comp/stable" in recipes to the same version with other user but same channel
dep/1.1: dep/1.1@system # To replace exact reference in recipes by the same one in the system
dep/1.1@*: dep/1.1@*/stable # To replace dep/[>=1.0 <2]@comp version range in recipes by 1.1 version in stable chanel
.. note:: **Best practices**

- Please make rational use of this feature. It is not a versioning mechanism and is not intended to replace actual requires in recipes.
- The usage of this feature is intended for **temporarily** solving conflicts or replacing a specific dependency by a system one in some cross-build scenarios.


.. _reference_config_files_profiles_replace_tool_requires:

[replace_tool_requires]
+++++++++++++++++++++++

.. include:: ../../common/experimental_warning.inc

Same usage as the `replace_requires` section but in this case for `tool_requires`.

.. code-block:: text
:caption: *myprofile*
[replace_tool_requires]
cmake/*: cmake/3.25.2
In this case, whatever version of ``cmake`` declared in recipes, will be replaced by the reference `cmake/3.25.2`.


.. _reference_config_files_profiles_platform_requires:

[platform_requires]
+++++++++++++++++++

.. include:: ../../common/experimental_warning.inc

This section allows the user to redefine requires of recipes replacing them with platform-provided dependencies, this means that Conan will not try to download the
reference or look for it in the cache and will assume that it is installed in your system and ready to be used.

For example, if the zlib 1.2.11 library is already installed in your system or it is part of your build toolchain and you would like Conan to use it,
you could specify so as:

.. code-block:: text
:caption: *myprofile*
[platform_requires]
zlib/1.2.11
.. _reference_config_files_profiles_platform_tool_requires:

[platform_tool_requires]
++++++++++++++++++++++++

.. include:: ../../common/experimental_warning.inc

Same usage as the `platform_requires` section but in this case for `tool_requires` such as `cmake`, `meson`...

As an example, let's say you have already installed ``cmake==3.24.2`` in your system:

.. code-block:: bash
$ cmake --version
cmake version 3.24.2
CMake suite maintained and supported by Kitware (kitware.com/cmake).
And you have in your recipe (or the transitive dependencies) declared a **tool_requires**, i.e., something like this:

.. code-block:: python
:caption: **conanfile.py**
from conan import ConanFile
class PkgConan(ConanFile):
name = "pkg"
version = "2.0"
# ....
# Exact version
def build_requirements(self):
self.tool_requires("cmake/3.24.2")
# Or even version ranges
def build_requirements(self):
self.tool_requires("cmake/[>=3.20.0]")
Given this situation, it could make sense to want to use your already installed CMake version, so it's enough to declare
it as a ``platform_tool_requires`` in your profile:

.. code-block:: text
:caption: *myprofile*
...
[platform_tool_requires]
cmake/3.24.2
Whenever you want to create the package, you'll see that build requirement is already satisfied because of the platform tool
declaration:

.. code-block:: bash
:emphasize-lines: 9,18
$ conan create . -pr myprofile --build=missing
...
-------- Computing dependency graph --------
Graph root
virtual
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767 - Cache
Build requirements
cmake/3.24.2 - Platform
-------- Computing necessary packages --------
-------- Computing necessary packages --------
pkg/2.0: Forced build from source
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767:20496b332552131b67fb99bf425f95f64d0d0818 - Build
Build requirements
cmake/3.24.2 - Platform
Note that if the ``platform_tool_requires`` declared **does not make a strict match** with the ``tool_requires`` one (version or
version range), then Conan will try to bring them remotely or locally as usual.


.. _reference_config_files_profiles_rendering:

Profile rendering
Expand Down

0 comments on commit 6376205

Please sign in to comment.