arduino_ci 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95cc7dc7ab0591e45ffe7c1a9cdf31f64b21a8cf794a12ea83a4190af20e7488
-  data.tar.gz: 6e20b49ad3b015445c79511e9795fddbf205f01e20eb8c413e7ff342f4b240f9
+  metadata.gz: c4765de27f7f477f5a64189afba2d70a280d1ae65e64916af6b98aa7d1a0266f
+  data.tar.gz: dd3748bdf67dfc526183d5a1372ce06d11b293cbaf984af19b90b999fdf1623e
 SHA512:
-  metadata.gz: f40e840a35f788a4e02e0e332b5e7669198214419d9361abf10cc03558028bc691bb16379143b95c258dd2527fb8b03924d3cfb240c3af6b2fac526966b30274
-  data.tar.gz: bf8dc24b59f479ad858b75450a546ebd5e7bee694e33c8b443d2fa89576fe40fb09dede3c17353b7ca6c9c7dcda921aa7bb3f156c3beb98fd62cc99123c03119
+  metadata.gz: ae3f368ed4f543f22a0702df9945abac4df15683f85e7d54c5c958cc60b951453bd21aad19beac73a54257bee558ea172d5c8cbcea69deed3a7b15da0cff0495
+  data.tar.gz: b2481e5d6096e6dd6df1aa86efb6465e6f13dc853840fca4ba6044c8dc51b1ac1c8c0196f3c9d49c1412c4e880177a40880346e1bba1d4fb7cc4967468f192f7

data/README.md

