Sketch build process

The process the Arduino development software uses to build a sketch. More useful information can be found in theArduino platform specification. Note that the following refers specifically to the buildprocess 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 developmentsoftware performs some minor pre-processing to turn your sketch into a C++ program. Next, dependencies of the sketch arelocated. It then gets passed to a compiler (e.g,avr-gcc), which turns the human readable code into machine readableinstructions (or object files). Then your code gets combined with (linked against) the standard Arduino libraries thatprovide basic functions likedigitalWrite() orSerial.print(). The result is a single Intel hex file, which containsthe specific bytes that need to be written to the program memory of the chip on the Arduino board. This file is thenuploaded to the board: transmitted over the USB or serial connection via the bootloader already on the chip or withexternal programming hardware.

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 thesketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .cfile from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in anextern "C" {}block that is defined only inside of C++ files.

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 theLocation Priority table below for library locations). For information on the allowed librarysub-folder structures seethe Arduino library specification.-I options aregenerated for the path to each library dependency and appended to theincludes property, to be used incompilation recipes in platform.txt.

If multiple libraries contain a file that matches the#include directive, the priority is determined by applying thefollowing rules, one by one in this order, until a rule determines a winner:

1. A library that has been specified using the--library option ofarduino-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 (seeArchitecture Matching)
3. A library with bothlibrary name andfolder name matching the include wins
4. A library that has better "library name priority" or "folder name priority" wins (seeLibrary Name Priority andFolder Name Priority)
5. A library that is architecture optimized wins against a library that is not architecture optimized (seeArchitecture Matching)
6. A library that has a better "location priority" wins (seeLocation 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 consideredcompatible with architectureX if thearchitectures field inlibrary.properties:

• explicitly contains the architectureX
• contains the catch-all*
• is not specified at all.

A library is consideredoptimized for architectureX only if thearchitectures field in library.propertiesexplicitly contains the architectureX. This means that a library that is optimized for architectureX is alsocompatible with it.

Examples:

Library Name Priority¶

A library's name is defined by thelibrary.propertiesnamefield. That value is sanitized by replacing spaces with_ before comparing it to the file name of the include.

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

Folder Name Priority¶

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

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 ofarduino-cli compile (in decreasing order of priority when multiple custom paths are defined)
2. The library is under thelibraries 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 thereferenced board platform/core
5. The library is bundled with the Arduino IDE (this location is determined by the Arduino CLI configuration settingdirectories.builtin.libraries)

Location priorities in Arduino Web Editor¶

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

1. Custom: the imported libraries, shown under theLibraries > Custom tab.
   • These libraries are under/tmp/\<some number>/custom
2. Pinned: libraries that wereassociated 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 theLibraries > 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 1.Core platform bundled
4. Built-in:
   • The non-platform bundled libraries listed under theLibraries > Default tab.
   • Libraries listed underLibraries > Library Manager.
   • These libraries are under/home/builder/opt/libraries/latest

Compilation¶

Sketches are compiled by architecture-specific versions ofgcc andg++ according to the variables in the boards.txtfile of the selected board'splatform.

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 thesketch's .ino and .pde files during the sketch pre-processing step). Source files of the target are compiled and outputwith .o extensions to this build directory, as are the main sketch files and any other source files in the sketch andany source files in any libraries which are#included in the sketch.

Before compiling a source file, an attempt is made to reuse the previously compiled .o file, which speeds up the buildprocess. A special .d (dependency) file provides a list of all other files included by the source. The compile step isskipped if the .o and .d files exist and have timestamps newer than the source and all the dependent files. If thesource 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 thenext 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 mostsketches.

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 ofthe 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 byvariables in the boards and main preferences files. See theArduino platform specificationpage for details.

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