What a library is
A library is a folder of someone else's code that one #include line pulls into your sketch. Some come with the board package, some with the IDE, and the rest you install into one folder in your sketchbook. When the IDE cannot find the folder, the compile stops on line one.
One line at the top
A sketch that writes to EEPROM, talks I2C or debounces a wire does not need the
code for any of that typed in. Someone has written it already, as a library:
a folder with a header (EEPROM.h) that declares the functions and one or more
.cpp files that hold the code. One line pulls it in:
#include <EEPROM.h>The IDE reads that line before compiling, finds a folder that holds EEPROM.h,
compiles that folder's code along with the sketch and links the two into the one
program that goes onto the chip. Only the functions the sketch calls take up
flash.
Where the IDE looks
There are three folders, and which one a library is in depends on who put it there:
- The board package. Arduino AVR Boards, the package the Uno and the Nano are both in, carries five libraries written for this chip: EEPROM, HID, SPI, SoftwareSerial and Wire. They arrive with the package.
- The IDE's own. Arduino IDE 2 installs a set of common libraries the first
time it starts, Servo, LiquidCrystal, SD and Stepper among them, into the
Arduino15folder. - Your sketchbook. Everything you install goes into the
librariesfolder inside the sketchbook:Documents\Arduino\librarieson Windows,Documents/Arduino/librarieson macOS,~/Arduino/librarieson Linux. File > Preferences shows the sketchbook location if yours is somewhere else.
If two folders hold equally good matches for the same header, the sketchbook wins, then the board package, then the IDE's own. That order is why you install into the sketchbook and leave the other two alone: an IDE update can replace them, and it does not touch yours.
When the folder is not there
Change the first line of the sketch to #include <Bounce2.h> and press Verify.
The compile stops before it reaches setup():
Library_Check.ino:6:10: fatal error: Bounce2.h: No such file or directory
#include <Bounce2.h>
^~~~~~~~~~~
compilation terminated.Nothing is wrong with the sketch. "No such file or directory" on an #include
line always means the same thing: no folder the IDE searched holds that header.
The cure is to install the library, and the next article does that for Bounce2.
Angle brackets or quotes
#include <Bounce2.h> searches the library folders. #include "config.h", in
quotes, looks in the sketch's own folder first, for a file you added to the
sketch as a new tab. Use angle brackets for
libraries and quotes for your own files, and the error above, when it comes,
points at the right place.
Every library brings examples
An installed library's examples appear in File > Examples: the board package's under your board's own heading, and the ones you install under Examples from Custom Libraries. Open one before writing your own code with a library. It compiles, it calls things in the right order, and it is the quickest proof that the library is installed where the IDE can see it.
The code
One #include and one call into the library. If it compiles, uploads and prints 1024 in the Serial Monitor at 9600 baud, the IDE found EEPROM.h and linked its code into the sketch.
// Library_Check.ino — one #include, and proof the IDE found it
// Tools > Board: Arduino Uno, or Arduino Nano with
// Processor ATmega328P (Old Bootloader if the upload says
// "not in sync")
// Tools > Port: the CH340 port
// Wiring: none.
#include <EEPROM.h> // ships with the board package
void setup() {
Serial.begin(9600);
Serial.print(F("EEPROM.h found. EEPROM bytes: "));
Serial.println(EEPROM.length());
}
void loop() {}EEPROM is in the board package, so there is nothing to install. Change the first line to #include <Bounce2.h> and verify again to see the error a missing library gives; the next article installs it.
When it does not work
No library folder the IDE searches holds that header. Either the library is not installed, or it is installed in a shape the IDE cannot read: a folder inside a folder, or loose files in the libraries folder. Install it from the Library Manager, or check the folder against the ZIP article.
File > Examples lists an installed library's examples under Examples from Custom Libraries. If you copied the folder in by hand while the IDE was open and they do not appear, close the IDE and open it again so it rescans the folder.
The header only declares the library's functions; the code that does the work is in its .cpp files. Install the whole library folder, not one file, so the compiler can build and link the rest.
Two folders hold the same header, and the IDE picked the other one. Turn on verbose compile output in File > Preferences and look for Multiple libraries were found: the Used line names the folder that was compiled.
Search, press Install, open the example: Bounce2, start to finish.
Install from the Library Manager →Edit this page — content/books/atmega328p/what-a-library-is.mdx
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.