Sketch project file

Sketch metadata is defined in a file named

sketch.yaml

Build profiles

Arduino CLI provides support for reproducible builds through the use of build profiles.

A profile is a complete description of all the resources needed to build a sketch. The sketch project file may contain multiple profiles.

Each profile will define:

• The board FQBN
• The programmer to use
• The target core platform name and version (with the 3rd party platform index URL if needed)
• A possible core platform name and version, that is a dependency of the target core platform (with the 3rd party platform index URL if needed)
• The libraries used in the sketch (including their version)
• The port and protocol to upload the sketch and monitor the board

The format of the file is the following:

1profiles:
2  <PROFILE_NAME>:
3    notes: <USER_NOTES>
4    fqbn: <FQBN>
5    programmer: <PROGRAMMER>
6    platforms:
7      - platform: <PLATFORM> (<PLATFORM_VERSION>)
8        platform_index_url: <3RD_PARTY_PLATFORM_URL>
9      - platform: <PLATFORM_DEPENDENCY> (<PLATFORM_DEPENDENCY_VERSION>)
10        platform_index_url: <3RD_PARTY_PLATFORM_DEPENDENCY_URL>
11    libraries:
12      - <LIB_NAME> (<LIB_VERSION>)
13      - <LIB_NAME> (<LIB_VERSION>)
14      - <LIB_NAME> (<LIB_VERSION>)
15    port: <PORT_NAME>
16    port_config:
17      <PORT_SETTING_NAME>: <PORT_SETTING_VALUE>
18      ...
19    protocol: <PORT_PROTOCOL>
20  ...more profiles here...

There is an optional

profiles:

• <PROFILE_NAME>

  is the profile identifier, it’s a user-defined field, and the allowed characters are alphanumerics, underscore

  _

  , dot

  .

  , and dash

  -

  .

• <PLATFORM>

  is the target core platform identifier, for example,

  arduino:avr

  or

  adafruit:samd

  .

• <PLATFORM_VERSION>

  is the target core platform version required.

• <3RD_PARTY_PLATFORM_URL>

  is the index URL to download the target core platform (also known as “Additional Boards Manager URLs” in the Arduino IDE). This field can be omitted for the official

  arduino:*

  platforms.

• <PLATFORM_DEPENDENCY>

  ,

  <PLATFORM_DEPENDENCY_VERSION>

  , and

  <3RD_PARTY_PLATFORM_DEPENDENCY_URL>

  contains the same information as

  <PLATFORM>

  ,

  <PLATFORM_VERSION>

  , and

  <3RD_PARTY_PLATFORM_URL>

  respectively but for the core platform dependency of the main core platform. These fields are optional.

• libraries:

  is a section where the required libraries to build the project are defined. This section is optional.

• <LIB_VERSION>

  is the version required for the library, for example,

  1.0.0

  .

• <USER_NOTES>

  is a free text string available to the developer to add comments. This field is optional.

• <PROGRAMMER>

  is the programmer that will be used. This field is optional.

The following fields are available since Arduino CLI 1.1.0:

• <PORT_NAME>

  is the port that will be used to upload and monitor the board (unless explicitly set otherwise). This field is optional.

• port_config

  section with

  <PORT_SETTING_NAME>

  and

  <PORT_SETTING_VALUE>

  defines the port settings that will be used in the

  monitor

  command. Typically is used to set the baudrate for the serial port (for example

  baudrate: 115200

  ) but any setting/value can be specified. Multiple settings can be set. These fields are optional.

• <PORT_PROTOCOL>

  is the protocol for the port used to upload and monitor the board. This field is optional.

A complete example of a sketch project file may be the following:

1profiles:
2  nanorp:
3    fqbn: arduino:mbed_nano:nanorp2040connect
4    platforms:
5      - platform: arduino:mbed_nano (2.1.0)
6    libraries:
7      - ArduinoIoTCloud (1.0.2)
8      - Arduino_ConnectionHandler (0.6.4)
9      - TinyDHT sensor library (1.1.0)
10
11  another_profile_name:
12    notes: testing the limit of the AVR platform, may be unstable
13    fqbn: arduino:avr:uno
14    platforms:
15      - platform: arduino:avr (1.8.4)
16    libraries:
17      - VitconMQTT (1.0.1)
18      - Arduino_ConnectionHandler (0.6.4)
19      - TinyDHT sensor library (1.1.0)
20    port: /dev/ttyACM0
21    port_config:
22      baudrate: 115200
23
24  tiny:
25    notes: testing the very limit of the AVR platform, it will be very unstable
26    fqbn: attiny:avr:ATtinyX5:cpu=attiny85,clock=internal16
27    platforms:
28      - platform: attiny:avr (1.0.2)
29        platform_index_url: https://raw.githubusercontent.com/damellis/attiny/ide-1.6.x-boards-manager/package_damellis_attiny_index.json
30      - platform: arduino:avr (1.8.3)
31    libraries:
32      - ArduinoIoTCloud (1.0.2)
33      - Arduino_ConnectionHandler (0.6.4)
34      - TinyDHT sensor library (1.1.0)
35
36  feather:
37    fqbn: adafruit:samd:adafruit_feather_m0
38    platforms:
39      - platform: adafruit:samd (1.6.0)
40        platform_index_url: https://adafruit.github.io/arduino-board-index/package_adafruit_index.json
41    libraries:
42      - ArduinoIoTCloud (1.0.2)
43      - Arduino_ConnectionHandler (0.6.4)
44      - TinyDHT sensor library (1.1.0)
45
46default_profile: nanorp

Building a sketch

When a sketch project file is present, it can be leveraged to compile the sketch with the

--profile/-m

compile

1arduino-cli compile --profile nanorp

In this case, the sketch will be compiled using the core platform and libraries specified in the nanorp profile. If a core platform or a library is missing it will be automatically downloaded and installed on the fly in an isolated directory inside the data folder. The dedicated storage is not accessible to the user and is meant as a "cache" of the resources used to build the sketch.

When using the profile-based build, the globally installed platforms and libraries are excluded from the compile and can not be used in any way. In other words, the build is isolated from the system and will rely only on the resources specified in the profile: this will ensure that the build is portable and reproducible independently from the platforms and libraries installed in the system.

Using a default profile

If a

default_profile

sketch.yaml

1arduino-cli compile [sketch]

will, instead, trigger a profile-based build using the default profile indicated in the

sketch.yaml

Default flags for Arduino CLI usage

The sketch project file may be used to set the default value for some command line flags of the Arduino CLI, in particular:

• The

  default_fqbn

  key sets the default value for the

  --fqbn

  flag
• The

  default_programmer

  key sets the default value for the

  --programmer

  flag
• The

  default_port

  key sets the default value for the

  --port

  flag
• The

  default_port_config

  key sets the default values for the

  --config

  flag in the

  monitor

  command (available since Arduino CLI 1.1.0)
• The

  default_protocol

  key sets the default value for the

  --protocol

  flag
• The

  default_profile

  key sets the default value for the

  --profile

  flag

For example:

1default_fqbn: arduino:samd:mkr1000
2default_programmer: atmel_ice
3default_port: /dev/ttyACM0
4default_port_config:
5  baudrate: 115200
6default_protocol: serial
7default_profile: myprofile

With this configuration set, it is not necessary to specify the

--fqbn

--programmer

--port

--protocol

--profile

arduino-cli compile

arduino-cli upload

arduino-cli debug

monitor

--config baudrate=115200