search

arduino / docs-content

Arduino documentation (docs.arduino.cc)
https://docs.arduino.cc/
Creative Commons Attribution Share Alike 4.0 International
173 stars 387 forks source link

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

Open dsyleixa opened 3 years ago

dsyleixa commented 3 years ago

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

superset 32bit boards

(probably to be reworked and continued)

dsyleixa commented 3 years ago

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

per1234 commented 3 years ago

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

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: https://github.com/arduino/arduino-cli/issues/988 and a related one here: https://github.com/arduino/arduino-cli/issues/1030. I have been treating https://github.com/arduino/arduino-cli/issues/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 commented 3 years ago

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.