Arduino IDE 1.5: Library specification

WARNING

this document is a DRAFT. to be completed...

This specification is a proposal for a new 3rd party library format to be used within Arduino IDE. This new library format is intended to be used together with an automatic Library Manager, that will be implemented in future versions of the Arduino IDE 1.5 series.

New (multi-platform) libraries

What's new with the new library format?

There are a couple of new elements:

1. a properties file called library.properties inside the library root folder. The Arduino IDE looks for this file and if found handles the library as a "New" library. This file also contains a bunch of useful metadata about the library itself.

   Servo/library.properties

2. the library's source code should be put inside a src folder.

3. An optional folder for every architecture the library is going to support. For example:

   Servo/src/... - source code (common to all architectures) Servo/src/avr/... - source code (for AVR only) Servo/src/sam/... - source code (for ARM only) Servo/src/xxxx/... - source code (xxxx architecture)

4. An example folder (the same as for old-style libraries)

   Servo/examples/... - Examples, valid for all architecture

library.properties file format

[...to be done...]

When the user chooses a board the IDE automatically selects the correct library implementation for the board's architecture. If there isn't such implementation the library will be ignored.

The examples are shown only if the library has an implementation for the currently selected board architecture.

The packagers should agree on a common name for every available architecture.

The library.properties file is a safe way to detect NEW libraries against old-style libraries.

How libraries are searched in the IDE

Assuming PACKAGE and PLATFORM are the package and platform for the selected board, the IDE will search for libraries inside the following folders (in order of priority):

1. arduino/hardware/PACKAGE/PLATFORM/libraries
2. arduino/libraries
3. SKETCHBOOKFOLDER/libraries

Note that the libraries in folder 1. are available only when the specific platform and package are selected, while the other libraries are always available even if the currently selected CPU architecture is incompatible.

Since the NEW libraries can explicitly declare on which architecture they run on, the folder 1. is going to be dismissed at some point.