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

c5812eea68afdb0e4e774f4f15ec4a34f0c3100c

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

• https://github.com/arduino/arduino-cli/issues/1269
• https://github.com/arduino/arduino-cli/issues/1822
• https://github.com/arduino/arduino-cli/issues/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

• https://github.com/arduino/arduino-cli/issues/1191
• https://github.com/arduino/arduino-cli/issues/1253
• https://github.com/arduino/arduino-cli/issues/1591
• https://github.com/arduino/arduino-cli/issues/1618
• https://github.com/arduino/arduino-cli/issues/1785
• https://github.com/arduino/arduino-cli/issues/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

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