Arduino IDE 1.5 3rd party Hardware specification

WARNING

This document is a Draft... to be completed!

This specification is a proposal of a new 3rd party Hardware format to be used in Arduino IDE starting from 1.5 series.
The correct implementation of this specification allows a 3rd party vendor/maintainer to add support for his boards to the Arduino IDE just by unzipping a file into the hardware folder of Arduino. It should be possible also to make a singlefile-hardware-addon that means adding a new 3rd party board(s) to Arduino IDE by providing just one configuration file.

Hardware Folders structure

New hardware folders are structured in two levels: the first level is the vendor/mantainer name; the second level is the name of supported architecture(s).

In the example below we have three hardware vendors called respectively "arduino", "yyyyy" and "xxxxx":

hardware/arduino/avr/...     - Arduino - AVR Boards
hardware/arduino/sam/...     - Arduino - SAM (32bit ARM) Boards
hardware/yyyyy/avr/...       - Yyy - AVR
hardware/xxxxx/avr/...       - Xxx - AVR

as already said, each vendor folder contains a second level of folders that are the architectures supported: in the example above the vendor "arduino" has two supported architecures (avr and sam), while "xxxxx" and "yyyyy" have only avr.

Architecture configurations

Each architecture of each vendor must be configured through a set of configuration files:

boards.txt - Definitions of the boards (board's metadata, parameters for building and uploading sketches, etc.)
platform.txt - Definitions for the CPU architecture used on the boards (compiler, build process parameters, tools used for upload, etc.)
programmers.txt - Definitions for external programmers (typically used to burn bootloaders on a blank CPU/board)

Before looking at the content of these file one by one, let's explain the format of these files.

Configuration files format

The configuration files are a list of "variable=value" properties. The value of every variable can be expressed using the value of another variable by putting his name inside brackets "{" "}". For example:

compiler.path=/tools/g++_arm_none_eabi/bin/
compiler.c.cmd=arm-none-eabi-gcc
[....]
recipe.c.o.pattern={compiler.path}{compiler.c.cmd}

in this example the variable recipe.c.o.pattern will be set to /tools/g++_arm_none_eabi/bin/arm-none-eabi-gcc that is the composition of the two variables compiler.path and compiler.c.cmd.

Global Predefined variables

The Arduino IDE sets the following variables that can be used in all configurations files:

runtime.hardware.path - the absolute path to the hardware folder
runtime.ide.path - the absolute path to the Arduino IDE folder
runtime.ide.version - the version number of the Arduino IDE as a number (for example "152" for Arduino IDE 1.5.2)
runtime.os - the running OS ("linux", "windows", "macosx")

Automatic variable selection for specific OS

We can specify an OS-specific value for a variable. For example the following snippet:

tools.bossac.cmd=bossac
tools.bossac.cmd.windows=bossac.exe

will set the variable tools.bossac.cmd to the value bossac on linux and macos and bossac.exe on windows.

Build process and platform.txt configuration file

The platform.txt file is used to configure the build process performed by the Arduino IDE through a list of recipes. Each recipe specify how to call the compiler or tools for every build step and which parameter should be passed to them.

The build process is performed by the Arduino IDE in 6 steps

1. Source compile

The Arduino IDE determine a list of files to compile. This list contains source code in C (.c files), C++ (.cpp files) or Assembly (.S files). Every language is compiled using its respective recipe

recipe.c.o.pattern       - for C files
recipe.cpp.o.pattern     - for CPP files
recipe.S.o.pattern       - for Assembly files

these recipe variables can be built using the following utility variables set by the IDE for each file:

ide_version              - the IDE version (ex. "152" for Arduino IDE 1.5.2)
includes                 - the list of include paths in the format "-I/include/path -I/another/path...."
source_file              - the path to the source file
object_file              - the path to the output file

TODO The recipes are defined for each type of file to be compiled (C, C++) through the variables:

recipe.ar.pattern
recipe.c.combine.pattern
recipe.objcopy.eep.pattern
recipe.objcopy.hex.pattern
recipe.size.pattern
recipe.size.regex