Sketch build process

The process the Arduino development software uses to build a sketch. More useful information can be found in the Arduino platform specification. Note that the following refers specifically to the build process for AVR targets. Other architectures follow a similar build process, but may use other tools and compilers.

Overview

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 (e.g,

avr-gcc

digitalWrite()

Serial.print()

Pre-Processing

The Arduino development software performs a few transformations to your sketch before passing it to the compiler (e.g.,

avr-gcc

• 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. The .cpp filename extension is then added to the resulting file.
• If not already present,

  #include <Arduino.h>

  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.

No pre-processing is done to files in a sketch with any extension other than .ino or .pde. Additionally, .h files in the sketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .c file from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in an

extern "C" {}

Dependency Resolution

The sketch is scanned recursively for dependencies. There are predefined include search paths:

1. Core library folder (as defined by

   {build.core}

   )
2. Variant folder (as defined by

   {build.variant}

   )
3. Standard system directories (e.g.,

   {runtime.tools.avr-gcc.path}/avr/include

   )
4. Include search paths added to resolve prior dependencies

If the dependency is not present in any of those locations, the installed libraries are then searched (see the Location Priority table below for library locations). For information on the allowed library sub-folder structures see the Arduino library specification.

-I

includes

If multiple libraries contain a file that matches the

#include

1. A library that has been specified using the

   --library

   option of

   arduino-cli compile

   wins against a library in other locations
2. A library that is architecture compatible wins against a library that is not architecture compatible (see Architecture Matching)
3. A library with both library name and folder name matching the include wins
4. A library that has better "library name priority" or "folder name priority" wins (see Library Name Priority and Folder Name Priority)
5. A library that is architecture optimized wins against a library that is not architecture optimized (see Architecture Matching)
6. A library that has a better "location priority" wins (see Location Priority)
7. A library that has a folder name with a better score using the "closest-match" algorithm wins
8. A library that has a folder name that comes first in alphanumeric order wins

Architecture Matching

A library is considered compatible with architecture

X

architectures

• explicitly contains the architecture

  X

• contains the catch-all

  *

• is not specified at all.

A library is considered optimized for architecture

X

architectures

X

X

Examples:

architectures

library.properties

avr

avr

architectures=*

architectures=avr

architectures=*,avr

architectures=*,esp8266

architectures=avr,esp8266

architectures=samd

Library Name Priority

A library's name is defined by the library.properties

name

_

The "library name priority" is determined as follows (in order of highest to lowest priority):

Arduino_Low_Power.h

Arduino Low Power

-main

Arduino Low Power-main

-master

Arduino Low Power-master

Arduino Low Power Whatever

Awesome Arduino Low Power

The Arduino Low Power Lib

Folder Name Priority

The "folder name priority" is determined as follows (in order of highest to lowest priority):

Servo.h

Servo

-main

Servo-main

-master

Servo-master

ServoWhatever

AwesomeServo

AnAwesomeServoForWhatever

Location Priority

The "location priority" is determined as follows (in order of highest to lowest priority):

1. The library is under a custom libraries path specified via the

   --libraries

   option of

   arduino-cli compile

   (in decreasing order of priority when multiple custom paths are defined)
2. The library is under the

   libraries

   subfolder of the IDE's sketchbook or Arduino CLI's user directory
3. The library is bundled with the board platform/core (

   {runtime.platform.path}/libraries

   )
4. The library is bundled with the referenced board platform/core
5. The library is bundled with the Arduino IDE (this location is determined by the Arduino CLI configuration setting

   directories.builtin.libraries

   )

Location priorities in Arduino Web Editor

The location priorities system works in the same manner in Arduino Web Editor, but its cloud-based nature may make the locations of libraries less obvious.

1. Custom: the imported libraries, shown under the Libraries > Custom tab.
   • These libraries are under

     /tmp/\<some number>/custom

2. Pinned: libraries that were associated with the sketch by choosing a specific version from the library's "Include" dropdown menu.
   • These libraries are under

     /tmp/\<some number>/pinned

   • Note: clicking the "Include" button does not result in the library being pinned to the sketch.
3. Platform bundled: these are listed under the Libraries > Default tab, but with "for \<architecture name>" appended to the library name (e.g., "SPI for AVR").
   • These libraries are under

     /home/builder/.arduino15/packages

   1. Board platform bundled
   2. Core platform bundled
4. Built-in:
   • The non-platform bundled libraries listed under the Libraries > Default tab.
   • Libraries listed under Libraries > Library Manager.
   • These libraries are under

     /home/builder/opt/libraries/latest

Compilation

Sketches are compiled by architecture-specific versions of

gcc

g++

The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux).

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

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 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 a platform-specific upload tool (e.g., avrdude). The upload process is also controlled by variables in the boards and main preferences files. See the Arduino platform specification page for details.

If verbose output during upload is enabled, debugging information will be output to the console, including the upload tool's command lines and verbose output.