documentation missing: clear overview for identification of boards: supersets, subsets, and single boards

[dsyleixa]

a documentation feat. a clear hierarchical overview for identification of boards (supersets, sets, subsets, and single boards) would be appreciated, to be identified via #ifdef,
because often definitions found and discussed in several forum threads are vague or ambiguous which optional #ifdef includes which different and/or single other ones and which not.
e.g.

superset 8bit boards

• set AVR
• • • single boards: Uno, Nano, Leonardo, Mega,,...

superset 32bit boards

• set SAMD

• • subset M0 SAMD21
• • • single boards: m0, zero, nano33, RP2040 ,...
• • subset M4 SAMD51
• • • single boards: Portenta H7 (?), Adafruit GrandCentral, Teensy 3.x (?)

• set ARM Cortex (non-SAMD)

• • subset SAM3X
• • • single board: M3 SAM3X8E Due
• • subset ARM Cortex M7 (?)
• • • single boards: Portenta H7, Teensy 4.x (?)

• set ESP

• • • single board: ESP8266
• • • single board: ESP32

(probably to be reworked and continued)

[dsyleixa]

where is the problem about a resasonable list of those preprocessor board type makros?

[per1234]

There are two common conventions for identification macros provided by Arduino boards platforms:

• The architecture identification macro (ARDUINO_ARCH_<architecture name>), which is mentioned here: https://arduino.github.io/arduino-cli/latest/library-specification/#working-with-multiple-architectures
• The board identification macro, which is mentioned here: https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt

The tricky thing is that these, and any other identification macros are created at the discretion of the toolchain or boards platform authors. And once you go beyond those two macros, there is no standardization or even common convention whatsoever. So it is not possible to create definitive documentation of such macros that would apply universally to all Arduino boards platforms. It would be possible to provide documentation that covers the official Arduino boards platforms, but your request goes significantly beyond that.

The current approach is generally that the conventions for which resources an Arduino boards platform is expected to provide are established implicitly by the official boards platforms and perhaps the 3rd party platforms will use them as a model and follow suit.

The correct approach in my opinion is to provide clear technical documentation of which standardized resources an Arduino boards platform is expected to provide. We currently have comprehensive technical documentation about what is required by the Arduino development software in the Arduino Platform Specification. However, with perhaps a few exceptions like the board definition macro, nothing about the additional resources which are expected, but not mandated by the software.

There is a request for technical documentation of expected standard identification macros here: arduino/arduino-cli#988 and a related one here: arduino/arduino-cli#1030. I have been treating arduino/arduino-cli#985 as somewhat of an umbrella issue for that type of request.

That is about technical documentation targeted to platform developers. My impression is that your request is for documentation targeted to sketch or library developers. But my feeling is that the creation and value of such content is benefited greatly by having a foundation of formal documentation to build on top of, rather than solely observations of conventions.

[dsyleixa]

thanks, I know both links you mentioned at the top of your post.
Nonetheless, the "arch" architecture does not distinguish between e.g. SAMD vs. SAM3X vs. ARM Cortex M7 boards and it not even states if all these are even subsets of ARDUINO_ARCH_SAM. It also doesn't mention ESP board types either.
The 2nd link of yours doesn't provide a systematical overview list at all.
OTOH, it must be a way to distinguish between e.g. SAMD (SAMD51) vs. SAM3X or arbitrarily or optionally target all at once because many libs (e.g. for dtostrf, BUFFER_LENGTH definitions and more) run either on a AVR or a Due but don't on a SAMD51 or on a ESP32 or vice versa.
Also it's ambiguous and confusing about the sorting and clear demarcation of e.g., __AVR__, __arm__, ARDUINO_SAMD_VARIANT_COMPLIANCE, __ESP32__, __ESP8266__ (which is the makro for both ESPs in one?), __XTENSA__ ....
So a hierarchical overview would be still needed.