Purpose of #ifndef and #define? Help & Information JoeRagu May 26, 2017, 4:13am 1 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> 1 Like Pharap (Pharap) May 26, 2017, 4:33am 2 C and C++ use a special component in their compilers called a preprocessor. It’s basically a fancy copy-and-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 the word 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 block.
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 This particular sequence of preprocessor directves is called an 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’.
This results in 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 defined (which would violate the one definition rule).
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 another kind of copy-and-paste operation, but rather than a single line, it copy-and-pastes the entire contents of a file. #include "file.h" basically means ‘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 is 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), but you don’t need to know about those unless you’re really curious.
An alternative to using include guards is to just put #pragma once at the top of your file. Technically it’s a non-standard extension, but pretty much every compiler supports it and it saves you the trouble of having to invent a new macro name for every single header file, so personally I’d recommend it. (It’s probably the only compiler extension I’d recommend using.)
6 Likes JoeRagu May 26, 2017, 4:42am 3 Thanks for the very in depth reply!
'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
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
Pharap (Pharap) May 26, 2017, 7:03am 4 Thanks for the very in depth reply!
No problem.
would this be a way it could be called twice if the #ifndef was not used?
Precisely.
Another example: Main.h includes Circle.h and Rectangle.h Circle.h includes Point.h Rectangle.h includes Point.h
I guess it sort of has the same effect as a PHP include_once statement?
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.
1 Like zeduckmaster May 26, 2017, 12:44pm 5 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:
largely supported more meaningful for beginners helps to remove noise code lines in header files can be optimized by certain compilers no need to create unique macro names 2 Likes Pharap (Pharap) May 26, 2017, 12:49pm 6 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)
1 Like MLXXXp (Scott) May 26, 2017, 1:23pm 7 If you use the quote syntax #include "bitmaps.h" then the preprocessor will look for the file locally.
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.
Why do external files have to end in .h?
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.)
1 Like JoeRagu May 26, 2017, 4:39pm 8 pragma once In the C and C++ programming languages, #pragma once is a non-standard but widely supported preprocessor directive designed to cause the current source file to be included only once in a single compilation. Thus, #pragma once serves the same purpose as include guards, but with several advantages, including: less code, avoidance of name clashes, and sometimes improvement in compilation speed. The most common alternative to #pragma once is to use #define to set an include guard macro, the name of...
Pharap (Pharap) May 27, 2017, 3:50am 9 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.”
MLXXXp (Scott) May 27, 2017, 11:09am 10 For the sake of pedantry, technically how both quote-includes and angle-bracket-includes search for files 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> ?
Topic Replies Views Activity .cpp and how to use em Help & Information 16 1971 November 7, 2017 Some questions I have about C++ Help & Information 17 497 December 31, 2022 Multiple .ino files vs. .h and .cpp Discussion 3 5295 December 2, 2018 .h and .cpp or .ino? Help & Information 3 4059 August 22, 2022 Understanding the core lib Classifieds 2 1062 May 28, 2016
Games Community × Install this page on iOS Enable Fullscreen Mode & Notifications Tap
Install this page on Android Enable Fullscreen Mode & Notifications
Add to Home screen Catalog Arduboy About
Shroom Knight Dazzle Dash RPG Ardynia Dark and Under Action Hopper Paku Paku Adventure Catacombs of the Damned Virus LQP-79 Strategy Micro City Higher Lower Platform Castleboy Trials of Astarok Puzzle Circuit Dude Sports ArduGolf Credit Card Sized Handheld Designed for Homebrew8-bit Games Every Game by Community Members for Free Open Source Hardware,Yours to Make and Modify Build Hardware and Create Games with Online Tutorials Learn more at Arduboy.com
then Add to Home Screen
Install this page on Android Enable Fullscreen Mode & Notifications 
Add to Home screen Catalog Arduboy About New! Shroom Knight Dazzle Dash RPG Ardynia Dark and Under Action Hopper Paku Paku Adventure Catacombs of the Damned Virus LQP-79 Strategy Micro City Higher Lower Platform Castleboy Trials of Astarok Puzzle Circuit Dude Sports ArduGolf Credit Card Sized Handheld Designed for Homebrew8-bit Games Every Game by Community Members for Free Open Source Hardware,Yours to Make and Modify Build Hardware and Create Games with Online Tutorials Learn more at Arduboy.com 
Share this App