From 0b555cc6145f746a7f5b9e4b905e5d6961902ba5 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 26 Jul 2020 23:22:28 -0700 Subject: [PATCH] Add headings to delineate the platform referencing documentation The platform referencing documentation content falls into four categories: - general - core - variant - tool Previously, it was not obvious where the content for each category began and ended. --- docs/platform-specification.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 3ce51a7d449..af46cb30b3f 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -731,6 +731,12 @@ There is no limit to the number of custom menus that can be defined. ## Referencing another core, variant or tool +The Arduino platform referencing system allows using components of other platforms in cases where it would otherwise be +necessary to duplicate those components. This feature allows us to reduce the minimum set of files needed to define a +new "hardware" to just the boards.txt file. + +### Core reference + Inside the boards.txt we can define a board that uses a core provided by another vendor/maintainer using the syntax **VENDOR_ID:CORE_ID**. For example, if we want to define a board that uses the "arduino" core from the "arduino" vendor we should write: @@ -750,20 +756,27 @@ The libraries from the referenced platform are used, thus there is no need to pr provided the list of available libraries are the sum of the 2 libraries where the referencing platform has priority over the referenced platform. -In the same way we can use variants and tools defined on another platform: +### Variant reference + +In the same way we can use a variant defined on another platform using the syntax **VENDOR_ID:VARIANT_ID**: [....] myboard.build.variant=arduino:standard - myboard.upload.tool=arduino:avrdude - myboard.bootloader.tool=arduino:avrdude [....] -Using this syntax allows us to reduce the minimum set of files needed to define a new "hardware" to just the boards.txt -file. - Note that referencing a variant in another platform does _not_ inherit any properties from that platform's platform.txt (like referencing a core does). +### Tool references + +Tool recipes defined in the platform.txt of other platforms can also be referenced using the syntax +**VENDOR_ID:TOOL_ID**: + + [....] + myboard.upload.tool=arduino:avrdude + myboard.bootloader.tool=arduino:avrdude + [....] + ### Platform Terminology Because boards can reference cores, variants and tools in different platforms, this means that a single build or upload