Add option to require sketch build failure

Closes #6

Author: per1234

.travis.yml

@@ -132,8 +132,8 @@ script:
   - build_sketch "${APPLICATION_FOLDER}/arduino/examples/01.Basics" "arduino:avr:uno" "false" '("1.8.1" "1.8.2")'
   # Test build_sketch with folder argument with an IDE version range
   - build_sketch "${APPLICATION_FOLDER}/arduino/examples/01.Basics" "arduino:avr:uno" "false" "1.8.1" "1.8.2"
-  # Test build_sketch with folder argument allowed to fail (this will fail because WirelessOregonV2 is AVR specific)
-  - build_sketch "${SKETCHBOOK_FOLDER}/libraries/WirelessOregonV2/examples" "arduino:sam:arduino_due_x_dbg" "true" "newest"
+  # Test build_sketch with folder argument required to fail (this will fail because WirelessOregonV2 is AVR specific)
+  - build_sketch "${SKETCHBOOK_FOLDER}/libraries/WirelessOregonV2/examples" "arduino:sam:arduino_due_x_dbg" "require" "newest"
 
   - publish_report_to_gist "$REPORT_GITHUB_TOKEN" "$REPORT_GIST_URL" "true"
 

README.md

@@ -89,7 +89,7 @@ Turn on/off arduino verbose output during compilation. This will show all the co
 Pass some parameters from .travis.yml to the script. `build_sketch` will echo the arduino exit code to the log, which is documented at https://github.com/arduino/Arduino/blob/master/build/shared/manpage.adoc#exit-status.
 - Parameter: **sketchPath** - Path to a sketch or folder containing sketches. If a folder is specified it will be recursively searched and all sketches will be verified.
 - Parameter: **boardID** - `package:arch:board[:parameters]` ID of the board to be compiled for. e.g. `arduino:avr:uno`. Board-specific parameters are only supported by Arduino IDE 1.5.5 and newer.
-- Parameter: **allowFail** - `true` or `false`. Allow the verification to fail without causing the CI build to fail.
+- Parameter: **allowFail** - `true`, `require`, or `false`. Allow the verification to fail without causing the CI build to fail. `require` will cause the build to fail if the sketch verification doesn't fail.
 - Parameter: **IDEversion** - A single version of the Arduino IDE to use to verify the sketch.
 - Parameter(optional): **IDEversionList** - A list of versions of the Arduino IDE to use to verify the sketch. e.g. `'("1.6.5-r5" "1.6.9" "1.8.2")'`. If no version list is provided all installed IDE versions will be used.
 - Parameter: **startIDEversion** - The start (inclusive) of a range of versions of the Arduino IDE to use to verify the sketch.

arduino-ci-script.sh

@@ -687,9 +687,6 @@ function build_this_sketch()
   local absoluteSketchName
   absoluteSketchName="$(cd "$(dirname "$1")"; pwd)/$(basename "$1")"
 
-  # Set default value of buildThisSketchExitCode
-  local buildThisSketchExitCode=0
-
   # Define a dummy value for arduinoExitCode so that the while loop will run at least once
   local arduinoExitCode=255
   # Retry the verification if arduino returns an exit code that indicates there may have been a temporary error not caused by a bug in the sketch or the arduino command
@@ -700,12 +697,25 @@ function build_this_sketch()
     local verifyCount=$((verifyCount + 1))
   done
 
-  # If the sketch build failed and failure is not allowed for this test then fail the Travis build after completing all sketch builds
   if [[ "$arduinoExitCode" != "0" ]]; then
-    if [[ "$allowFail" != "true" ]]; then
-      buildThisSketchExitCode=1
+    # Sketch build failed
+    if [[ "$allowFail" == "true" || "$allowFail" == "require" ]]; then
+      # Failure is allowed for this test
+      local -r buildThisSketchExitCode=0
+    else
+      # Failure is not allowed for this test, fail the Travis build after completing all sketch builds
+      local -r buildThisSketchExitCode=1
     fi
   else
+    # Sketch build succeeded
+    if [[ "$allowFail" == "require" ]]; then
+      # Failure is required for this test, fail the Travis build after completing all sketch builds
+      local -r buildThisSketchExitCode=1
+    else
+      # Success is allowed
+      local -r buildThisSketchExitCode=0
+    fi
+
     # Parse through the output from the sketch verification to count warnings and determine the compile size
     local warningCount=0
     while read -r outputFileLine; do