What exactly does the Arduino preprocessor do?

Question

Arduino claims to be a "language," not just an "application framework," and Arduino files have their own extension, .ino. The language is obviously C++, but not quite. My understanding is that Arduino has some sort of special preprocessor which converts .ino files into C++ files before compiling them.

My question is: What exactly does this preprocessor do? What exactly are the differences between "Arduino language" and real C++? The Arduino documentation seems to gloss over this.

In particular, I've had weird things happen when I try to define my own classes in my sketch. It's hard to figure out what I'm doing wrong when the language doesn't seem to be specified anywhere.

Answer 1

It does four things, basically:

1. It adds #include <Arduino.h> to the top of your file, which gives you access to all the classes, functions and defined variables/macros of the API.
2. It joins together all the INO files together into a single monolithic file (in the same order as the tabs in the window),
3. It matches #include entries with libraries and adds the files in those libraries to the list of files to compile, and
4. It scans through the ino file(s) looking for functions and adds prototypes to them to the top of your file.

It's the latter that can cause problems. Historically it never got the prototypes in the right place, and if you ever passed a structure of your own devising to a function it would break horribly. It does a better job these days, but it's still not 100% perfect.

It basically means that you don't have to adhere to the "You must define it before you use it" rule of C/C++. Which of course makes for lazy programmers.

Answer 2

See my answer: How the IDE organizes things

I'm not sure if link-only answers which refer to a Stack Exchange link are OK. In case they are not, here is the first part of that answer:

This is how the IDE organizes your "sketch":

• The main .ino file is the one of the same name as the folder it is in. So, for foobar.ino in foobar folder - the main file is foobar.ino.
• Any other .ino files in that folder are concatenated together, in alphabetic order, at the end of the main file (regardless of where the main file is, alphabetically).
• This concatenated file becomes a .cpp file (eg. foobar.cpp) - it is placed in a temporary compilation folder.
• The preprocessor "helpfully" generates function prototypes for functions it finds in that file.
• The main file is scanned for #include <libraryname> directives. This triggers the IDE to also copy all relevant files from each (mentioned) library into the temporary folder, and generate instructions to compile them.
• Any .c, .cpp or .asm files in the sketch folder are added to the build process as separate compilation units (that is, they are compiled in the usual way as separate files)
• Any .h files are also copied into the temporary compilation folder, so they can be referred to by your .c or .cpp files.
• The compiler adds into the build process standard files (like main.cpp)
• The build process then compiles all the above files into object files.
• If the compilation phase succeeds they are linked together along with the AVR standard libraries (eg. giving you strcpy etc.)

A side-effect of all this is that you can consider the main sketch (the .ino files) to be C++ to all intents and purposes. The function prototype generation however can lead to obscure error messages if you are not careful.