diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md new file mode 100644 index 0000000..6bf995e --- /dev/null +++ b/RFCs/0000-global-defines.md @@ -0,0 +1,94 @@ +# Restore the possibility of using global defines across a project + +## Overview + +This RFC proposes a simple and generic change in the arduino-cli tool (used by arduino-ide) to give to a sketch the ability to properly configure its environment (the libraries): the ability to define global macros (which is the `-DMACRO=value` compiler option seen in almost every makefile). + +## Problem + +A long-term issue with the Arduino environment has been the inability for the user to declare macros for them to be available across all source files (sketch, libraries, not the core). + +Both users and library maintainers are restrained in their action because of the lack of globally configurable macro definitions, on which C/C++ historically rely on, but which is not possible from the user point of view in this environment from the beginning. + +As a consequence, + +- A user needs to manually edit a library and change the default definitions. +- A library maintainer who is willing to provide the ability to change the defaults must provide a runtime API (vs compile-time defines) for configuration. Such API can be space consuming and can be a real issue with small targets. Also noting that nowadays modern c++ code tend to use more and more of template and constexpr which are also a compiler way of implementing preprocessor defines (the reason in this case is performance). +- Many attempts were proposed during the past 9 years (see appendix) + +Also note that Arduino's `build*extra_flags=` is an installation-wide configuration [barely accessible](https://arduino.github.io/arduino-cli/0.19/platform-specification/#platformlocaltxt) to the average user. + +## Constraints + +It is not advised to expect already existing libraries to adapt themselves to a new feature. However, some of them are already providing support for overrides: + +```cpp +#ifndef BUFFER_SIZE +#define BUFFER_SIZE 128 +#endif +``` + +Such overrides are usable with other integration environments, or when using `arduino-cli` from command-line and scripts. Arduino-IDE currently has no mean to achieve such definition globally and this RFC aims at helping with this situation. + +## Recommended Solution + +- `sketch_globals.h` next to `sketch.ino` + +## Solutions + +### 1) "arduifine" + +A [closed pull request](https://github.com/arduino/arduino-cli/pull/1117) providing a POC has received no answer for almost a year. + +#### Strengths + +- Providing an answer to the described issue +- Requiring no further parsing of source code +- Requiring no change from libraries supporting overrides +- Answering to requests such as the one listed in https://github.com/arduino/Arduino/issues/421#issuecomment-327003003 + +#### Weaknesses + +- Proof of concept +- `const char* ARDUIFINE_blah = "-DMACRO=value"` is not really the way. The goal was to have a discussion. + +### 2) "libdefs": a way for user to configure libraries + +It is another [closed pull request](https://github.com/arduino/arduino-cli/pull/1517) inspired by https://github.com/arduino-libraries/ArduinoBearSSL/pull/45. + +#### Strengths + +- Using standard C/C++ way of defining macro + +#### Weaknesses + +- Requiring changes in libraries as pointed by @ubidefeo in https://github.com/arduino/arduino-cli/pull/1517#issuecomment-946634476 + +### 3) `sketch_globals.h` next to `sketch.ino` + +An [on-going pull-request](https://github.com/arduino/arduino-cli/pull/1524) implements this proposal. It allows the automatic inclusion of "`_global.h`" file _from sketch and libraries_ but not core files. + +#### Strengths + +- IDE friendly: user needs to open a new file with a clearly defined and hopefully unique name in the sketch directory +- Self contained: A source file which can be released as part of a user project +- Compatible with libraries supporting overrides + +#### Weaknesses + +- Can be seen as competing with [RFC-0003-build-profiles](https://github.com/arduino/tooling-rfcs/blob/main/RFCs/0003-build-profiles.md). + But it is not, it rather should be seen as complementary. Average arduino users may be familiar more with `#define BUFFER_SIZE 128` than with the proposed yaml file which is, beside allowing global defines, and if I understand, mainly aimed at project releasers providing nightly builds across multiple architectures. + +### 4) Other proposals + +See appendix for a list of still ongoing pull request. + +## Appendix + +- List of other attempts + - many requests and proposals in 9yo https://github.com/arduino/Arduino/issues/421 + - https://github.com/arduino/Arduino/pull/1808#issuecomment-103507284 closed claiming for richer APIs in libraries instead of global defines + - Still opened PR from https://github.com/arduino/arduino-cli/issues/846 \'s OP compiled by @per1234 + (there are quite a number of closed attempts clearly showing the lack of something) + - https://github.com/arduino/arduino-builder/pull/29 + - https://github.com/arduino/arduino-builder/pull/282