@@ -5,8 +5,8 @@ This is the specification for the 3rd party library format to be used with Ardui
* rev.2.1 will be implemented starting from version 1.6.10
* rev.2.2 will be implemented starting from version 1.8.10
This new library format is intended to be used in tandem with the Arduino IDE"s **Library Manager**, available since version 1.6.2. The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy to use graphic interface. It doesn't yet take care of dependencies between libraries.
More information about how Library Manager works are available [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
This new library format is intended to be used in tandem with the Arduino IDE's **Library Manager**, available since version 1.6.2. The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy to use graphic interface. It doesn't yet take care of dependencies between libraries.
More information about how Library Manager works is available [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
Arduino IDE 1.5.x+ supports multiple microcontroller architectures (e.g. AVR, SAM, etc), meaning that libraries may need to work on multiple architectures. The new 1.5 library format doesn’t contain special support for cross-architecture libraries, but it does provide a preprocessor based mechanism for libraries to target sections of code to specific architectures.
...
...
@@ -28,31 +28,29 @@ This file allows the *Library Manager* to search and install a library and its d
The library.properties file is a key=value properties list. Every field in this file is UTF-8 encoded. Unless noted otherwise below, **all fields are required**. The available fields are:
***name** - the name of the library. Library names must contain only basic letters (`A`-`Z` or `a`-`z`) and numbers (`0`-`9`), spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). It cannot start or end with a space, and also it cannot start with a number. Note that libraries with a `name` value starting with `Arduino` will no longer be allowed [addition to the Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) as these names are now reserved for official Arduino libraries.
***version** - version of the library. Version should be [semver](http://semver.org/) compliant. 1.2.0 is correct; 1.2 is accepted; r5, 003, 1.1c are invalid
***author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma ","
***maintainer** - name and email of the maintainer
***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
***category** - (defaults to `Uncategorized`) if present, one of these:
* Display
* Communication
* Signal Input/Output
* Sensors
* Device Control
* Timing
* Data Storage
* Data Processing
* Other
***url** - the URL of the library project, for a person to visit. For example, the library's GitHub page. This is used for the "More info" links in Library Manager
***architectures** - (defaults to `*`) a comma separated list of architectures supported by the library. If the library doesn’t contain architecture specific code use `*` to match all architectures. This field is used as one factor in determining priority when multiple libraries match an `#include` directive and to provide a warning message when the library is compiled for a board of an architecture that doesn't match any on the list.
***depends** - **(available from Arduino IDE 1.8.10)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). Library Manager will offer to install the dependencies during installation of the library. Since spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the name without ambiguity for example:
`depends=Very long library name, Another library with long-name`
***dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as normal. Then instead of including all .o files in the linker command directly, all .o files are saved into a .a file, which is then included in the linker command. [1.5 format library folder structure](#layout-of-folders-and-files) is required.
***includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the IDE. If the `includes` property is missing all the headers files (.h) on the root source folder are included.
***precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. The static library should be linked as an ldflag.
***name** - the name of the library. Library names must contain only basic letters (`A`-`Z` or `a`-`z`) and numbers (`0`-`9`), spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). It cannot start or end with a space, and also it cannot start with a number. Note that libraries with a `name` value starting with `Arduino` will no longer be allowed [addition to the Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) as these names are now reserved for official Arduino libraries.
***version** - version of the library. Version should be [semver](http://semver.org/) compliant. 1.2.0 is correct; 1.2 is accepted; r5, 003, 1.1c are invalid
***author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma ","
***maintainer** - name and email of the maintainer
***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
***category** - (defaults to `Uncategorized`) if present, one of these:
* Display
* Communication
* Signal Input/Output
* Sensors
* Device Control
* Timing
* Data Storage
* Data Processing
* Other
***url** - the URL of the library project, for a person to visit. For example, the library's GitHub page. This is used for the "More info" links in Library Manager
***architectures** - (defaults to `*`) a comma separated list of architectures supported by the library. If the library doesn’t contain architecture specific code use `*` to match all architectures. This field is used as one factor in determining priority when multiple libraries match an `#include` directive and to provide a warning message when the library is compiled for a board of an architecture that doesn't match any on the list.
***depends** - **(available from Arduino IDE 1.8.10)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). Library Manager will offer to install the dependencies during installation of the library. Since spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the name without ambiguity for example:<br>
`depends=Very long library name, Another library with long-name`
***dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as normal. Then instead of including all .o files in the linker command directly, all .o files are saved into a .a file, which is then included in the linker command. [1.5 format library folder structure](#layout-of-folders-and-files) is required.
***includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the IDE. If the `includes` property is missing, all the header files (.h) on the root source folder are included.
***precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. The static library should be linked as an ldflag.
***ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. Ex: `ldflags=-lm`
Example:
...
...
@@ -84,7 +82,7 @@ For 1.5.x+-only libraries, the source code resides in the **src** folder. For ex
Servo/src/Servo.h
Servo/src/Servo.cpp
The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the "Tools > Import Library" menu), an #include statement will be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.
The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the "Sketch > Include Library" menu), an `#include` statement will be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.
For backward compatibility with Arduino 1.0.x, the library author may opt to place source code into the root folder, instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched from the **library root folder** and the **utility** folder, for example:
...
...
@@ -115,7 +113,7 @@ A list of keywords for the library may be specified in a file named keywords.txt
Servo/keywords.txt
An example keywords file:
An example keywords.txt file:
```
# Syntax Coloring Map For ExampleLibrary
...
...
@@ -129,7 +127,7 @@ doSomething KEYWORD2
# Constants (LITERAL1)
```
This keywords file would cause the Arduino IDE to highlight `Test` as a DataType, and `doSomething` as a method / function.
This file would cause the Arduino IDE to highlight `Test` as a DataType, and `doSomething` as a method / function.
#### keywords.txt format
keywords.txt is formatted in four fields which are separated by a single true tab (not spaces):
...
...
@@ -183,7 +181,7 @@ A hypothetical library named "Servo" that adheres to the specification follows:
## Working with multiple architectures
In 1.5.x+, libraries placed in the user’s sketchbook folder (in the libraries/ subfolder) will be made available for all boards, which may include multiple different processor architectures. To provide architecture-specific code or optimizations, library authors can use the ARDUINO_ARCH_XXX preprocessor macro (#define), where XXX is the name of the architecture (as determined by the name of the folder containing it), e.g. ARDUINO_ARCH_AVR will be defined when compiling for AVR-based boards. For example,
In 1.5.x+, libraries placed in the user’s sketchbook folder (in the libraries/ subfolder) will be made available for all boards, which may include multiple different processor architectures. To provide architecture-specific code or optimizations, library authors can use the `ARDUINO_ARCH_XXX` preprocessor macro (`#define`), where XXX is the name of the architecture (as determined by the name of the folder containing it), e.g. `ARDUINO_ARCH_AVR` will be defined when compiling for AVR-based boards. For example,
This specification is a 3rd party Hardware format to be used in Arduino IDE starting from 1.5.x series.<br>
This specification is a 3rd party hardware format to be used in Arduino IDE starting from 1.5.x series.<br>
This specification allows a 3rd party vendor/maintainer to add support for new boards inside the Arduino IDE by providing a file to unzip into the *hardware* folder of Arduino's sketchbook folder.<br>
It is also possible to add new 3rd party boards by providing just one configuration file.
## Hardware Folders structure
The new hardware folders have a hierarchical structure organized in two levels:
- the first level is the vendor/maintainer
- the second level is the supported architecture
...
...
@@ -57,7 +58,7 @@ will set the property **tools.bossac.cmd** to the value **bossac** on Linux and
#### Global Predefined properties
The Arduino IDE sets the following properties that can be used globally in all configurations files:
The Arduino IDE sets the following properties that can be used globally in all configuration files:
*`{runtime.platform.path}`: the absolute path of the [board platform](#platform-terminology) folder (i.e. the folder containing boards.txt)
*`{runtime.hardware.path}`: the absolute path of the hardware folder (i.e. the folder containing the [board platform](#platform-terminology) folder)
...
...
@@ -79,13 +80,14 @@ The following meta-data must be defined:
version=1.5.3
The **name** will be shown in the Boards menu of the Arduino IDE.<br>
The **version** is currently unused, it is reserved for future use (probably together with the libraries manager to handle dependencies on cores).
The **version** is currently unused, it is reserved for future use (probably together with the Boards Manager to handle dependencies on cores).
### Build process
The platform.txt file is used to configure the build process performed by the Arduino IDE. This is done through a list of **recipes**. Each recipe is a command line expression that explains how to call the compiler (or other tools) for every build step and which parameter should be passed.
The Arduino IDE, before starting the build, determines the list of files to compile. The list is composed by:
The Arduino IDE, before starting the build, determines the list of files to compile. The list is composed of:
- the user's Sketch
- source code in the selected board's Core
- source code in the Libraries used in the sketch
...
...
@@ -413,7 +415,7 @@ In this example if the user enables verbose mode, then **{upload.params.verbose}
Most Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interpret a bitrate of 1200bps as a signal the bootloader should be started.
#### 1200bps bootloader reset
Most Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interprets a bitrate of 1200 bps as a signal the bootloader should be started.
To let the IDE perform these steps, two board parameters can be set:
*`use_1200bps_touch` causes the IDE to briefly open the selected serial port at 1200bps (8N1) before starting the upload.
*`wait_for_upload_port` causes the IDE to wait for the serial port to (re)appear before and after the upload. This is only used when `use_1200bps_touch` is also set. When set, after doing the 1200bps touch, the IDE will wait for a new serial port to appear and use that as the port for uploads. Alternatively, if the original port does not disappear within a few seconds, the upload continues with the original port (which can be the case if the board was already put into bootloader manually, or the IDE missed the disconnect and reconnect). Additionally, after the upload is complete, the IDE again waits for a new port to appear (or the originally selected port to be present).
*`use_1200bps_touch` causes the IDE to briefly open the selected serial port at 1200bps (8N1) before starting the upload.
*`wait_for_upload_port` causes the IDE to wait for the serial port to (re)appear before and after the upload. This is only used when `use_1200bps_touch` is also set. When set, after doing the 1200bps touch, the IDE will wait for a new serial port to appear and use that as the port for uploads. Alternatively, if the original port does not disappear within a few seconds, the upload continues with the original port (which can be the case if the board was already put into bootloader manually, or the IDE missed the disconnect and reconnect). Additionally, after the upload is complete, the IDE again waits for a new port to appear (or the originally selected port to be present).
Note that the IDE implementation of this 1200bps touch has some peculiarities, and the newer `arduino-cli` implementation also seems different (does not wait for the port after the reset, which is probably only needed in the IDE to prevent opening the wrong port on the serial monitor, and does not have a shorter timeout when the port never disappears).
Note that the IDE implementation of this 1200bps touch has some peculiarities, and the newer `arduino-cli` implementation also seems different (does not wait for the port after the reset, which is probably only needed in the IDE to prevent opening the wrong port on the serial monitor, and does not have a shorter timeout when the port never disappears).
### Serial port
...
...
@@ -554,7 +556,7 @@ Note that we don't need to specify any architecture since the same architecture
The platform.txt settings are inherited from the referenced core platform, thus there is no need to provide a platform.txt unless there are some specific properties that need to be overridden.
The libraries from the referenced platform are used, thus there is no need to provide a libraries. If libraries are provided the list of available libraries are the sum of the 2 libraries where the referencing platform has priority over the referenced platform.
The libraries from the referenced platform are used, thus there is no need to provide those libraries. If libraries are provided the list of available libraries are the sum of the 2 libraries where the referencing platform has priority over the referenced platform.
In the same way we can use variants and tools defined on another platform:
...
...
@@ -570,6 +572,7 @@ Note that referencing a variant in another platform does *not* inherit any prope
### Platform Terminology
Because boards can reference cores, variants and tools in different platforms, this means that a single build or upload can use data from up to four different platforms. To keep this clear, the following terminology is used:
* The "board platform" is the platform that defines the currently selected board (e.g. the platform that contains the board.txt the board is defined in.
* The "core platform" is the the platform that contains the core to be used.
* The "variant platform" is the platform that contains the variant to be used.
@@ -7,12 +7,13 @@ A number of things have to happen for your Arduino code to get onto the Arduino
## Pre-Processing
The Arduino environment performs a few transformations to your sketch before passing it to the avr-gcc compiler:
- All .ino and .pde files in the sketch folder (shown in the IDE as tabs with no extension) are concatenated together, starting with the file that matches the folder name followed by the others in alphabetical order, and the .cpp extension is added to the filename.
- If not already present, `#include <Arduino.h>` is added to the sketch. This header file (found in the core folder for the currently selected board) includes all the definitions needed for the standard Arduino core.
- Prototypes are generated for all function definitions in .ino/.pde files that don't already have prototypes. In some rare cases prototype generation may fail for some functions. To work around this, you can provide your own prototypes for these functions.
-`#line` directives are added to make warning or error messages reflect the original sketch layout.
No pre-processing is done to files in a sketch with any extension other than .ino or .pde. Additionally, .h files in the sketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .c file from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in an 'extern "C" {}' block that is defined only inside of C++ files.
No pre-processing is done to files in a sketch with any extension other than .ino or .pde. Additionally, .h files in the sketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .c file from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in an `extern "C" {}` block that is defined only inside of C++ files.
## Dependency Resolution
...
...
@@ -37,6 +38,7 @@ If multiple libraries contain a file that matches the `#include` directive, the
### Architecture Matching
A library is considered **compatible** with architecture `X` if the `architectures` field in [library.properties](library-specification.md#library-metadata):
- explicitly contains the architecture `X`
- contains the catch-all `*`
- is not specified at all.
...
...
@@ -83,7 +85,7 @@ Sketches are compiled by avr-gcc and avr-g++ according to the variables in the b
The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux).
Files taken as source files for the build process are .S, .c and .cpp files (including the .cpp file generated from the sketch's .ino and .pde files during the sketch pre-processing step).
Source files of the target are compiled and output with .o extensions to this build directory, as are the main sketch files and any other source files in the sketch and any source files in any libraries which are #included in the sketch.
Source files of the target are compiled and output with .o extensions to this build directory, as are the main sketch files and any other source files in the sketch and any source files in any libraries which are `#include`d in the sketch.
Before compiling a source file, an attempt is made to reuse the previously compiled .o file, which speeds up the build process. A special .d (dependency) file provides a list of all other files included by the source. The compile step is skipped if the .o and .d files exist and have timestamps newer than the source and all the dependent files. If the source or any dependent file has been modified, or any error occurs verifying the files, the compiler is run normally, writing a new .o & .d file. After a new board is selected from the Tools menu, all source files are rebuilt on the next compile.
