[skip changelog] Migrate relevant documentation pages from arduino/Arduino wiki (#616)

* Migrate relevant documentation from arduino/Arduino wiki

* Trim trailing whitespace

* Add newline to end of file

* Increase heading levels so that the minimum level is h2

This is required for table of contents generation.

* Use supported line break markup

The backslash at end of line to cause line break is not supported by the documentation build system.

* Update links to migrated pages

* Fix list markup

The documentation build system requires a blank line before the start of a list

Author: per1234

docs/FAQ.md

@@ -11,8 +11,8 @@ When you run `arduino-cli board list`, your board doesn't show up. Possible caus
 ##  What's the FQBN string?
 
 For a deeper understanding of how FQBN works, you should understand
-Arduino Hardware specification. You can find more information in this
-[arduino/Arduino wiki page][0].
+Arduino Hardware specification. You can find more information in the
+[Arduino platform specification][0].
 
 
-[0]: https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification
+[0]: platform-specification.md

docs/img/boards-manager-screenshot.png

@@ -0,0 +1,208 @@
+This is the specification for the 3rd party library format to be used with Arduino IDE 1.5.x onwards.
+
+* rev.1 has been implemented starting with IDE version 1.5.3 (now superseded by rev.2)
+* rev.2 will be implemented starting from version 1.5.6
+* 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).
+
+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.
+
+## See also
+
+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
+
+## 1.5 library format (rev. 2.2)
+
+### Library metadata
+
+The most significant addition to the format is the ability to add information about the library itself through a properties file called **library.properties**.
+
+This file allows the *Library Manager* to search and install a library and its dependencies in an easy and automated way. It must be located in the root of the library folder.
+
+#### library.properties file format
+
+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.
+* **ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. Ex: `ldflags=-lm`
+
+Example:
+
+    name=WebServer
+    version=1.0.0
+    author=Cristian Maglie <c.maglie@example.com>, Pippo Pluto <pippo@example.com>
+    maintainer=Cristian Maglie <c.maglie@example.com>
+    sentence=A library that makes coding a Webserver a breeze.
+    paragraph=Supports HTTP1.1 and you can do GET and POST.
+    category=Communication
+    url=http://example.com/
+    architectures=avr
+    includes=WebServer.h
+    depends=ArduinoHttpClient
+
+### Layout of folders and files
+
+Each folder has a specific purpose (sources, examples, documentation, etc). Folders not covered in this specification may be added as needed to future revisions.
+
+#### Library Root folder
+
+The library root folder name must start with a basic letter (`A`-`Z` or `a`-`z`) or number (`0`-`9`), followed by basic letters, numbers, spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). The maximum length is 63 characters.
+
+#### Source code
+
+For 1.5.x+-only libraries, the source code resides in the **src** folder. For example:
+
+    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.
+
+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:
+
+    Servo/Servo.h
+    Servo/Servo.cpp
+    Servo/utility/ServoTimers.h
+    Servo/utility/ServoTimers.cpp
+
+This will allow existing 1.0.x libraries to compile under 1.5.x+ as well and vice-versa. If a library only needs to run on 1.5.x+, we recommend placing all source code in the src/ folder. If a library requires recursive compilation of nested source folders, its code must be in the src/ folder (since 1.0.x doesn’t support recursive compilation, backwards compatibility wouldn’t be possible anyway).
+
+#### Library Examples
+
+Library examples must be placed in the **examples** folder. Note that the **examples** folder must be written exactly like that (with lower case letters).
+
+    Servo/examples/...
+
+Sketches contained inside the examples folder will be shown in the Examples menu of the IDE.
+
+#### Extra documentation
+
+An **extras** 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 not be such a good idea.
+
+The content of the *extras* folder is totally ignored by the IDE; you are free to put anything inside such as supporting documentation, etc.
+
+### Keywords
+
+A list of keywords for the library may be specified in a file named keywords.txt located in the root of the library folder. When a keyword of any installed library is used in a sketch the Arduino IDE colors it.
+
+    Servo/keywords.txt
+
+An example keywords file:
+```
+# Syntax Coloring Map For ExampleLibrary
+
+# Datatypes (KEYWORD1)
+Test	KEYWORD1
+
+# Methods and Functions (KEYWORD2)
+doSomething	KEYWORD2
+
+# Instances (KEYWORD2)
+
+# Constants (LITERAL1)
+```
+This keywords 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):
+```
+KEYWORD	KEYWORD_TOKENTYPE	REFERENCE_LINK	RSYNTAXTEXTAREA_TOKENTYPE
+```
+It is permitted to leave a field empty.
+##### `KEYWORD_TOKENTYPE`
+KEYWORD_TOKENTYPE | Use for | Theme property
+---|---|---
+`KEYWORD1` | datatypes | `editor.data_type.style`
+`KEYWORD2` | functions | `editor.function.style`
+`KEYWORD3` | structures | `editor.function.style`
+`LITERAL1` | constants | `editor.reserved_word_2.style`
+`LITERAL2` | ? | `editor.function.style`
+
+##### `REFERENCE_LINK`
+This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via **Right Click > Find in Reference** or **Help > Find in Reference** when the cursor is on that keyword. Generally it does not make sense to define the `REFERENCE_LINK` field for 3rd party library keywords since they are not likely to be in the Arduino Language Reference.
+
+##### `RSYNTAXTEXTAREA_TOKENTYPE`
+In Arduino IDE 1.6.5 and newer this field overrides `KEYWORD_TOKENTYPE`. In previous IDE versions the `RSYNTAXTEXTAREA_TOKENTYPE` field is ignored and `KEYWORD_TOKENTYPE` is used instead.
+
+RSYNTAXTEXTAREA_TOKENTYPE | Theme property | KEYWORD_TOKENTYPE equivalent
+---|---|---
+`RESERVED_WORD` | `editor.reserved_word.style` | `KEYWORD3`
+`RESERVED_WORD_2` | `editor.reserved_word_2.style` | `LITERAL1`
+`DATA_TYPE` | `editor.data_type.style` | `KEYWORD1`
+`PREPROCESSOR` | `editor.preprocessor.style` | `KEYWORD3`
+`LITERAL_BOOLEAN` | `editor.literal_boolean.style` | `LITERAL1`
+
+### Development flag file
+
+Normally the Arduino IDE treats the contents of the library folder as read-only. This is to prevent users from accidentally modifying example sketches. During the library development process you may want to edit example sketches in place using the Arduino IDE. With Arduino IDE 1.6.6 and newer, the read-only behavior can be disabled by adding a file named .development to the root of the library folder. A [library.properties](#libraryproperties-file-format) file must also be present. The [Library Manager indexer](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) will not pick up releases that contain a .development file so be sure not to push this file to your remote repository.
+
+### A complete example
+
+A hypothetical library named "Servo" that adheres to the specification follows:
+
+    Servo/
+    Servo/library.properties
+    Servo/keywords.txt
+    Servo/src/
+    Servo/src/Servo.h
+    Servo/src/Servo.cpp
+    Servo/src/ServoTimers.h
+    Servo/examples/
+    Servo/examples/Sweep/Sweep.ino
+    Servo/examples/Pot/Pot.ino
+    Servo/extras/
+    Servo/extras/Servo_Connectors.pdf
+
+## 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,
+
+    #if defined(ARDUINO_ARCH_AVR)
+      // AVR-specific code
+    #elif defined(ARDUINO_ARCH_SAM)
+      // SAM-specific code
+    #else
+      // generic, non-platform specific code
+    #endif
+
+Alternatively, if a library only works on certain architectures, you can provide an explicit error message (instead of allowing the compilation to fail in a difficult to understand way):
+
+    #if defined(ARDUINO_ARCH_AVR)
+      // AVR-specific code
+    #elif defined(ARDUINO_ARCH_SAM)
+      // SAM-specific code
+    #else
+      #error “This library only supports boards with an AVR or SAM processor.”
+    #endif
+
+## Old library format (pre-1.5)
+
+In order to support old libraries (from Arduino 1.0.x), Arduino 1.5.x+ will also compile libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in 1.0.x).

docs/library-specification.md

@@ -0,0 +1,302 @@
+Starting from version 1.6.4 the Boards Manager of the Arduino IDE can be used to automatically install support for **3rd party hardware** by simply entering an URL in the **File > Preferences** dialog. The URL must be provided by the 3rd party hardware producer and should point to a JSON file that contains an index of the boards available to install and the location of the installation archives. Boards Manager also allows easy updates of installed Boards when new versions are released.
+
+## Naming of the JSON index file
+
+The IDE may use many different index files coming from different vendors, so each vendor should name his own index file in a way that won't conflict with others. The file must be named as follows:
+
+`package_YOURNAME_PACKAGENAME_index.json`
+
+The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the IDE) while the choice of `YOURNAME_PACKAGENAME` is left to the packager.
+We suggest using a domain name owned by the packager. For example:
+
+`package_arduino.cc_index.json`
+
+or
+
+`package_example.com_avr_boards_index.json`
+
+The index URL is periodically checked for updates so expect a constant flow of downloads (proportional to the number of active users).
+
+## JSON Index file contents
+
+The root of the JSON index is an array of `packages`:
+
+```json
+{
+  "packages": [
+      PACKAGE_XXXX
+   ]
+}
+```
+
+3rd party vendors should use a single `PACKAGE_XXXX` that is a dictionary map with the vendor's metadata, a list of `PLATFORMS` and a list of `TOOLS`. For example:
+
+```json
+{
+  "name": "arduino",
+  "maintainer": "Arduino LLC",
+  "websiteURL": "http://www.arduino.cc/",
+  "email": "packages@arduino.cc",
+
+  "platforms": [
+      PLATFORM_AVR,
+      PLATFORM_ARM,
+      PLATFORM_XXXXX,
+      PLATFORM_YYYYY,
+  ],
+
+  "tools": [
+      TOOLS_COMPILER_AVR,
+      TOOLS_UPLOADER_AVR,
+      TOOLS_COMPILER_ARM,
+      TOOLS_XXXXXXX,
+      TOOLS_YYYYYYY,
+   ],
+}
+```
+
+The metadata fields are:
+
+* `name`: the folder used for the installed cores. The [vendor folder](platform-specification.md#hardware-folders-structure) name of the installed package is determined by this field
+* `maintainer`: the extended name of the vendor that is displayed on the Boards Manager GUI
+* `websiteURL`: the URL to the vendor's website, appears on the Boards Manager as a "More info" link
+* `email`: the email of the vendor/maintainer
+
+Now, before looking at `PLATFORMS`, let's explore first how `TOOLS` are made.
+
+### Tools definitions
+
+Each tool describes a binary distribution of a command line tool. A tool can be:
+
+* a compiler toolchain
+* an uploader
+* a file preprocessor
+* a debugger
+* a program that performs a firmware upgrade
+
+basically anything that can run on the user's host PC and do something useful.
+
+For example, Arduino uses two command line tools for the AVR boards: avr-gcc (the compiler) and avrdude (the uploader).
+
+Tools are mapped as JSON in this way:
+
+```json
+        {
+          "name": "avr-gcc",
+          "version": "4.8.1-arduino5",
+          "systems": [
+            {
+              "host": "i386-apple-darwin11",
+              "url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-i386-apple-darwin11.tar.bz2",
+              "archiveFileName": "avr-gcc-4.8.1-arduino5-i386-apple-darwin11.tar.bz2",
+              "size": "24437400",
+              "checksum": "SHA-256:111b3ef00d737d069eb237a8933406cbb928e4698689e24663cffef07688a901"
+            },
+            {
+              "host": "x86_64-linux-gnu",
+              "url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-x86_64-pc-linux-gnu.tar.bz2",
+              "archiveFileName": "avr-gcc-4.8.1-arduino5-x86_64-pc-linux-gnu.tar.bz2",
+              "size": "27093036",
+              "checksum": "SHA-256:9054fcc174397a419ba56c4ce1bfcbcad275a6a080cc144905acc9b0351ee9cc"
+            },
+            {
+              "host": "i686-linux-gnu",
+              "url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-i686-pc-linux-gnu.tar.bz2",
+              "archiveFileName": "avr-gcc-4.8.1-arduino5-i686-pc-linux-gnu.tar.bz2",
+              "size": "25882375",
+              "checksum": "SHA-256:7648b7f549b37191da0b0be53bae791b652f82ac3cb4e7877f85075aaf32141f"
+            },
+            {
+              "host": "i686-mingw32",
+              "url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-i686-mingw32.zip",
+              "archiveFileName": "avr-gcc-4.8.1-arduino5-i686-mingw32.zip",
+              "size": "46044779",
+              "checksum": "SHA-256:d4303226a7b41d3c445d901b5aa5903458def3fc7b7ff4ffef37cabeb37d424d"
+            }
+          ]
+        },
+```
+
+The field `name` and `version` are respectively the name and version of the tool.
+Each tool is uniquely identified by the triple (`vendor`, `name`, `version`) and there can be many different versions of the same tool available at the same time, for example:
+
+* (`arduino`, `avr-gcc`, `4.8.1-arduino2`)
+* (`arduino`, `avr-gcc`, `4.8.1-arduino3`)
+* (`arduino`, `avr-gcc`, `4.8.1-arduino5`)
+* (`arduino`, `avrdude`, `5.11`)
+* (`arduino`, `avrdude`, `6.0`)
+* (`arduino`, `avrdude`, `6.1`)
+*  .....
+
+Each tool version may come in different build flavours for different OS. Each flavour is listed under the `systems` array. In the example above `avr-gcc` comes with builds for:
+
+* Linux 64-bit (`x86_64-linux-gnu`),
+* Linux 32-bit (`i686-linux-gnu`),
+* Windows (`i686-mingw32`),
+* Mac (`i386-apple-darwin11`)
+
+The IDE will take care to install the right flavour based on the `host` value, or fail if a needed flavour is missing.<br>
+Note that the IDE does not use this information to select the toolchain during verify. If you want the IDE to use this specific version you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt.
+
+The other fields are:
+
+* `url`: the download URL of the tool's archive
+* `archiveFileName`: the name of the file saved to disk after the download (some web servers don't provide the filename through the HTTP request)
+* `size`: the size of the archive in bytes
+* `checksum`: the checksum of the archive, used to check if the file has been corrupted. The format is `ALGORITHM:CHECKSUM`, currently `MD5`, `SHA-1`,`SHA-256` algorithm are supported, we recommend `SHA-256`.  On *nix or MacOSX you may be able to use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are many free options for Windows including md5deep, there are also online utilities for generating checksums.
+
+##### How a tool's path is determined in platform.txt
+
+When the IDE needs a tool it downloads the corresponding archive file and unpacks the content into
+a private folder that can be referenced from `platform.txt` using one of the following properties:
+
+* `{runtime.tools.TOOLNAME-VERSION.path}`
+* `{runtime.tools.TOOLNAME.path}`
+
+For example to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or `{runtime.tools.avr-gcc.path}`.
+
+### Platforms definitions
+
+Finally, let's see how `PLATFORMS` are made.
+
+```json
+        {
+          "name": "Arduino AVR Boards",
+          "architecture": "avr",
+          "version": "1.6.6",
+          "category": "Arduino",
+          "help": {
+            "online": "http://www.arduino.cc/en/Reference/HomePage"
+          },
+          "url": "http://downloads.arduino.cc/cores/avr-1.6.6.tar.bz2",
+          "archiveFileName": "avr-1.6.6.tar.bz2",
+          "checksum": "SHA-256:08ad5db4978ebea22344edc5d77dce0923d8a644da7a14dc8072e883c76058d8",
+          "size": "4876916",
+          "boards": [
+            {"name": "Arduino Yún"},
+            {"name": "Arduino Uno"},
+            {"name": "Arduino Diecimila"},
+            {"name": "Arduino Nano"},
+            {"name": "Arduino Mega"},
+            {"name": "Arduino MegaADK"},
+            {"name": "Arduino Leonardo"},
+          ],
+          "toolsDependencies": [
+            { "packager": "arduino", "name": "avr-gcc", "version": "4.8.1-arduino5" },
+            { "packager": "arduino", "name": "avrdude", "version": "6.0.1-arduino5" }
+          ]
+        },
+```
+
+Each PLATFORM describes a core for a specific architecture. The fields needed are:
+
+* `name`: the extended name of the platform that is displayed on the Boards Manager GUI
+* `architecture`: is the architecture of the plaftorm (avr, sam, etc...). It must match the architecture of the core as explained in the [Arduino platform specification](platform-specification.md#hardware-folders-structure)
+* `version`: the version of the platform.
+* `category`: this field is reserved, a 3rd party core must set it to `Contributed`
+* `help`/`online`: is a URL that is displayed on the Boards Manager as an "Online Help" link
+* `url`, `archiveFileName`, `size` and `checksum`: metadata of the core archive file. The meaning is the same as for the TOOLS
+* `boards`: the list of boards supported (note: just the names to display on the GUI! the real boards definitions are inside `boards.txt` inside the core archive file)
+* `toolsDependencies`: the tools needed by this core. Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can reference tools available in other packages as well.
+
+The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the rules Arduino IDE follows for parsing versions ([source](https://github.com/arduino/Arduino/blob/master/arduino-core/src/cc/arduino/contributions/VersionHelper.java)):
+
+* Split the version at the - character and continue with the first part.
+* If there are no dots (`.`), parse `version` as an integer and form a Version from that integer using `Version.forIntegers`
+* If there is one dot, split `version` into two, parse each part as an integer, and form a Version from those integers using `Version.forIntegers`
+* Otherwise, simply parse `version` into a Version using `Version.valueOf`
+
+Note: if you miss a bracket in the JSON index, then add the URL to your Preferences, and open Boards Manager it can cause the Arduino IDE to no longer load until you have deleted the file from your arduino15 folder.
+
+### Example JSON index file
+
+```json
+{
+  "packages": [
+    {
+      "name": "myboard",
+      "maintainer": "Jane Developer",
+      "websiteURL": "https://github.com/janedeveloper/myboard",
+      "email": "jane@janedeveloper.org",
+      "help": {
+        "online": "http://janedeveloper.org/forum/myboard"
+      },
+      "platforms": [
+        {
+          "name": "My Board",
+          "architecture": "avr",
+          "version": "1.0.0",
+          "category": "Contributed",
+          "help": {
+            "online": "http://janedeveloper.org/forum/myboard"
+          },
+          "url": "https://janedeveloper.github.io/myboard/myboard-1.0.0.zip",
+          "archiveFileName": "myboard-1.0.0.zip",
+          "checksum": "SHA-256:ec3ff8a1dc96d3ba6f432b9b837a35fd4174a34b3d2927de1d51010e8b94f9f1",
+          "size": "15005",
+          "boards": [
+            {"name": "My Board"},
+            {"name": "My Board Pro"}
+          ],
+          "toolsDependencies": [
+            {
+              "packager": "arduino",
+              "name": "avr-gcc",
+              "version": "4.8.1-arduino5"
+            },
+            {
+              "packager": "arduino",
+              "name": "avrdude",
+              "version": "6.0.1-arduino5"
+            }
+          ]
+        },
+        {
+          "name": "My Board",
+          "architecture": "avr",
+          "version": "1.0.1",
+          "category": "Contributed",
+          "help": {
+            "online": "http://janedeveloper.org/forum/myboard"
+          },
+          "url": "https://janedeveloper.github.io/myboard/myboard-1.0.1.zip",
+          "archiveFileName": "myboard-1.0.1.zip",
+          "checksum": "SHA-256:9c86ee28a7ce9fe33e8b07ec643316131e0031b0d22e63bb398902a5fdadbca9",
+          "size": "15125",
+          "boards": [
+            {"name": "My Board"},
+            {"name": "My Board Pro"}
+          ],
+          "toolsDependencies": [
+            {
+              "packager": "arduino",
+              "name": "avr-gcc",
+              "version": "4.8.1-arduino5"
+            },
+            {
+              "packager": "arduino",
+              "name": "avrdude",
+              "version": "6.0.1-arduino5"
+            }
+          ]
+        }
+      ],
+      "tools":[]
+    }
+  ]
+}
+```
+In the example there is one `PACKAGE`, My Board. The package is compatible with the AVR architecture. There are two versions of the `PACKAGE`, 1.0.0 and 1.0.1. No `TOOLS` needed to be installed so that section was left blank.
+
+Here is the Boards Manager entry created by the example:
+![Boards Manager screenshot](img/boards-manager-screenshot.png)
+
+## Installation archive structure
+
+The installation archives contain the Board support files. Supported formats are .zip, .tar.bz2, and .tar.gz.
+
+The folder structure of the core archive is slightly different from the standard manually installed Arduino 1.5+ compatible hardware folder structure. You must remove the architecture folder(e.g., `avr` or `arm`), moving all the files and folders within the architecture folder up a level.
+
+***
+
+After adding Boards Manager support for your boards, please share the JSON index file URL on the [Unofficial list of 3rd party boards support urls](https://github.com/arduino/Arduino/wiki/Unofficial-list-of-3rd-party-boards-support-urls).

docs/package_index_json-specification.md

@@ -0,0 +1,100 @@
+The process the Arduino environment uses to build a sketch. More useful information can be found in the [Arduino platform specification](platform-specification.md). Note that the following refers specifically to the build process for AVR targets. Other architectures will have a similar build process.
+
+## Overview
+
+A number of things have to happen for your Arduino code to get onto the Arduino board. First, the Arduino environment performs some minor pre-processing to turn your sketch into a C++ program. Next, dependencies of the sketch are located. It then gets passed to a compiler (avr-gcc), which turns the human readable code into machine readable instructions (or object files). Then your code gets combined with (linked against) the standard Arduino libraries that provide basic functions like `digitalWrite()` or `Serial.print()`. The result is a single Intel hex file, which contains the specific bytes that need to be written to the program memory of the chip on the Arduino board. This file is then uploaded to the board: transmitted over the USB or serial connection via the bootloader already on the chip or with external programming hardware.
+
+## 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.
+
+## Dependency Resolution
+
+The sketch is scanned recursively for dependencies. There are predefined include search paths:
+
+1. Core library folder (as defined by [`{build.core}`](platform-specification.md#boardstxt))
+1. Variant folder (as defined by [`{build.variant}`](platform-specification.md#boardstxt))
+1. Standard system directories (e.g., [`{runtime.tools.avr-gcc.path}/avr/include`](platform-specification.md#tools))
+1. Include search paths added to resolve prior dependencies
+
+If the dependency is not present in any of those locations, the installed libraries are then searched (see the [**Location Priority** table](#location-priority) below for library locations). For information on the allowed library sub-folder structures see [the Arduino library specification](library-specification.md#source-code). `-I` options are generated for the path to each library dependency and appended to the [`includes` property](platform-specification.md#recipes-to-compile-source-code), to be used in [compilation recipes](platform-specification.md#recipes-to-compile-source-code) in platform.txt.
+
+If multiple libraries contain a file that matches the `#include` directive, the priority is determined by applying the following rules, one by one in this order, until a rule determines a winner:
+
+1. A library that is architecture compatible wins against a library that is not architecture compatible (see [**Architecture Matching**](#architecture-matching))
+1. A library that has better "folder name priority" wins (see [**Folder Name Priority**](#folder-name-priority))
+1. A library that is architecture optimized wins against a library that is not architecture optimized (see [**Architecture Matching**](#architecture-matching))
+1. A library that has a better "location priority" wins (see [**Location Priority**](#location-priority))
+1. A library that has a folder name with a better score using the "closest-match" algorithm wins
+1. A library that has a folder name that comes first in alphanumeric order wins
+
+### 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.
+
+A library is considered **optimized** for architecture `X` only if the `architectures` field in library.properties explicitly contains the architecture `X`. This means that a library that is optimized for architecture `X` is also compatible with it.
+
+Examples:
+
+`architectures` field in `library.properties` | Compatible with `avr` | Optimized for `avr`
+---|---|---
+not specified | YES | NO
+`architectures=*` | YES | NO
+`architectures=avr` | YES | YES
+`architectures=*,avr` | YES | YES
+`architectures=*,esp8266` | YES | NO
+`architectures=avr,esp8266` | YES | YES
+`architectures=samd` | NO | NO
+
+### Folder Name Priority
+
+The "folder name priority" is determined as follows (in order of highest to lowest priority):
+
+Rule | Example for `Servo.h`
+---|---
+The folder name matches the include 100% | `Servo`
+The folder name matches the include 100%, except with a `-master` suffix | `Servo-master`
+The folder name has a matching prefix | `ServoWhatever`
+The folder name has a matching suffix | `AwesomeServo`
+The folder name contains the include | `AnAwesomeServoForWhatever`
+
+### Location Priority
+
+The "location priority" is determined as follows (in order of highest to lowest priority):
+
+1. The library is in the sketchbook (`{sketchbook path}/libraries`)
+1. The library is bundled with the board platform/core ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties))
+1. The library is bundled with the [referenced](platform-specification.md#referencing-another-core-variant-or-tool) board platform/core
+1. The library is bundled with the IDE ([`{runtime.ide.path}/libraries`](platform-specification.md#global-predefined-properties))
+
+## Compilation
+
+Sketches are compiled by avr-gcc and avr-g++ according to the variables in the boards.txt file of the selected board's [platform](platform-specification.md).
+
+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.
+
+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.
+
+These .o files are then linked together into a static library and the main sketch file is linked against this library. Only the parts of the library needed for your sketch are included in the final .hex file, reducing the size of most sketches.
+
+The .hex file is the final output of the compilation which is then uploaded to the board.
+
+If verbose output during compilation is checked in the Preferences dialog, the complete command line of each external command executed as part of the build process will be printed in the editor console.
+
+## Uploading
+
+Sketches are uploaded by avrdude. The upload process is also controlled by variables in the boards and main preferences files. See the [Arduino platform specification](platform-specification.md) page for details.
+
+If verbose output during upload is checked in the Preferences dialog, debugging information will be output to the editor console, including avrdude command lines and verbose output.

docs/platform-specification.md

@@ -103,3 +103,7 @@ nav:
     - monitor: rpc/monitor.md
     - settings: rpc/settings.md
     - debug: rpc/debug.md
+  - sketch-build-process.md
+  - library-specification.md
+  - platform-specification.md
+  - package_index.json specification: package_index_json-specification.md