pert
January 23, 2021, 8:09am
2
To affect all boards, you can add this property to the global platform.txt:https://arduino.github.io/arduino-cli/latest/platform-specification/#global-platformtxt
A couple things to note though:
build.extra_flags property is intended for use by the platform developer. What this means is that you may end up overriding important flags with your custom definition. Here's an example:
leonardo.build.extra_flags={build.usb_flags}
and the definition of build.usb_flags here:
tools.avrdude.bootloader.pattern="{cmd.path}" "-C{config.path}" {bootloader.verbose} -p{build.mcu} -c{protocol} {program.extra_params} "-Uflash:w:{runtime.platform.path}/bootloaders/{bootloader.file}:i" -Ulock:w:{bootloader.lock_bits}:m
tools.avrdude_remote.upload.pattern=/usr/bin/run-avrdude /tmp/sketch.hex {upload.verbose} -p{build.mcu}
tools.avrdude.upload.network_pattern="{network_cmd}" -address {serial.port} -port {upload.network.port} -sketch "{build.path}/{build.project_name}.hex" -upload {upload.network.endpoint_upload} -sync {upload.network.endpoint_sync} -reset {upload.network.endpoint_reset} -sync_exp {upload.network.sync_return}
# USB Default Flags
# Default blank usb manufacturer will be filled in at compile time
# - from numeric vendor ID, set to Unknown otherwise
build.usb_manufacturer="Unknown"
build.usb_flags=-DUSB_VID={build.vid} -DUSB_PID={build.pid} '-DUSB_MANUFACTURER={build.usb_manufacturer}' '-DUSB_PRODUCT={build.usb_product}'
build.usb_flags=-DUSB_VID={build.vid} -DUSB_PID={build.pid} '-DUSB_MANUFACTURER={build.usb_manufacturer}' '-DUSB_PRODUCT={build.usb_product}'
So use build.extra_flags cautiously.
From reading the comments in the official platform level platform.txt files:
# 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=
it seems that the compiler.x.extra_flags properties are intended for use by the user (because platform developers have no need for platform.local.txt). So you are better off to use those properties. Unfortunately, some platform developers have unnecessarily used these properties as well. For example:
but it's at least less common than build.extra_flags.
There is some interesting discussion on how this situation might be improved here:
opened 03:04PM - 20 Jul 20 UTC
type: enhancement
topic: documentation
criticality: high
topic: build-process
### Describe the request
Establish two sets of standard "extra flags" build p… roperties:
- 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](https://arduino.github.io/arduino-cli/latest/platform-specification/) as well (https://github.com/arduino/arduino-cli/issues/985).
### Describe the current behavior
Arduino has established a convention of providing "extra flags" properties in [`platform.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#platformtxt). 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
```text
# 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](https://github.com/arduino/ArduinoCore-avr/blob/1.8.6/platform.txt#L58)).
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`](https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt)
- [`boards.local.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#boardslocaltxt)
- [`platform.local.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#platformlocaltxt)
- [`global platform.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#global-platformtxt)
or from the command line:
- [`arduino-cli compile --build-property`](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_compile/#options)
- [`arduino --pref`](https://github.com/arduino/Arduino/blob/master/build/shared/manpage.adoc#options)
---
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., https://github.com/arduino/arduino-cli/issues/210#issuecomment-493892258, https://github.com/arduino/Arduino/issues/6344), but there are other uses.
However, platform developers sometimes use these properties in their `boards.txt` file ([example](https://github.com/MCUdude/MightyCore/blob/v2.0.5/avr/boards.txt#L103-L111)). 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](https://github.com/arduino/arduino-cli/issues/2041)).
### 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:
- https://github.com/arduino/arduino-builder/issues/15
- https://github.com/arduino/arduino-builder/pull/29
- https://github.com/arduino/arduino-builder/pull/282
- https://github.com/arduino/arduino-builder/issues/283
- https://github.com/arduino/arduino-builder/issues/354
- https://github.com/arduino/arduino-ide/issues/1837
- https://github.com/arduino/Arduino/issues/421
- https://github.com/arduino/Arduino/issues/2547
- https://github.com/arduino/Arduino/issues/3635
- https://github.com/arduino/Arduino/pull/3717
- https://github.com/arduino/Arduino/pull/3757
- https://github.com/arduino/Arduino/issues/4528
- https://github.com/arduino/Arduino/issues/5084
- https://github.com/arduino/Arduino/issues/5390
- https://github.com/arduino/Arduino/issues/7189
- https://github.com/arduino/Arduino/issues/11108
- https://github.com/arduino/arduino-cli/issues/159
- https://github.com/arduino/arduino-cli/issues/210
- https://github.com/arduino/arduino-cli/pull/1117
- https://github.com/arduino/arduino-cli/pull/1517
- https://github.com/arduino/tooling-rfcs/issues/9
- https://github.com/arduino/tooling-rfcs/issues/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 (https://github.com/arduino/arduino-builder/issues/15#issuecomment-145558252). 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](https://github.com/arduino/ArduinoCore-avr/commit/2b9f022eaad0d107b1516c22ac02bdac4977223b), yet I haven't seen it result in any significant incorporation of user set global macros into the user-level API of Arduino libraries.
### Issue checklist
- [X] I searched for previous requests in [the issue tracker](https://github.com/arduino/arduino-cli/issues?q=)
- [X] I verified the feature was still missing when using the latest [nightly build](https://arduino.github.io/arduino-cli/dev/installation/#nightly-builds)
- [X] My request contains all necessary details
1 Like