From ce3cb1bc0e0a3c245214f6790a15089630d3450e Mon Sep 17 00:00:00 2001 From: david gauchard Date: Wed, 20 Oct 2021 16:47:09 +0200 Subject: [PATCH 1/6] Proposal for a user-friendly way to define global macros --- RFCs/0000-global-defines.md | 95 +++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 RFCs/0000-global-defines.md diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md new file mode 100644 index 0000000..2f550aa --- /dev/null +++ b/RFCs/0000-global-defines.md @@ -0,0 +1,95 @@ +# Restore the possibility of using global defines accross 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 accross 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 attemps 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 accross multiple achitectures. + +### 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 + + From a38fcbaf52b4509d8ef15e2bc273687e9fdf6c08 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Wed, 20 Oct 2021 16:55:00 +0200 Subject: [PATCH 2/6] remove trailing spaces --- RFCs/0000-global-defines.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md index 2f550aa..36ad7a6 100644 --- a/RFCs/0000-global-defines.md +++ b/RFCs/0000-global-defines.md @@ -12,7 +12,7 @@ Both users and library maintainers are restrained in their action because of the 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). +- 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 attemps 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. @@ -91,5 +91,3 @@ See appendix for a list of still ongoing pull request. (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 - - From d09bb4677adf9aeda436c52e2b6d4f3ceb0d657c Mon Sep 17 00:00:00 2001 From: david gauchard Date: Wed, 20 Oct 2021 16:56:45 +0200 Subject: [PATCH 3/6] spelling --- RFCs/0000-global-defines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md index 36ad7a6..3bbfdf1 100644 --- a/RFCs/0000-global-defines.md +++ b/RFCs/0000-global-defines.md @@ -1,4 +1,4 @@ -# Restore the possibility of using global defines accross a project +# Restore the possibility of using global defines across a project ## Overview @@ -6,14 +6,14 @@ This RFC proposes a simple and generic change in the arduino-cli tool (used by a ## Problem -A long-term issue with the Arduino environment has been the inability for the user to declare macros for them to be available accross all source files (sketch, libraries, not the core). +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 attemps were proposed during the past 9 years (see appendix) +- 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. @@ -76,7 +76,7 @@ An [on-going pull-request](https://github.com/arduino/arduino-cli/pull/1524) imp #### 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 accross multiple achitectures. + 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 From 2441705548cfaaa55fdf981299b27ddd7b236276 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Wed, 20 Oct 2021 16:59:16 +0200 Subject: [PATCH 4/6] formatting --- RFCs/0000-global-defines.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md index 3bbfdf1..674dc98 100644 --- a/RFCs/0000-global-defines.md +++ b/RFCs/0000-global-defines.md @@ -11,6 +11,7 @@ A long-term issue with the Arduino environment has been the inability for the us 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) @@ -89,5 +90,5 @@ See appendix for a list of still ongoing pull request. - 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 + - https://github.com/arduino/arduino-builder/pull/29 + - https://github.com/arduino/arduino-builder/pull/282 From 2c3079021c7c75d29713cb1dd51a6ea90c1d0128 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Wed, 20 Oct 2021 17:02:13 +0200 Subject: [PATCH 5/6] remove double spaces --- RFCs/0000-global-defines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md index 674dc98..7e29241 100644 --- a/RFCs/0000-global-defines.md +++ b/RFCs/0000-global-defines.md @@ -13,14 +13,14 @@ Both users and library maintainers are restrained in their action because of the 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). +- 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: +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 @@ -28,7 +28,7 @@ It is not advised to expect already existing libraries to adapt themselves to a #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. +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 @@ -77,7 +77,7 @@ An [on-going pull-request](https://github.com/arduino/arduino-cli/pull/1524) imp #### 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. + 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 From da66434a2ed30b67e1bee9213f68b0f47fab673c Mon Sep 17 00:00:00 2001 From: david gauchard Date: Wed, 20 Oct 2021 17:04:16 +0200 Subject: [PATCH 6/6] obscure formatting :] --- RFCs/0000-global-defines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RFCs/0000-global-defines.md b/RFCs/0000-global-defines.md index 7e29241..6bf995e 100644 --- a/RFCs/0000-global-defines.md +++ b/RFCs/0000-global-defines.md @@ -66,7 +66,7 @@ It is another [closed pull request](https://github.com/arduino/arduino-cli/pull/ ### 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. +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