Perhaps this will help make library handling a little less painful. I hope so anyway. It’s based on my experience - I might have some stuff incorrect or incomplete below, hopefully I’ll be corrected if so.
PlatformIO Library Handling.
I’m assuming PlatformIO version 5.0.0 and above, as some of this stuff is new. I’m also only “skilled” (for want of a better word) in AVR stuff at the moment, so the following is biased towards AVR kit - Uno, Duemilanove, NormDuino!
None of the following will be global, everything relates to local installations for the current project.
How are Libraries Installed?
When you use lib_deps
, the library details are passed to the pio lib install
command to install the appropriate library locally.
Library Names
Adding the following to lib_deps
does different things:
-
lib_deps=servo
will install a library which is built in to the framework you are using. I’m on AVR so I get the Arduino Servo library installed for my project. The install is local to this project only.
-
lib_deps=NormanDunbar/Servo
will find and install the Servo library supplied by some bloke named NormanDunbar. In the event that there is a Servo library in the framework I’m using, it will not be used, only the NormanDunbar supplied one is used.
-
lib_deps=https://github.com/NormanDunbar/Servo.git
will look for a Servo library, on GitHub.com, under a repository named “Servo” and in the user “NormanDunbar”. Don’t go looking though, there isn’t one!
-
lib_deps=NDServo=https://github.com/NormanDunbar/Servo.git
I’m not sure about this one. I think it gives the afore mentioned GitHub Servo library, an alias? I’ve never used this option. Anyone want to jump in?
Library Version Numbers
The above will just install a library, whichever happens to be the latest version. Usually, that’s fine. However, sometimes a new version of a library will cause problems, for example, and should be ignored.
-
lib_deps=servo@1.2.3
will only ever install and use Servo library 1.2.3.
-
lib_deps=servo@^1.2.3 is the recommended method to use. It will use the library version given, or any backwards compatible future versions.
-
lib_deps=servo@~1.2.3
will only ever install or use the Servo library, versions 1.2.x where ‘x’ is 3 or higher.
-
lib_deps=servo@>1.2.3
will use any version of the library greater than version 1.2.3. The highest version found will be used.
-
lib_deps=servo@>=1.2.3
will use any version of the library greater than or equal to version 1.2.3. The highest version found will be used.
-
lib_deps=servo@<1.2.3
will use any version of the library less than version 1.2.3. The highest version found which is lower than 1.2.3, will be used.
-
lib_deps=servo@<=1.2.3
will use any version of the library less than or equal to version 1.2.3. The highest version found which is lower than 1.2.3, will be used assuming that 1.2.3 is not found.
So, you have version 1.2.3 of the servo library, but version 1.2.4 is available but has a bug that stops it working for you. What to do? Simple, tell PlatformIO not to use 1.2.4.
-
lib_deps=servo@>=1.2.3,!1.2.4
will use any version of the library greater than or equal to version 1.2.3, but not version 1.2.4. The highest allowed version found will be used.
Ah! But! There’s a version 2.0.0 out now, and it is not suitable for my board. 1.2.4 is still broken though. What can I do?
-
lib_deps=servo@>=1.2.3,!1.2.4,<2.0.0
will use any version of the library greater than or equal to version 1.2.3, but not version 1.2.4. The highest allowed version found which is less than version 2.0.0 will be used.
My Local Libraries
Ok, this is all well and good, but I have written my own libraries and I’ve got them saved away safely in a central location. How can I use them in my projects? Especially as I just want all my projects to use them, I don’t want to install each one each and every time I start a new project?
Let’s assume that I have this sort of thing set up. I don’t, but let’s assume under my central library directory named /home/norman/SourceCode/Libraries/
:
In each of those directories, I have the header and source files for my various libraries. I can therefore add the following line(s) to my ini file. There are three ‘/’ characters after the file
word, because I’m on Linux. I suspect, Windows would use file://c:\whatever\wherever\something
etc. (Don’t quote me!)
-
lib_deps=file:///home/norman/SourceCode/Libraries/AVRusart
to include my USART stuff.
If I need both libraries, I can do this:
I can even zip up the source and header files in each of those libraries to save space, and get PlatformIO to unzip them for me:
-
lib_deps=file:///home/norman/SourceCode/Libraries/AVRusart/AVRusart.zip
.
And, as I’m on Linux, I’m most likely to have a tar
red up and compressed source file.
-
lib_deps=file:///home/norman/SourceCode/Libraries/AVRusart/AVRusart.tar.gz
.
Where is my Library?
Assuming lib_deps=servo
, then the pio lib install
command will find the best version of the Servo library, and copy the source to <PROJECT_HOME>/.pio/libdeps/<ENVIRONMENT>/<LIBRARY_NAME>/
For my Uno, and the Servo library, that would be: /home/norman/SourceCode/PlatformIO/PIO_Servo/.pio/libdeps/uno/Servo/
.
Under that directory, I would (can!) see the following files and directories:
-
keywords.txt
the file which tells the Arduino IDE how to colourise keywords for this library.
-
library.properties
another Arduino IDE file for the library manager.
-
README.adoc
contains brief details about the library, and how it is licenced.
-
examples/
where the example sketches can be found – examples/Knob
and examples/Sweep
.
-
src/
where the source file(s) for the Servo library can be found for various frameworks. The header file Servo.h
lives in src/
. I have the following sub-directories where appropriate versions of the Servo library files live:
src/avr/
src/mbed/
src/megaavr/
src/ntf52/
src/sam/
src/samd/
src/stm32f4/
Compiling a library.
When you compile a project, any library sources will also be compiled into <PROJECT_HOME>/.pio/build/<ENVIRONMENT>/libnnnn<LIBRARY_NAME>/<FRAMEWORK_NAME>
which in my example is: /home/norman/SourceCode/PlatformIO/PIO_Servo/.pio/build/uno//lib506/Servo/
Note: I have no idea where the lib506
comes from!
Summary
I never, manually download a library and install it somewhere. I let PlatformIO do all the hard work of finding and installing the libraries for me.
I don’t use global libraries, each project gets its own install, if necessary, locally.
Lib_deps
does all the hard work for me, I don’t even have to think about it.
Have fun!