Codecov Report

Base: 36.56% // Head: 36.66% // Increases project coverage by +0.10% 🎉

Coverage data is based on head (27a8394) compared to base (4b70e02).
Patch coverage: 100.00% of modified lines in pull request are covered.

@@            Coverage Diff             @@
##           master    #1887      +/-   ##
==========================================
+ Coverage   36.56%   36.66%   +0.10%     
==========================================
  Files         228      228              
  Lines       19376    19396      +20     
==========================================
+ Hits         7084     7111      +27     
+ Misses      11463    11455       -8     
- Partials      829      830       +1     

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

I still need to update documentation, I'll do that after validating the changes.

the tool provided by the board's package

Should this not be the boards platform (instead of the board's package)?
Is that the selected platform only or the selected platform and the referenced platform?
And if the selected platform and the referenced platform both have the tool (Which is possible but I have never seen it) which is selected?

in absence of it, the tool (from a 3rd party) with the greatest version according to semver

FYI
If I remember correctly I had a similar implementation in Sloeber one day and it caused lots of boards to fail build yet they build successfully in Arduino IDE.

Should this not be the boards platform (instead of the board's package)?

It's the same since the tools are defined at the package level (and referenced at platform level as toolsDependecies).
After re-reading the PR I see that my first explanation was a bit rushed... I made a much better explanation in the documentation changes: https://github.com/arduino/arduino-cli/pull/1887/files#diff-29b8b99faa5765ef9cc15dbe6010806716089af4475d8483766b02c237f33753R274-R288
here is the extract:

When the IDE needs a tool, it downloads the corresponding archive file and unpacks the content into a private folder
that can be referenced from platform.txt using one of the following properties:

• {runtime.tools.TOOLNAME-VERSION.path}
• {runtime.tools.TOOLNAME.path}

For example, to obtain the avr-gcc 4.8.1 folder we can use {runtime.tools.avr-gcc-4.8.1.path} or
{runtime.tools.avr-gcc.path}.

In general the same tool may be provided by different platforms (for example the Arduino AVR platform may provide an
arduino:avr-gcc and another 3rd party platform may provide their own 3rdparty:avr-gcc). The rules to disambiguate
are as follows:

• The property {runtime.tools.TOOLNAME.path} points, in order of priority, to:

1. the tool, version and packager specified via toolsDependencies in the package_index.json
2. the highest version of the tool provided by the packager of the current platform
3. the highest version of the tool provided by any other packager (in case of tie, the first packager in alphabetical
   order wins)

• The property {runtime.tools.TOOLNAME-VERSION.path} points, in order of priority, to:
  1. the tool and version provided by the packager of the current platform
  2. the tool and version provided by any other packager (in case of tie, the first packager in alphabetical order wins)

I should change the sentence:

In general the same tool may be provided by different platforms (for example the Arduino AVR platform may provide an
arduino:avr-gcc and another 3rd party platform may provide their own 3rdparty:avr-gcc). The rules to disambiguate
are as follows:

to

In general the same tool may be provided by different packagers (for example the Arduino packager may provide an
arduino:avr-gcc and another 3rd party platform may provide their own 3rdparty:avr-gcc). The rules to disambiguate
are as follows:

In practice the idea is that when the toolsDependencies is not defined or not available, we first try to select the tools from the same packager or, if not found, from another packager.

About the other question:

Is that the selected platform only or the selected platform and the referenced platform?

That is a really good point, I didn't consider the referenced platform, and I must add that in this PR.

And if the selected platform and the referenced platform both have the tool (Which is possible but I have never seen it) which is selected?

The selected platform of course.

Thanks for the feedback @jantje

I just tested git master and this also solves an issue I had with a git checkout of the stm32duino core that had been annoying for quite some time (but I could fix it by just retrying and it would randomly work or not work, so wasn't annoying enough to investigate ;-p). Thanks!

so wasn't annoying enough to investigate

We should increase the annoyance then :-)