arduino_ci 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 38db4872f12c8a48cbdf7033fba9b09ad530e140
-  data.tar.gz: 558c406c46bc3365bfaecfb9bef40155f0a95514
+  metadata.gz: c195767b10bc2c1a3e837b89f087962251fb514c
+  data.tar.gz: 2188e52c1fa37664c72067bec73281fc8d5582e6
 SHA512:
-  metadata.gz: 68ef58a63df5eb220ba7c5a27833db522bef6f15fa77bc71d5533392d5af5c8bf11337ce88d9c69ba112327db4176a25971c25aaf115c17ddd2be7093753e3ec
-  data.tar.gz: 32460f132b22f151825590e6dfb845ec36a0a1058ed72b730987b3772db08e01291201c029d473cc2020d6721c55f0d0745fd7e178bb529c2239cbb177c94a2e
+  metadata.gz: ef354ff7e588004f7d8394999d3044edd1a40aeb2187fe607a4cd76535f7bd23aabfb916226640dfa3778f084b67f32ffd1a30e22b86e7a9b06094ac021d7130
+  data.tar.gz: 3e53f5fefb40d4fe7593e66118f7e51b73b01921cff1b2489787ccadcca5dadac2be3f9d9b2947ad0018f692747984c092365157d3a22a7cbdc180c51cde0ef4

data/README.md

@@ -1,7 +1,7 @@
 
-# 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/0.4.0)
+# 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.0.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)
 
 You want to run tests on your Arduino library (bonus: without hardware present), but the IDE doesn't support that.  Arduino CI provides that ability.
@@ -10,13 +10,14 @@ You want to precisely replicate certain software states in your library, but you
 
 You want your Arduino library to be automatically built and tested every time someone contributes code to your project on GitHub, but the Arduino IDE lacks the ability to run unit tests. [Arduino CI](https://github.com/Arduino-CI/arduino_ci) provides that ability.
 
-`arduino_ci` is a cross-platform build/test system, consisting of a Ruby gem and a series of C++ mocks.  It enables tests to be run both locally and as part of a CI service like Travis or Appveyor.  Any OS that can run the Arduino IDE can run `arduino_ci`.
+`arduino_ci` is a cross-platform build/test system, consisting of a Ruby gem and a series of C++ mocks.  It enables tests to be run both locally and as part of a CI service like GitHub Actions, TravisCI, Appveyor, etc.  Any OS that can run the Arduino IDE can run `arduino_ci`.
+
 
 Platform | CI Status
 ---------|:---------
-OSX      | [![OSX Build Status](http://badges.herokuapp.com/travis/Arduino-CI/arduino_ci?env=BADGE=osx&label=build&branch=master)](https://travis-ci.org/Arduino-CI/arduino_ci)
-Linux    | [![Linux Build Status](http://badges.herokuapp.com/travis/Arduino-CI/arduino_ci?env=BADGE=linux&label=build&branch=master)](https://travis-ci.org/Arduino-CI/arduino_ci)
-Windows  | [![Windows Build status](https://ci.appveyor.com/api/projects/status/abynv8xd75m26qo9/branch/master?svg=true)](https://ci.appveyor.com/project/ianfixes/arduino-ci)
+OSX      | [![OSX Build Status](https://github.com/Arduino-CI/arduino_ci/workflows/macos/badge.svg)](https://github.com/Arduino-CI/arduino_ci/actions?workflow=macos)
+Linux    | [![Linux Build Status](https://github.com/Arduino-CI/arduino_ci/workflows/linux/badge.svg)](https://github.com/Arduino-CI/arduino_ci/actions?workflow=linux)
+Windows  | [![Windows Build status](https://github.com/Arduino-CI/arduino_ci/workflows/windows/badge.svg)](https://github.com/Arduino-CI/arduino_ci/actions?workflow=windows)
 
 
 ## Comparison to Other Arduino Testing Tools
@@ -36,6 +37,9 @@ For a bare-bones example that you can copy from, see [SampleProjects/DoSomething
 
 The complete set of C++ unit tests for the `arduino_ci` library itself are in the [SampleProjects/TestSomething](SampleProjects/TestSomething) project.  The [test files](SampleProjects/TestSomething/test/) are named after the type of feature being tested.
 
+> 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** 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).
+>
+> 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**
 
 ### You Need Ruby and Bundler
 
@@ -127,6 +131,28 @@ The following prerequisites must be fulfilled:
 > **Note:** `arduino_ci.rb` expects to be run from the root directory of your Arduino project library.
 
 
+#### GitHub Actions
+
+GitHub Actions allows you to automate your workflows directly in GitHub.
+No additional steps are needed.
+Just create a YAML file with the information below in your repo under the `.github/workflows/` directory.
+
+```yaml
+on: [push, pull_request]
+jobs:
+  runTest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - run: |
+          bundle install
+          bundle exec arduino_ci_remote.rb
+```
+
+
 #### 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.
@@ -155,6 +181,7 @@ test_script:
   - bundle exec arduino_ci.rb
 ```
 
+
 ## Known Problems
 
 * The Arduino library is not fully mocked.

data/cpp/arduino/Client.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <Stream.h>
+#include <IPAddress.h>
 
 class Client : public Stream {
 public:

data/exe/arduino_ci.rb

@@ -9,6 +9,7 @@ FIND_FILES_INDENT = 4
 
 @failure_count = 0
 @passfail = proc { |result| result ? "✓" : "✗" }
+@backend = nil
 
 # Use some basic parsing to allow command-line overrides of config
 class Parser
@@ -29,11 +30,6 @@ class Parser
         output_options[:skip_unittests] = p
       end
 
-      opts.on("--skip-compilation", "Don't compile example sketches (deprecated)") do |p|
-        puts "The option --skip-compilation has been deprecated in favor of --skip-examples-compilation"
-        output_options[:skip_compilation] = p
-      end
-
       opts.on("--skip-examples-compilation", "Don't compile example sketches") do |p|
         output_options[:skip_compilation] = p
       end
@@ -68,11 +64,11 @@ end
 def terminate(final = nil)
   puts "Failures: #{@failure_count}"
   unless @failure_count.zero? || final
-    puts "Last message: #{@arduino_cmd.last_msg}"
+    puts "Last message: #{@backend.last_msg}"
     puts "========== Stdout:"
-    puts @arduino_cmd.last_out
+    puts @backend.last_out
     puts "========== Stderr:"
-    puts @arduino_cmd.last_err
+    puts @backend.last_err
   end
   retcode = @failure_count.zero? ? 0 : 1
   exit(retcode)
@@ -161,7 +157,7 @@ end
 # print out some files
 def display_files(pathname)
   # `find` doesn't follow symlinks, so we should instead
-  realpath = pathname.symlink? ? pathname.readlink : pathname
+  realpath = Host.symlink?(pathname) ? Host.readlink(pathname) : pathname
 
   # suppress directories and dotfile-based things
   all_files = realpath.find.select(&:file?)
@@ -172,25 +168,33 @@ def display_files(pathname)
   non_hidden.each { |p| puts "#{margin}#{p}" }
 end
 
-def install_arduino_library_dependencies(aux_libraries)
-  aux_libraries.each do |l|
-    if @arduino_cmd.library_present?(l)
-      inform("Using pre-existing library") { l.to_s }
+# @return [Array<String>] The list of installed libraries
+def install_arduino_library_dependencies(library_names, on_behalf_of, already_installed = [])
+  installed = already_installed.clone
+  library_names.map { |n| @backend.library_of_name(n) }.each do |l|
+    if installed.include?(l)
+      # do nothing
+    elsif l.installed?
+      inform("Using pre-existing dependency of #{on_behalf_of}") { l.name }
     else
-      assure("Installing aux library '#{l}'") { @arduino_cmd.install_library(l) }
+      assure("Installing dependency of #{on_behalf_of}: '#{l.name}'") do
+        next nil unless l.install
+
+        l.name
+      end
     end
+    installed << l.name
+    installed += install_arduino_library_dependencies(l.arduino_library_dependencies, l.name, installed)
   end
+  installed
 end
 
-def perform_unit_tests(file_config)
+def perform_unit_tests(cpp_library, file_config)
   if @cli_options[:skip_unittests]
     inform("Skipping unit tests") { "as requested via command line" }
     return
   end
   config = file_config.with_override_config(@cli_options[:ci_config])
-  cpp_library = ArduinoCI::CppLibrary.new(Pathname.new("."),
-                                          @arduino_cmd.lib_dir,
-                                          config.exclude_dirs.map(&Pathname.method(:new)))
 
   # check GCC
   compilers = config.compilers_to_use
@@ -214,10 +218,25 @@ def perform_unit_tests(file_config)
 
   # iterate boards / tests
   if !cpp_library.tests_dir.exist?
-    inform_multiline("Skipping unit tests; no tests dir at #{cpp_library.tests_dir}") do
-      puts "  In case that's an error, this is what was found in the library:"
-      display_files(cpp_library.tests_dir.parent)
-      true
+    # alert future me about running the script from the wrong directory, instead of doing the huge file dump
+    # otherwise, assume that the user might be running the script on a library with no actual unit tests
+    if Pathname.new(__dir__).parent == Pathname.new(Dir.pwd)
+      inform_multiline("arduino_ci seems to be trying to test itself") do
+        [
+          "arduino_ci (the ruby gem) isn't an arduino project itself, so running the CI test script against",
+          "the core library isn't really a valid thing to do... but it's easy for a developer (including the",
+          "owner) to mistakenly do just that.  Hello future me, you probably meant to run this against one of",
+          "the sample projects in SampleProjects/ ... if not, please submit a bug report; what a wild case!"
+        ].each { |l| puts "  #{l}" }
+        false
+      end
+      exit(1)
+    else
+      inform_multiline("Skipping unit tests; no tests dir at #{cpp_library.tests_dir}") do
+        puts "  In case that's an error, this is what was found in the library:"
+        display_files(cpp_library.tests_dir.parent)
+        true
+      end
     end
   elsif cpp_library.test_files.empty?
     inform_multiline("Skipping unit tests; no test files were found in #{cpp_library.tests_dir}") do
@@ -228,7 +247,7 @@ def perform_unit_tests(file_config)
   elsif config.platforms_to_unittest.empty?
     inform("Skipping unit tests") { "no platforms were requested" }
   else
-    install_arduino_library_dependencies(config.aux_libraries_for_unittest)
+    install_arduino_library_dependencies(config.aux_libraries_for_unittest, "<unittest/libraries>")
 
     config.platforms_to_unittest.each do |p|
       config.allowable_unittest_files(cpp_library.test_files).each do |unittest_path|
@@ -256,39 +275,12 @@ def perform_unit_tests(file_config)
   end
 end
 
-def perform_compilation_tests(config)
+def perform_example_compilation_tests(cpp_library, config)
   if @cli_options[:skip_compilation]
     inform("Skipping compilation of examples") { "as requested via command line" }
     return
   end
 
-  # index the existing libraries
-  attempt("Indexing libraries") { @arduino_cmd.index_libraries } unless @arduino_cmd.libraries_indexed
-
-  # initialize library under test
-  installed_library_path = attempt("Installing library under test") do
-    @arduino_cmd.install_local_library(Pathname.new("."))
-  end
-
-  if !installed_library_path.nil? && installed_library_path.exist?
-    inform("Library installed at") { installed_library_path.to_s }
-  else
-    assure_multiline("Library installed successfully") do
-      if installed_library_path.nil?
-        puts @arduino_cmd.last_msg
-      else
-        # print out the contents of the deepest directory we actually find
-        @arduino_cmd.lib_dir.ascend do |path_part|
-          next unless path_part.exist?
-
-          break display_files(path_part)
-        end
-        false
-      end
-    end
-  end
-  library_examples = @arduino_cmd.library_examples(installed_library_path)
-
   # gather up all required boards for compilation so we can install them up front.
   # start with the "platforms to unittest" and add the examples
   # while we're doing that, get the aux libraries as well
@@ -297,6 +289,7 @@ def perform_compilation_tests(config)
   aux_libraries = Set.new(config.aux_libraries_for_build)
   # while collecting the platforms, ensure they're defined
 
+  library_examples = cpp_library.example_sketches
   library_examples.each do |path|
     ovr_config = config.from_example(path)
     ovr_config.platforms_to_build.each do |platform|
@@ -317,13 +310,8 @@ def perform_compilation_tests(config)
   # do that, set the URLs, and download the packages
   all_packages = example_platform_info.values.map { |v| v[:package] }.uniq.reject(&:nil?)
 
-  # inform about builtin packages
-  all_packages.select { |p| config.package_builtin?(p) }.each do |p|
-    inform("Using built-in board package") { p }
-  end
-
   # make sure any non-builtin package has a URL defined
-  all_packages.reject { |p| config.package_builtin?(p) }.each do |p|
+  all_packages.each do |p|
     assure("Board package #{p} has a defined URL") { board_package_url[p] }
   end
 
@@ -333,19 +321,18 @@ def perform_compilation_tests(config)
 
   unless all_urls.empty?
     assure("Setting board manager URLs") do
-      @arduino_cmd.board_manager_urls = all_urls
+      @backend.board_manager_urls = all_urls
     end
   end
 
   all_packages.each do |p|
     assure("Installing board package #{p}") do
-      @arduino_cmd.install_boards(p)
+      @backend.install_boards(p)
     end
   end
 
-  install_arduino_library_dependencies(aux_libraries)
+  install_arduino_library_dependencies(aux_libraries, "<compile/libraries>")
 
-  last_board = nil
   if config.platforms_to_build.empty?
     inform("Skipping builds") { "no platforms were requested" }
     return
@@ -356,46 +343,58 @@ def perform_compilation_tests(config)
     return
   end
 
-  attempt("Setting compiler warning level")  { @arduino_cmd.set_pref("compiler.warning_level", "all") }
-
-  # switching boards takes time, so iterate board first
-  # _then_ whichever examples match it
-  examples_by_platform = library_examples.each_with_object({}) do |example_path, acc|
+  library_examples.each do |example_path|
     ovr_config = config.from_example(example_path)
     ovr_config.platforms_to_build.each do |p|
-      acc[p] = [] unless acc.key?(p)
-      acc[p] << example_path
-    end
-  end
-
-  examples_by_platform.each do |platform, example_paths|
-    board = example_platform_info[platform][:board]
-    assure("Switching to board for #{platform} (#{board})") { @arduino_cmd.use_board(board) } unless last_board == board
-    last_board = board
-
-    example_paths.each do |example_path|
+      board = example_platform_info[p][:board]
       example_name = File.basename(example_path)
-      attempt("Verifying #{example_name}") do
-        ret = @arduino_cmd.verify_sketch(example_path)
+      attempt("Compiling #{example_name} for #{board}") do
+        ret = @backend.compile_sketch(example_path, board)
         unless ret
           puts
-          puts "Last command: #{@arduino_cmd.last_msg}"
-          puts @arduino_cmd.last_err
+          puts "Last command: #{@backend.last_msg}"
+          puts @backend.last_err
         end
         ret
       end
     end
   end
-
 end
 
 # initialize command and config
 config = ArduinoCI::CIConfig.default.from_project_library
 
-@arduino_cmd = ArduinoCI::ArduinoInstallation.autolocate!
-inform("Located Arduino binary") { @arduino_cmd.binary_path.to_s }
+@backend = ArduinoCI::ArduinoInstallation.autolocate!
+inform("Located arduino-cli binary") { @backend.binary_path.to_s }
+
+# initialize library under test
+cpp_library_path = Pathname.new(".")
+cpp_library = assure("Installing library under test") do
+  @backend.install_local_library(cpp_library_path)
+end
+
+assumed_name = @backend.name_of_library(cpp_library_path)
+ondisk_name = cpp_library_path.realpath.basename
+if assumed_name != ondisk_name
+  inform("WARNING") { "Installed library named '#{assumed_name}' has directory name '#{ondisk_name}'" }
+end
+
+if !cpp_library.nil?
+  inform("Library installed at") { cpp_library.path.to_s }
+else
+  # this is a longwinded way of failing, we aren't really "assuring" anything at this point
+  assure_multiline("Library installed successfully") do
+    puts @backend.last_msg
+    false
+  end
+end
+
+install_arduino_library_dependencies(
+  cpp_library.arduino_library_dependencies,
+  "<#{ArduinoCI::CppLibrary::LIBRARY_PROPERTIES_FILE}>"
+)
 
-perform_unit_tests(config)
-perform_compilation_tests(config)
+perform_unit_tests(cpp_library, config)
+perform_example_compilation_tests(cpp_library, config)
 
 terminate(true)

data/exe/arduino_library_location.rb

@@ -2,6 +2,6 @@
 require 'arduino_ci'
 
 # locate and/or forcibly install Arduino, keep stdout clean
-@arduino_cmd = ArduinoCI::ArduinoInstallation.autolocate!($stderr)
+@backend = ArduinoCI::ArduinoInstallation.autolocate!($stderr)
 
-puts @arduino_cmd.lib_dir
+puts @backend.lib_dir

data/lib/arduino_ci/arduino_backend.rb

@@ -0,0 +1,218 @@
+require 'fileutils'
+require 'pathname'
+require 'json'
+
+# workaround for https://github.com/arduino/Arduino/issues/3535
+WORKAROUND_LIB = "USBHost".freeze
+
+module ArduinoCI
+
+  # To report errors that we can't resolve or possibly even explain
+  class ArduinoExecutionError < StandardError; end
+
+  # Wrap the Arduino executable.  This requires, in some cases, a faked display.
+  class ArduinoBackend
+
+    # We never even use this in code, it's just here for reference because the backend is picky about it. Used for testing
+    # @return [String] the only allowable name for the arduino-cli config file.
+    CONFIG_FILE_NAME = "arduino-cli.yaml".freeze
+
+    # the actual path to the executable on this platform
+    # @return [Pathname]
+    attr_accessor :binary_path
+
+    # If a custom config is deired (i.e. for testing), specify it here.
+    # Note https://github.com/arduino/arduino-cli/issues/753 : the --config-file option
+    # is really the director that contains the file
+    # @return [Pathname]
+    attr_accessor :config_dir
+
+    # @return [String] STDOUT of the most recently-run command
+    attr_reader   :last_out
+
+    # @return [String] STDERR of the most recently-run command
+    attr_reader   :last_err
+
+    # @return [String] the most recently-run command
+    attr_reader   :last_msg
+
+    # @return [Array<String>] Additional URLs for the boards manager
+    attr_reader   :additional_urls
+
+    def initialize(binary_path)
+      @binary_path        = binary_path
+      @config_dir         = nil
+      @additional_urls    = []
+      @last_out           = ""
+      @last_err           = ""
+      @last_msg           = ""
+    end
+
+    def _wrap_run(work_fn, *args, **kwargs)
+      # do some work to extract & merge environment variables if they exist
+      has_env = !args.empty? && args[0].class == Hash
+      env_vars = has_env ? args[0] : {}
+      actual_args = has_env ? args[1..-1] : args  # need to shift over if we extracted args
+      custom_config = @config_dir.nil? ? [] : ["--config-file", @config_dir.to_s]
+      full_args = [binary_path.to_s, "--format", "json"] + custom_config + actual_args
+      full_cmd = env_vars.empty? ? full_args : [env_vars] + full_args
+
+      shell_vars = env_vars.map { |k, v| "#{k}=#{v}" }.join(" ")
+      @last_msg = " $ #{shell_vars} #{full_args.join(' ')}"
+      work_fn.call(*full_cmd, **kwargs)
+    end
+
+    # build and run the arduino command
+    def run_and_output(*args, **kwargs)
+      _wrap_run((proc { |*a, **k| Host.run_and_output(*a, **k) }), *args, **kwargs)
+    end
+
+    # run a command and capture its output
+    # @return [Hash] {:out => String, :err => String, :success => bool}
+    def run_and_capture(*args, **kwargs)
+      ret = _wrap_run((proc { |*a, **k| Host.run_and_capture(*a, **k) }), *args, **kwargs)
+      @last_err = ret[:err]
+      @last_out = ret[:out]
+      ret
+    end
+
+    def capture_json(*args, **kwargs)
+      ret = run_and_capture(*args, **kwargs)
+      ret[:json] = JSON.parse(ret[:out])
+      ret
+    end
+
+    # Get a dump of the entire config
+    # @return [Hash] The configuration
+    def config_dump
+      capture_json("config", "dump")[:json]
+    end
+
+    # @return [String] the path to the Arduino libraries directory
+    def lib_dir
+      Pathname.new(config_dump["directories"]["user"]) + "libraries"
+    end
+
+    # Board manager URLs
+    # @return [Array<String>] The additional URLs used by the board manager
+    def board_manager_urls
+      config_dump["board_manager"]["additional_urls"] + @additional_urls
+    end
+
+    # Set board manager URLs
+    # @return [Array<String>] The additional URLs used by the board manager
+    def board_manager_urls=(all_urls)
+      raise ArgumentError("all_urls should be an array, got #{all_urls.class}") unless all_urls.is_a? Array
+
+      @additional_urls = all_urls
+    end
+
+    # check whether a board is installed
+    # we do this by just selecting a board.
+    #   the arduino binary will error if unrecognized and do a successful no-op if it's installed
+    # @param boardname [String] The board to test
+    # @return [bool] Whether the board is installed
+    def board_installed?(boardname)
+      # capture_json("core", "list")[:json].find { |b| b["ID"] == boardname } # nope, this is for the family
+      run_and_capture("board", "details", "--fqbn", boardname)[:success]
+    end
+
+    # install a board by name
+    # @param name [String] the board name
+    # @return [bool] whether the command succeeded
+    def install_boards(boardfamily)
+      result = run_and_capture("core", "install", boardfamily)
+      result[:success]
+    end
+
+    # @return [Hash] information about installed libraries via the CLI
+    def installed_libraries
+      capture_json("lib", "list")[:json]
+    end
+
+    # @param path [String] The sketch to compile
+    # @param boardname [String] The board to use
+    # @return [bool] whether the command succeeded
+    def compile_sketch(path, boardname)
+      ext = File.extname path
+      unless ext.casecmp(".ino").zero?
+        @last_msg = "Refusing to compile sketch with '#{ext}' extension -- rename it to '.ino'!"
+        return false
+      end
+      unless File.exist? path
+        @last_msg = "Can't compile Sketch at nonexistent path '#{path}'!"
+        return false
+      end
+      ret = run_and_capture("compile", "--fqbn", boardname, "--warnings", "all", "--dry-run", path.to_s)
+      ret[:success]
+    end
+
+    # Guess the name of a library
+    # @param path [Pathname] The path to the library (installed or not)
+    # @return [String] the probable library name
+    def name_of_library(path)
+      src_path = path.realpath
+      properties_file = src_path + CppLibrary::LIBRARY_PROPERTIES_FILE
+      return src_path.basename.to_s unless properties_file.exist?
+      return src_path.basename.to_s if LibraryProperties.new(properties_file).name.nil?
+
+      LibraryProperties.new(properties_file).name
+    end
+
+    # Create a handle to an Arduino library by name
+    # @param name [String] The library "real name"
+    # @return [CppLibrary] The library object
+    def library_of_name(name)
+      raise ArgumentError, "name is not a String (got #{name.class})" unless name.is_a? String
+
+      CppLibrary.new(name, self)
+    end
+
+    # Create a handle to an Arduino library by path
+    # @param path [Pathname] The path to the library
+    # @return [CppLibrary] The library object
+    def library_of_path(path)
+      # the path must exist... and if it does, brute-force search the installed libs for it
+      realpath = path.realpath  # should produce error if the path doesn't exist to begin with
+      entry = installed_libraries.find { |l| Pathname.new(l["library"]["install_dir"]).realpath == realpath }
+      probable_name = entry["real_name"].nil? ? realpath.basename.to_s : entry["real_name"]
+      CppLibrary.new(probable_name, self)
+    end
+
+    # install a library from a path on the local machine (not via library manager), by symlink or no-op as appropriate
+    # @param path [Pathname] library to use
+    # @return [CppLibrary] the installed library, or nil
+    def install_local_library(path)
+      src_path         = path.realpath
+      library_name     = name_of_library(path)
+      cpp_library      = library_of_name(library_name)
+      destination_path = cpp_library.path
+
+      # things get weird if the sketchbook contains the library.
+      # check that first
+      if cpp_library.installed?
+        # maybe the project has always lived in the libraries directory, no need to symlink
+        return cpp_library if destination_path == src_path
+
+        uhoh = "There is already a library '#{library_name}' in the library directory (#{destination_path})"
+        # maybe it's a symlink? that would be OK
+        if Host.symlink?(destination_path)
+          current_destination_target = Host.readlink(destination_path)
+          return cpp_library if current_destination_target == src_path
+
+          @last_msg = "#{uhoh} and it's symlinked to #{current_destination_target} (expected #{src_path})"
+          return nil
+        end
+
+        @last_msg = "#{uhoh}.  It may need to be removed manually."
+        return nil
+      end
+
+      # install the library
+      libraries_dir = destination_path.parent
+      libraries_dir.mkpath unless libraries_dir.exist?
+      Host.symlink(src_path, destination_path)
+      cpp_library
+    end
+  end
+end