Add libraries super compatibility and explicit incompatibility in the spec

[umbynos]

Describe the request

Add support for a field named supported in the library.properties library metadata file. This field is a comma-separated list of patterns to match against an FQBN.

This will allow library developers to define the supported boards for the library down to board-level granularity.

The result would be something like this in the library.properties file:

name=Camera
version=1.0
author=Arduino
maintainer=Arduino <[email protected]>
sentence=Camera library for Portenta H7 Vision Shield
paragraph=
category=Other
url=https://github.com/arduino/ArduinoCore-mbed/tree/master/libraries/Camera
architectures=mbed,!avr
supported=*:mbed:portenta,!*:*:nano33ble
#supported=mbed:portenta,!mbed:nano33ble <- without wildcards

This information could be used for applications such as:

• Accurately populate the "Compatibility" lists in the Arduino Library Reference (this would require also changing the libraries-repository-engine tool to include the information in the Library Manager index).
• Select the best library for the selected board during library discovery.
• Print a warning when compiling the library for an unsupported board.
• Disallow compilation of the library for boards that are explicitly specified as being unsupported.

Describe the current behavior

Library developers can only indicate compatibility at architecture-level granularity. A library may have dependencies on attributes that only present on a subset of boards of a given architecture.

This means it is not possible for tools to accurately determine whether a specific board is supported by a library.

For example, the "Keyboard" library specifies compatibility with the avr architecture:

https://github.com/arduino-libraries/Keyboard/blob/1.0.4/library.properties#L9

architectures=avr, samd, sam

However, not all AVR microcontrollers have the required native USB capability. This results in inaccurate information about the library's support for those boards.

The library is listed in lib list command output when the FQBN of an unsupported board (e.g., Uno) is specified via the --fqbn flag:

$ arduino-cli lib install Keyboard
Downloading [email protected]...
[email protected] [email protected] already downloaded
Installing [email protected]...
Installed [email protected]

$ arduino-cli lib list Keyboard --fqbn arduino:avr:uno
Name     Installed     Available         Location              Description
Keyboard 1.0.4         -                 LIBRARY_LOCATION_USER -

Unsupported boards are included in the automatically generated "Compatibility" list of the library's reference page:

https://www.arduino.cc/reference/en/libraries/keyboard/

Arduino CLI version

0.32.2

Operating system

N/A

Operating system version

N/A

Additional context

The newly added field should be ignored by versions of Arduino development tools that don't have support for the new field. If so, this change would not result in any backwards incompatibility of the libraries that use it.

---

Relevant code:

arduino-cli/arduino/libraries/libraries.go

Line 78 in 743c3e9

CompatibleWith map[string]bool

Related

• Library reference pages may list incompatible boards in the compatibility list Arduino#11871
• Portenta X8 examples: QSPIFBlockDevice not found ArduinoCore-mbed#529 (comment)
• Use accurate description for platform bundled library examples in menu arduino-ide#1304
• Arduino IoT Cloud Docs arduino-libraries/ArduinoIoTCloud#380 (comment)
• https://forum.arduino.cc/t/documentation-for-keyboard-library-needs-some-correction/1126221
• https://forum.arduino.cc/t/arduino-keyboard-not-working-on-arduino-uno-r3/1102400
• https://forum.arduino.cc/t/sketch-funktioniert-nicht-keyboard/1099364/6
• https://forum.arduino.cc/t/issue-on-keyboard-library/1065385
• https://forum.arduino.cc/t/what-is-wrong-here/1080550/7
• https://forum.arduino.cc/t/comments-on-arduino-1-5-specifications/162030/72 / https://forum.arduino.cc/t/comments-on-arduino-1-5-specifications/162030/83
• https://forum.arduino.cc/t/comments-on-arduino-1-5-specifications/162030/84

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the nightly build
• My request contains all necessary details

[umbynos]

Original reporter @facchinm