u8g2/u8x8 lib: #include <Arduino.h> DON'T!!!

[AndrewBCN]

Hi,
I was trying a few example sketches included with U8g2 on an STM32F411CEU6 Black Pill development board. The U8g2 example sketches usually begin with the following includes:

Code: Select all

#include <Arduino.h>
#include <U8x8lib.h>

I found out that including <Arduino.h> in my sketches explicitly was causing some weird problems, and it's not even needed: the Arduino build system always automatically includes <Arduino.h> anyways.

So just a warning for those using U8g2/u8x8, which is a great library btw:

DON'T
#include <Arduino.h>

explicitly in your STM32duino sketches if you are using the U8g2/u8x8 library.

My software environment: Ubuntu 20.10, Arduino IDE 1.8.13, STM32 core release 2.0.0 with a few fixes.

EDIT: see the solution for this mystery below. In short, either don't explicitly #include <Arduino.h> (it's not needed), or if you do, do so at the very top of your sketch.

[fpiSTM]

This should not change anything.
When you build with Aduino IDE, the .ino is converted to cpp file and Arduino.h include is added on top of this file.
So in fact you have twice time the include but this is not an issue as it contains include guards.

Code: Select all

#include <Arduino.h>
#line 1 "C:\\STM32\\arduino\\arduino-1.8.13\\portable\\sketchbook\\test\\test.ino"
#include <Arduino.h>

[AndrewBCN]

This should not change anything.
When you build with Aduino IDE, the .ino is converted to cpp file and Arduino.h include is added on top of this file.
So in fact you have twice time the include but this is not an issue as it contains include guards.

Code: Select all

#include <Arduino.h>
#line 1 "C:\\STM32\\arduino\\arduino-1.8.13\\portable\\sketchbook\\test\\test.ino"
#include <Arduino.h>

It seems it does change something, somewhere . An example:

Code: Select all

#include <Arduino.h>
#if !defined(STM32_CORE_VERSION) || (STM32_CORE_VERSION  < 0x02000000)
#error "Due to API change, this sketch is compatible with STM32_CORE_VERSION  >= 0x02000000"
#endif
...

triggers the error during compilation. Without the #include <Arduino.h>, the code compiles fine.

[fpiSTM]

I've made a simple test with an empty sketch with :

Code: Select all

#if !defined(STM32_CORE_VERSION) || (STM32_CORE_VERSION  < 0x02000000)
#error "Due to API change, this sketch is compatible with STM32_CORE_VERSION  >= 0x02000000"
#endif

Hereafter the result of the ino conversion:

• Without include in the sketch:

Code: Select all

#include <Arduino.h>
#line 1 "C:\\Users\\<username>\\AppData\\Local\\Temp\\arduino_modified_sketch_67459\\sketch_may05b.ino"
#if !defined(STM32_CORE_VERSION) || (STM32_CORE_VERSION  < 0x02000000)
#error "Due to API change, this sketch is compatible with STM32_CORE_VERSION  >= 0x02010100"
#endif

• With include in the sketch:

Code: Select all

#line 1 "C:\\Users\\<username>\\AppData\\Local\\Temp\\arduino_modified_sketch_28109\\sketch_may05c.ino"
#include <Arduino.h>
#if !defined(STM32_CORE_VERSION) || (STM32_CORE_VERSION  < 0x02000000)
#error "Due to API change, this sketch is compatible with STM32_CORE_VERSION  >= 0x02010100"
#endif

In both case I have the build error. As you can see if the Arduino.h is included at sketch level it is not added twice (before #line1) in the converted sketch cpp file.

The only difference seems I'm on Windows but I think it is the same behaviour on Linux. So, maybe you should open an issue on Arduino side to tack this as it is mainly an Arduino IDE issue related to the way it builds.

[AndrewBCN]

...

In both case I have the build error. As you can see if the Arduino.h is included at sketch level it is not added twice (before #line1) in the converted sketch cpp file.

The only difference seems I'm on Windows but I think it is the same behaviour on Linux. So, maybe you should open an issue on Arduino side to tack this as it is mainly an Arduino IDE issue related to the way it builds.

I agree, this seems to be a build system bug in the Arduino IDE.

I am going to file an issue in the Arduino stable github, and I'll report back on whatever reply I get there. Thank you very much for your testing this strange bug.

EDIT
====

1. I took a long look at the Arduino Github (Arduino IDE Github is for version 2.0 which is still in Beta) at the open and closed issues, and problems with the placement of #include <Arduino.h> have been reported and there is an issue still open since 2017 or so.

2. I tested further and the compilation problem only occurs when I use the u8g2/u8x8 library. So the problem really involves an interaction between:

a. the Arduino CLI (which is where the .ino sketch is built),
b. the STM32 source wrapper, and
c. the u8g2/u8x8 library.

I don't really have the time to further research this complex issue and post on GitHub in three different projects, so for now I can only reiterate my initial warning:

If one is using the U8g2/u8x8 library in an STM32 project, DON'T #include <Arduino.h> explicitly. It is not needed and it will cause strange problems during compilation.

EDIT: I couldn't help it and ended up posting an issue in the u8g2 github, here: https://github.com/olikraus/u8g2/issues/1486 and in the Arduino github, here: https://github.com/arduino/Arduino/issues/11488

[AndrewBCN]

Matthijs Kooijman (matthijskooijman) in the Arduino github has solved this mystery:
- If you decide to explicitly

Code: Select all

#include <Arduino.h>

in your STM32 sketch (redundant, since it's included automatically at the top of the generated .cpp during preprocessing), it must be included at the top of the sketch, before any STM32 defines/core version test/etc.

You can read his very clear explanation here: https://github.com/arduino/Arduino/issues/11488

[fpiSTM]

Ok. It is what I think.
I always thought you put the Arduino.h on top of your file else it is a non sense.
That's why I've answered to your first post as I thought it strange

And that's why I didn't reproduce your issue as my test alwaysvinclude it on top. If you have shared your sketch I would be able to answer you

[fpiSTM]

It seems it does change something, somewhere . An example:y

Code: Select all

#include <Arduino.h>
#if !defined(STM32_CORE_VERSION) || (STM32_CORE_VERSION  < 0x02000000)
#error "Due to API change, this sketch is compatible with STM32_CORE_VERSION  >= 0x02000000"
#endif
...

triggers the error during compilation. Without the #include <Arduino.h>, the code compiles fine.

Anyway this does not explains this comment
As without Arduino.h include it should not compile fine, error should be raised....

[AndrewBCN]

Ok. It is what I think.
I always thought you put the Arduino.h on top of your file else it is a non sense.
That's why I've answered to your first post as I thought it strange

And that's why I didn't reproduce your issue as my test alwaysvinclude it on top. If you have shared your sketch I would be able to answer you

Yes, you were right from the beginning. Sorry that I was a little bit confused by this. In fact I am using both the STM32 core version test and the U8g2/u8x8 library in my quite long GPSDO sketch, so when I got the compilation error I was wondering what I was doing wrong. But now I understand.

I can be a little bit slow sometimes...

[fpiSTM]

No worry