-
Notifications
You must be signed in to change notification settings - Fork 0
Arduino IDE 1.5: Library specification
This specification is a proposal for a new 3rd party library format to be used in the Arduino IDE starting with version 1.5.3. This new library format is intended to be used in tandem with an automatic Library Manager, that will be implemented in future versions of the Arduino IDE. The Library Manager will allow users to automatically download and install the libraries needed in their projects, taking care of dependencies between libraries, with an easy to use graphic interface. Eventually, there will be an online centralized repository, provided by Arduino, where contributed libraries will reside.
The Arduino library style guide is here : http://arduino.cc/en/Reference/APIStyleGuide
The style guide for examples is here : http://arduino.cc/en/Reference/StyleGuide
The most significant addition to the format is the ability to add information about the library itself through a properties file called library.properties.
This file will allow the future Library Manager to search and install a library and its dependencies in an easy and automated way.
The library.properties file is a key=value properties list. Every field in this file is UTF8 encoded. The available fields are:
name - the actual name of the library
author - the author's username
email - the author’s name and email
sentence - a sentence explaining the purpose of the library
paragraph - a longer description of the library. The value of sentence always will be prepended, so you should start by writing the second sentence here.
url - 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 * and ? 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]>
sentence=A library that makes coding a Webserver a breeze.
paragraph=Supports HTTP1.1 and you can do GET and POST.
url=http://asdasd.com/
architectures=avr,sam
version=1.0
dependencies=Ethernet (>=1.0),Servo (=2.0)
core-dependencies=arduino (>=1.5.0)
Arduino libraries will be composed of a number of folders. Each folder has a specific purpose (sources, examples, documentation, etc). Folders not covered in this specification may be added as needed to future revisions.
The library's source code resides in the src folder. Code for libraries that are optimized for a specific CPU architecture should be placed in a sub-folder of the arch folder for each architecture the library supports. For example:
Servo/src/... - source code common to all architectures.
Servo/arch/avr/... - source code optimized for AVR architecture only
Servo/arch/sam/... - source code optimized for ARM architecture only
Servo/arch/xxxx/... - source code optimized for an hypothetical xxxx architecture
An unoptimized variant can reside inside a folder called arch/default. This folder will be used when a version optimized for the current architecture is not found.
Servo/arch/default/... - source code not optimized
For example, if we try to compile the above library for a board based on AVR architecture, the IDE will automatically compile and include the following folders:
Servo/src/*
Servo/arch/avr/*
If we choose a board based on an architecture that is different from both AVR and SAM, the default folder is compiled:
Servo/src/*
Servo/arch/default/*
The implementation found inside default may use the generic functions provided by the Arduino core or use the standard C libraries that are slower, but which have the advantage of being portable across different architectures.
Library examples must be placed in the examples folder (the same as with pre-1.5 libraries).
Note that the examples folder must be written exactly like that (with lower case letters).
Servo/examples/... - Examples, valid for all architecture
Sketches contained inside the examples folder will be shown in the Examples menu of the IDE.
An extras folder can be used by the developer to put documentation or other items to be bundled with the library. Remember that files placed inside this folder will increase the size of the library, so putting a 20MB PDF in a library that weights a few kilobytes may be not a good idea.
The content of the extras folder is totally ignored by the IDE; you are free to put anything inside such as supporting documentation, etc. Similarly, you cannot put anything that is not covered in this specification outside the extras folder.
The list of highlighted keywords must be placed in a file called keywords.txt. The format of this file is the same as the old-style libraries.
Servo/kewords.txt
A hypothetical library named "Servo" that adheres to the specification follows:
Servo/
Servo/library.properties
Servo/keywords.txt
Servo/src/
Servo/src/Servo.h
Servo/arch/avr/
Servo/arch/avr/ServoTimers.h
Servo/arch/avr/Servo.cpp
Servo/arch/sam/
Servo/arch/sam/ServoTimers.h
Servo/arch/sam/Servo.cpp
Servo/arch/default/
Servo/arch/default/ServoTimers.h
Servo/arch/default/Servo.cpp
Servo/examples/
Servo/examples/Sweep/Sweep.ino
Servo/examples/Pot/Pot.ino
Servo/extras/
Servo/extras/Servo_Connectors.pdf
Some notes:
- the library has a Servo.h file that is common for every architecture.
- there are three copies of ServoTimers.h, one for AVR architecture, one for SAM, and one that is generic (default).
- ServoTimers.h is included from Servo.h. The IDE will set the include-path based on the currently selected board so only the correct version of the file is included.
- the same happens for the Servo.cpp file: there are three variants of this file, but only one is compiled and linked by the IDE.
- there are two examples, these are the same for every architecture
- there is one PDF file provided as documentation in the extras folder
You can see an example of how an existing library can be ported to the new structure here: https://github.com/cmaglie/LibTest/tree/master/libraries/Servo2 Servo2 is the 1.5+ version of the library, explicitly supporting two different architectures.
When the user chooses a board the IDE automatically selects the correct library implementation for the board's architecture. If a library doesn't provide an implementation for the currently selected architecture, the library is not displayed cannot be selected. Examples are shown only if the library has an implementation for the currently selected board architecture.
The list of the supported architectures is provided in the architectures field in the library.properties file. For example, the following settings:
[....]
architectures=avr,sam
[....]
means that the library is shown only for AVR and SAM architectures, while:
[....]
architectures=*
[....]
means that the library is shown for every architecture.
Library packagers should agree on short-names used for every available architecture.
Old libraries are deprecated, but they can still be used on the Arduino IDE 1.5 series.
At some point in the future, the IDE will drop pre-1.5 library support. There is no specific timeline for this, it will be determined once the new library format has become widespread.
In the old library structure there is no information regarding the architecture they worked on. This led to some instances where the the library would be shown by the IDE but it may not have worked with the selected architecture.