Skip to content

Commit c45d227

Browse files
perseoGIAbrilRBS
perseoGI
and
AbrilRBS
authored
Added docs for conan lock upgrade command (#4001)
* Added docs for conan lock upgrade command * Apply suggestions from code review Co-authored-by: Abril Rincón Blanco <[email protected]> * Improve description * Info condensed * Update reference/commands/lock/upgrade.rst Co-authored-by: Abril Rincón Blanco <[email protected]> --------- Co-authored-by: Abril Rincón Blanco <[email protected]>
1 parent 7ed8b30 commit c45d227

File tree

2 files changed

+138
-1
lines changed

2 files changed

+138
-1
lines changed

‎reference/commands/lock.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@ In addition to these commands, most of the Conan commands that compute a graph,
1717
- :doc:`conan lock add <lock/add>`: Manually add items to a lockfile
1818
- :doc:`conan lock remove <lock/remove>`: Manually remove items from a lockfile
1919
- :doc:`conan lock create <lock/create>`: Evaluates a dependency graph and save a lockfile
20-
- :doc:`conan lock merge <lock/merge>`: Merge several existing lockfiles into one.
20+
- :doc:`conan lock merge <lock/merge>`: Merge several existing lockfiles into one
2121
- :doc:`conan lock update <lock/update>`: Manually update items from a lockfile
22+
- :doc:`conan lock update <lock/upgrade>`: (Experimental) Upgrade items from a lockfile
2223

2324

2425
.. autocommand::

‎reference/commands/lock/upgrade.rst

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
conan lock upgrade
2+
==================
3+
4+
.. include:: ../../../common/experimental_warning.inc
5+
6+
.. autocommand::
7+
:command: conan lock upgrade -h
8+
9+
10+
The ``conan lock upgrade`` command is able to upgrade ``requires``, ``build_requires``, ``python_requires`` or ``config_requires`` items from an existing lockfile.
11+
12+
For example, if we have the following ``conan.lock``:
13+
14+
.. code-block:: bash
15+
16+
$ cat conan.lock
17+
{
18+
"version": "0.5",
19+
"requires": [
20+
"package/1.0#b0546195fd5bf19a0e6742510fff8855%1740472377.653885"
21+
],
22+
"build_requires": [
23+
"cmake/1.0#85d927a4a067a531b1a9c7619522c015%1702683583.3411012",
24+
]
25+
}
26+
27+
28+
And these packages available in the cache:
29+
30+
.. code-block:: bash
31+
32+
$ conan list "*" --format=compact
33+
34+
Found 9 pkg/version recipes matching * in local cache
35+
Local Cache
36+
package/1.0
37+
package/1.9
38+
cmake/3.29.0
39+
cmake/3.30.5
40+
41+
42+
Using the ``conan lock upgrade`` command with the appropiate ``--update-**`` arguments:
43+
44+
.. code-block:: bash
45+
46+
$ conan lock upgrade --requires=package/[>=1.0 <2] --update-requires=package/[*]
47+
48+
Will result in the following ``conan.lock``:
49+
50+
.. code-block:: bash
51+
52+
$ cat conan.lock
53+
{
54+
"version": "0.5",
55+
"requires": [
56+
"package/1.9#b0546195fd5bf19a0e6742510fff8855%1740484122.108484"
57+
],
58+
"build_requires": [
59+
"cmake/3.29.0#85d927a4a067a531b1a9c7619522c015%1702683583.3411012",
60+
]
61+
}
62+
63+
The same can be done for ``build_requires`` and ``python_requires``.
64+
65+
66+
The command will upgrade existing locked references that match the same
67+
package name with versions that match the version ranges provided by required
68+
arguments.
69+
70+
71+
The ``conan lock upgrade`` command may also be able to upgrade ``requires``, ``build_requires``, ``python_requires`` from a conanfile.
72+
This use case enhances the functionality of version ranges.
73+
74+
Let's consider the following conanfile:
75+
76+
.. code-block:: python
77+
78+
from conan import ConanFile
79+
class HelloConan(ConanFile):
80+
requires = ("math/[>=1.0 <2]")
81+
tool_requires = "ninja/[>=1.0]"
82+
83+
.. code-block:: bash
84+
85+
$ conan list "*" --format=compact
86+
87+
Found 9 pkg/version recipes matching * in local cache
88+
Local Cache
89+
math/1.0
90+
math/2.0
91+
ninja/1.0
92+
ninja/1.1
93+
94+
Starting from the same environment and ``conan.lock`` file from previous example.
95+
Running the following command:
96+
97+
.. code-block:: bash
98+
99+
$ conan lock upgrade . --update-requires=math/1.0 --update-build-requires=ninja/[*]
100+
101+
Will result in the following ``conan.lock``:
102+
103+
.. code-block:: bash
104+
105+
{
106+
"version": "0.5",
107+
"requires": [
108+
"math/1.0#b0546195fd5bf19a0e6742510fff8855%1740488410.356828"
109+
],
110+
"build_requires": [
111+
"ninja/1.1#dc77a17d3e566df710241e3b1f380b8c%1740488410.371875"
112+
]
113+
}
114+
115+
``math`` package have not been updated due to the version range specified in
116+
the conanfile, but ``ninja`` has been updated to the latest version available
117+
in the cache.
118+
119+
If a dependency is updated and in the new revision, a transitive dependency is
120+
added, the ``lock upgrade`` command will reflect the new transitive dependency
121+
in the lockfile. E.g.
122+
123+
- ``liba/1.0`` depends on ``libb/1.0``
124+
- ``libb/1.0`` depends on ``libc/1.0``
125+
126+
If ``libb/2.0`` depends also on ``libd/1.0``:
127+
128+
.. code-block:: bash
129+
130+
$ conan lock upgrade --requires=libb/[>=2] --update-requires=libb/*
131+
132+
The resulting lockfile will contain both ``libc/1.0`` and ``libd/1.0``.
133+
134+
.. note::
135+
136+
Updating transitive dependencies is not supported yet. This is an experimental feature and it may change in the future.

0 commit comments

Comments
 (0)