Skip to content

Improve or remove Keyboard/Mouse compilation error interpretations #1126

New issue
New issue
Open
Open
Improve or remove Keyboard/Mouse compilation error interpretations#1126
Labels
topic: codeRelated to content of the project itselftype: enhancementProposed improvement
@per1234

Description

@per1234
per1234
opened on Jun 29, 2022

Describe the request

Evaluate the often irrelevant supplemental interpretations the Arduino IDE provides on Keyboard and Mouse library-related compilation errors.

  • Can false interpretations be reduced?
  • Can the interpretation message be adjusted to avoid confusion in the event of false positives?
  • Should the interpretations be removed altogether?

Describe the current behavior

The Arduino IDE attempts to provide some additional guidance to users in response to some specific compilation error messages:

arduino-ide/arduino-ide-extension/src/node/cli-error-parser.ts

Lines 134 to 164 in 34ef25c

/**
* Converts cryptic and legacy error messages to nice ones. Taken from the Java IDE.
*/
function remapErrorMessages(result: ParseResult): ParseResult {
const knownError = KnownErrors[result.error];
if (!knownError) {
return result;
}
const { message, error } = knownError;
return {
...result,
...(message && { message }),
...(error && { error }),
};
}
// Based on the Java IDE: https://github.com/arduino/Arduino/blob/43b0818f7fa8073301db1b80ac832b7b7596b828/arduino-core/src/cc/arduino/Compiler.java#L528-L578
const KnownErrors: Record<string, { error: string; message?: string }> = {
"'Mouse' was not declared in this scope": {
error: nls.localize(
'arduino/cli-error-parser/mouseError',
"'Mouse' not found. Does your sketch include the line '#include <Mouse.h>'?"
),
},
"'Keyboard' was not declared in this scope": {
error: nls.localize(
'arduino/cli-error-parser/keyboardError',
"'Keyboard' not found. Does your sketch include the line '#include <Keyboard.h>'?"
),
},
};

This is accomplished by matching a subset of the error message produced by the compilation toolchain and then printing an additional message in a notification and to the "Output" panel. That message is intended to make the cause and resolution for the error easier for less advanced users to understand.

Two such interpretations were put in place at the time of a breaking change 7 years ago resulting from moving the popular keyboard and mouse emulation APIs out of the core to standalone libraries: arduino/Arduino#3304

Prior to the change, the APIs could be used without adding an extra #include directive to the sketch:

void setup() {
  Keyboard.begin();
  Keyboard.print("hello");
}
void loop() {}

After the change, it was necessary to add an #include directive for the appropriate header file:

#include <Keyboard.h>
void setup() {
  Keyboard.begin();
  Keyboard.print("hello");
}
void loop() {}

Attempting to compile the previously valid code results in an error:

C:\Users\per\AppData\Local\Temp\.arduinoIDE-unsaved2022528-3144-18az9y0.lofa\sketch_jun28a\sketch_jun28a.ino: In function 'void setup()':
C:\Users\per\AppData\Local\Temp\.arduinoIDE-unsaved2022528-3144-18az9y0.lofa\sketch_jun28a\sketch_jun28a.ino:2:3: error: 'Keyboard' was not declared in this scope
   Keyboard.begin();
   ^~~~~~~~

exit status 1

These supplemental interpretations are also displayed by the Arduino IDE:

'Mouse' not found. Does your sketch include the line '#include <Mouse.h>'?

'Keyboard' not found. Does your sketch include the line '#include <Keyboard.h>'?

Arduino and the Arduino community have done a good job of adapting to the change and it is now very rare to find any legacy code without these #include directives. There is always the chance a user will forget to add an #include directive in a sketch they write from scratch, but that is just as likely to occur with any arbitrary header file, so does not justify giving these two special treatment.

Meanwhile, another mistake related to keyboard and mouse emulation code is just as prevalent as ever: attempting to use it with a board which does not have native USB support (e.g., Uno, Mega). Unfortunately, doing this produces the same compilation error as omitting the #include directive, which also triggers the interpretations. In this case the interpretation message is completely irrelevant because the user already has that #include directive in their sketch and the error is caused by something completely different.

🙁 The interpretation message increases confusion in the cases where it is irrelevant. The cases where it is relevant are increasingly rare as time goes on.

Arduino IDE version

2.0.0-rc8-snapshot-34ef25c

Operating system

Windows

Operating system version

10

Additional context

Related: #1113

Issue checklist

  • I searched for previous requests in the issue tracker
  • I verified the feature was still missing when using the latest nightly build
  • My request contains all necessary details

Metadata

Metadata

Assignees

No one assigned

    Labels

    topic: codeRelated to content of the project itselftype: enhancementProposed improvement

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions