Skip to content

Remove obsolete compilation error interpretations #1113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 28, 2022
Merged

Remove obsolete compilation error interpretations #1113

merged 1 commit into from
Jun 28, 2022

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented Jun 26, 2022

I was not diligent enough in my review duties and missed the migration of some legacy code from Arduino IDE 1.x that was intended to be removed as part of the rewrite (arduino/Arduino#8385 (comment)).


The Arduino IDE attempts to provide some additional guidance to users based on matches against compilation error messages.

This practice was established during a time when some significant breaking changes were made to the common APIs in order to ease the transition.

Since that time, the practice has mostly been discontinued. The interpretations are only valid for very old code that is unlikely to be used by the target users now. So their benefit is negligible. The patterns used are inexact, meaning that the interpretations may be printed inappropriately, which is more and more likely as the cases where the matches would be valid become increasingly rare. When the maintenance burden is taken into consideration, it is clear that the harm is far more than any benefits from these. So they are removed.

Notes for specific interpretations:

Please import the SPI library from the Sketch > Import Library menu.
As of Arduino 0019, the Ethernet library depends on the SPI library.
You appear to be using it or another library that depends on the SPI library.

The target error was more common prior to Arduino IDE 1.6.6 (released ~6.5 years ago), when it was necessary for the sketch to contain #include directives for transitive in addition to direct library dependencies (the "SPI" library is a common transitive dependency).

Due to the nature of the "SPI" library, it is not often used directly, and when it is used directly it is done by more advanced users who are unlikely to forget the #include directive and would have no need for this interpretation even if they did.

It is far more likely for the user to forget an #include for a popular library, yet Arduino rightly does not attempt to maintain interpretations for those.

The "Sketch > Import Library" menu path was renamed to "Sketch > Include Library" ~7 years ago.

Arduino IDE 0019 was released ~12 years ago. We can safely assume the migration to the new "Ethernet" library API is complete.


The 'BYTE' keyword is no longer supported.
As of Arduino 1.0, the 'BYTE' keyword is no longer supported.
Please use Serial.write() instead.

Arduino IDE 1.0 was released ~10.5 years ago. We can safely assume the migration to the new Serial API is complete.

This compilation error pattern is now far more likely to occur due to incorrect usage of a completely unrelated occurrence of the common BYTE name in the user's code.


The Server class has been renamed EthernetServer.
As of Arduino 1.0, the Server class in the Ethernet library has been renamed to EthernetServer.

The Client class has been renamed EthernetClient.
As of Arduino 1.0, the Client class in the Ethernet library has been renamed to EthernetClient.

The Udp class has been renamed EthernetUdp.
As of Arduino 1.0, the Udp class in the Ethernet library has been renamed to EthernetUdp.

Arduino IDE 1.0 was released ~10.5 years ago. We can safely assume the migration to the new "Ethernet" library API is complete.

The compilation error patterns are in no way specific to the "Ethernet" library so is prone to false positives (e.g., arduino/Arduino#8385).


Wire.send() has been renamed Wire.write().
As of Arduino 1.0, the Wire.send() function was renamed to Wire.write() for consistency with other libraries.

Wire.receive() has been renamed Wire.read().
As of Arduino 1.0, the Wire.receive() function was renamed to Wire.read() for consistency with other libraries.

Arduino IDE 1.0 was released ~10.5 years ago. We can safely assume the migration to the new "Wire" library API is complete.

Due to the nature of the "Wire" library, it is not often used directly, and when it is used directly it is done by more advanced users who have less need for an interpretation of the compiler error.


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

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

I left these in because they are the most "recent" (added due to a breaking change made 7 years ago: arduino/Arduino#3304).

However, I also feel that these are harmful and should either be removed or changed. The problem is that there is a false match when the user attempts to compile the Keyboard or Mouse libraries for a board which does not have native USB support (e.g., Uno, Mega), even when their sketch does contain the #include directives that are recommended by the interpretation. That cause of the compilation error matching the pattern is more common than the case where the user is compiling old code or forgot the #include directive, for which the interpretation is valid.

Reviewer checklist

  • PR addresses a single concern.
  • The PR has no duplicates (please search among the Pull Requests before creating one)
  • PR title and description are properly filled.
  • Docs have been added / updated (for bug fixes / features)

The Arduino IDE attempts to provide some additional guidance to users based on matches against compilation error
messages.

This practice was established during a time when some significant breaking changes were made to the common APIs in order
to ease the transition.

Since that time, the practice has mostly been discontinued. The interpretations are only valid for very old code that is
unlikely to be used by the target users now. So their benefit is negligible. The patterns used are inexact, meaning that
the interpretations may be printed inappropriately, which is more and more likely as the cases where the matches would
be valid become increasingly rare. When the maintenance burden is taken into consideration, it is clear that the harm is
far more than any benefits from these. So they are removed.

Notes for specific interpretations:

> Please import the SPI library from the Sketch > Import Library menu.
> As of Arduino 0019, the Ethernet library depends on the SPI library.
> You appear to be using it or another library that depends on the SPI library.

The target error was more common prior to Arduino IDE 1.6.6 (released ~6.5 years ago), when it was necessary for the
sketch to contain `#include` directives for transitive in addition to direct library dependencies (SPI is a common
transitive dependency).

Due to the nature of the SPI library, it is not often used directly, and when it is used directly it is done by more
advanced users who are unlikely to forget the `#include` directive and would have no need for this interpretation even
if they did.

It is far more likely for the user to forget an `#include` for a popular library, yet Arduino rightly does not attempt
to maintain interpretations for those.

The "Sketch > Import Library" menu path was renamed to "Sketch > Include Library" ~7 years ago.

Arduino IDE 0019 was released ~12 years ago. We can safely assume the migration to the new Ethernet API is complete.

> The 'BYTE' keyword is no longer supported.
> As of Arduino 1.0, the 'BYTE' keyword is no longer supported.
> Please use Serial.write() instead.

Arduino IDE 1.0 was released ~10.5 years ago. We can safely assume the migration to the new Serial API is complete.

This compilation error pattern is now far more likely to occur due to incorrect usage of a completely unrelated
occurrence of the common `BYTE` name in the user's code.

> The Server class has been renamed EthernetServer.
> As of Arduino 1.0, the Server class in the Ethernet library has been renamed to EthernetServer.

> The Client class has been renamed EthernetClient.
> As of Arduino 1.0, the Client class in the Ethernet library has been renamed to EthernetClient.

> The Udp class has been renamed EthernetUdp.
> As of Arduino 1.0, the Udp class in the Ethernet library has been renamed to EthernetUdp.

Arduino IDE 1.0 was released ~10.5 years ago. We can safely assume the migration to the new Ethernet API is complete.

The compilation error patterns are in no way specific to the Ethernet library so is prone to false positives.

> Wire.send() has been renamed Wire.write().
> As of Arduino 1.0, the Wire.send() function was renamed to Wire.write() for consistency with other libraries.

> Wire.receive() has been renamed Wire.read().
> As of Arduino 1.0, the Wire.receive() function was renamed to Wire.read() for consistency with other libraries.

Arduino IDE 1.0 was released ~10.5 years ago. We can safely assume the migration to the new Wire API is complete.

Due to the nature of the Wire library, it is not often used directly, and when it is used directly it is done by more
advanced users who have less need for an interpretation of the compiler error.

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

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

I left these in because they are the most "recent" (added due to a breaking change made 7 years ago).

However, I also feel that these are harmful and should either be removed or changed. The problem is that there is a
false match when the user attempts to compile the Keyboard or Mouse libraries for a board which does not have native USB
support (e.g., Uno, Mega), even when their sketch does contain the `#include` directives that are recommended by the
interpretation. That cause of the compilation error matching the pattern is more common than the case where the user is
compiling old code or forgot the `#include` directive, for which the interpretation is valid.
@per1234 per1234 added type: enhancement Proposed improvement topic: code Related to content of the project itself labels Jun 26, 2022
@per1234 per1234 requested a review from kittaakos June 26, 2022 03:12
@per1234 per1234 self-assigned this Jun 26, 2022
@per1234 per1234 merged commit e454acb into arduino:main Jun 28, 2022
@per1234 per1234 deleted the remove-obsolete-compiler-interpretations branch June 28, 2022 15:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic: code Related to content of the project itself type: enhancement Proposed improvement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants