README
¶
Arduino Builder 
A command line tool for compiling Arduino sketches
This tool is able to parse Arduino Hardware specifications, properly run gcc and produce compiled sketches.
An Arduino sketch differs from a standard C program in that it misses a main (provided by the Arduino core), function prototypes are not mandatory, and libraries inclusion is automagic (you just have to #include them).
This tool generates function prototypes and gathers library paths, providing gcc with all the needed -I params.
Usage
-
-compileor-dump-prefsor-preprocess: Optional. If omitted, defaults to-compile.-dump-prefswill just print all build preferences used,-compilewill use those preferences to run the actual compiler,-preprocesswill only print preprocessed code to stdout. -
-hardware: Mandatory. Folder containing Arduino platforms. An example is thehardwarefolder shipped with the Arduino IDE, or thepackagesfolder created by Arduino Boards Manager. Can be specified multiple times. If conflicting hardware definitions are specified, the last one wins. -
-tools: Mandatory. Folder containing Arduino tools (gcc,avrdude...). An example is thehardware/toolsfolder shipped with the Arduino IDE, or thepackagesfolder created by Arduino Boards Manager. Can be specified multiple times. -
-libraries: Optional. Folder containing Arduino libraries. An example is thelibrariesfolder shipped with the Arduino IDE. Can be specified multiple times. -
-fqbn: Mandatory. Fully Qualified Board Name, e.g.: arduino:avr:uno -
-build-path: Optional. Folder where to save compiled files. If omitted, a folder will be created in the temporary folder specified by your OS. -
-prefs=key=value: Optional. It allows to override some build properties. -
-warnings: Optional, can be "none", "default", "more" and "all". Defaults to "none". Used to tellgccwhich warning level to use (-Wflag). -
-verbose: Optional, turns on verbose mode. -
-quiet: Optional, supresses almost every output. -
-debug-level: Optional, defaults to "5". Used for debugging. Set it to 10 when submitting an issue. -
-core-api-version: Optional, defaults to "10600". The version of the Arduino IDE which is using this tool. -
-logger: Optional, can be "human", "humantags" or "machine". Defaults to "human". If "humantags" the messages are qualified with a prefix that indicates their level (info, debug, error). If "machine", messages emitted will be in a format which the Arduino IDE understands and that it uses for I18N. -
-version: if specified, prints version and exits. -
-build-options-file: it specifies path to a localbuild.options.jsonfile (see paragraph below), which allows you to omit specifying params such as-hardware,-tools,-libraries,-fqbn,-prefand-ide-version. -
-vid-pid: when specified, VID/PID specific build properties are used, if boards supports them.
Final mandatory parameter is the sketch to compile (of course).
What is and how to use build.options.json file
Every time you run this tool, it will create a build.options.json file in build path. It's used to understand if build options (such as hardware folders, fqbn and so on) were changed when compiling the same sketch.
If they changed, the whole build path is wiped out. If they didn't change, previous compiled files will be reused if the corresponding source files didn't change as well.
You can save this file locally and use it instead of specifying -hardware, -tools, -libraries, -fqbn, -pref and -ide-version.
Using it for continuously verify your libraries or cores
See Doing continuous integration with arduino builder.
Building from source
You need a recent version of Go (>=1.8.0).
To build, run the following commands:
go get github.com/go-errors/errors
go get github.com/stretchr/testify
go get github.com/jstemmer/go-junit-report
go get github.com/arduino/go-properties-map
go get github.com/arduino/go-timeutils
go get github.com/arduino/arduino-builder
go build github.com/arduino/arduino-builder/arduino-builder
TDD
In order to run the tests, type:
go test github.com/arduino/arduino-builder/arduino-builder/...
This runs all tests, showing any failures and a summary at the end. Add the -v option to show each test as it is being ran. Currently, arduino-builder itself also generates copious output, even for non-failing testcases and without -v, and testing does not stop at the first failure, so you probably want to redirect test output so you can scroll back to find any failures.
To run a single test, use the -run option, which accepts a regular expression (see also go help testflag).
go test github.com/arduino/arduino-builder/arduino-builder/... -run 'TestBuilderEmptySketch'
go test github.com/arduino/arduino-builder/arduino-builder/... -run 'TestPrototypesAdder.*'
In jenkins, use
go test -v github.com/arduino/arduino-builder/arduino-builder/... | bin/go-junit-report > report.xml
The first time you run the tests, some needed files (toolchains and
source files) will be downloaded, which needs about 1GB of space (at the
time of writing). If you have a slow connection, this download might
exceed the default 10 minute timeout for a single test. If you run into
this, add -timeout 60m or similar to the commandline to extend the
timeout. If you are running on slower system (like a rasbperry pi),
increasing the timeout might be needed as well.
License and Copyright
arduino-builder is licensed under General Public License version 2, as published by the Free Software Foundation. See LICENSE.txt.
Copyright (C) 2017 Arduino AG and contributors
See https://www.arduino.cc/ and https://github.com/arduino/arduino-builder/graphs/contributors
Documentation
¶
Index ¶
- Constants
- Variables
- func GeneratePreprocPatternFromCompile(compilePattern string) string
- func PrintRingNameIfDebug(ctx *types.Context, command types.Command)
- func ResolveLibrary(ctx *types.Context, header string) *types.Library
- func RunBuilder(ctx *types.Context) error
- func RunParseHardwareAndDumpBuildProperties(ctx *types.Context) error
- func RunPreprocess(ctx *types.Context) error
- type AddAdditionalEntriesToContext
- type AddBuildBoardPropertyIfMissing
- type AddMissingBuildPropertiesFromParentPlatformTxtFiles
- type AdditionalSketchFilesCopier
- type Builder
- type CTagsRunner
- type CTagsTargetFileSaver
- type ContainerAddPrototypes
- type ContainerBuildOptions
- type ContainerFindIncludes
- type ContainerMergeCopySketchFiles
- type ContainerSetupHardwareToolsLibsSketchAndProps
- type CreateBuildOptionsMap
- type DumpBuildProperties
- type EnsureBuildPathExists
- type FailIfBuildPathEqualsSketchPath
- type FailIfImportedLibraryIsWrong
- type FilterSketchSource
- type GCCPreprocRunner
- type GCCPreprocRunnerForDiscoveringIncludes
- type GCCPreprocSourceSaver
- type GenerateBuildPathIfMissing
- type HardwareLoader
- type IncludesFinderWithRegExp
- type LibrariesLoader
- type LoadPreviousBuildOptionsMap
- type LoadVIDPIDSpecificProperties
- type MergeSketchWithBootloader
- type ParseHardwareAndDumpBuildProperties
- type PlatformKeysRewriteLoader
- type Preprocess
- type PrintPreprocessedSource
- type PrintUsedAndNotUsedLibraries
- type PrintUsedLibrariesIfVerbose
- type PrototypesAdder
- type ReadFileAndStoreInContext
- type RecipeByPrefixSuffixRunner
- type RewriteHardwareKeys
- type SetCustomBuildProperties
- type SetupBuildProperties
- type SketchLoader
- type SketchSaver
- type SketchSourceMerger
- type StoreBuildOptionsMap
- type TargetBoardResolver
- type ToolsLoader
- type UnusedCompiledLibrariesRemover
- type WarnAboutArchIncompatibleLibraries
- type WarnAboutPlatformRewrites
- type WipeoutBuildPathIfBuildOptionsChanged
Constants ¶
const DEFAULT_BUILD_CORE = "arduino"
const DEFAULT_DEBUG_LEVEL = 5
const DEFAULT_SOFTWARE = "ARDUINO"
const DEFAULT_WARNINGS_LEVEL = "none"
Variables ¶
var ADDITIONAL_FILE_VALID_EXTENSIONS = map[string]bool{".h": true, ".c": true, ".hpp": true, ".hh": true, ".cpp": true, ".s": true}
var ADDITIONAL_FILE_VALID_EXTENSIONS_NO_HEADERS = map[string]bool{".c": true, ".cpp": true, ".s": true}
var INCLUDE_REGEXP = regexp.MustCompile("(?ms)^\\s*#[ \t]*include\\s*[<\"](\\S+)[\">]")
var LIBRARY_CATEGORIES = map[string]bool{ "Display": true, "Communication": true, "Signal Input/Output": true, "Sensors": true, "Device Control": true, "Timing": true, "Data Storage": true, "Data Processing": true, "Other": true, "Uncategorized": true, }
var LIBRARY_MANDATORY_PROPERTIES = []string{constants.LIBRARY_NAME, constants.LIBRARY_VERSION, constants.LIBRARY_AUTHOR, constants.LIBRARY_MAINTAINER}
var LIBRARY_NOT_SO_MANDATORY_PROPERTIES = []string{constants.LIBRARY_SENTENCE, constants.LIBRARY_PARAGRAPH, constants.LIBRARY_URL}
var MAIN_FILE_VALID_EXTENSIONS = map[string]bool{".ino": true, ".pde": true}
Functions ¶
func RunBuilder ¶
func RunPreprocess ¶
Types ¶
type AddAdditionalEntriesToContext ¶
type AddAdditionalEntriesToContext struct{}
type AddBuildBoardPropertyIfMissing ¶
type AddBuildBoardPropertyIfMissing struct{}
type AddMissingBuildPropertiesFromParentPlatformTxtFiles ¶
type AddMissingBuildPropertiesFromParentPlatformTxtFiles struct{}
type AdditionalSketchFilesCopier ¶
type AdditionalSketchFilesCopier struct{}
type CTagsRunner ¶
type CTagsRunner struct{}
type CTagsTargetFileSaver ¶
type ContainerAddPrototypes ¶
type ContainerAddPrototypes struct{}
type ContainerBuildOptions ¶
type ContainerBuildOptions struct{}
type ContainerFindIncludes ¶
type ContainerFindIncludes struct{}
type ContainerMergeCopySketchFiles ¶
type ContainerMergeCopySketchFiles struct{}
type ContainerSetupHardwareToolsLibsSketchAndProps ¶
type ContainerSetupHardwareToolsLibsSketchAndProps struct{}
type CreateBuildOptionsMap ¶
type CreateBuildOptionsMap struct{}
type DumpBuildProperties ¶
type DumpBuildProperties struct{}
type EnsureBuildPathExists ¶
type EnsureBuildPathExists struct{}
type FailIfBuildPathEqualsSketchPath ¶
type FailIfBuildPathEqualsSketchPath struct{}
type FailIfImportedLibraryIsWrong ¶
type FailIfImportedLibraryIsWrong struct{}
type FilterSketchSource ¶
type FilterSketchSource struct {
Source *string
}
type GCCPreprocRunner ¶
type GCCPreprocRunnerForDiscoveringIncludes ¶
type GCCPreprocSourceSaver ¶
type GCCPreprocSourceSaver struct{}
type GenerateBuildPathIfMissing ¶
type GenerateBuildPathIfMissing struct{}
type HardwareLoader ¶
type HardwareLoader struct{}
type IncludesFinderWithRegExp ¶
type IncludesFinderWithRegExp struct {
Source *string
}
type LibrariesLoader ¶
type LibrariesLoader struct{}
type LoadPreviousBuildOptionsMap ¶
type LoadPreviousBuildOptionsMap struct{}
type LoadVIDPIDSpecificProperties ¶
type LoadVIDPIDSpecificProperties struct{}
type MergeSketchWithBootloader ¶
type MergeSketchWithBootloader struct{}
type ParseHardwareAndDumpBuildProperties ¶
type ParseHardwareAndDumpBuildProperties struct{}
type PlatformKeysRewriteLoader ¶
type PlatformKeysRewriteLoader struct{}
type Preprocess ¶
type Preprocess struct{}
type PrintPreprocessedSource ¶
type PrintPreprocessedSource struct{}
type PrintUsedAndNotUsedLibraries ¶
type PrintUsedAndNotUsedLibraries struct {
// Was there an error while compiling the sketch?
SketchError bool
}
type PrintUsedLibrariesIfVerbose ¶
type PrintUsedLibrariesIfVerbose struct{}
type PrototypesAdder ¶
type PrototypesAdder struct{}
type ReadFileAndStoreInContext ¶
type ReadFileAndStoreInContext struct {
Target *string
}
type RewriteHardwareKeys ¶
type RewriteHardwareKeys struct{}
type SetCustomBuildProperties ¶
type SetCustomBuildProperties struct{}
type SetupBuildProperties ¶
type SetupBuildProperties struct{}
type SketchLoader ¶
type SketchLoader struct{}
type SketchSaver ¶
type SketchSaver struct{}
type SketchSourceMerger ¶
type SketchSourceMerger struct{}
type StoreBuildOptionsMap ¶
type StoreBuildOptionsMap struct{}
type TargetBoardResolver ¶
type TargetBoardResolver struct{}
type ToolsLoader ¶
type ToolsLoader struct{}
type UnusedCompiledLibrariesRemover ¶
type UnusedCompiledLibrariesRemover struct{}
type WarnAboutArchIncompatibleLibraries ¶
type WarnAboutArchIncompatibleLibraries struct{}
type WarnAboutPlatformRewrites ¶
type WarnAboutPlatformRewrites struct{}
type WipeoutBuildPathIfBuildOptionsChanged ¶
type WipeoutBuildPathIfBuildOptionsChanged struct{}
Source Files
¶
- add_additional_entries_to_context.go
- add_build_board_property_if_missing.go
- add_missing_build_properties_from_parent_platform_txt_files.go
- additional_sketch_files_copier.go
- builder.go
- container_add_prototypes.go
- container_build_options.go
- container_find_includes.go
- container_merge_copy_sketch_files.go
- container_setup.go
- create_build_options_map.go
- ctags_runner.go
- ctags_target_file_saver.go
- dump_build_properties.go
- ensure_buildpath_exists.go
- fail_if_buildpath_equals_sketchpath.go
- fail_if_imported_library_is_wrong.go
- filter_sketch_source.go
- gcc_preproc_runner.go
- gcc_preproc_source_saver.go
- generate_buildpath_if_missing.go
- hardware_loader.go
- includes_finder_with_regexp.go
- libraries_loader.go
- load_previous_build_options.go
- load_vid_pid_specific_properties.go
- merge_sketch_with_bootloader.go
- platform_keys_rewrite_loader.go
- print_preprocessed_source.go
- print_used_and_not_used_libraries.go
- print_used_libraries_if_verbose.go
- prototypes_adder.go
- read_file_and_store_in_context.go
- recipe_runner.go
- resolve_library.go
- rewrite_hardware_keys.go
- set_custom_build_properties.go
- setup_build_properties.go
- sketch_loader.go
- sketch_saver.go
- sketch_source_merger.go
- store_build_options_map.go
- target_board_resolver.go
- tools_loader.go
- unused_compiled_libraries_remover.go
- warn_about_arch_incompatible_libraries.go
- warn_about_platform_rewrites.go
- wipeout_build_path_if_build_options_changed.go
Directories