|
| 1 | +# arduino-builder.py |
| 2 | + |
| 3 | +This script manages _[arduino-builder](https://github.com/arduino/arduino-builder)_ command line tool for compiling Arduino sketch(es). |
| 4 | + |
| 5 | +## Requirements |
| 6 | +- [Arduino IDE](https://www.arduino.cc/en/Main/Software) (_[arduino-builder](https://github.com/arduino/arduino-builder)_ is included) |
| 7 | +- Python version greater than or equal to 3.2 (due to `concurrent.futures` usage) |
| 8 | + |
| 9 | +## Usage |
| 10 | + |
| 11 | +``` |
| 12 | +usage: arduino-builder.py [-h] [-l [{board,sketch}] | -a] [-b pattern] [-c] |
| 13 | + [--arch architecture] |
| 14 | + [--config <core configuration file>] [-v] |
| 15 | + [--bin | --travis] |
| 16 | + [-i <shetch filepath> | -f <sketches list filepath> | -s pattern | -e <excluded sketches list filepath>] |
| 17 | +
|
| 18 | +Manage arduino-builder command line tool for compiling Arduino sketch(es). |
| 19 | +
|
| 20 | +optional arguments: |
| 21 | + -h, --help show this help message and exit |
| 22 | + -l [{board,sketch}], --list [{board,sketch}] |
| 23 | + list available board(s) or sketch(es) |
| 24 | + -a, --all build all sketches found for all available boards |
| 25 | + -b pattern, --board pattern |
| 26 | + pattern to find one or more board(s) to build |
| 27 | + -c, --clean clean output directory |
| 28 | + <user path config>/arduinoBuilderOutput |
| 29 | + --arch architecture core architecture to build. Default build architecture |
| 30 | + is stm32 |
| 31 | + --config <core configuration file> |
| 32 | + JSON file containing the build configuration for one |
| 33 | + or more maintainer/architecture. Board options for |
| 34 | + build, applicability of sketches for boards or |
| 35 | + required options. If sketch is not listed then |
| 36 | + applicable to all board. Default core configuration is |
| 37 | + for 'stm32' architecture in: conf/cores_config.json |
| 38 | + -v, --verbose enable arduino-builder verbose mode |
| 39 | + --bin save binaries |
| 40 | + --travis Custom configuration for Travis CI build |
| 41 | +
|
| 42 | +Sketch(es) options: |
| 43 | + By default build <arduino path>/examples/01.Basics/BareMinimum/BareMinimum.ino |
| 44 | +
|
| 45 | + -i <shetch filepath>, --ino <shetch filepath> |
| 46 | + single ino file to build |
| 47 | + -f <sketches list filepath>, --file <sketches list filepath> |
| 48 | + file containing list of sketches to build |
| 49 | + -s pattern, --sketches pattern |
| 50 | + pattern to find one or more sketch to build |
| 51 | + -e <excluded sketches list filepath>, --exclude <excluded sketches list filepath> |
| 52 | + file containing pattern of sketches to ignore. Default |
| 53 | + path : conf/exclude_list.txt |
| 54 | +``` |
| 55 | + |
| 56 | +## Cores configuration files |
| 57 | + |
| 58 | +Script is able to uses a JSON configuration file containing the build configuration for one or more maintainer/architecture. |
| 59 | +A default configuration file is provided: [cores_config.json](conf/cores_config.json) |
| 60 | + |
| 61 | + |
| 62 | +#### Template |
| 63 | +```json |
| 64 | +{ |
| 65 | + "cores": [ |
| 66 | + { |
| 67 | + "maintainer": "maintainer/vendor name", |
| 68 | + "architecture": "architecture name", |
| 69 | + "boards": [ |
| 70 | + { |
| 71 | + "name": "board1", |
| 72 | + "options": "specific options for board1 to concatenate with the fqbn" |
| 73 | + }, |
| 74 | + { |
| 75 | + "name": "board2", |
| 76 | + "fqbn": "Fully Qualified Board Name and options, used instead of generated one" |
| 77 | + } |
| 78 | + ], |
| 79 | + "sketches": [ |
| 80 | + { |
| 81 | + "pattern": "sketche(s) pattern", |
| 82 | + "applicable": true, |
| 83 | + "boards": [ "List of boards (comma separated) which can be built for the sketche(s) pattern. Only those listed board will be built." ], |
| 84 | + "options": "specific options to build the matched sketch pattern to concatenate with the fqbn (optional)" |
| 85 | + }, |
| 86 | + { |
| 87 | + "pattern": "sketche(s) pattern", |
| 88 | + "applicable": false, |
| 89 | + "boards": [ "List of boards (comma separated) which cannot be built for the sketche(s) pattern. All others available boards will be built." ] |
| 90 | + } |
| 91 | + ] |
| 92 | + }, |
| 93 | + { |
| 94 | + "maintainer": "Other maintainer/vendor name", |
| 95 | + "architecture": "Other architecture name", |
| 96 | + "boards": [ |
| 97 | + { |
| 98 | + "name": "boardx", |
| 99 | + "options": "specific options for board1 to concatenate with the fqbn" |
| 100 | + } |
| 101 | + ], |
| 102 | + "sketches": [ |
| 103 | + { |
| 104 | + "pattern": "sketchbook", |
| 105 | + "applicable": true, |
| 106 | + "boards": [ "" ] |
| 107 | + } |
| 108 | + ] |
| 109 | + } |
| 110 | + ] |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +#### Examples |
| 115 | + |
| 116 | +Will add `flash=C8` option to the fqbn of the BLUEPILL_F103C8 board |
| 117 | +```json |
| 118 | + { |
| 119 | + "name": "BLUEPILL_F103C8", |
| 120 | + "options": "flash=C8" |
| 121 | + } |
| 122 | +``` |
| 123 | + |
| 124 | +Will ignore `04.Communication/MultiSerial.ino` and `04.Communication/SerialPassthrough.ino` |
| 125 | +```json |
| 126 | + { |
| 127 | + "pattern": "04.Communication/(Multi)?Serial(Passthrough)?", |
| 128 | + "applicable": true, |
| 129 | + "boards": [ "" ] |
| 130 | + } |
| 131 | +``` |
| 132 | + |
| 133 | +Will build all sketches available in `09.USB/*` for the listed boards and add `usb=HID` option to the fqbn |
| 134 | +```json |
| 135 | + { |
| 136 | + "pattern": "09.USB", |
| 137 | + "applicable": true, |
| 138 | + "boards": [ "NUCLEO_F429ZI", "DISCO_L475VG_IOT", "DISCO_F407VG" ], |
| 139 | + "options": "usb=HID" |
| 140 | + } |
| 141 | +``` |
| 142 | + |
| 143 | +## Usage examples |
| 144 | + |
| 145 | +* List all boards containing `F1` or `L4` (not case sensitive): |
| 146 | + |
| 147 | +`python3 arduino-builder.py -l -b "F1|l4"` |
| 148 | + |
| 149 | +Will produce on the [stm32](https://github.com/stm32duino/Arduino_Core_STM32) core: |
| 150 | +``` |
| 151 | +Cores configuration JSON file that will be used: conf/cores_config.json |
| 152 | +Build configuration for 'STM32' maintainer and 'stm32' architecture |
| 153 | +9 board(s) available |
| 154 | +BLUEPILL_F103C8 |
| 155 | +DISCO_F100RB |
| 156 | +DISCO_L475VG_IOT |
| 157 | +MAPLEMINI_F103CB |
| 158 | +NUCLEO_F103RB |
| 159 | +NUCLEO_L432KC |
| 160 | +NUCLEO_L476RG |
| 161 | +NUCLEO_L496ZG |
| 162 | +NUCLEO_L496ZG-P |
| 163 | +``` |
| 164 | + |
| 165 | +* List all sketch containing `digital` or `analog` (not case sensitive): |
| 166 | + |
| 167 | +`python3 arduino-builder.py -l sketch -s "Digital|analog"` |
| 168 | + |
| 169 | +Will produce on the [stm32](https://github.com/stm32duino/Arduino_Core_STM32) core: |
| 170 | +``` |
| 171 | +Cores configuration JSON file that will be used: conf/cores_config.json |
| 172 | +Build configuration for 'STM32' maintainer and 'stm32' architecture |
| 173 | +<Arduino path>/examples/01.Basics/AnalogReadSerial/AnalogReadSerial.ino |
| 174 | +<Arduino path>/examples/01.Basics/DigitalReadSerial/DigitalReadSerial.ino |
| 175 | +<Arduino path>/examples/01.Basics/ReadAnalogVoltage/ReadAnalogVoltage.ino |
| 176 | +<Arduino path>/examples/02.Digital/BlinkWithoutDelay/BlinkWithoutDelay.ino |
| 177 | +<Arduino path>/examples/02.Digital/Button/Button.ino |
| 178 | +<Arduino path>/examples/02.Digital/Debounce/Debounce.ino |
| 179 | +<Arduino path>/examples/02.Digital/DigitalInputPullup/DigitalInputPullup.ino |
| 180 | +<Arduino path>/examples/02.Digital/StateChangeDetection/StateChangeDetection.ino |
| 181 | +<Arduino path>/examples/02.Digital/toneKeyboard/toneKeyboard.ino |
| 182 | +<Arduino path>/examples/02.Digital/toneMelody/toneMelody.ino |
| 183 | +<Arduino path>/examples/02.Digital/toneMultiple/toneMultiple.ino |
| 184 | +<Arduino path>/examples/02.Digital/tonePitchFollower/tonePitchFollower.ino |
| 185 | +<Arduino path>/examples/03.Analog/AnalogInOutSerial/AnalogInOutSerial.ino |
| 186 | +<Arduino path>/examples/03.Analog/AnalogInput/AnalogInput.ino |
| 187 | +<Arduino path>/examples/03.Analog/AnalogWriteMega/AnalogWriteMega.ino |
| 188 | +<Arduino path>/examples/03.Analog/Calibration/Calibration.ino |
| 189 | +<Arduino path>/examples/03.Analog/Fading/Fading.ino |
| 190 | +<Arduino path>/examples/03.Analog/Smoothing/Smoothing.ino |
| 191 | +<Arduino path>/examples/10.StarterKit_BasicKit/p08_DigitalHourglass/p08_DigitalHourglass.ino |
| 192 | +19 sketches found |
| 193 | +``` |
| 194 | + |
| 195 | +* Build all sketches containing `digital` or `analog` for all boards containing `F1` or `L4` (not case sensitive): |
| 196 | + |
| 197 | +`python3 arduino-builder.py -s "Digital|analog" -b "F1|l4"` |
| 198 | + |
| 199 | +* List all boards for STM32F1 core: |
| 200 | + |
| 201 | +`python3 arduino-builder.py -l --arch STM32F1` |
| 202 | + |
| 203 | +Will list: |
| 204 | +``` |
| 205 | +Cores configuration JSON file that will be used: conf/cores_config.json |
| 206 | +Build configuration for 'Arduino_STM32' maintainer and 'STM32F1' architecture |
| 207 | +23 board(s) available |
| 208 | +NucleoF103_HSE |
| 209 | +NucleoF103_HSI |
| 210 | +STM32F103C8 |
| 211 | +STM32F103CB |
| 212 | +STM32F103R8 |
| 213 | +STM32F103RB |
| 214 | +STM32F103RC |
| 215 | +STM32F103RE |
| 216 | +STM32F103T8 |
| 217 | +STM32F103TB |
| 218 | +STM32F103VB |
| 219 | +STM32F103VC |
| 220 | +STM32F103VD |
| 221 | +STM32F103VE |
| 222 | +STM32F103ZC |
| 223 | +STM32F103ZD |
| 224 | +STM32F103ZE |
| 225 | +STM32VLD |
| 226 | +hytiny-stm32f103t |
| 227 | +maple |
| 228 | +mapleMini |
| 229 | +mapleRET6 |
| 230 | +microduino32_flash |
| 231 | +``` |
0 commit comments