@@ -1,14 +1,14 @@
 
 # ArduinoCI Ruby gem (`arduino_ci`)
 [![Gem Version](https://badge.fury.io/rb/arduino_ci.svg)](https://rubygems.org/gems/arduino_ci)
-[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/arduino_ci/1.2.0)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/arduino_ci/1.3.0)
 [![Gitter](https://badges.gitter.im/Arduino-CI/arduino_ci.svg)](https://gitter.im/Arduino-CI/arduino_ci?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 [![GitHub Marketplace](https://img.shields.io/badge/Get_it-on_Marketplace-informational.svg)](https://github.com/marketplace/actions/arduino_ci)
 
 Arduino CI was created to enable better collaboration among Arduino library maintainers and contributors, by enabling automated code checks to be performed as part of a pull request process.
 
 * enables running unit tests against the library **without hardware present**
-* provides a system of mocks that allow fine-grained control over the hardare inputs, including the system's clock
+* provides a system of mocks that allow fine-grained control over the hardware inputs, including the system's clock
 * verifies compilation of any example sketches included in the library
 * can test a wide range of arduino boards with different hardware options available
 * compares entries in `library.properties` to the contents of the library and reports mismatches
@@ -29,69 +29,91 @@ Windows  | [![Windows Build status](https://github.com/Arduino-CI/arduino_ci/wor
 
 ## Quick Start
 
-### You Need Your Arduino Library
+This project has the following dependencies:
 
-For a fairly minimal practical example of a unit-testable library repo that you can copy from, see [the `Arduino-CI/Blink` repository](https://github.com/Arduino-CI/Blink).
+* `ruby` 2.5 or higher
+* A compiler like `g++` (on OSX, `clang` works; on Cygwin, use the `mingw-gcc-c++` package)
+* `python` (if using a board architecutre that requires it, e.g. ESP32, ESP8266; see [this issue](https://github.com/Arduino-CI/arduino_ci/issues/235#issuecomment-739629243)). Consider `pyserial` as well.
+
+In that environment, you can install by running `gem install arduino_ci`.  To update to a latest version, use `gem update arduino_ci`.
+
+You can now test your library by simply running the command `arduino_ci.rb` from your library directory.  This will perform the following:
 
-> Note: The `SampleProjects` directory you see within _this_ repo contains tests for validing the `arduino_ci` framework itself, and due to that coupling will not be helpful to duplicate.  That said, the [SampleProjects/TestSomething](SampleProjects/TestSomething) project contains [test files](SampleProjects/TestSomething/test/) (each named after the type of feature being tested) that may be illustrative of testing strategy and capabilities _on an individual basis_.
+* validation of some fields in `library.properties`, if it exists
+* running unit tests from files found in `test/`, if they exist
+* testing compilation of example sketches found in `examples/`, if they exist
+
+### Assumptions About Your Repository
 
 Arduino expects all libraries to be in a specific `Arduino/libraries` directory on your system.  If your library is elsewhere, `arduino_ci` will _automatically_ create a symbolic link in the `libraries` directory that points to the directory of the project being tested.  This simplifieds working with project dependencies, but **it can have unintended consequences on Windows systems**.
 
 > If you use a Windows system **it is recommended that you only run `arduino_ci` from project directories that are already inside the `libraries` directory** because [in some cases deleting a folder that contains a symbolic link to another folder can cause the _entire linked folder_ to be removed instead of just the link itself](https://superuser.com/a/306618).
 
+### Changes to Your Repository
 
-### You Need Ruby and Bundler
-
-You'll need Ruby version 2.5 or higher, and to `gem install bundler` if it's not already there.
+Unit testing binaries created by `arduino_ci` should not be commited to the codebase.  To avoid that, add the following to your `.gitignore`:
 
+```ignore-list
+# arduino_ci unit test binaries and artifacts
+*.bin
+*.bin.dSYM
+```
 
-### You Need A Compiler (`g++`)
+### A Quick Example
 
-For unit testing, you will need a compiler; [g++](https://gcc.gnu.org/) is preferred.
+For a fairly minimal practical example of a unit-testable library repo that you can copy from, see [the `Arduino-CI/Blink` repository](https://github.com/Arduino-CI/Blink).
 
-* **Linux**: `gcc`/`g++` is likely pre-installed.
-* **OSX**: `g++` is an alias for `clang`, which is provided by Xcode and the developer tools.  You are free to `brew install gcc` as well; this is also tested and working.
-* **Windows**: you will need Cygwin, and the `mingw-gcc-g++` package.
 
+## Advanced Start
 
-### You _May_ Need `python`
+New features and bugfixes reach GitHub before they reach a released ruby gem.  Alternately, it may be that (for your own reasons) you do not wish to install `arduino_ci` globally on your system.  A few additional setup steps are required if you wish to do this.
 
-ESP32 and ESP8266 boards have [a dependency on `python` that they don't install themselves](https://github.com/Arduino-CI/arduino_ci/issues/235#issuecomment-739629243).  If you intend to test on these platforms (which are included in the default list of platforms to test against), you will need to make `python` (and possibly `pyserial`) available in the test environment.
+### You Need Ruby _and_ Bundler
 
-Alternately, you might configure `arduino_ci` to simply not test against these.  Consult the reference for those details.
+In addition to version 2.5 or higher, you'll also need to `gem install bundler` to a minimum of version 2.0 if it's not already there.  You may find it easiest to do this by using [`rbenv`](https://github.com/rbenv/rbenv).
 
+You will need to add a file called `Gemfile` (no extension) to your Arduino project.
 
-### Changes to Your Repo
+#### Non-root installation
 
-Add a file called `Gemfile` (no extension) to your Arduino project:
+If you are simply trying to avoid the need to install `arduino_ci` system-wide (which may require administrator permissions), your `Gemfile` would look like this:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'arduino_ci' '~> 1.1'
+
+# Replace 1.2 with the desired version of arduino_ci.  See https://guides.rubygems.org/patterns/#pessimistic-version-constraint
+gem 'arduino_ci', '~> 1.2'
 ```
 
-At the time of this writing, `1.1` is the latest version available, and the `~>` syntax will allow your system to update it to the latest `1.x.x` version.  The list of all available versions can be found on [rubygems.org](https://rubygems.org/gems/arduino_ci) if you prefer to explicitly pin a higher version.
+It would also make sense to add the following to your `.gitignore`:
+```ignore-list
+/.bundle/
+vendor
+```
+
+> Note: this used to be the recommended installation method, but with the library's maturation it's better to avoid the use of `Gemfile` and `bundle install` by just installing as per the "Quick Start" instructions above.
+
 
-It would also make sense to add the following to your `.gitignore`, or copy [the `.gitignore` used by this project](.gitignore):
+#### Using the latest-available code
+
+If you want to use the latest code on GitHub, your `Gemfile` would look like this:
+
+```ruby
+source 'https://rubygems.org'
 
+# to use the latest github code in a given repo and branch, replace the below values for git: and ref: as needed
+gem 'arduino_ci', git: 'https://github.com/ArduinoCI/arduino_ci.git', ref: '<your desired ref, branch, or tag>'
 ```
-/.bundle/
-/.yardoc
-Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-vendor
-*.gem
 
-# rspec failure tracking
-.rspec_status
 
-# C++ stuff
-*.bin
-*.bin.dSYM
+#### Using a version of `arduino_ci` source code on your local machine
+
+First, Thanks!  See [CONTRIBUTING.md](CONTRIBUTING.md).  Your `Gemfile` would look like this:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'arduino_ci', path: '/path/to/development/dir/for/arduino_ci'
 ```
 
 
@@ -103,17 +125,18 @@ $ bundle install   # adds packages to global library (may require admin rights)
 $ bundle install --path vendor/bundle   # adds packages to local library
 ```
 
+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.
 
-### Running tests
+
+
+### Running `arduino_ci.rb` To Test Your Library
 
 With that installed, just the following shell command each time you want the tests to execute:
 
-```
+```console
 $ bundle exec arduino_ci.rb
 ```
 
-`arduino_ci.rb` is the main entry point for this library.  This command will iterate over all the library's `examples/` and attempt to compile them.  If you set up unit tests, it will run those as well.
-
 
 ### Reference
 
@@ -128,18 +151,14 @@ For more information on the usage of `arduino_ci.rb`, see [REFERENCE.md](REFEREN
 
 ## Setting up Pull Request Testing and/or External CI
 
-The following prerequisites must be fulfilled:
-
-* A GitHub (or other repository-hosting) project for your library
-* A CI system like [Travis CI](https://travis-ci.org/) or [Appveyor](https://www.appveyor.com/) that is linked to your project
-
+> **Note:** `arduino_ci.rb` expects to be run from the root directory of your Arduino project library.
 
-### Testing with remote CI
+### Arduino CI's Own GitHub action
 
-> **Note:** `arduino_ci.rb` expects to be run from the root directory of your Arduino project library.
+[![GitHub Marketplace](https://img.shields.io/badge/Get_it-on_Marketplace-informational.svg)](https://github.com/marketplace/actions/arduino_ci)
 
 
-#### GitHub Actions
+### Your Own Scripted GitHub Action
 
 GitHub Actions allows you to automate your workflows directly in GitHub.
 No additional steps are needed.
@@ -156,12 +175,12 @@ jobs:
         with:
           ruby-version: 2.6
       - run: |
-          bundle install
-          bundle exec arduino_ci_remote.rb
+          gem install arduino_ci
+          arduino_ci.rb
 ```
 
 
-#### Travis CI
+### Travis CI
 
 You'll need to go to https://travis-ci.org/profile/ and enable testing for your Arduino project.  Once that happens, you should be all set.  The script will test all example projects of the library and all unit tests.
 
@@ -171,12 +190,12 @@ Next, you need this in `.travis.yml` in your repo
 sudo: false
 language: ruby
 script:
-  - bundle install
-  - bundle exec arduino_ci.rb
+  - gem install arduino_ci
+  - arduino_ci.rb
 ```
 
 
-#### Appveyor CI
+### Appveyor CI
 
 You'll need to go to https://ci.appveyor.com/projects and add your project.
 
@@ -185,8 +204,8 @@ Next, you'll need this in `appveyor.yml` in your repo.
 ```yaml
 build: off
 test_script:
-  - bundle install
-  - bundle exec arduino_ci.rb
+  - gem install arduino_ci
+  - arduino_ci.rb
 ```
 
 

data/REFERENCE.md

@@ -46,7 +46,7 @@ This allows a file (or glob) pattern to be executed in your tests directory, cre
 
 ### `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.  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.
+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.
 
 
 ### `USE_SUBDIR` environment variable
@@ -64,11 +64,6 @@ If set, testing will fail if no unit test files are detected (or if the director
 If set, testing will fail if no example sketches are detected.  This is to avoid communicating a passing status in cases where a commit may have accidentally moved or deleted the examples.
 
 
-### `SKIP_LIBRARY_PROPERTIES` environment variable
-
-If set, testing will skip validating `library.properties` entries.  This is to work around any possible bugs in `arduino_ci`'s interpretation of what is "correct".
-
-
 ## Indirectly Overriding Build Behavior (medium term use), and Advanced Options
 
 For build behavior that you'd like to persist across commits (e.g. defining the set of platforms to test against, disabling a test that you expect to re-enable at some future point), a special configuration file called `.arduino-ci.yml` can be used.  There are 3 places you can put them:

data/exe/arduino_ci.rb

@@ -9,7 +9,6 @@ VAR_CUSTOM_INIT_SCRIPT = "CUSTOM_INIT_SCRIPT".freeze
 VAR_USE_SUBDIR         = "USE_SUBDIR".freeze
 VAR_EXPECT_EXAMPLES    = "EXPECT_EXAMPLES".freeze
 VAR_EXPECT_UNITTESTS   = "EXPECT_UNITTESTS".freeze
-VAR_SKIP_LIBPROPS      = "SKIP_LIBRARY_PROPERTIES".freeze
 
 @failure_count = 0
 @passfail = proc { |result| result ? "✓" : "✗" }
@@ -22,7 +21,6 @@ class Parser
     output_options = {
       skip_unittests: false,
       skip_compilation: false,
-      skip_library_properties: false,
       ci_config: {
         "unittest" => unit_config
       },
@@ -39,10 +37,6 @@ class Parser
         output_options[:skip_compilation] = p
       end
 
-      opts.on("--skip-library-properties", "Don't validate library.properties entries") do |p|
-        output_options[:skip_compilation] = p
-      end
-
       opts.on("--testfile-select=GLOB", "Unit test file (or glob) to select") do |p|
         unit_config["testfiles"] ||= {}
         unit_config["testfiles"]["select"] ||= []
@@ -154,10 +148,32 @@ def inform_multiline(message, &block)
   perform_action(message, true, nil, nil, false, false, &block)
 end
 
+def rule(char)
+  puts char[0] * WIDTH
+end
+
 def warn(message)
   inform("WARNING") { message }
 end
 
+def phase(name)
+  puts
+  rule("=")
+  inform("Beginning the next phase of testing") { name }
+end
+
+def banner
+  art = [
+    "         .                  __  ___",
+    " _, ,_  _| , . * ._   _    /  `  | ",
+    "(_| [ `(_] (_| | [ ) (_)   \\__. _|_   v#{ArduinoCI::VERSION}",
+  ]
+
+  pad = " " * ((WIDTH - art[2].length) / 2)
+  art.each { |l| puts "#{pad}#{l}" }
+  puts
+end
+
 # Assure that a platform exists and return its definition
 def assured_platform(purpose, name, config)
   platform_definition = config.platform_definition(name)
@@ -351,7 +367,7 @@ def choose_platform_set(config, reason, desired_platforms, library_properties)
     # completely ignore default config, opting for brute-force library matches
     # OTOH, we don't need to assure platforms because we defined them
     return inform_multiline("Default config, platforms matching architectures in library.properties") do
-      supported_platforms.each_key do |p|
+      supported_platforms.keys.each do |p|  # rubocop:disable Style/HashEachMethods
         puts "    #{p}"
       end # this returns supported_platforms
     end
@@ -366,34 +382,9 @@ def choose_platform_set(config, reason, desired_platforms, library_properties)
   end
 end
 
-# tests of sane library.properties values
-def perform_property_tests(cpp_library)
-  return inform("Skipping library.properties tests") { "as requested via command line" } if @cli_options[:skip_library_properties]
-  return inform("Skipping library.properties tests") { "as requested via environment" } unless ENV[VAR_SKIP_LIBPROPS].nil?
-  return inform("Skipping library.properties tests") { "file not found" } unless cpp_library.library_properties?
-
-  props = cpp_library.library_properties
-
-  props.depends&.each do |l|
-    assure("library.properties 'depends=' entry '#{l}' is available via the library manager") { @backend.library_available?(l) }
-  end
-
-  # the IDE would add these entries to a sketch (as "#include <...>" lines), they are nothing to do with the compioler
-  props.includes&.map(&:strip)&.map(&Pathname::method(:new))&.each do |f|
-    if (cpp_library.path + f).exist?
-      inform("library.properties 'includes=' entry found") { f }
-    elsif (cpp_library.path + "src" + f).exist?
-      inform("library.properties 'includes=' entry found") { Pathname.new("src") + f }
-    else
-      # this is if they want to "#include <math>" or something -- may or may not be valid!  so just warn.
-      warn("library.properties 'includes=' entry '#{f}' does not refer to a file in the library")
-    end
-  end
-
-end
-
 # Unit test procedure
 def perform_unit_tests(cpp_library, file_config)
+  phase("Unit testing")
   if @cli_options[:skip_unittests]
     inform("Skipping unit tests") { "as requested via command line" }
     return
@@ -424,6 +415,7 @@ def perform_unit_tests(cpp_library, file_config)
   install_arduino_library_dependencies(config.aux_libraries_for_unittest, "<unittest/libraries>")
 
   platforms.each do |p|
+    puts
     config.allowable_unittest_files(cpp_library.test_files).each do |unittest_path|
       unittest_name = unittest_path.basename.to_s
       compilers.each do |gcc_binary|
@@ -449,6 +441,7 @@ def perform_unit_tests(cpp_library, file_config)
 end
 
 def perform_example_compilation_tests(cpp_library, config)
+  phase("Compilation of example sketches")
   if @cli_options[:skip_compilation]
     inform("Skipping compilation of examples") { "as requested via command line" }
     return
@@ -463,23 +456,25 @@ def perform_example_compilation_tests(cpp_library, config)
 
   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)
     platforms = choose_platform_set(ovr_config, "library example", ovr_config.platforms_to_build, cpp_library.library_properties)
 
     if platforms.empty?
       explain_and_exercise_envvar(VAR_EXPECT_EXAMPLES, "examples compilation", "platforms and architectures") do
-        puts "    Configured platforms: #{config.platforms_to_build}"
-        puts "    Configuration is default: #{config.is_default}"
+        puts "    Configured platforms: #{ovr_config.platforms_to_build}"
+        puts "    Configuration is default: #{ovr_config.is_default}"
         arches = cpp_library.library_properties.nil? ? nil : cpp_library.library_properties.architectures
         puts "    Architectures in library.properties: #{arches}"
       end
     end
 
     install_all_packages(platforms, ovr_config)
+    install_arduino_library_dependencies(ovr_config.aux_libraries_for_build, "<compile/libraries>")
 
     platforms.each do |p|
-      install_arduino_library_dependencies(ovr_config.aux_libraries_for_build, "<compile/libraries>")
-
       board = ovr_config.platform_info[p][:board]
       attempt("Compiling #{example_name} for #{board}") do
         ret = @backend.compile_sketch(example_path, board)
@@ -494,10 +489,18 @@ def perform_example_compilation_tests(cpp_library, config)
   end
 end
 
+banner
+inform("Host OS") { ArduinoCI::Host.os }
+
 # initialize command and config
 config = ArduinoCI::CIConfig.default.from_project_library
 @backend = ArduinoCI::ArduinoInstallation.autolocate!
 inform("Located arduino-cli binary") { @backend.binary_path.to_s }
+if @backend.lib_dir.exist?
+  inform("Found libraries directory") { @backend.lib_dir }
+else
+  assure("Creating libraries directory") { @backend.lib_dir.mkpath || true }
+end
 
 # run any library init scripts from the library itself.
 perform_custom_initialization(config)
@@ -524,8 +527,6 @@ else
   end
 end
 
-perform_property_tests(cpp_library)
-
 install_arduino_library_dependencies(
   cpp_library.arduino_library_dependencies,
   "<#{ArduinoCI::CppLibrary::LIBRARY_PROPERTIES_FILE}>"

data/lib/arduino_ci/version.rb

@@ -1,3 +1,3 @@
 module ArduinoCI
-  VERSION = "1.2.0".freeze
+  VERSION = "1.3.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arduino_ci
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Ian Katz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-07 00:00:00.000000000 Z
+date: 2021-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: os