Further bugfixes and documentation fixes

.github/workflows/linter.yaml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           # Full git history is needed to get a proper list of changed files within `super-linter`
           fetch-depth: 0

.github/workflows/linux.yaml

@@ -7,7 +7,7 @@ jobs:
   "rubocop":
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -21,7 +21,7 @@ jobs:
   "rspec-linux":
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -34,7 +34,7 @@ jobs:
   "TestSomething":
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -44,12 +44,13 @@ jobs:
           bundle install
           cd SampleProjects/TestSomething
           bundle install
+          bundle exec arduino_ci.rb --help
           bundle exec arduino_ci.rb
 
   NetworkLib:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -65,7 +66,7 @@ jobs:
   SharedLibrary:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

.github/workflows/macos.yaml

@@ -7,7 +7,7 @@ jobs:
   "rubocop":
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -21,7 +21,7 @@ jobs:
   "rspec-macos":
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -34,7 +34,7 @@ jobs:
   "TestSomething":
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -44,12 +44,13 @@ jobs:
           bundle install
           cd SampleProjects/TestSomething
           bundle install
+          bundle exec arduino_ci.rb --help
           bundle exec arduino_ci.rb
 
   NetworkLib:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -65,7 +66,7 @@ jobs:
   SharedLibrary:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

.github/workflows/spelling.yaml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           # Full git history is needed to get a proper list of changed files within `super-linter`
           fetch-depth: 0

.github/workflows/windows.yaml

@@ -7,7 +7,7 @@ jobs:
   "rubocop":
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -21,7 +21,7 @@ jobs:
   "rspec-windows":
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -34,7 +34,7 @@ jobs:
   TestSomething:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -44,12 +44,13 @@ jobs:
           bundle install
           cd SampleProjects/TestSomething
           bundle install
+          bundle exec arduino_ci.rb --help
           bundle exec arduino_ci.rb
 
   NetworkLib:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6
@@ -65,7 +66,7 @@ jobs:
   SharedLibrary:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

CHANGELOG.md

@@ -7,16 +7,25 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
+- C++ definitions of `ARDUINO_CI_COMPILATION_MOCKS` and `ARDUINO_CI_GODMODE` to aid in compilation macros
+- `CIConfig.available_override_config_path()` to search for available override files in standard locations
+- `CIConfig.override_file_from_project_library` and `CIConfig.override_file_from_example` to expose config locations
+- CI runner script now expliclty informs about config overrides
+- A project `examples/` directory can now provide its own configuration override file, which provides no new flexibility but simply mirrors the behavior for `tests/`.
 
 ### Changed
+- `CIConfig` now uses `Pathname` instead of strings
 
 ### Deprecated
 
 ### Removed
+- `CIConfig.with_config`, which was only used internally
 
 ### Fixed
+- `arduino_ci.rb --help` no longer crashes
 
 - Fix missing `LED_BUILTIN` definition for Arduino Due, Zero and Circuit Playground.
+- No longer ignore failures if the first step of compiling files for the unit test fails.
 
 ### Security
 
@@ -30,7 +39,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Support for `dtostrf()`
 - Added a CI workflow to lint the code base
 - Added a CI workflow to check for spelling errors
-- Extraction of byes usage in a compiled sketch is now calculated in a method: `ArduinoBackend.last_bytes_usage`
+- Extraction of bytes usage in a compiled sketch is now calculated in a method: `ArduinoBackend.last_bytes_usage`
 - Added ```nano_every``` platform to represent ```arduino:megaavr``` architecture
 - Working directory is now printed in test runner output
 - Explicitly include `irb` via rubygems

README.md

@@ -118,11 +118,11 @@ gem 'arduino_ci', path: '/path/to/development/dir/for/arduino_ci'
 
 ### Installing the Dependencies
 
-Fulfilling the `arduino_ci` library dependency is as easy as running either of these two commands:
+Fulfilling the `arduino_ci` library dependency is as easy as running one or both of these commands:
 
 ```console
-$ bundle install   # adds packages to global library (may require admin rights)
-$ bundle install --path vendor/bundle   # adds packages to local library
+$ bundle config set --local path 'vendor/bundle'   # if you lack administrative privileges to install globally
+$ bundle install
 ```
 
 This will create a `Gemfile.lock` in your project directory, which you may optionally check into source control.  A broader introduction to ruby dependencies is outside the scope of this document.
@@ -169,7 +169,7 @@ jobs:
   runTest:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

REFERENCE.md

@@ -44,6 +44,11 @@ This allows a file (or glob) pattern to be executed in your tests directory, cre
 This allows a file (or glob) pattern to be executed in your tests directory, creating a blacklist of files to skip.  E.g. `--testfile-reject=test_animal_*.cpp` would match `test_animal_cat.cpp` and `test_animal_dog.cpp` (skipping those) and test only `test_plant_rose.cpp`, `test_plant_daisy.cpp`, etc.
 
 
+### `--min-free-space` option
+
+This specifies the minimum free SRAM memory for stack/heap, in bytes, that _must_ be leftover after compilation.  This value applies globally -- to _all_ platforms that will be included in a test run.
+
+
 ### `CUSTOM_INIT_SCRIPT` environment variable
 
 If set, testing will execute (using `/bin/sh`) the script referred to by this variable -- relative to the current working directory (i.e. the root directory of the library).  The script will _run_ in the Arduino Libraries directory (changing to the Libraries directory, running the script, and returning to the individual library root afterward).  This enables use cases like the GitHub action to install custom library versions (i.e. a version of a library that is different than what the library manager would automatically install by name) prior to CI test runs.

SampleProjects/TestSomething/examples/.arduino-ci.yml

@@ -0,0 +1,4 @@
+compile:
+  platforms:
+    - uno
+    - due

SampleProjects/TestSomething/examples/TestSomethingExample/.arduino-ci.yml

@@ -0,0 +1,4 @@
+compile:
+  platforms:
+    - uno
+    - due

cpp/arduino/Arduino.h

@@ -5,6 +5,11 @@ Mock Arduino.h library.
 Where possible, variable names from the Arduino library are used to avoid conflicts
 
 */
+
+// signal to the developer that we are in an arduino_ci mocked environment
+#define ARDUINO_CI_COMPILATION_MOCKS
+
+
 // Chars and strings
 
 #include "ArduinoDefines.h"

cpp/arduino/ArduinoDefines.h

@@ -90,6 +90,7 @@
 #define TIMER5C 18
 
 #if defined(__AVR_ATmega328P__) || defined(__AVR_ATmega32U4__) || defined(__AVR_ATmega328__) || defined(__AVR_ATmega168__) || defined(__AVR_ATmega1280__) || defined(__AVR_ATmega2560__) || defined(__SAM3X8E__) || defined(__SAMD21G18A__)
+  // Verified on these platforms, see https://github.com/Arduino-CI/arduino_ci/pull/341#issuecomment-1368118880
   #define LED_BUILTIN 13
 #endif
 

cpp/arduino/Godmode.h

@@ -6,6 +6,9 @@
 #include "WString.h"
 #include "PinHistory.h"
 
+// signal to the developer that we are in an arduino_ci mocked environment
+#define ARDUINO_CI_GODMODE
+
 // random
 void randomSeed(unsigned long seed);
 long random(long vmax);

exe/arduino_ci.rb

@@ -69,7 +69,6 @@ def self.parse(options)
         puts " - #{VAR_USE_SUBDIR} - if set, the script will install the library from this subdirectory of the cwd"
         puts " - #{VAR_EXPECT_EXAMPLES} - if set, testing will fail if no example sketches are present"
         puts " - #{VAR_EXPECT_UNITTESTS} - if set, testing will fail if no unit tests are present"
-        puts " - #{VAR_SKIP_LIBPROPS} - if set, testing will skip [experimental] library.properties validation"
         exit
       end
     end
@@ -194,6 +193,13 @@ def assured_platform(purpose, name, config)
   platform_definition
 end
 
+def inform_override(from_where, &block)
+  inform("Using configuration override from #{from_where}") do
+    file = block.call
+    file.nil? ? "<none>" : file
+  end
+end
+
 # Return true if the file (or one of the dirs containing it) is hidden
 def file_is_hidden_somewhere?(path)
   # this is clunkly but pre-2.2-ish ruby doesn't return ascend as an enumerator
@@ -436,7 +442,7 @@ def perform_unit_tests(cpp_library, file_config)
     puts
     compilers.each do |gcc_binary|
       # before compiling the tests, build a shared library of everything except the test code
-      next unless build_shared_library(gcc_binary, p, config, cpp_library)
+      next @failure_count += 1 unless build_shared_library(gcc_binary, p, config, cpp_library)
 
       # now build and run each test using the shared library build above
       config.allowable_unittest_files(cpp_library.test_files).each do |unittest_path|
@@ -489,12 +495,17 @@ def perform_example_compilation_tests(cpp_library, config)
     return
   end
 
+  inform_override("examples") { config.override_file_from_example(cpp_library.examples_dir) }
+  ex_config = config.from_example(cpp_library.examples_dir)
+
   library_examples.each do |example_path|
     example_name = File.basename(example_path)
     puts
     inform("Discovered example sketch") { example_name }
 
-    ovr_config = config.from_example(example_path)
+    inform_override("example") { ex_config.override_file_from_example(example_path) }
+    ovr_config = ex_config.from_example(example_path)
+
     platforms = choose_platform_set(ovr_config, "library example", ovr_config.platforms_to_build, cpp_library.library_properties)
 
     # having no platforms defined is probably an error
@@ -542,9 +553,13 @@ def perform_example_compilation_tests(cpp_library, config)
 inform("Working directory") { Dir.pwd }
 
 # initialize command and config
-config = ArduinoCI::CIConfig.default.from_project_library
+default_config = ArduinoCI::CIConfig.default
+inform_override("project") { default_config.override_file_from_project_library }
+config = default_config.from_project_library
+
 @backend = ArduinoCI::ArduinoInstallation.autolocate!
 inform("Located arduino-cli binary") { @backend.binary_path.to_s }
+inform("Using arduino-cli version") { @backend.version.to_s }
 if @backend.lib_dir.exist?
   inform("Found libraries directory") { @backend.lib_dir }
 else

lib/arduino_ci/arduino_backend.rb

@@ -182,7 +182,10 @@ def install_boards(boardfamily)
       result = if @additional_urls.empty?
         run_and_capture("core", "install", boardfamily)
       else
-        run_and_capture("core", "install", boardfamily, "--additional-urls", @additional_urls.join(","))
+        urls = @additional_urls.join(",")
+        # update the index, then install. if the update step fails, return that result
+        updater = run_and_capture("core", "update-index", "--additional-urls", urls)
+        updater[:success] ? run_and_capture("core", "install", boardfamily, "--additional-urls", urls) : updater
       end
       result[:success]
     end