Describe the request

Establish two sets of standard "extra flags" build properties:

• one set for use by platform developer
• one set for use by the user

These should be clearly documented as being dedicated to the exclusive use by either the platform developer or the user.

The properties proposed here are only arbitrary properties, without any special use by the build system, so no changes would required in the build system. It is only a matter of setting an example for 3rd party platform developers by adding these additional properties to the platform.txt files of the official platforms with comments clearly explaining their intent.

Ideally, the properties would be documented in the Arduino platform specification as well (#985).

Describe the current behavior

Arduino has established a convention of providing "extra flags" properties in platform.txt. These properties are intended to allow the compilation process to be customized by the addition of arbitrary flags in the compilation commands.

For example:

https://github.com/arduino/ArduinoCore-avr/blob/1.8.6/platform.txt#L39-L49

# This can be overridden in boards.txt
build.extra_flags=

# These can be overridden in platform.local.txt
compiler.c.extra_flags=
compiler.c.elf.extra_flags=
compiler.S.extra_flags=
compiler.cpp.extra_flags=
compiler.ar.extra_flags=
compiler.objcopy.eep.extra_flags=
compiler.elf2hex.extra_flags=

These properties are referenced in the appropriate compilation recipes in platform.txt (example).

The empty definitions in platform.txt ensure that if the extra flags are not defined elsewhere, the compilation recipes referencing them will still work. Those default empty definitions can be overrriden from any of the other platform configuration files:

• boards.txt
• boards.local.txt
• platform.local.txt
• global platform.txt

or from the command line:

• arduino-cli compile --build-property
• arduino --pref

From the comments in the official platform.txt files, it seems that build.extra_flags is intended to be for the use of the boards platform developer, while the other "extra flags" properties are intended to be for the use of the user (because a platform developer has no need for platform.local.txt).

A common use case of these properties for the user would be to add -D flags (e.g., #210 (comment), arduino/Arduino#6344), but there are other uses.

However, platform developers sometimes use these properties in their boards.txt file (example). This presents the problem that the user risks inadvertently overriding the flags defined by the boards platform if they use the "extra flags" properties to modify the compilation command (example).

Arduino CLI version

N/A

Operating system

All

Operating system version

Any

Additional context

Re: Possible Harmful Effect on APIs

On a certain level, this does provide the user the global macro setting capability that has been often requested, and often rejected:

• Include global UserSettings.h file arduino-builder#15
• Adding support for sketch-specific build properties arduino-builder#29
• Read additional BuildProperties from optional ./platform.sketch.txt file arduino-builder#282
• A further generalized idea of modifying UserSettings.txt sketch-wide arduino-builder#283
• Include sketch directory to include search path  arduino-builder#354
• Please add a way to include project wide #defines within the IDE arduino-ide#1837
• Ability to specify additional compiler flags [imported] Arduino#421
• Library file dependent on sketch file not compiling in Arduino IDE Arduino#2547
• Add sketch path to the compile include path Arduino#3635
• Issue #3635 Added the sketch folder to the path Arduino#3717
• Include sketchbook folder and LibrarySettings.h Arduino#3757
• Feature Request - ability to append to build.extra_flags from within main sketch file. Arduino#4528
• Generate global macros according to contents of specially named header file in sketch Arduino#5084
• Add current sketch dir to include path when compile library Arduino#5390
• Provide advanced compilation features Arduino#7189
• Possibility to specify compilation flags to arduino-builder from the IDE Arduino#11108
• Using -D cppflags possible? #159
• Build flags set in my boards.txt file not used in the compilation command #210
• ARDUIFINE: global compiler options extracted from ctags parsing #1117
• libdefs: a way for user to configure libraries #1517
• Use of defines in reproducible builds tooling-rfcs#9
• Source/Header file edits for build profiles. tooling-rfcs#22

However, I think this proposal strikes the right balance of:

• Allowing advanced users to do advanced things
• Not exposing standard users to additional complexity that makes the Arduino development software less beginner friendly
• Being very easy for Arduino to implement

The concern has been that allowing users to set global macros will result in library developers unnecessarily using these as part of the API, making that API less beginner friendly (arduino/arduino-builder#15 (comment)). However, if the user is required to use a command line interface or create a specially formatted configuration file in a difficult to access location, the average user won't be interested, and so it will only make sense for a library developer to use this feature for advanced, rarely used features of the library (e.g., enable debug output for troubleshooting of the library). We have already had this "extra flags" capability since 2014, yet I haven't seen it result in any significant incorporation of user set global macros into the user-level API of Arduino libraries.

Additional requests

• Provide dedicated sets of "extra flags" properties for platform developers and users #846 (comment)
• https://forum.arduino.cc/t/using-build-property-to-set-optimize-and-define-symbols/1254465
• https://forum.arduino.cc/t/compiler-option-defines-overriding-esp32-and-not-compiling/990862
• https://forum.arduino.cc/t/how-to-add-compile-options-to-arduino-ide-1-8-13/692640/3
• https://forum.arduino.cc/t/ide-to-command-line-build-support-d/682481/3
• https://forum.arduino.cc/t/what-could-prevent-platform-local-txt-from-being-read/674998

Related

• esp32-c3 linker errors, project works fine on windows #2706
• Please correct the order in which the compiler flags are compiled? espressif/arduino-esp32#11087

Issue checklist

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