Documentation for libraries 2.0


#1

Using libraries

Applications include the library using #include <library-name.h> instead of #include <library-name/library-name.h>.

Doing particle library add library-name adds the latest version of that library to project.properties. To update to a newer version, just do particle library add library-name again. To use a particular version, do particle library add library-name@0.1.0

If multiple versions of a library are requested (app depends on lib-a and lib-b, and lib-a depends on lib-b) then the highest version requested will be used.

Published libraries vs vendored libraries

Libraries available on api.particle.io are published. These are equivalent to the libraries previously published on Build. To use a published library, add it as a dependency in project.properties (or through the UI in Build) and it will be installed automatically by the compile server.

It is also possible to put libraries directly into the lib directory of a project. These are called vendored library (better name TBD). They are not added to project.properties and their code gets sent to the compile server.

Structure of a 2.0 library

For Arduino compatibilitiy metadata is now stored in library.properties instead of spark.json. Old libraries can be migrated to the new format with particle library migrate

+- doc +- examples | +- example1 | | +- example1.ino | +- example2 | +- example2.ino | +- otherfile.h +- src | +- other | | +- utils.h | +- TheLibrary.cpp | +- TheLibrary.h +- test | +- integration | | +- test1 | | +- test1.cpp | +- unit | +- test2 | +- test2.cpp +- library.properties

library.properties contains the name of the library, author, description and dependencies on other libraries. See the description of the Arduino library format for details. Dependencies is a Particle extension.

Libraries are added to the search path, so user applications refer to the library like this:
#include <TheLibrary.h>

Example library.properties

name=neopixel version=0.0.10 license=GNU GPLv3 author=Phil Burgess / Paint Your Dragon for Adafruit Industries maintainer=Brett Walach <technobly@gmail.com> sentence=Neopixel LED library paragraph=An Implementation of Adafruit's NeoPixel Library for the Spark Core, Particle Photon, P1, Electron and RedBear Duo category=Other url=https://github.com/technobly/SparkCore-NeoPixel architectures=avr,spark-core,particle-photon,particle-p1,particle-electron,redbear-duo

Structure of a project

Simple projects with the same flat structure as before but now support libraries!

Extended projects allow more complex projects to organize code in subdirectories and will also support libraries.

Extended projects also allow having vendored libraries, which means modified versions of published libraries that are stored in the same directory tree as the project source code.

+- doc +- lib | +- CustomLibrary | +- src | | +- CustomLibrary.h | | +- CustomLibrary.cpp | +- library.properties +- src | +- other | | +- common.h | +- application.cpp | +- header.h +- test | +- integration | | +- test1 | | +- test1.cpp | +- unit | +- test2 | +- test2.cpp +- project.properties <-- mandatory for extended project


Libraries 2.0 Resources guide
Publish a library
Examples in library prevent build?