NAME

arduino_builder - Build system for Arduino programs

SYNOPSIS

arduino_builder [options] command ...

DESCRIPTION

COMMANDS

The following commands can be passed to the tool. If several commands are present, they will all be executed in the order in which they are listed below (not in the order in which they are passed). Passing a command more than once has no effect.

clean

Clean the content of the build directory (without removing the build directory itself). This command can be used only if the builder.default_build_directory configuration value is set in the project config. Otherwise, you should manually run the rm -fr directory command.

build

Build the project and all its dependencies (Arduino core and libraries).

The command tries to not rebuild unecessary parts of the binary and of its dependencies if their sources have not changed. In some circumstance we may not detect correctly all dependencies so it may be useful to run the clean command (in particular if you have deleted a source file).

discover

Run the board discovery to detect your board. This command is implied by the upload and/or monitor commands.

upload

Upload the compiled binary to your board. If the build command is not executed, the binary must already exist and no new version will be compiled before the upload.

Note that the end of the compilation phase will report whether your binary can hold in your board memory (and will abort the program if not) but the upload command itself does not perform such a check.

monitor

Open a connection to the board that allows to interract with a running program. This is usually, but not necessarily, done through a serial port.

OPTIONS

--help, -h

--project-dir dir, -p

--build-dir dir, -b

--log-level level, -l

--parallelize N, -j

--config k=v, -c

--menu m=v, -m

--skip step

--force step

--only step

--stack-trace-on-error, --stack

--target-port port, --port

CONFIGURATION FILE SYNTAX

The syntax of the configuration file used by this tool is the same as those used to describe Arduino platforms. You can read about it here.

Informally, the format is a UTF-8 text file, where empty lines and lines starting with # are ignored (but note that you can’t have end-of-line comments on non-comment lines). Other lines have an key=value syntax where keys can contain letters, numbers and ., _, and - characters and values can contain anything. Values can be expressed with other values by putting their key in brackets. For examples:

value.name=text with {other.value}

CONFIGURATION FILES

When you start arduino_builder it will read a set of configuration files. Once a key is defined by a given file it will not be overriden by other files defining the same key. So the most specific configuration should be loaded first.

The following files are read in that order when they exist (any of these files is allowed to be missing):

- Command line options. These are not actually configuration files but options passed with the --config or --menu command line switches will take precedance over any other configuration files that will be read afterward.

- arduino_builder.local file in the project directory.

- arduino_builder.config file in the project directory.

- boards.local.txt file in the platform package directory.

- boards.txt file in the platform package directory.

This file and the previous ones are treated specially: once they are read, configuration properties are filtered to keep only thoses prefixed by the name of the board specified by the builder.package.board configuration (that is expected to be present in the arduino_builder.config file). And that prefix is removed from the configuration keys.

After that step, the "Menu Resolution" happens and the resulting configuration values will override those read in the boards.local.txt and boards.txt files (but not those read in previous files).

- platform.local.txt file in the platform package directory.

- platform.txt file in the platform package directory.

- programmers.local.txt file in the platform package directory.

- programmers.txt.txt file in the platform package directory.

CONFIGURATION VALUES

Note that all paths set in configuration values must be absolute path (they will not be interpreted as relative path to the config file for example). However you can make these paths be relative by using another configuration value to provide the absolute part. For example:

builder.default_build_dir={builder.project_dir}/_build

In the list below, the configuration names followed by an asterisk * are those that should usually be in arduino_builder.local file rather than in the arduino_builder.config one.

builder.project_name

builder.package.name

builder.package.path*

builder.package.arch

builder.package.board

builder.arduino.install_dir

builder.default_build_dir

builder.source.path

builder.source.is_recursive

builder.menu.XXX

builder.library.XXX

builder.parallelize*

builder.config.append.XXX

builder.upload.port*

The port to use to upload and/or monitor the board. The passed value should be the label of a port found by the monitor command (typically the name of the serial port to use). You can run arduino_builder monitor -l debug to see which ports are found by the command.

You can also use a comma separated list for this configuration value in case your board can appear under different ports.

builder.project_dir

The path to the root directory of the project (typically the directory that contains the arduino_builder.config file). In general, you should not set this value and it will be set automatically. However this value is commonly used as part of other values to defines paths relative to your project directory (see the example at the top of this section).

Other standard properties of the Arduino build system, documented here, are also implemented and can be used when defining the config of your project.

MENU RESOLUTION

BINARY UPLOAD

ENVIRONMENT VARIABLES

ARDUINO_BUILDER_LOG_LEVEL

CAVEATS

Not all features of the Arduino GUI are currently implemented. The main missing features are the following ones:

Library auto-discovery

For now, you have to specify explicitly all the libraries that are used by your program as well as where these libraries are installed.

Core and libraries download

Arduino Builder can’t (yet) download missing core and libraries. They must all be installed on your system before compiling.

Pre-compiled libraries

The Arduino GUI can use pre-compiled libraries for closed source code. This is not supported yet by this tool.

Core, variant and library reference

The configuration syntax to reference other packages (documented here) is not yet supported.

Non MS-Windows systems

Only the basic features of the tool have been tested on Linux and, for now, no tests have been performed on MacOS. Please report any bug that you encounter with these OSs with as much details as you can.

Automatic board detection

There are some mechanism in the Arduino software to identify a connected board. For now we require that the user specifies the port used to communicate with the board.

Upload verification

The verification step, documented here, is not yet implemented.

Similarly uploads using external programmers and bootloader burning are not handled.

1200bps bootloader reset

If the reset to bootloader is not performed by the upload tools used, Arduino Builder cannot yet perform this reset itself (documented here). =back

AUTHOR

This program has been written by Mathias Kende.

COPYRIGHT AND LICENSE

Copyright 2022 Mathias Kende

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SEE ALSO

Arduino CLI

cpanm App::ArduinoBuilder

perl -MCPAN -e shell
install App::ArduinoBuilder