Generated function prototype injected before declaration of custom parameter type

[6v6gt-duino]

Describe the problem

In order to make it easier for beginners to get started with writing Arduino sketches, and for the convenience of all users, Arduino CLI automatically generates and adds prototypes for functions defined in a .ino file of a sketch.

Under certain specific conditions, the function prototype is inserted into the code at a location before the declaration of a custom type referenced in the function signature.

🐛 The sketch compilation fails spuriously.

To reproduce

Setup environment

$ arduino-cli version

arduino-cli  Version: git-snapshot Commit: c5812eea6 Date: 2024-09-02T17:16:38Z

$ mkdir -P "/tmp/FooSketch"

$ printf '
void foo() {}  // This causes the prototype to be inserted before the declaration of `bar_t`
enum bar_t {};
void baz(bar_t qux) {
  (void)qux;  // Fix "unused parameter" warning
}
void setup() {}
void loop() {}
' > "/tmp/FooSketch/FooSketch.ino"

Demo

$ arduino-cli compile --fqbn arduino:avr:uno "/tmp/FooSketch"

C:\Users\per\AppData\Local\Temp\FooSketch\FooSketch.ino:4:10: error: variable or field 'baz' declared void
 void baz(bar_t qux) {
          ^~~~~
C:\Users\per\AppData\Local\Temp\FooSketch\FooSketch.ino:4:10: error: 'bar_t' was not declared in this scope

🐛 There was a spurious compilation failure of valid code.

By looking at the C++ code generated by the Arduino sketch preprocessor, we can see the cause of the error:

$ arduino-cli compile --fqbn arduino:avr:uno --preprocess "/tmp/FooSketch"

#include <Arduino.h>
#line 1 "C:\\Users\\per\\AppData\\Local\\Temp\\FooSketch\\FooSketch.ino"

#line 2 "C:\\Users\\per\\AppData\\Local\\Temp\\FooSketch\\FooSketch.ino"
void foo();
#line 4 "C:\\Users\\per\\AppData\\Local\\Temp\\FooSketch\\FooSketch.ino"
void baz(bar_t qux);
#line 7 "C:\\Users\\per\\AppData\\Local\\Temp\\FooSketch\\FooSketch.ino"
void setup();
#line 8 "C:\\Users\\per\\AppData\\Local\\Temp\\FooSketch\\FooSketch.ino"
void loop();
#line 2 "C:\\Users\\per\\AppData\\Local\\Temp\\FooSketch\\FooSketch.ino"
void foo() {}  // This causes the prototype to be inserted before the declaration of `bar_t`
enum bar_t {};
void baz(bar_t qux) {
  (void)qux;  // Fix "unused parameter" warning
}
void setup() {}
void loop() {}

🐛 The spurious compilation failure was caused by Arduino CLI placing the prototype for the baz function before the declaration of the bar_t type.

Expected behavior

Generated function prototypes should be inserted after the declarations of types used in the function signature.

Arduino CLI version

Original report

Arduino IDE 1.8.13

Last verified with

c5812ee

Operating system

• Windows

Operating system version

• Windows 11

Additional context

Originally reported at https://forum.arduino.cc/t/weird-g-error-compiling-simple-type-definition/680759

Additional reports

• Generated function prototype injected before declaration of custom parameter type #1269
• An other preprocessing bug (probably). #1822
• Enum defined after a function template cannot be compiled #2525
• https://forum.arduino.cc/t/tab-local-structs/689088
• https://forum.arduino.cc/t/include-in-multiple-sketches/1133645/11
• https://forum.arduino.cc/t/compiler-flaw-probably-deliberate-infuriating/1146637
• https://forum.arduino.cc/t/does-the-ardiuno-compiler-fully-support-templates/1274584

Related

• #line directives inserted into raw string literal by sketch preprocessor #1191
• ) in comment breaks function prototype generation #1253
• Generated prototype incorrectly prefixed with extern "C" when comment contains // #1591
• Generated prototype incorrectly prefixed with extern "C" when using extern "C" { ... } to mix C functions in an .ino file. #1618
• Backslash incorrectly inserted into generated prototype for multiline template function  #1785
• Prototype incorrectly generated for struct member function under certain conditions #2161
• https://forum.arduino.cc/t/is-the-location-of-a-global-function-important/996378/18
• https://forum.arduino.cc/t/ide-mistakes-javascript-function-for-type/953022
• https://forum.arduino.cc/t/c-super-quotes-compiler-bug/990071
• https://forum.arduino.cc/t/over-length-line-in-editor-forces-forward-declaration/955571
• https://forum.arduino.cc/t/solved-multiple-ide-tabs-issue/988086
• https://forum.arduino.cc/t/declaration-of-functions/687199/11

Workaround

Manually add a function prototype at the appropriate location:

void foo() {}
enum bar_t {};
void baz(bar_t qux);  // Manually added function prototype to workaround prototype generator bug.
void baz(bar_t qux) {
  (void)qux;  // Fix "unused parameter" warning
}
void setup() {}
void loop() {}

Issue checklist

• I searched for previous reports in the issue tracker
• I verified the problem still occurs when using the nightly build
• My report contains all necessary details

[facchinm]

Hi @6v6gt-duino ,
thank for reporting! The issue lies in the prototype generator as you noticed. What bothers me is that both functions are already declared before their usage so the prototype generator shouldn't create anything.
We'll investigate soon and report back