-
-
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.
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 a future libraries manager to search and install a library and its dependencies in an easy and automatic way. There will be a centralized repository where (most of) all the libraries published will reside.
The file is a key=value property 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 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)
An Arduino library is composed of many folders (sources, examples, documentation, etc). Below an (almost) complete list:
The library's source code resides inside the src folder.
Some libraries are optimized for, or contains code that runs only 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 put unoptimized code inside a folder called 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 compiles and includes the following folders:
Servo/src/*
Servo/arch/avr/*
If we choose a board based on an architecture different from both avr and sam, the default folder is compiled:
Servo/src/*
Servo/arch/default/*
The implementation found inside default may the generic function provided by the Arduino core or by the standard C libraries, that may be slower but should be portable across different architectures.
Examples must be placed in the examples folder (the same as for old-style libraries).
Note that the examples folder should be named 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 everything considered useful to be bundled with the library. The content of this 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 of the old-style libraries.
Servo/kewords.txt
An hypothetical library that follows the specification could be the following:
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.
- 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, shown for every architecture
- there is one PDF file provided as documentation
When the user chooses a board the IDE automatically selects the correct library implementation for the board's architecture. If a library doesn't provides an implementation for the currently selected architecture, the library is now showed 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 names used for every available architecture.
Old libraries are deprecated, but they can still be used on the IDE 1.5.x series. In the future, when the new library format become more widespread, the support for old libraries will be dropped.
With the old libraries we didn't have any information on the architecture they works on: the library is always shown by the IDE but its not guaranteed to work on every architecture.
This is the best we can do with pre-1.5 libraries.