-
Notifications
You must be signed in to change notification settings - Fork 0
Arduino IDE 1.5: Library specification
WARNING
This specification is a proposal for a new 3rd party library format to be used in the Arduino IDE starting from version 1.5.4. 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.
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 important improvement is the possibility 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. Eventually, there will be a centralized repository, provided by Arduino, where contributed libraries will reside.
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, in future revisions.
The library's source code resides in the src folder.
Some libraries are optimized or contains code that runs on a specific CPU architecture: such code should be placed in a sub-folder of the arch folder for every architecture the library is going to support. 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
We can also provide an unoptimized variant 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 for old-style libraries).
Note that the examples folder must be written exactly like that (with lower case letters).
Servo/examples/... - Examples, valid for all architecture
The sketches contained inside the examples folder will be shown in the Examples menu of the IDE.
An extra 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 extra folder is totally ignored by the IDE, so the library's developer is free to put anything inside. On the other hand, the developer is denied to put anything that is not covered in this specification outside the extra 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 follows 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/extra/
Servo/extra/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 take care to set the include-path so only the correct one of the three is included (based on the currently selected board).
- 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
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 In this example, the Servo library is the pre-1.5 version. 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 showed at all and cannot be selected. Also the examples are shown only if the library has an implementation for the currently selected board's architecture.
The list of the implemented architectures is given through 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 libraries support. There is not 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.