arduino-builder

Compile a sketch

$ arduino-builder -compile [path/to/sketch.ino]

$ arduino-builder -debug-level [1..10]

$ arduino-builder -build-path [path/to/build_directory]

$ arduino-builder -build-options-file [path/to/build.options.json]

$ arduino-builder -verbose [true]

arduino-builder [options] <sketch_path>
Example: arduino-builder -fqbn arduino:avr:uno -hardware /opt/arduino/hardware -tools /opt/arduino/tools -libraries /opt/arduino/libraries -build-path /tmp/build_dir /path/to/your/sketch.ino

-fqbn <fqbn>
    Specifies the Fully Qualified Board Name (e.g., arduino:avr:uno) for compilation. This is a critical parameter.

-build-path <path>
    Defines the directory where all intermediate and final build artifacts (.o files, .hex file, etc.) will be stored.

-hardware <path>
    Adds a path to search for hardware definitions (boards, platforms, cores). Can be specified multiple times for various locations.

-tools <path>
    Adds a path to search for build tools (compilers, uploaders, etc.). Can be specified multiple times.

-libraries <path>
    Adds a path to search for Arduino libraries. Can be specified multiple times for custom library locations.

-verbose
    Enables verbose output during the compilation process, showing detailed compiler commands and progress.

-warnings <level>
    Sets the compiler warning level. Possible values include none, default, more, and all.

-debug-level <level>
    Sets the internal debug level for arduino-builder itself.

-build-properties <prop=value>
    Passes custom build properties directly to the underlying build system, overriding default values from platform.txt.

-vid <vid>
    Overrides the USB Vendor ID read from boards.txt for specific board configurations.

-pid <pid>
    Overrides the USB Product ID read from boards.txt.

-only-verify-preprocessor
    Runs only the preprocessor phase, useful for checking syntax and include paths without full compilation.

-compile
    (Default) Compiles the sketch. This option is implicitly enabled if no other action is specified.

-upload
    Uploads the compiled sketch to the board after successful compilation. Requires a configured uploader tool.

-port <port>
    Specifies the serial port (e.g., /dev/ttyUSB0 or COM3) to use for uploading the sketch.

-version
    Prints the version of arduino-builder and exits.

-help
    Displays a help message detailing available command-line options.

arduino-builder is a fundamental command-line tool that serves as the core build system for Arduino sketches and libraries. It parses sketch code, resolves dependencies, locates necessary hardware definitions (boards, platforms), compiles C/C++ files using the appropriate toolchain (like avr-gcc), links object files, and generates the final executable (e.g., .hex file for AVR boards). This separation of the build logic from the Arduino IDE allows for headless compilation, automated testing, and integration into continuous integration/delivery (CI/CD) pipelines, providing a consistent and robust build process across various environments. It is often invoked by higher-level tools like arduino-cli or directly within custom build scripts.

Using arduino-builder effectively often requires a good understanding of the Arduino project structure and how boards.txt and platform.txt files define the build process.
It relies on a well-configured Arduino environment (correct paths for hardware, tools, libraries).
Error messages, especially from underlying compilers, can sometimes be cryptic.
While it can compile and upload, it does not provide the full development experience of the Arduino IDE or arduino-cli (e.g., board manager, library manager).

The arduino-builder orchestrates several key phases during compilation:
1. Pre-processing: Handles .ino file conversion, resolves includes, and prepares the sketch.
2. Core & Library Compilation: Compiles the Arduino core library and any included user/third-party libraries.
3. Sketch Compilation: Compiles the user's specific sketch files (.ino, .c, .cpp).
4. Linking: Combines all compiled object files with necessary toolchain libraries to create the final executable.
5. Hex File Generation: Converts the executable into a platform-specific uploadable format (e.g., an .hex file for AVR microcontrollers).
6. (Optional) Upload: If specified, invokes the appropriate programmer tool (e.g., avrdude) to flash the compiled code onto the board.

arduino-builder was introduced to modularize the Arduino IDE's build process, separating the core compilation logic from the graphical user interface. Prior to its existence, the IDE directly handled all build steps, making headless compilation and automated testing challenging. Its development marked a significant step towards enabling command-line automation and integration of Arduino projects into modern software development workflows, ultimately leading to the creation and widespread adoption of arduino-cli as the official command-line tool.

arduino-cli(1), make(1), gcc(1), avr-gcc(1)