Fix libraries priority selection (again)

[cmaglie]

This PR changes again the lib priority selection to improve backward compatibility. Now the algorithm should be (hopefully) 100% compatible with legacy algorithm used in the arduino-builder.

The priority is determined by applying the following rules, one by one in this order, until a rule determine a winner:

1. A library that is architecture compatibile wins against a library that is not architecture compatible
2. A library that has better "name priority" wins (see below for details)
3. A library that is architecture optimized wins against a library that is vanilla
4. A library that has a better "location priority" wins (see below for details)
5. A library that has a name with a better score using "closest-match" algorithm wins
6. A library that has a name that comes first in alphanumeric order wins

Usually the first four rules are enough, the rule 5 is rarely applied and the rule 6 is even more rare. Anyway they are there to not leave the selection process undefined even in those extreme cases.

@per1234 could you check if this solves #572?
I think that this issue alone calls for another release of the Arduino IDE.

---

Details about rules:

A library is considered compatible with architecture X if the architecture field in library.properties:

• contains explicitly the architecure X
• contains the catch-all *
• is not specified at all.
  (see table below for an example)

A library is considered optimized for architecture X only if the architecture field in library.properties contains explicitly the architecure X.

architecture field in library.properties	Compatible with avr	Optimized for avr
not specified	YES	NO
architectures=*	YES	NO
architectures=avr	YES	YES
architectures=*,avr	YES	YES
architectures=*,esp8266	YES	NO
architectures=avr,esp8266	YES	YES
architectures=samd	NO	NO

The "name priority" is determined as follows (higher is better):

Priority	Rule	Example for Servo.h
5	The name match the include 100%	Servo
4	The name match the include 100% with a -master suffix	Servo-master
3	The name has a matching prefix	ServoWhatever
2	The name has a matching suffix	AwesomeServo
1	The name contains the include	AnAwesomeServoForWhatever

The "location priority" is determined as follows (higher is better):

Priority	Rule
4	The library is in the sketchbook
3	The library is bundled in the board platform/core
2	The library is bundled in the referenced board platform/core
1	The library is bundled in the IDE

[per1234]

I confirm this does fix #572 for me. Thanks!

Excellent documentation! Should we publish this information to a more "official" location? I think https://github.com/arduino/Arduino/wiki/Build-Process would be the most appropriate location in our existing documentation.

Regarding the IDE release, I like the idea of moving quickly to resolve serious bugs, though I know the release verification process is a lot of work for you. Some other bugs that would be nice to get resolved before the release:

• "Add .ZIP Library" freezes Microsoft Store version of the Arduino IDE Arduino#9710
• And another Library Manager and Board Manager issue with "package_index.json" Arduino#8474 (comment) (I can reproduce that, and will submit a dedicated issue today)
• IDE 1.8.11 slow on Pi3 B+ Arduino#9701 (may be related to And another Library Manager and Board Manager issue with "package_index.json" Arduino#8474 (comment))

[cmaglie]

Excellent documentation!

Thanks! After rereading it this morning it really looks like a draft-I-quickly-written-just-after-fixing-the-issue. It surely need some rewording with a better idiomatic english :-)

Anyway it's nice to see how nice and linear the algorithm turned out to be after straightening and refactoring the legacy code.

Should we publish this information to a more "official" location? I think https://github.com/arduino/Arduino/wiki/Build-Process would be the most appropriate location in our existing documentation.

Sure, can you take care of it?

[per1234]

I have added the library priorities documentation to the Build Process wiki page:
https://github.com/arduino/Arduino/wiki/Build-Process/_compare/bbff14b72ab76c35b0e40de31853a9e027511269...5046ffe2a448f259bff6315896e054089e921f74

In addition to some minor rewording and fixing of typos, I made the following additions/changes:

• Expanded it to be a high level overview of the dependency resolution process
• Changed "name" to "folder name" to differentiate it from the library.properties name, which does not influence library selection priority
• Removed priority numbers from tables. I felt they did not add anything of value, and made the documentation appear slightly more complex than necessary.
• More specifically defined locations

I'm happy to make corrections or improvements if anyone has feedback for me (and, of course, feel free to edit the wiki directly).