From 48ed79e9ab558742206dcd2cd2eb7877093fcae5 Mon Sep 17 00:00:00 2001
From: per1234 <accounts@perglass.com>
Date: Sun, 26 Jun 2022 21:20:15 -0700
Subject: [PATCH] [skip changelog] Document library dependency version
 constraints

Arduino libraries may specify dependencies on other libraries in their metadata. The Arduino Library Manager offers the
option to install these dependencies when the user installs the library.

By default, the latest version of the dependency is installed. However, libraries may be compatible or tested working
only with specific versions of a dependency. In this case, the library developer may wish to specify a particular
version or version range of the dependency.

Arduino CLI and the Arduino Library index system has had support for such dependency version constraints for the last
2.5 years, but it was never documented so has only been used by the few library developers who discovered it via other
means.

The dependencies version constraint system is hereby fully documented in the Arduino library specification. This will
allow meaningful benefit to finally come from the work done to add this valuable capability.
---
 docs/library-specification.md | 54 ++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/docs/library-specification.md b/docs/library-specification.md
index 034686d8d3b..d3d233c52b3 100644
--- a/docs/library-specification.md
+++ b/docs/library-specification.md
@@ -74,7 +74,9 @@ otherwise below, **all fields are required**. The available fields are:
   install the dependencies during installation of the library.
   [`arduino-cli lib install`](commands/arduino-cli_lib_install.md) will automatically install the dependencies. Since
   spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the
-  name without ambiguity for example:<br> `depends=Very long library name, Another library with long-name`
+  name without ambiguity for example:<br> `depends=Very long library name, Another library with long-name`<br>
+  [Version constraints](#version-constraints) for the dependency may be specified in parentheses after the name:<br>
+  `depends=ArduinoHttpClient (>=1.0.0)`
 - **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to
   `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as
   normal. Then instead of including all .o
@@ -117,6 +119,56 @@ includes=WebServer.h
 depends=ArduinoHttpClient
 ```
 
+#### Version constraints
+
+**(available from Arduino IDE 2.0.0-beta.3/Arduino CLI 0.7.0)**
+
+By default, the latest version of a dependency specified in the `depends` field of
+[`library.properties`](#libraryproperties-file-format) is installed along with the library. Specifying an exact version
+or range of versions is also supported.
+
+The following operators are available:
+
+<!-- code tags used below to reconcile mismatch between Prettier and Python-Markdown handling of pipe characters -->
+
+|                   |                               |
+| ----------------- | ----------------------------- |
+| `=`               | equal to                      |
+| `>`               | greater than                  |
+| `>=`              | greater than or equal to      |
+| `<`               | less than                     |
+| `<=`              | less than or equal to         |
+| `!`               | NOT [<sup>1</sup>](#not-note) |
+| `&&`              | AND                           |
+| <code>\|\|</code> | OR                            |
+| `(`, `)`          | constraint group              |
+
+<a id="not-note"></a> <sup>1</sup> Available from Arduino IDE 2.0.0-rc7/Arduino CLI 0.22.0
+
+##### Examples
+
+If the library "ArduinoHttpClient" has the following releases:
+
+- `0.1.0`
+- `1.0.0`
+- `2.0.0`
+- `2.1.0`
+
+The version of it installed as a dependency would be as follows:
+
+| `depends` field value                                           | Installs<br> version |
+| --------------------------------------------------------------- | -------------------- |
+| `ArduinoHttpClient`                                             | `2.1.0`              |
+| `ArduinoHttpClient (=1.0.0)`                                    | `1.0.0`              |
+| `ArduinoHttpClient (>1.0.0)`                                    | `2.1.0`              |
+| `ArduinoHttpClient (>=1.0.0)`                                   | `2.1.0`              |
+| `ArduinoHttpClient (<2.0.0)`                                    | `1.0.0`              |
+| `ArduinoHttpClient (<=2.0.0)`                                   | `2.0.0`              |
+| `ArduinoHttpClient (!=1.0.0)`                                   | `2.1.0`              |
+| `ArduinoHttpClient (>1.0.0 && <2.1.0)`                          | `2.0.0`              |
+| <code>ArduinoHttpClient (<1.0.0 \|\| >2.0.0)</code>             | `2.1.0`              |
+| <code>ArduinoHttpClient ((>0.1.0 && <2.0.0) \|\| >2.1.0)</code> | `1.0.0`              |
+
 ### Layout of folders and files
 
 Each folder has a specific purpose (sources, examples, documentation, etc). Folders not covered in this specification