I always see header files starting with
#ifndef BITMAPS_H
#define BITMAPS_H
and end with:
#endif
Why do we have to do this?
Why do external files have to end in .h?
What is the correct way of including .h files in my .ino?
#include "bitmaps.h"
or
#include <bitmaps.h>C and C++ use a special component in their compilers called a preprocessor. Itâs basically a fancy copy-paste machine.
Firstly a breakdown of what all the different preprocessor words mean (you can skip this if youâre sure you know how they work).
#define defines a word to mean something else.
E.g. #define FIVE 5 would result in all instances of FIVE being replaced with 5.
#if tests if a condition is true.
#else provides an alternative case for an #if, in case it is not true.
#endif ends an #if
e.g.
#if VERSION > 5
useNewFeature();
#else
useOldFeature();
#endif
#ifdef tests if a word is defined and #ifndef does the opposite - it tests if a word has not been defined.
e.g.
#define FIVE
#ifdef FIVE
// This is used
#else
// This isn't
#endif
So now thatâs out of the way, letâs examine this.
#ifndef BITMAPS_H
#define BITMAPS_H
// lots of bitmaps
#endif
The correct name for this sequence is a âinclude guardâ.
This says âif BITMAPS_H isnât defined, define it, then look at this C++ codeâ which implicitly means âif BITMAPS_H is defined, ignore all this codeâ.
What this results in is a block of code that can only be examined once. This is done for a good reason - trying to read certain bits of code twice will upset the compiler because it will think you are trying to redefine something you have already stated.
The compiler doesnât realise itâs the same file and doesnât know to ignore it unless you use that special define sequence.
If your wondering why the compiler might try to read it twice, thatâs because of how #include works.
#include is basically a copy-paste. #include "file.h" says 'copy the contents of file.h and paste it all here. This means that if file.h gets #included more than once, youâll have duplicate sets of code, which is why you need the include guards - to make sure the compiler ignores the duplicates.
As youâve pointed out, there are two kinds of includes, and they both have different behaviour. The difference is where the preprocessor looks for the file.
If you use the quote syntax #include "bitmaps.h" then the preprocessor will look for the file locally. E.g. if you had a file âProject/Main.hâ and it had a line #include "Other.h", the preprocessor would look for âProject/Other.hâ.
The angle bracket syntax on the other hand, looks for the file in a specially designated library folder and it typically used for external libraries.
What this means is that for files local to your project you want to use the quote-style #include "bitmaps.h" and for external librarys you want to use angle-bracket-style, like when you #include <Arduboy2.h>.
I hope that all makes sense.
Post Script:
There are a few details Iâve left out like #if defined(WORD) and #pragma once, but you donât need to know about those unless youâre really curious.
Thanks for the very in depth reply!
I guess a way that it could be included twice is in this case:
You include bitmaps.h in your main file
You include xyz.h also in main file
xyz.h includes bitmaps.h itself within xyz.h
would this be a way it could be called twice if the #ifndef was not used?
I guess it sort of has the same effect as a PHP include_once statement?[quote=âPharap, post:2, topic:3592â]
What this means is that for files local to your project you want to use the quote-style #include âbitmaps.hâ and for external librarys you want to use angle-bracket-style, like when you #include <Arduboy2.h>.
[/quote]
Oh i get it now
No problem.
Precisely.
Another example:
Main.h includes Circle.h and Rectangle.h
Circle.h includes Point.h
Rectangle.h includes Point.h
Based on the description on php.net yes, itâs a different mechanism to achieve the same effect of having code only declared once. In C++'s case though, trying to define something twice is a compile-time error so your program wouldnât even compile. I suspect PHP is a bit more forgiving.
Just use #pragma once at the beginning of your header files instead of macros #ifdef #endif to safe guard your includes. It has the same effect.
It is:
It also breaks under certain weird conditions involving hard links, sym links and mounting and isnât supported by older compilers (older being around early 2000s).
(I still use and advocate it, but somebody has to mention the small disclaimer. :P)
To be more precise, quote syntax means look for the file locally and then if it isnât found locally continue searching for it as if you had used angle bracket syntax.
So if you wanted, you could always use quotes, never angle brackets. If it isnât a local file, the external path will still be searched. However, by using angle brackets when you know itâs not a local file, it makes the code clearer and can help with solving âfile not foundâ type errors. It helps to indicate where the file is actually expected to be located.
This is not a rule but a convention. The .h extension indicates itâs a header file. The traditional rule of thumb is that header files declare definitions (such as #define statements), and may include other header files, but donât contain statements that actually generate any code. Another purpose of header files is to provide function prototypes and class declarations, but because of extra pre-compiler work performed by the IDE, declaring function prototypes is rarely required in the Arduino world with a properly written sketch.
You will find that many people actually do put code generating statements in header files. Putting bitmaps, music scores and other constant data in a header file is somewhat acceptable for Arduino sketches for simplicity, due to the way IDE compiling works. Otherwise, I personally donât feel functions or other code should go in header files but I donât want to start any holy wars about it (which has already been done to death). (And Iâll add that there are some exceptions, such as C++ templates.)
For the sake of pedantry, technically how both quote-includes and angle-bracket-includes search for files is implementation defined (âsearches a sequence of implementation-defined places for a headerâ/âThe named source file is searched for in an implementation-defined
mannerâ), so the quote-include could be configured to search somewhere else and the angle-bracket-include could search locally.
The angle-bracket-include also technically doesnât have to be a filename, or even a URL.
âHow the places are specified or the header identified is implementation-defined.â
True. I didnât want to go to that level of detail to avoid information overload, but I did want to point out that (at least for Arduino) quote-includes can find files beyond the local directory. This was in anticipation of someone asking: Why does #include "Arduboy2.h" work, as Iâve seen in other sketches, instead of requiring #include <Arduboy2.h> ?