What is a library?

My apologies if this is an FAQ, but so far Google etc. hasn't turned up anything.

From the point of view of the IDE as of v1.8.10, what criteria are checked before a library shows up in the Sketch -> Include Library menu?

I'm looking at a Waveshare e-paper display, and for some reason the standard EPD2 library and demos aren't working. If, however, I download Demo code V2(Purchased after April 26, 2019, the V2 logo is attached to the screen.) I can build a working demo... I'll try to work out the differences later.

Unfortunately, the only way that I can get the demo from the .7z file to compile is by copying the .ino file and associated library files into the same directory. My understanding is that in order to have a library that shows up in the Sketch -> Include Library menu I need to put something in the sketchbook directory (/home/markMLl/Arduino according to the IDE) but so far I haven't managed to get it right.

What does the IDE check here? I've tried simplifying the directory name, I've tried moving files so that they are only a single-layer deep, I've tried creating a minimal library.properties, and obviously I've done everything with an eye on the standards and conventions exhibited by other libraries in the same tree (e.g. RTClib).

MarkMLl

MarkMLl:
what criteria are checked before a library shows up in the Sketch -> Include Library menu?

They are here:

MarkMLl:
the only way that I can get the demo from the .7z file to compile is by copying the .ino file and associated library files into the same directory.

Here's the easiest way to install the library:

  • Download the demo code: https://www.waveshare.com/w/upload/a/a6/2.13inch_e-paper_code(V2).7z
  • Extract the downloaded file.
  • (In the Arduino IDE) Sketch > Include Library > Add .ZIP Library...
  • Select the folder arduino/libraries that you extracted from the downloaded file.
  • Click the "Open" button.
  • Wait until the status bar shows that the library was successfully installed.

It's not obvious from the menu name, but "Add .ZIP Library..." works to install libraries from folders as well as .zip files.

MarkMLl:
My understanding is that in order to have a library that shows up in the Sketch -> Include Library menu I need to put something in the sketchbook directory (/home/markMLl/Arduino according to the IDE) but so far I haven't managed to get it right.

It's best to use the Library Manager (which you can't do in this case) or "Add .ZIP Library" installation methods because these will make sure the library installation is done correctly. It is possible to do a manual installation, as explained here:
https://www.arduino.cc/en/guide/libraries#toc5
but I don't recommend it.

pert:
They are here:
Arduino IDE 1.5: Library specification · arduino/Arduino Wiki · GitHub
Here's the easiest way to install the library:

  • Download the demo code: https://www.waveshare.com/w/upload/a/a6/2.13inch_e-paper_code(V2).7z
  • Extract the downloaded file.
  • (In the Arduino IDE) Sketch > Include Library > Add .ZIP Library...
  • Select the folder arduino/libraries that you extracted from the downloaded file.
  • Click the "Open" button.
  • Wait until the status bar shows that the library was successfully installed.

It's not obvious from the menu name, but "Add .ZIP Library..." works to install libraries from folders as well as .zip files.
It's best to use the Library Manager (which you can't do in this case) or "Add .ZIP Library" installation methods because these will make sure the library installation is done correctly. It is possible to do a manual installation, as explained here:
Arduino - Libraries
but I don't recommend it.

Trying to work through this methodically, in case the example helps anybody with the same question in the future.

If I download the file it's called 2.13inch_e-paper_code(V2).7z , note the thoroughly-improper parentheses. If I unpack that in e.g. ~/Downloads/scratch I end up with

'2.13inch_e-paper_code(V2).7z'
arduino
RaspberryPi
STM32
STM32.7z

where the arduino directory contains

$ ls -1 arduino
epd2in13-demo
libraries

$ ls -1 arduino/libraries
Debug.h
DEV_Config.cpp
DEV_Config.h
font12.c
font12CN.c
font16.c
font20.c
font24.c
font24CN.c
font8.c
fonts.h
GUI_Paint.cpp
GUI_Paint.h

