Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use optimal bundled library name #8088

Merged
merged 1 commit into from
May 31, 2021
Merged

Use optimal bundled library name #8088

merged 1 commit into from
May 31, 2021

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented May 30, 2021

When multiple libraries contain files matching an #include directive in the program, the Arduino build system must pick one to use for compilation. Multiple factors are used in order to make an intelligent determination of which library is best, as documented here.

In order to enhance this determination, the closeness of match between the library.properties name value and the filename in the #include directive is being added as one of those factors. This new factor is referred to as "Library Name Priority". This change has been made in Arduino CLI (though not yet released): arduino/arduino-cli#1300. It will propagate from there to the classic Arduino IDE, Arduino IDE 2.x, and Arduino Web Editor after the next release of Arduino CLI.

Unfortunately, this change can result in platform bundled libraries which had previously been correctly correctly chosen
no longer being given priority over their equivalent standalone libraries, which may be incompatible or not optimized for the platform's boards.

This priority inversion only occurs when all the following conditions are true:

  • There is a standalone library installed which provides a header filename collision.
  • The platform bundled library is architecture optimized (e.g., architectures=esp32).
  • The standalone library is architecture compatible (architectures=*).
  • The standalone library has equal "Folder Name Priority".
  • The standalone library has better "Library Name Priority" (e.g., name=SD vs name=SD(ESP32) for a library with primary header file SD.h.

The fix is to simply give the platform bundled library a perfect "Library Name Priority", as provided by the change in this PR.

Some platform bundled libraries were given a modified name as a workaround to a bug in the Arduino IDE's Library Manager which caused Library Manager to always show the library as updatable under specific circumstances. That bug was fixed in Arduino IDE 1.8.6, ~3 years ago.

For more information or discussion regarding this change, please see arduino/arduino-cli#1292

When multiple libraries contain files matching an #include directive in the program, the Arduino build system must pick
one to use for compilation. Multiple factors are used in order to make an intelligent determination of which library is
best.

In order to enhance this determination, the closeness of match between the library.properties name value and the
filename in the #include directive is being added as one of those factors. This new factor is referred to as
"Library Name Priority".

Unfortunately, this change can result in platform bundled libraries which had previously been correctly correctly chosen
no longer being given priority over their equivalent standalone libraries, which may be incompatible or not optimized
for the platform's boards.

This priority inversion only occurs when all the following conditions are true:

- There is a standalone library installed which provides a header filename collision.
- The platform bundled library is architecture optimized (e.g., architectures=esp32).
- The standalone library is architecture compatible (architectures=*).
- The standalone library has equal "Folder Name Priority".
- The standalone library has better "Library Name Priority" (e.g., name=SD vs name=SD(ESP32) for a library with primary
  header file SD.h.

The fix is to simply give the platform bundled library a perfect "Library Name Priority".

Some platform bundled libraries were given a modified name as a workaround to a bug in the Arduino IDE's Library Manager
which caused Library Manager to always show the library as updatable under specific circumstances. That bug was fixed in
Arduino IDE 1.8.6, ~3 years ago.
@earlephilhower earlephilhower merged commit e21ae06 into esp8266:master May 31, 2021
@d-a-v
Copy link
Collaborator

d-a-v commented Jun 3, 2021

@per1234 you are suggesting in arduino/arduino-cli#1292 (comment) that Servo should receive the same change.
Then probably LittleFS too.

Should we proceed to these changes right now ?

edit: done in #8098

@per1234
Copy link
Contributor Author

per1234 commented Jun 3, 2021

There is no urgent requirement that I'm aware of to bring those library names into compliance with the specification. My investigation indicated that they are not affected by arduino/arduino-cli#1292.

In the case of the Servo library, the standalone version provides an explicit list of compatible architectures:
https://github.com/arduino-libraries/Servo/blob/master/library.properties#L9

architectures=avr,megaavr,sam,samd,nrf52,stm32f4,mbed,mbed_nano,mbed_portenta,mbed_rp2040

Since esp8266 is not on that list, and the platform bundled Servo library does list compatibility:
https://github.com/esp8266/Arduino/blob/master/libraries/Servo/library.properties#L9
the platform bundled version wins on the first library priority factor:
https://arduino.github.io/arduino-cli/dev/sketch-build-process/#dependency-resolution

A library that is architecture compatible wins against a library that is not architecture compatible (see Architecture Matching)

So even with the current library name/#include filename mismatch, the correct Servo library will still always be chosen.

However, there is no guarantee of continued support for non-compliant bundled library names. So I do think it is safest to bring them into compliance with an eye on the future.

If you're still concerned about people using >3 year outdated versions of the Arduino IDE being affected by arduino/Arduino#4189, you can change the library names to something that is still unique from the Library Manager library names, but in a specification compliant manner. Something like:

name=Servo-ESP8266

That works just as well for the arduino/Arduino#4189 workaround. The parentheses were in no way required, but only a dumb idea I had at the time.

In the case of LittleFS, it is not even susceptible to arduino/Arduino#4189 because there is no library in the Library Manager index with that name.

@d-a-v
Copy link
Collaborator

d-a-v commented Jun 3, 2021

Thanks once again for the very detailed explanation.
Because SD will not be compatible with old&affected arduino IDE version, let's keep it simple and remove (esp8266) from both Servo and LittleFS to keep coherency.

d-a-v added a commit to d-a-v/Arduino that referenced this pull request Jun 3, 2021
d-a-v added a commit that referenced this pull request Jun 3, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants