From 98334b87366ecd5360bf904e8e13dbb4c0ab675c Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 12 Apr 2020 05:35:02 -0700 Subject: [PATCH] [skip changelog] Fix incorrect software specificity/non-specificity in documentation The documentation imported from the arduino/Arduino wiki was mostly written when Arduino's only official development software was the Arduino IDE. This resulted in many statements that mentioned the Arduino IDE specifically, when they actually apply to other development software as well. Conversely, there were Arduino-IDE specific statements which were not qualified as such. --- docs/library-specification.md | 33 +++---- docs/package_index_json-specification.md | 20 +++-- docs/platform-specification.md | 108 ++++++++++++----------- docs/sketch-build-process.md | 16 ++-- 4 files changed, 93 insertions(+), 84 deletions(-) diff --git a/docs/library-specification.md b/docs/library-specification.md index 72767a34cc5..31e24d72f03 100644 --- a/docs/library-specification.md +++ b/docs/library-specification.md @@ -1,14 +1,15 @@ 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 +* rev.1 has been implemented starting with Arduino IDE version 1.5.3 (now superseded by rev.2) +* rev.2 will be implemented starting from version Arduino IDE 1.5.6 +* rev.2.1 will be implemented starting from version Arduino IDE 1.6.10 +* rev.2.2 will be implemented starting from version Arduino IDE 1.8.10 + +This new library format is intended to be used in tandem with **Library Manager**, available since Arduino IDE 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 in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and [Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11) as well as [`arduino-cli lib`](https://arduino.github.io/arduino-cli/commands/arduino-cli_lib/). It doesn't yet take care of dependencies between libraries. -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. +Arduino development software 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 @@ -46,10 +47,10 @@ The library.properties file is a key=value properties list. Every field in this * 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** - **(available from Arduino IDE 1.8.10/Arduino CLI 0.7.0)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). The Arduino IDE's Library Manager will offer to install the dependencies during installation of the library. [`arduino-cli lib install`](https://arduino.github.io/arduino-cli/commands/arduino-cli_lib_install/) will automatically install the dependencies. 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 header files (.h) on the root source folder are included. +* **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 Arduino 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` @@ -82,16 +83,16 @@ 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 "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. +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 Arduino IDE's "Sketch > Include Library" menu or the Arduino Web Editor's "Include" button), 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: +For backward compatibility with Arduino IDE 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). +This will allow existing 1.0 format libraries to compile under Arduino IDE 1.5.x+ as well and vice-versa. If a library only needs to run on Arduino IDE 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 Arduino IDE 1.0.x doesn’t support recursive compilation, backwards compatibility wouldn’t be possible anyway). #### Library Examples @@ -99,13 +100,13 @@ Library examples must be placed in the **examples** folder. Note that the **exam Servo/examples/... -Sketches contained inside the examples folder will be shown in the Examples menu of the IDE. +Sketches contained inside the examples folder will be shown in the Examples menu of the Arduino IDE and Arduino Web Editor. #### 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. +The content of the *extras* folder is totally ignored by the Arduino development software; you are free to put anything inside such as supporting documentation, etc. ### Keywords @@ -145,7 +146,7 @@ KEYWORD_TOKENTYPE | Use for | Theme property `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. +This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via the Arduino IDE's **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. @@ -181,7 +182,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, +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 @@ -203,4 +204,4 @@ Alternatively, if a library only works on certain architectures, you can provide ## 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). +In order to support old libraries (from Arduino IDE 1.0.x), the Arduino IDE/Pro IDE and Arduino CLI will also compile libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino IDE 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in Arduino IDE 1.0.x). diff --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md index d893d84af6a..17420623b43 100644 --- a/docs/package_index_json-specification.md +++ b/docs/package_index_json-specification.md @@ -1,12 +1,14 @@ -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. +Introduced in Arduino IDE 1.6.4, Boards Manager makes it easy to install and update Arduino platforms. In order to provide Boards Manager installation support for a platform, a JSON formatted index file must be published. This is the specification for that file. + +Boards Manager functionality is provided by [Arduino CLI](getting-started.md#adding-3rd-party-cores), [Arduino IDE](https://www.arduino.cc/en/Guide/Cores), and Arduino Pro IDE. ## 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: +Many different index files coming from different vendors may be in use, 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. +The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the Arduino development software) 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` @@ -58,8 +60,8 @@ The root of the JSON index is an array of `packages`: 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 +* `maintainer`: the extended name of the vendor that is displayed on the Arduino IDE/Pro IDE's Boards Manager GUI +* `websiteURL`: the URL to the vendor's website, appears on the Arduino IDE/Pro IDE's 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. @@ -136,7 +138,7 @@ Each tool version may come in different build flavours for different OS. Each fl * 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.
-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. +Note that this information is not used to select the toolchain during compilation. If you want this specific version to be used, you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt. The other fields are: @@ -194,9 +196,9 @@ Each PLATFORM describes a core for a specific architecture. The fields needed ar * `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 +* `help`/`online`: is a URL that is displayed on the Arduino IDE's 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) +* `boards`: the list of boards supported (note: just the names to display on the Arduino IDE and Arduino Pro IDE's Boards Manager 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)): @@ -295,7 +297,7 @@ Here is the Boards Manager entry created by the example: 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. +The folder structure of the core archive is slightly different from the standard manually installed Arduino IDE 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. *** diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 5e874c30f4b..513ecb91199 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -1,5 +1,5 @@ -This specification is a 3rd party hardware format to be used in Arduino IDE starting from 1.5.x series.
-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.
+This specification is a 3rd party hardware format to be used in Arduino development software starting from the Arduino IDE 1.5.x series.
+This specification allows a 3rd party vendor/maintainer to add support for new boards to the Arduino development software by providing a file to unzip into the *hardware* folder of Arduino's sketchbook folder.
It is also possible to add new 3rd party boards by providing just one configuration file. ## Hardware Folders structure @@ -58,16 +58,16 @@ 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 configuration files: +The following automatically generated properties 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) -* `{runtime.ide.path}`: the absolute path of the Arduino IDE folder -* `{runtime.ide.version}`: the version number of the Arduino IDE as a number (this uses two digits per version number component, and removes the points and leading zeroes, so Arduino IDE 1.8.3 becomes `01.08.03` which becomes `runtime.ide.version=10803`). +* `{runtime.ide.path}`: the absolute path of the Arduino IDE or Arduino CLI folder +* `{runtime.ide.version}`: the version number of the Arduino IDE as a number (this uses two digits per version number component, and removes the points and leading zeroes, so Arduino IDE 1.8.3 becomes `01.08.03` which becomes `runtime.ide.version=10803`). When using Arduino development software other than the Arduino IDE, this is set to a meaningless version number. * `{ide_version}`: Compatibility alias for `{runtime.ide.version}` * `{runtime.os}`: the running OS ("linux", "windows", "macosx") -Compatibility note: Versions before 1.6.0 only used one digit per version number component in `{runtime.ide.version}` (so 1.5.9 was `159`, not `10509`). +Compatibility note: Versions before Arduino IDE 1.6.0 only used one digit per version number component in `{runtime.ide.version}` (so 1.5.9 was `159`, not `10509`). ## platform.txt @@ -79,20 +79,20 @@ The following meta-data must be defined: name=Arduino AVR Boards version=1.5.3 -The **name** will be shown in the Boards menu of the Arduino IDE.
+The **name** will be shown in the Arduino IDE's Board menu or the Name field of [`arduino-cli core`](https://arduino.github.io/arduino-cli/commands/arduino-cli_core/)'s output.
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 platform.txt file is used to configure the build process. 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 of: +The Arduino development software, 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 -The IDE creates a temporary folder to store the build artifacts whose path is available through the global property **{build.path}**. A property **{build.project_name}** with the name of the project and a property **{build.arch}** with the name of the architecture is set as well. +A temporary folder is created to store the build artifacts whose path is available through the global property **{build.path}**. A property **{build.project_name}** with the name of the project and a property **{build.arch}** with the name of the architecture is set as well. * `{build.path}`: The path to the temporary folder to store build artifacts * `{build.project_name}`: The project name @@ -102,13 +102,13 @@ There are some other **{build.xxx}** properties available, that are explained in #### Recipes to compile source code -We said that the Arduino IDE determines a list of files to compile. Each file can be source code written in C (.c files), C++ (.cpp files) or Assembly (.S files). Every language is compiled using its respective **recipe**: +We said that the Arduino development software determines a list of files to compile. Each file can be source code written 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 -The recipes can be built concatenating other properties set by the IDE (for each file compiled): +The recipes can be built concatenating the following automatically generated properties (for each file compiled): * `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...." * `{source_file}`: the path to the source file @@ -132,7 +132,7 @@ Note that some properties, like **{build.mcu}** for example, are taken from the The core of the selected board is compiled as described in the previous paragraph, but the object files obtained from the compile are also archived into a static library named *core.a* using the **recipe.ar.pattern**. -The recipe can be built concatenating the following properties set by the IDE: +The recipe can be built concatenating the following automatically generated properties: * `{object_file}`: the object file to include in the archive * `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`. @@ -152,7 +152,7 @@ For example, Arduino provides the following for AVR: All the artifacts produced by the previous steps (sketch object files, libraries object files and core.a archive) are linked together using the **recipe.c.combine.pattern**. -The recipe can be built concatenating the following properties set by the IDE: +The recipe can be built concatenating the following automatically generated properties: * `{object_files}`: the list of object files to include in the archive ("file1.o file2.o ....") * `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`. @@ -170,7 +170,7 @@ For example the following is used for AVR: #### Recipes for extraction of executable files and other binary data -An arbitrary number of extra steps can be performed by the IDE at the end of objects linking. +An arbitrary number of extra steps can be performed at the end of objects linking. These steps can be used to extract binary data used for upload and they are defined by a set of recipes with the following format: recipe.objcopy.FILE_EXTENSION_1.pattern=[.....] @@ -182,7 +182,7 @@ These steps can be used to extract binary data used for upload and they are defi recipe.objcopy.eep.pattern=[.....] recipe.objcopy.hex.pattern=[.....] -There are no specific properties set by the IDE here. +There are no specific properties set by the Arduino development software here. A full example for the AVR platform can be: ## Create eeprom @@ -193,7 +193,7 @@ A full example for the AVR platform can be: #### Recipes to compute binary sketch size -At the end of the build the Arduino IDE shows the final binary sketch size to the user. The size is calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed through the regular expression set in the property **recipe.size.regex**. The regular expression must match the sketch size. +At the end of the build the Arduino development software shows the final binary sketch size to the user. The size is calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed through the regular expression set in the property **recipe.size.regex**. The regular expression must match the sketch size. For AVR we have: @@ -205,7 +205,7 @@ For AVR we have: #### Recipes to export compiled binary -When you do a **Sketch > Export compiled Binary**, the compiled binary is copied from the build folder to the sketch folder. Two binaries are copied; the standard binary, and a binary that has been merged with the bootloader file (identified by the `.with_bootloader` in the filename). +When you do a **Sketch > Export compiled Binary** in the Arduino IDE, the compiled binary is copied from the build folder to the sketch folder. Two binaries are copied; the standard binary, and a binary that has been merged with the bootloader file (identified by the `.with_bootloader` in the filename). Two recipes affect how **Export compiled Binary** works: @@ -214,14 +214,14 @@ Two recipes affect how **Export compiled Binary** works: As with other processes, there are pre and post build hooks for **Export compiled Binary**. -The **recipe.hooks.savehex.presavehex.NUMBER.pattern** and **recipe.hooks.savehex.postsavehex.NUMBER.pattern** hooks (but not **recipe.output.tmp_file** and **recipe.output.save_file**) can be built concatenating the following properties set by the IDE: +The **recipe.hooks.savehex.presavehex.NUMBER.pattern** and **recipe.hooks.savehex.postsavehex.NUMBER.pattern** hooks (but not **recipe.output.tmp_file** and **recipe.output.save_file**) can be built concatenating the following automatically generated properties: {sketch_path} - the absolute path of the sketch folder #### Recipe to run the preprocessor -For detecting what libraries to include in the build, and for generating function prototypes, the Arduino IDE must be able to run (just) the preprocessor. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source file, writing the preprocessed output to a given output file, and generate (only) preprocessor errors on standard output. This preprocessor run should happen with the same defines and other preprocessor-influencing-options as for normally compiling the source files. +For detecting what libraries to include in the build, and for generating function prototypes, (just) the preprocessor is run. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source file, writing the preprocessed output to a given output file, and generate (only) preprocessor errors on standard output. This preprocessor run should happen with the same defines and other preprocessor-influencing-options as for normally compiling the source files. -The recipes can be built concatenating other properties set by the IDE (for each file compiled): +The recipes can be built concatenating other automatically generated properties (for each file compiled): * `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...." * `{source_file}`: the path to the source file @@ -232,11 +232,11 @@ For example the following is used for AVR: preproc.macros.flags=-w -x c++ -E -CC recipe.preproc.macros="{compiler.path}{compiler.cpp.cmd}" {compiler.cpp.flags} {preproc.macros.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {compiler.cpp.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{preprocessed_file_path}" -Note that the `{preprocessed_file_path}` might point to (your operating system's equivalent) of `/dev/null`. In this case, also passing `-MMD` to gcc is problematic, as it will try to generate a dependency file called `/dev/null.d`, which will usually result in a permission error. Since platforms typically include `{compiler.cpp.flags}` here, which includes `-MMD`, the Arduino IDE automatically filters out the `-MMD` option from the `recipe.preproc.macros` recipe to prevent this error. +Note that the `{preprocessed_file_path}` might point to (your operating system's equivalent) of `/dev/null`. In this case, also passing `-MMD` to gcc is problematic, as it will try to generate a dependency file called `/dev/null.d`, which will usually result in a permission error. Since platforms typically include `{compiler.cpp.flags}` here, which includes `-MMD`, the `-MMD` option is automatically filtered out of the `recipe.preproc.macros` recipe to prevent this error. -Note that older IDE versions used the **recipe.preproc.includes** recipe to determine includes, which is undocumented here. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is no longer used. +Note that older Arduino IDE versions used the **recipe.preproc.includes** recipe to determine includes, which is undocumented here. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is no longer used. -#### Pre and post build hooks (since IDE 1.6.5) +#### Pre and post build hooks (since Arduino IDE 1.6.5) You can specify pre and post actions around each recipe. These are called "hooks". Here is the complete list of available hooks: @@ -271,7 +271,7 @@ recipe.hooks.sketch.prebuild.11.pattern=echo 11 ## Global platform.txt -Properties defined in a platform.txt created in the **hardware** subfolder of the IDE installation folder will be used for all platforms and will override local properties. +Properties defined in a platform.txt created in the **hardware** subfolder of the Arduino IDE installation folder will be used for all platforms and will override local properties. This feature is currently only available when using the Arduino IDE. ## platform.local.txt @@ -296,11 +296,11 @@ For example the board ID chosen for the Arduino Uno board is "uno". An extract o Note that all the relevant keys start with the board ID **uno.xxxxx**. -The **uno.name** property contains the name of the board shown in the Board menu of the Arduino IDE. +The **uno.name** property contains the human-friendly name of the board. This is shown in the Board menu of the IDEs, the "Board Name" field of Arduino CLI's text output, or the "name" key of Arduino CLI's JSON output. -The **uno.build.board** property is used to set a compile-time variable **ARDUINO_{build.board}** to allow use of conditional code between `#ifdef`s. The Arduino IDE automatically generates a **build.board** value if not defined. In this case the variable defined at compile time will be `ARDUINO_AVR_UNO`. +The **uno.build.board** property is used to set a compile-time variable **ARDUINO_{build.board}** to allow use of conditional code between `#ifdef`s. A **build.board** value is automatically generated if not defined. In this case the variable defined at compile time will be `ARDUINO_AVR_UNO`. -The other properties will override the corresponding global properties of the IDE when the user selects the board. These properties will be globally available, in other configuration files too, without the board ID prefix: +The other properties will override the corresponding global properties when the user selects the board. These properties will be globally available, in other configuration files too, without the board ID prefix: uno.build.mcu => build.mcu uno.build.f_cpu => build.f_cpu @@ -309,7 +309,7 @@ The other properties will override the corresponding global properties of the ID uno.build.variant => build.variant This explains the presence of **{build.mcu}** or **{build.board}** in the platform.txt recipes: their value is overwritten respectively by **{uno.build.mcu}** and **{uno.build.board}** when the Uno board is selected! -Moreover the IDE automatically provides the following properties: +Moreover the following properties are automatically generated: * `{build.core.path}`: The path to the selected board's core folder (inside the [core platform](#platform-terminology), for example hardware/arduino/avr/core/arduino) * `{build.system.path}`: The path to the [core platform](#platform-terminology)'s system folder if available (for example hardware/arduino/sam/system) @@ -323,7 +323,7 @@ Cores are placed inside the **cores** subfolder. Many different cores can be pro * `hardware/arduino/avr/cores/arduino`: the Arduino Core * `hardware/arduino/avr/cores/rtos`: an hypothetical RTOS Core -The board's property **build.core** is used by the Arduino IDE to find the core that must be compiled and linked when the board is selected. For example if a board needs the Arduino core the **build.core** variable should be set to: +The board's property **build.core** is used to find the core that must be compiled and linked when the board is selected. For example if a board needs the Arduino core the **build.core** variable should be set to: uno.build.core=arduino @@ -363,11 +363,11 @@ instead, the Arduino Leonardo board needs the *leonardo* variant: In the example above, both Uno and Leonardo share the same core but use different variants.
In any case, the contents of the selected variant folder path is added to the include search path and its contents are compiled and linked with the sketch. -The parameter **build.variant.path** is automatically found by the IDE. +The parameter **build.variant.path** is automatically generated. ## Tools -The Arduino IDE uses external command line tools to upload the compiled sketch to the board or to burn bootloaders using external programmers. Currently *avrdude* is used for AVR based boards and *bossac* for SAM based boards, but there is no limit, any command line executable can be used. The command line parameters are specified using **recipes** in the same way used for platform build process. +The Arduino development software uses external command line tools to upload the compiled sketch to the board or to burn bootloaders using external programmers. Currently *avrdude* is used for AVR based boards and *bossac* for SAM based boards, but there is no limit, any command line executable can be used. The command line parameters are specified using **recipes** in the same way used for platform build process. Tools are configured inside the platform.txt file. Every Tool is identified by a short name, the Tool ID. A tool can be used for different purposes: @@ -400,11 +400,11 @@ Let's look at how the **upload** action is defined for avrdude: A **{runtime.tools.TOOL_NAME.path}** and **{runtime.tools.TOOL_NAME-TOOL_VERSION.path}** property is generated for the tools of Arduino AVR Boards and any other platform installed via Boards Manager. **{runtime.tools.TOOL_NAME.path}** points to the latest version of the tool available. -The Arduino IDE makes the tool configuration properties available globally without the prefix. For example, the **tools.avrdude.cmd.path** property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration variables. +The tool configuration properties are available globally without the prefix. For example, the **tools.avrdude.cmd.path** property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration variables. #### Verbose parameter -It is possible for the user to enable verbosity from the Arduino IDE's Preferences panel. This preference is transferred to the command line by the IDE using the **ACTION.verbose** property (where ACTION is the action we are considering).
+It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose` flag. This preference is transferred to the command line using the **ACTION.verbose** property (where ACTION is the action we are considering).
When the verbose mode is enabled the **tools.TOOL_ID.ACTION.params.verbose** property is copied into **ACTION.verbose**. When the verbose mode is disabled, the **tools.TOOL_ID.ACTION.params.quiet** property is copied into **ACTION.verbose**. Confused? Maybe an example will clear things: tools.avrdude.upload.params.verbose=-v -v -v -v @@ -421,8 +421,8 @@ If the user didn't enable verbose mode, then **{upload.params.quiet}** is used i ### Sketch upload configuration -The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar. -The Arduino IDE selects the tool to be used for upload by looking at the **upload.tool** property. +The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar or uses [`arduino-cli upload`](https://arduino.github.io/arduino-cli/commands/arduino-cli_upload/). +The **upload.tool** property determines the tool to be used for upload. A specific **upload.tool** property should be defined for every board in boards.txt: [......] @@ -458,16 +458,16 @@ Most **{upload.XXXX}** variables are used later in the avrdude upload recipe in #### 1200 bps 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: +To let the Arduino development software perform these steps, two board parameters can be set: -* `use_1200bps_touch` causes the IDE to briefly open the selected serial port at 1200 bps (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 1200 bps 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 selected serial port to be briefly opened at 1200 bps (8N1) before starting the upload. +* `wait_for_upload_port` causes the upload procedure 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 1200 bps touch, the development software 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 the disconnect and reconnect was missed). 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 1200 bps 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 -The Arduino IDE auto-detects all available serial ports on the running system and lets the user choose one from the GUI. The selected port is available as a configuration property **{serial.port}**. +The port selected via the IDE or [`arduino-cli upload`](https://arduino.github.io/arduino-cli/commands/arduino-cli_upload/)'s `--port` option is available as a configuration property **{serial.port}**. ### Upload using an external programmer @@ -479,13 +479,19 @@ The platform.txt associated with the selected programmer will be used. **TODO...** The platform.txt associated with the selected board will be used. -## Custom board menus +## Custom board options -The Arduino IDE allows adding extra menu items under the Tools menu. With these sub-menus the user can select different configurations for a specific board (for example a board could be provided in two or more variants with different CPUs, or may have different crystal speed based on the board model, and so on...). +It can sometimes be useful to provide user selectable configuration options for a specific board. For example, a board could be provided in two or more variants with different CPUs, or may have different crystal speed based on the board model, and so on... -Let's see an example of how a custom menu is implemented. +When using Arduino CLI, the option can be selected via the FQBN. + +In the Arduino IDE the options add extra menu items under the "Tools" menu. + +In Arduino Web Editor, the options are displayed in the "Flavours" menu. + +Let's see an example of how a custom option is implemented. The board used in the example is the Arduino Duemilanove. This board was produced in two models, one with an ATmega168 CPU and another with an ATmega328P.
-We are going then to define a custom menu "Processor" that allows the user to choose between the two +We are going then to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two different microcontrollers. We must first define a set of **menu.MENU_ID=Text** properties. Text is what is displayed on the GUI for every custom menu we are going to create and must be declared at the beginning of the boards.txt file: @@ -493,7 +499,7 @@ We must first define a set of **menu.MENU_ID=Text** properties. Text is what is menu.cpu=Processor [.....] -in this case we declare only one custom menu "Processor" which we refer using the "cpu" MENU_ID.
+in this case, the menu name is "Processor".
Now let's add, always in the boards.txt file, the default configuration (common to all processors) for the duemilanove board: menu.cpu=Processor @@ -507,7 +513,7 @@ Now let's add, always in the boards.txt file, the default configuration (common duemilanove.build.variant=standard [.....] -Now let's define the options to show in the "Processor" menu: +Now let's define the possible values of the "cpu" option: [.....] duemilanove.menu.cpu.atmega328=ATmega328P @@ -515,9 +521,9 @@ Now let's define the options to show in the "Processor" menu: duemilanove.menu.cpu.atmega168=ATmega168 [.....] -We have defined two options: "ATmega328P" and "ATmega168".
-Note that the property keys must follow the format **BOARD_ID.menu.MENU_ID.OPTION_ID=Text**.
-Finally, the specific configuration for every option: +We have defined two values: "atmega328" and "atmega168".
+Note that the property keys must follow the format **BOARD_ID.menu.MENU_ID.OPTION_ID=Text**, where Text is what is displayed under the "Processor" menu in the IDE's GUI.
+Finally, the specific configuration for each option value: [.....] ## Arduino Duemilanove w/ ATmega328P @@ -533,7 +539,7 @@ Finally, the specific configuration for every option: duemilanove.menu.cpu.atmega168.build.mcu=atmega168 [.....] -Note that when the user selects an option, all the "sub properties" of that option are copied in the global configuration. For example when the user selects "ATmega168" from the "Processor" menu the Arduino IDE makes the configuration under atmega168 available globally: +Note that when the user selects an option value, all the "sub properties" of that value are copied in the global configuration. For example when the user selects "ATmega168" from the "Processor" menu, or uses the FQBN `arduino:avr:duemilanove:cpu=atmega168` with Arduino CLI, the configuration under atmega168 is made available globally: duemilanove.menu.cpu.atmega168.upload.maximum_size => upload.maximum_size duemilanove.menu.cpu.atmega168.upload.speed => upload.speed @@ -589,4 +595,4 @@ Introduced in Arduino IDE 1.6.6. This file can be used to override properties de ## keywords.txt -As of Arduino IDE 1.6.6, per-platform keywords can be defined by adding a keywords.txt file to the platform's architecture folder. These keywords are only highlighted when one of the boards of that platform are selected. This file follows the [same format](library-specification.md#keywords) as the keywords.txt used in libraries. Each keyword must be separated from the keyword identifier by a tab. +As of Arduino IDE 1.6.6, per-platform keywords can be defined by adding a keywords.txt file to the platform's architecture folder. These keywords are only highlighted in the Arduino IDE when one of the boards of that platform are selected. This file follows the [same format](library-specification.md#keywords) as the keywords.txt used in libraries. Each keyword must be separated from the keyword identifier by a tab. diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index 9ad149ae95a..908fa84b78f 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -1,14 +1,14 @@ -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. +The process the Arduino development software 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. +A number of things have to happen for your Arduino code to get onto the Arduino board. First, the Arduino development software 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: +The Arduino development software 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. +- All .ino and .pde files in the sketch folder (shown in the Arduino 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 ` 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. @@ -76,7 +76,7 @@ The "location priority" is determined as follows (in order of highest to lowest 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)) +1. The library is bundled with the Arduino IDE ([`{runtime.ide.path}/libraries`](platform-specification.md#global-predefined-properties)) ## Compilation @@ -87,16 +87,16 @@ The sketch is built in a temporary directory in the system-wide temporary direct 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 `#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. +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 IDE's Board 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. +If verbose output during compilation is enabled, the complete command line of each external command executed as part of the build process will be printed in the 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. +If verbose output during upload is enabled, debugging information will be output to the console, including avrdude command lines and verbose output.