Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Updated and refined documentation #2760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 27, 2024
Merged

Updated and refined documentation #2760

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b744f86
Cleared usage of identification properties
cmaglie Nov 20, 2024
bd3c784
Expanded docs on default directories configuration
cmaglie Nov 21, 2024
dbd2498
Refined platform specification on installation folder for platforms
cmaglie Nov 21, 2024
195977b
Apply suggestions from code review
cmaglie Nov 21, 2024
ddaf0a0
Use real platforms in example
cmaglie Nov 25, 2024
ab0cbe4
Apply code review suggestions
cmaglie Nov 27, 2024
f250df9
Fixed doc formatting, after upgrade of 'prettier'
cmaglie Nov 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Refined platform specification on installation folder for platforms
  • Loading branch information
@cmaglie
cmaglie committed Nov 21, 2024
commit dbd24989979f5ec63f487b425e45a476b785a9d7
61 changes: 46 additions & 15 deletions docs/platform-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,62 @@ Platforms add support for new boards to the Arduino development software. They a
[Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's
sketchbook folder (AKA "user directory").<br> A platform may consist of as little as a single configuration file.

## Hardware Folders structure
## Platform installation directories

The new hardware folders have a hierarchical structure organized in two levels:
If the platforms are installed using the Board Manager the installation directory location will be as follow:

- the first level is the vendor/maintainer
- the second level is the supported architecture
`{directories.data}/packages/{VENDOR_NAME}/hardware/{ARCHITECTURE}/{VERSION}/...`

A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called
"arduino", "yyyyy" and "xxxxx":
- `{directories.data}` is the data directory as specified in the
[configuration file](configuration.md#default-directories).
- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform.
- `{ARCHITECTURE}` is the architecture of the CPU used in the platform.
- `{VERSION}` is the platform version.

Alternatively, a platform may be manually installed by the user inside the Sketchbook/user directory as follows:

`{directories.user}/hardware/{VENDOR_NAME}/{ARCHITECTURE}/...`

- `{directories.user}` is the user directory as specified in the
[configuration file](configuration.md#default-directories).
- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform.
- `{ARCHITECTURE}` is the architecture of the CPU used in the platform.

A vendor/maintainer can have multiple supported architectures.

For example, below we have four platforms downloaded from three hypothetical hardware vendors called "arduino", "foo"
and "bar", and installed using the Board Manager:

```
{directories.data}/packages/arduino/hardware/avr/1.2.3/...
{directories.data}/packages/arduino/hardware/sam/1.4.5/...
{directories.data}/packages/foo/hardware/avr/1.0.2/...
{directories.data}/packages/bar/hardware/avr/1.1.0/...
```
hardware/arduino/avr/... - Arduino - AVR Boards
hardware/arduino/sam/... - Arduino - SAM (32bit ARM) Boards
hardware/yyyyy/avr/... - Yyy - AVR
hardware/xxxxx/avr/... - Xxx - AVR

If the same platform were manually installed by the user, he should have unpacked them inside the following directories:

```
{directories.user}/hardware/arduino/avr/...
{directories.user}/hardware/arduino/sam/...
{directories.user}/hardware/foo/avr/...
{directories.user}/hardware/bar/avr/...
```

The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR.
In this latter case the version is omitted.

We can also see that the vendor "arduino" has two supported architectures (AVR and SAM), while "foo" and "bar" have only
AVR.

### Notes about the choosing the architecture name

Architecture values are case sensitive (e.g. `AVR` != `avr`).

If possible, follow existing architecture name conventions when creating hardware packages. Use the vendor folder name
to differentiate your package. The architecture folder name is used to determine library compatibility and to permit
referencing resources from another core of the same architecture, so use of a non-standard architecture name can have a
harmful effect.
Platform developers should follow the existing architecture name conventions when creating hardware packages, if you
need to differentiate your package use the vendor/maintainer folder name to do so.

The architecture name is used to determine the libraries compatibility and to permit referencing resources from another
platform of the same architecture. Use of a non-standard architecture name can have a harmful effect.

## Architecture configurations

Expand Down