I have a few duplicate libraries. Arduino-builder chooses among these libraries and sometimes the choice is seemingly counter-intuitive.
And so I have been puzzling over the library priorities exercised by arduino-builder, where there are duplicate libraries.
What are the rules?
I naively assumed that this was determined by the order of the -libraries flag, with the last specified library having precedence.
But no, this is not so. It is more complicated than that, as explained by issue #574 (https://github.com/arduino/arduino-cli/pull/574).
I am excerpting these rules below because I think they can be useful to many people. Over and above these rules, I wish that I could specify an overriding priority without resorting to the "#include" syntax.
And so I have been puzzling over the library priorities exercised by arduino-builder, where there are duplicate libraries.
What are the rules?
I naively assumed that this was determined by the order of the -libraries flag, with the last specified library having precedence.
But no, this is not so. It is more complicated than that, as explained by issue #574 (https://github.com/arduino/arduino-cli/pull/574).
I am excerpting these rules below because I think they can be useful to many people. Over and above these rules, I wish that I could specify an overriding priority without resorting to the "#include" syntax.
Code:
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:
A library that is architecture compatibile wins against a library that is not architecture compatible
A library that has better "name priority" wins (see below for details)
A library that is architecture optimized wins against a library that is vanilla
A library that has a better "location priority" wins (see below for details)
A library that has a name with a better score using "closest-match" algorithm wins
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