-
-
Notifications
You must be signed in to change notification settings - Fork 7k
Arduino IDE 1.5: Library specification
WARNING
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.
Let's look directly to an example:
Servo/
Servo/library.properties
Servo/keywords.txt
Servo/src/
Servo/src/Servo.h
Servo/src/Servo.cpp
Servo/src/avr/
Servo/src/avr/Servo.cpp
Servo/src/sam/
Servo/src/sam/Servo.cpp
Servo/examples/
Servo/examples/Sweep/Sweep.ino
Servo/examples/Pot/Pot.ino
Servo/extra/
Servo/extra/Servo_Connectors.pdf
There are a couple of new elements:
-
the most important is 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 meta-data about the library itself (more on that below).
Servo/library.properties
-
the library's source code resides inside a src folder.
-
code for specific architectures resides in an optional sub-folder for every architecture the library is going to support. For example:
Servo/src/... - source code (common to all architectures) Servo/src/arch-avr/... - source code (for AVR only) Servo/src/arch-sam/... - source code (for ARM only) Servo/src/arch-xxxx/... - source code (for an hypothetical xxxx architecture)
-
examples resides in the examples folder (the same as for old-style libraries)
Servo/examples/... - Examples, valid for all architecture
-
an extra folder that can be used by the developer to put everything considered useful to be bundled with the library
-
An important rule: no other sub-folders or files must be put inside the library root. Any root's sub-folder or file is reserved for future expansion of this specification.
This file contains a property list with various meta-data about the library. These data is used by a library management system that will allow to download and install a library (and its dependencies) automatically. There will be a centralized repository where (most of) all the libraries published will reside.
Every field in this file is UTF8 encoded.
name - the actual name of the library
author - the author's username
email - the author’s name and email
description - a sentence or paragraph explaining the propose of the library
homepage - the URL of the library project, for a person to visit. Can be a github or similar page as well.
architectures - a list of supported architectures (wildcards allowed)
version - version string, numeric only
dependencies - a list of other libraries that are needed by this one, optionally including version numbers
core-dependecies - the core on which this library works on (multiple cores can be specified)
Example:
name=WebServer
author=cmaglie
email=Cristian Maglie <[email protected]>
description=A library that makes coding Webserver a breeze.
homepage=http://asdasd.com/
architectures=avr,sam
version=1.0
dependencies=Ethernet (>=1.0)
core-dependencies=arduino (>=1.0.0)
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.
Library packagers should agree on a common name for every available architecture.
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):
- arduino/hardware/PACKAGE/PLATFORM/libraries
- arduino/libraries
- 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.