Which is the directory that I should be telling the IDE to install as a library: the one called 'libraries' or something nearer the root of the tree?

MarkMLl

MarkMLl:
Which is the directory that I should be telling the IDE to install as a library: the one called 'libraries'

Yes.

OK. Noting that Sketch -> Include Library -> Add .ZIP Library also works for an uncompressed directory:

If I select (without opening) ~/Downloads/scratch/arduino/libraries that successfully adds "libraries" to the Sketch -> Include Library menu (under Contributed Libraries), and copies the directory "libraries" to ~/Arduino/libraries so that it's visible to all sketches. If I roll back by deleting the created directory it is removed from the IDE's menu.

If I rename ~/Downloads/scratch/arduino/libraries to 2.13inch_e-paper_code_V2 (i.e. in compliance with the naming convention in the link given me earlier Arduino IDE 1.5: Library specification it can then be added to the IDE and appear with a sensible name.

If I copy the demo directory/sketch to my home directory ~ it will compile and run since the e-paper library is now in a location where it will be found by the IDE.

Thanks very much for the help, and hopefully my attempt to write a fairly concise summing up will help somebody in the future.

MarkMLl

MarkMLl:
If I rename ~/Downloads/scratch/arduino/libraries to libraries 2.13inch_e-paper_code_V2 (i.e. in compliance with the naming convention in the link given me earlier Arduino IDE 1.5: Library specification it can then be added to the IDE and appear with a sensible name.

Good idea! I also didn't like the folder name "libraries", but I wanted to provide the most simple instructions I could.

What were the developers at WaveShare thinking? It always makes me sad when these companies that base their business on selling products to Arduino users don't bother to learn the most basic concepts about how the Arduino IDE works. This stuff is made to be simple for beginners, so surely experienced professional developers could learn it in a few hours.

MarkMLl:
Thanks very much for the help, and hopefully my attempt to write a fairly concise summing up will help somebody in the future.

You're welcome, and thank you for taking the time to write up your findings. That sort of extra effort is what makes the Arduino Forum an amazing collection of knowledge that will continue to help huge numbers of Arduino users for decades to come.

pert:
Good idea! I also didn't like the folder name "libraries", but I wanted to provide the most simple instructions I could.

What were the developers at WaveShare thinking? It always makes me sad when these companies that base their business on selling products to Arduino users don't bother to learn the most basic concepts about how the Arduino IDE works. This stuff is made to be simple for beginners, so surely experienced professional developers could learn it in a few hours.

I agree, particularly since they've gone to the trouble of doing a fairly good job making sure their demo works (I'll try to take another look at EPD2 presently). From my perspective, not blithely calling the directory "libraries" and having a single sentence on their wiki ("Unpack, and then add /this/ directory to your IDE") would have saved a lot of headscratching.

I suppose that there is always a possibility that they were using a different development environment (e.g. Eclipse CDT, which I wrestled with a few weeks ago) or had tweaked the Arduino IDE to interwork with their VCS... but they definitely garner kudos for a working demo.

pert:
You're welcome, and thank you for taking the time to write up your findings. That sort of extra effort is what makes the Arduino Forum an amazing collection of knowledge that will continue to help huge numbers of Arduino users for decades to come.

Frankly, I /like/ writing stuff up. And with the importance of Google et al. when it comes to modern R&D I think it's worthwhile summarising work so that the next time somebody has a similar problem the answer's in one concise message.

MarkMLl

Be very patient. This whole library thing will be the source of most of your consternation with the Arduino product. I has always been for me.

The safest thing to do when you download from GitHub is just manually copy the new files to your directory called libraries. The compiler should be able to find them if you do that. Another thing to do is copy them directly into your sketch folder if you still find the compiler can’t find them.

Using new boards you bought also opens up a whole new source of consternation. To this day I have no idea where the board info is actually stored. And these ESP devices have a whole new level of variants and settings that have to be set and there is no good source that I am aware of that will tell you how to get the right board software and how to set the settings.

And, when I buy a board off the internet, it is hard to tell even what board it is. I end up searching with google images to find something that looks similar and working back from that.

sevenoutpinball:
The safest thing to do when you download from GitHub is just manually copy the new files to your directory called libraries.

The safest thing is to use the Arduino IDE's Sketch > Include Library > Add .ZIP Library... installation method. That will ensure that the library is correctly installed. You can do manual installation if you like, but it's slower and you need to understand how to do it correctly. So why would you do that?

sevenoutpinball:
To this day I have no idea where the board info is actually stored.

Start a new thread about it (or post a link to your existing thread) and I'll tell you how to find it.

sevenoutpinball:
And these ESP devices have a whole new level of variants and settings that have to be set and there is no good source that I am aware of that will tell you how to get the right board software and how to set the settings.

And, when I buy a board off the internet, it is hard to tell even what board it is. I end up searching with google images to find something that looks similar and working back from that.

Off topic. Start a new thread and we'll help you out.

The safest thing to do when you download from GitHub is just manually copy the new files to your directory called libraries.

Please don't do that as library files do not belong in the libraries folder despite its name. What does belong there are folders containing the library files, which is not the same thing at all.

For instance, if the library is named Wibble and there are files named Wibble.h and Wibble.cpp belonging to the library then there should be a folder named Wibble in the libraries folder and that folder should contain the .h and .cpp files of the same name

Better still, download the library .zip file and do as pert suggests and install the library from that

Better still, download the library .zip file and do as pert suggests and install the library from that

Well this what happens when I do that on my Mac. first, the file is already de-zipped and the flow of add zip forces me to add each file one at a time, there is no way to do the whole thing as a zip. The zip is already sitting in my trash. I suppose I could take it out and try that way, but whatever.

sevenoutpinball:
first, the file is already de-zipped

Easy solution, just don't de-zip it. If you do have a situation where the library is not in a .zip file, no problem. Despite the name "Add .ZIP Library" also works to install libraries from a folder.

sevenoutpinball:
the flow of add zip forces me to add each file one at a time

I can tell you've never used "Add .ZIP Library". You can't use it to install individual library files. Only .zip files or folders containing the full library.

pert:
Easy solution, just don't de-zip it. If you do have a situation where the library is not in a .zip file, no problem. Despite the name "Add .ZIP Library" also works to install libraries from a folder.
I can tell you've never used "Add .ZIP Library". You can't use it to install individual library files. Only .zip files or folders containing the full library.

I have not because my Mac defaults to unzipping everything.

my Mac defaults to unzipping everything.

Naughty Mac !

Adding this for newbies who searched their way here: including a library does not load the library into the.IDE or sketch. Including the library allows the IDE to incorporate only those lines of code which are required at compile time. If you are running out of memory, the libraries you have included are not a factor.

I have been wondering about that to the point of just copying the needed lines from cpp and .h to my sketch.

Including the library allows the IDE to incorporate only those lines of code which are required at compile time

True, but

If you are running out of memory, the libraries you have included are not a factor.

Not true if the required lines of code or variables associated with them cause you to run out of memory

sevenoutpinball:
I have not because my Mac defaults to unzipping everything.

Including the .7z type which was the topic of my OP?

And what about the odd naming convention: the parentheses in the archive name and the fact that the libraries were contained in a directory "libraries" rather than something that usefully described the content?

This whole library thing will be the source of most of your consternation with the Arduino product.

Actually, the source of my consternation is more likely to be that I can't hook on the effing great logic analyser that I'm used to using for this type of work :slight_smile:

MarkMLl

UKHeliBob:
True, but
Not true if the required lines of code or variables associated with them cause you to run out of memory

Could I have a reality check here please. Am I correct in assuming that the granularity of the linker is that of an entire .cpp file (hence object file) and that it's unable to discard functions which aren't actually called?

MarkMLl

Functions that are not used are not compiled into the program but, of course, required functions and associated memory requirements may still cause you to run low on memory, which is the point that I was making