How to properly include C/C++ headers and source files in your Arduino Project
Quick summary
(Added June 2023)
Arduino is C++, with some C source code and object files mixed in, but they have added some preprocessing steps to their build system which make it behave slightly differently from normal C++.
So, to include your own custom header files, you must:
Ensure all source files have the .cpp
extension, not .c
. Your files are already fine in this regard. Last I checked years ago, Arduino also prefers header files to end in .h
, not .hh
or .hpp
.
Ensure you put your custom header and source files in the same directory as your project .ino
file. So you need to fix this.
Do this:
project
foo.h
foo.cpp
project.ino
Not this:
project
folder <-- custom subfolders are not allowed in Arduino!
foo.h
foo.cpp
project.ino
You'll then include your custom library like this:
// Inside project.ino
#include "foo.h"
I haven't tested it yet, but Arduino may also recognize and be okay with a directory named src
only.
Possibly okay:
project
src
foo.h
foo.cpp
project.ino
If you use a src
folder, one of the following includes should work, but I haven't tested it to see which:
// Inside project.ino
// (I haven't tested this)
#include "src/foo.h"
// or maybe
#include "foo.h"
That's about it. I'd have to try the latest Arduino IDE and command-line build system to see if anything has evolved or improved over the last few years regarding includes.
You can stop here if the above works for you. Or, read below for more info. and details and learning.
Original answer details
(Written 2019)
This answer has been tested and compiled to ensure it works. (Completed in Linux Ubuntu with the Arduino 1.8.7 IDE).
You have 2 problems.
1st: Arduino's unusual build process (described here) doesn't allow including from sub-folders in your project directory where your .ino
file for this project is located.
[UPDATE: THIS ONE MAY HAVE BEEN MY MISTAKE ONLY, NOT YOURS, when I was duplicating your code on my PC: I accidentally used foo.c
instead of foo.cpp
]
2nd: C++ can only be used inside C++ source files, so you must change foo.c
to foo.cpp
, since Serial.println()
is a C++ call to a C++ class's (Serial
's) println()
method.
To fix 1, simply change your folder structure to have everything in a single folder:
project
├── foo.cpp
├── foo.hh
└── project.ino
I present an alternate fix for #1 below too.
To fix 2, (this is mandatory!) make foo.c
--> foo.cpp
and (optionally, but recommended, to show it is a C++ header file) foo.h
--> foo.hh
. Update your includes in the .ino and .cpp file now too to #include "foo.hh"
. Update 7 June 2023: just use .h
. Arduino may not like .hh
, but I haven't tested this in the latest Arduino IDE. Your call.
That's it! Now close the Arduino IDE, then reopen it and reopen your project, and you'll see the following new tabs show up:
It now compiles just fine!
Learning: how did I figure this out?
First, turn on verbose compilation in the Arduino IDE: File --> Preferences --> check the box for "Show verbose output during 'compilation'".
Now, when you compile, all errors will show up in the bottom of the IDE window, as well as the exact compilation or linking commands which throw the error.
Once I fixed the folder structure, but your files were still C instead of C++ files, I saw this error:
Compiling sketch...
/home/gabriel/Downloads/Install_Files/Arduino/arduino-1.8.7/hardware/tools/avr/bin/avr-gcc -c -g -Os -w -std=gnu11 -ffunction-sections -fdata-sections -MMD -flto -fno-fat-lto-objects -mmcu=atmega328p -DF_CPU=16000000L -DARDUINO=10807 -DARDUINO_AVR_NANO -DARDUINO_ARCH_AVR -I/home/gabriel/Downloads/Install_Files/Arduino/arduino-1.8.7/hardware/arduino/avr/cores/arduino -I/home/gabriel/Downloads/Install_Files/Arduino/arduino-1.8.7/hardware/arduino/avr/variants/eightanaloginputs /tmp/arduino_build_233569/sketch/foo.c -o /tmp/arduino_build_233569/sketch/foo.c.o
/tmp/arduino_build_233569/sketch/foo.c: In function 'bar':
foo.c:9:5: error: 'Serial' undeclared (first use in this function)
Serial.println("bar");
^
/tmp/arduino_build_233569/sketch/foo.c:9:5: note: each undeclared identifier is reported only once for each function it appears in
exit status 1
'Serial' undeclared (first use in this function)
Notice the file it failed to compile was /tmp/arduino_build_233569/sketch/foo.c
, and that the avr-gcc
C compiler (rather than the avr-g++
C++ compiler) was in use at the time.
I then opened the /tmp/arduino_build_233569/sketch/foo.c
file to examine it and look for anything unusual about it.
Next, I used Eclipse to start tracking down includes, to see where Serial
gets pulled in (it should have been obvious to me already what the problem was, but I didn't see it yet). I found the following:
Arduino.h is found in "Arduino/Source/Arduino/hardware/arduino/avr/cores/arduino/Arduino.h". It includes "HardwareSerial.h"
. This header extern
s the Serial
object:
#if defined(UBRRH) || defined(UBRR0H)
extern HardwareSerial Serial;
#define HAVE_HWSERIAL0
#endif
HOWEVER, looking back at Arduino.h
you'll see that HardwareSerial.h
is ONLY included if you are compiling with C++:
#ifdef __cplusplus // <========= This means that the following headers are ONLY included if you are compiling with C++! BOOM! That's when it hit me! You're compiling a C file with the C compiler to access a C++ object. That's not ok. Use the C++ compiler!
#include "WCharacter.h"
#include "WString.h"
#include "HardwareSerial.h"
#include "USBAPI.h"
#if defined(HAVE_HWSERIAL0) && defined(HAVE_CDCSERIAL)
#error "Targets with both UART0 and CDC serial not supported"
#endif
#ifdef __cplusplus
means that the headers above are ONLY included if you are compiling with C++! That's when it hit me! You're compiling a C file with the C compiler to access a C++ object. That's not ok. You must use the C++ compiler instead. Do this simply by changing foo.c
to foo.cpp
. Done.
Alternate fix for your problem #1 (the folder structure):
Find your "Sketchbook location" from Arduino IDE: File --> Preferences. Mine, for example, is /home/gabriel/dev/Arduino/Sketches
.
Now, go there and create a "libraries" folder. For me that would now be /home/gabriel/dev/Arduino/Sketches/libraries
. Everything inside this folder is now considered an Arduino "library", and can be included. Move foo.h
[do NOT use foo.hh
in this case] and foo.cpp
there, like this:
/home/gabriel/dev/Arduino/Sketches/libraries/foo
├── foo.cpp
└── foo.h <==== NOT foo.hh in this case!
Now close and reopen the Arduino IDE, then go to Sketch --> Include Library --> foo, and it will automatically add the following line for you:
#include <foo.h>
The reason you can't use foo.hh
in this case is simply because Arduino is looking for .h
files only when you add your library include using the menus in this way. That's a bug as far as I'm concerned, and should probably be reported to the Arduino developers. Feel free to take that on.
Addendum:
16 Apr. 2019:
A google search for "arduino add include path" led me to this: https://forum.arduino.cc/index.php?topic=445230.0, where user @pert says:
In recent versions of the Arduino IDE(including 1.6.10) if you want to include libraries from the sketch folder you need to put them in a src subfolder. For example:
Blink
|_Blink.ino
|_src
|_BlinkLib
|_BlinkLib.h
He then says you can include like this:
#include "src/BlinkLib/BlinkLib.h"
I haven't tried this, but that'd be super useful if it works. Give it a shot and let me know if it works. Be sure to tell us which OS and Arduino IDE version you are using.
See Also:
- Additional discussion on Github here: https://github.com/arduino/Arduino/issues/5186.
- The official Arduino Library specification here: https://arduino.github.io/arduino-cli/latest/library-specification/.
bar()
has exactly the same signature as declared infoo.h
.