-
-
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 in Arduino IDE starting from version 1.5. This new library format is intended to be used together with an automatic Libraries Manager, that will be implemented in future versions of the Arduino IDE.
The most important improvement is the possibility to add information about the library itself through a properties file called library.properties.
This file allows a future Libraries Manager to search and install a library and its dependencies in an easy and automated way. There will be a centralized repository, provided by Arduino, where (hopefully) all the published 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 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. Each folder is reserved for 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 compiles and includes 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 they have the advantage to be 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 stuff to be bundled with the library. Consider that the files placed inside this folder will increase the size of the library, so putting a 20MB PDF in a library that weights a bunch of 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
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 (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, 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 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.
By the way, future releases of the IDE, at some point, will drop the pre-1.5 libraries support, when the new library format become more widespread.
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.