stop recommending a Gemfile

Author: ianfixes

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Better indications of which example sketch is being compiled as part of testing
 
 ### Changed
+- Topmost installtion instructions now suggest `gem install arduino_ci` instead of using a `Gemfile`.  Reasons for using a `Gemfile` are listed and discussed separately further down the README.
 
 ### Deprecated
 

README.md

@@ -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:
+
+* 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
 
-> 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_.
+### 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'
+
+# to use the latest available gem, replace the below values for git: and ref: as needed
+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.
+> At the time of this writing, `1.2` 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`, or copy [the `.gitignore` used by this project](.gitignore):
 
-```
+It would also make sense to add the following to your `.gitignore`:
+```ignore-list
 /.bundle/
-/.yardoc
-Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
 vendor
-*.gem
+```
 
-# rspec failure tracking
-.rspec_status
+#### Using the latest-available code
 
-# C++ stuff
-*.bin
-*.bin.dSYM
+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>'
+```
+
+
+#### 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
 
@@ -171,8 +194,8 @@ 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
 ```
 
 
@@ -185,8 +208,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
 ```
 
 

SampleProjects/README.md

@@ -1,10 +1,9 @@
 Arduino Sample Projects
 =======================
 
-This directory contains projects that are intended solely for testing the various features of this gem -- to test the testing framework itself.  The RSpec tests refer specifically to these projects.
-
-Because of this, these projects include some intentional quirks that differ from what a well-formed an Arduino project for testing with `arduino_ci` might contain.  See other projects in the "Arduino-CI" GitHub organization for practical examples.
+This directory contains projects that are intended solely for testing the various features of this gem -- to test the testing framework itself.  The RSpec tests refer specifically to these projects, and as a result _some are explicity designed to fail_.
 
+> **If you are a first-time `arduino_ci` user an are looking for an example to copy from, see [the `Arduino-CI/Blink` repository](https://github.com/Arduino-CI/Blink) instead.**
 
 * "TestSomething" contains a minimial library, but tests for all the C++ compilation feature-mocks of arduino_ci.
 * "DoSomething" is a simple test of the testing framework (arduino_ci) itself to verfy that passes and failures are properly identified and reported.  Because of this, it includes test files that are expected to fail -- they are prefixed with "bad-".
@@ -13,3 +12,4 @@ Because of this, these projects include some intentional quirks that differ from
 * "OnePointFiveDummy" is a non-functional library meant to test file inclusion logic on libraries conforming to the ["1.5" specfication](https://arduino.github.io/arduino-cli/latest/library-specification/)
 * "DependOnSomething" is a non-functional library meant to test file inclusion logic with dependencies
 * "ExcludeSomething" is a non-functional library meant to test directory exclusion logic
+* "NetworkLib" tests the Ethernet library

SampleProjects/TestSomething/README.md

@@ -1,5 +1,6 @@
 # TestSomething
 
-This is a "beater" example that is referenced by tests of the Arduino CI module itself.
 
 All the tests of our mocked `Arduino.h` implementation live here.
+
+This example project is tightly coupled to the tests of the Arduino CI module itself.  In that sense, each of the individual test files will be illustrative of the testing strategy and capabilities of the core library itself.