Skip to content

Commit 0e5dd67

Browse files
cmagliecmaglie
committed
Added profiles specification docs
1 parent 2332639 commit 0e5dd67

File tree

2 files changed

+125
-0
lines changed

2 files changed

+125
-0
lines changed

‎docs/sketch-profiles.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
Arduino CLI provides support for reproducible builds through the use of build profiles.
2+
3+
## Sketch project file `sketch.yaml` and build profiles.
4+
5+
A profile is a complete description of all the resources needed to build a sketch. Profiles are defined in a project
6+
file called `sketch.yaml`. This file will be in YAML format and it will contain one or more profiles, in particular each
7+
profile will define:
8+
9+
- The board FQBN
10+
- The target core platform name and version (with the 3rd party platform index URL if needed)
11+
- A possible core platform name and version, that is a dependency of the target core platform (with the 3rd party
12+
platform index URL if needed)
13+
- The libraries used in the sketch (including their version)
14+
15+
The format of the file is the following:
16+
17+
```
18+
profiles:
19+
<PROFILE_NAME>:
20+
notes: <USER_NOTES>
21+
fqbn: <FQBN>
22+
platforms:
23+
- platform: <PLATFORM> (<PLATFORM_VERSION>)
24+
platform_index_url: <3RD_PARTY_PLATFORM_URL>
25+
- platform: <PLATFORM_DEPENDENCY> (<PLATFORM_DEPENDENCY_VERSION>)
26+
platform_index_url: <3RD_PARTY_PLATFORM_DEPENDENCY_URL>
27+
libraries:
28+
- <LIB_NAME> (<LIB_VERSION>)
29+
- <LIB_NAME> (<LIB_VERSION>)
30+
- <LIB_NAME> (<LIB_VERSION>)
31+
32+
...more profiles here...
33+
```
34+
35+
There is a 'profiles:' section containing all the profiles. Each field is self-explanatory, in particular:
36+
37+
- `<PROFILE_NAME>` is the profile identifier, it’s a user-defined field, and the allowed characters are alphanumerics,
38+
underscore `_`, dot `.`, and dash `-`
39+
- `<PLATFORM>` is the target core platform identifier, for example, `arduino:avr` or `adafruit:samd`
40+
- `<PLATFORM_VERSION>` is the target core platform version required
41+
- `<3RD_PARTY_PLATFORM_URL>` is the index URL to download the target core platform (also known as “Additional Boards
42+
Manager URLs” in the Arduino IDE). This field can be omitted for the official `arduino:*` platforms.
43+
- `<PLATFORM_DEPENDENCY>`, `<PLATFORM_DEPENDENCY_VERSION>`, and `<3RD_PARTY_PLATFORM_DEPENDENCY_URL>` contains the same
44+
information as `<PLATFORM>`, `<PLATFORM_VERSION>`, and `<3RD_PARTY_PLATFORM_URL>` but for the core platform dependency
45+
of the main core platform. These fields are optional.
46+
- `<LIB_VERSION>` is the version required for the library, for example, `1.0.0`
47+
- `<USER_NOTES>` is a free text string available to the developer to add comments
48+
- `<DEFAULT_PROFILE_NAME>` is the profile used by default (more on that later)
49+
50+
A complete example of a `sketch.yaml` may be the following:
51+
52+
```
53+
profiles:
54+
nanorp:
55+
fqbn: arduino:mbed_nano:nanorp2040connect
56+
platforms:
57+
- platform: arduino:mbed_nano (2.1.0)
58+
libraries:
59+
- ArduinoIoTCloud (1.0.2)
60+
- Arduino_ConnectionHandler (0.6.4)
61+
- TinyDHT sensor library (1.1.0)
62+
63+
another_profile_name:
64+
notes: testing the limit of the AVR platform, may be unstable
65+
fqbn: arduino:avr:uno
66+
platforms:
67+
- platform: arduino:avr (1.8.4)
68+
libraries:
69+
- VitconMQTT (1.0.1)
70+
- Arduino_ConnectionHandler (0.6.4)
71+
- TinyDHT sensor library (1.1.0)
72+
73+
tiny:
74+
notes: testing the very limit of the AVR platform, it will be very unstable
75+
fqbn: attiny:avr:ATtinyX5:cpu=attiny85,clock=internal16
76+
platforms:
77+
- platform: attiny:[email protected]
78+
platform_index_url: https://raw.githubusercontent.com/damellis/attiny/ide-1.6.x-boards-manager/package_damellis_attiny_index.json
79+
- platform: arduino:[email protected]
80+
libraries:
81+
- ArduinoIoTCloud (1.0.2)
82+
- Arduino_ConnectionHandler (0.6.4)
83+
- TinyDHT sensor library (1.1.0)
84+
85+
feather:
86+
fqbn: adafruit:samd:adafruit_feather_m0
87+
platforms:
88+
- platform: adafruit:samd (1.6.0)
89+
platform_index_url: https://adafruit.github.io/arduino-board-index/package_adafruit_index.json
90+
libraries:
91+
- ArduinoIoTCloud (1.0.2)
92+
- Arduino_ConnectionHandler (0.6.4)
93+
- TinyDHT sensor library (1.1.0)
94+
```
95+
96+
### Building a sketch
97+
98+
When a `sketch.yaml` file exists in the sketch, it can be leveraged to compile the sketch with the `--profile/-m` flag
99+
in the `compile` command:
100+
101+
```
102+
arduino-cli compile --profile nanorp
103+
```
104+
105+
In this case, the sketch will be compiled using the core platform and libraries specified in the nanorp profile. If a
106+
core platform or a library is missing it will be automatically downloaded and installed on the fly in a isolated
107+
directory inside the data folder. The dedicated storage is not accessible to the user and is meant as a "cache" of the
108+
resources used to build the sketch.
109+
110+
When using the profile-based build, the globally installed platforms and libraries are excluded from the compile and can
111+
not be used in any way. In other words, the build is isolated from the system and will rely only on the resources
112+
specified in the profile: this will ensure that the build is portable and reproducible independently from the platforms
113+
and libraries installed in the system.

‎docs/sketch-specification.md

+12
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,18 @@ The `included_libs` key defines the library versions the Arduino Web Editor uses
7979
Arduino Web Editor specific because all versions of all the Library Manager libraries are pre-installed in Arduino Web
8080
Editor, while only one version of each library may be installed when using the other Arduino development software.
8181

82+
### Build profiles and reproducible builds
83+
84+
Arduino CLI provides support for reproducible builds through the use of a project file `sketch.yaml`.
85+
86+
Inside `sketch.yaml` the user can define one or more "profiles": each profile is a description of all the resources
87+
needed to build the sketch (platform and libraries each pinned to a specific version).
88+
89+
When using a profile to compile, Arduino CLI will install all the required resources in a isolated environment, used
90+
only for the build, leaving the libraries and platforms installed globally in the system untouched.
91+
92+
For more information see the [profiles documentation](commands/sketch-profiles.md).
93+
8294
### Secrets
8395

8496
Arduino Web Editor has a

0 commit comments

Comments
 (0)