Added which Ceedling documentation

docs/CeedlingPacket.md

@@ -134,18 +134,22 @@ It's just all mixed together.
  configuration options — from project paths to command line tools to plugins and
  much, much more.
 
-1. **[Build Directive Macros][packet-section-12]**
+1. **[Which Ceedling][packet-section-12]**
+
+ Sometimes you may need to point to a different Ceedling to run.
+
+1. **[Build Directive Macros][packet-section-13]**
 
  These code macros can help you accomplish your build goals When Ceedling’s 
  conventions aren’t enough.
 
-1. **[Ceedling Plugins][packet-section-13]**
+1. **[Ceedling Plugins][packet-section-14]**
 
  Ceedling is extensible. It includes a number of built-in plugins for code coverage,
  test report generation, continuous integration reporting, test file scaffolding 
  generation, sophisticated release builds, and more.
 
-1. **[Global Collections][packet-section-14]**
+1. **[Global Collections][packet-section-15]**
 
  Ceedling is built in Ruby. Collections are globally available Ruby lists of paths,
  files, and more that can be useful for advanced customization of a Ceedling project 
@@ -162,9 +166,10 @@ It's just all mixed together.
 [packet-section-9]: #using-unity-cmock--cexception
 [packet-section-10]: #how-to-load-a-project-configuration-you-have-options-my-friend
 [packet-section-11]: #the-almighty-ceedling-project-configuration-file-in-glorious-yaml
-[packet-section-12]: #build-directive-macros
-[packet-section-13]: #ceedling-plugins
-[packet-section-14]: #global-collections
+[packet-section-12]: #which-ceedling
+[packet-section-13]: #build-directive-macros
+[packet-section-14]: #ceedling-plugins
+[packet-section-15]: #global-collections
 
 ---
 
@@ -2273,22 +2278,11 @@ migrated to the `:test_build` and `:release_build` sections.
 
  This is an advanced project option primarily meant for development work
  on Ceedling itself. This setting tells the code that launches the 
- Ceedling application where to find the code to launch. It’s not uncommon 
- in Ceedling development work to have the last production gem installed 
- while modifying the application code in a locally cloned repository. Or, 
- you may be bouncing between local versions of Ceedling to troubleshoot
- changes.
-
- This value can be `gem` to indicate the command line utility `ceedling` 
- should launch the application packaged in the installed gem. It can also 
- be a relative or absolute path in your file system. If it is a path, that
- path should point to the top-level directory that contains Ceedling’s
- `bin/` and `lib/` sub-directories.
-
- _Note:_ If you are working on the code in `bin/` and want to run it,
- you must take the additional step of specifying the path to `ceedling`
- in your file system at your command prompt — e.g. 
- `> my/ceedling/changes/bin/ceedling <args>`.
+ Ceedling application where to find the code to launch.
+
+ This entry can be either a directory path or `gem`.
+
+ See the section [Which Ceedling](#which_ceedling) for full details.
 
  **Default**: `gem`
 
@@ -4232,6 +4226,83 @@ If no reporting plugins are specified, Ceedling will print to `$stdout` the
 
 <br/>
 
+# Which Ceedling
+
+In certain scenarios you may need to run a different version of Ceedling.
+Typically, Ceedling developers need this ability. But, it could come in
+handy in certain advanced Continuous Integration build scenarios or some
+sort of version behavior comparison.
+
+It’s not uncommon in Ceedling development work to have the last production 
+gem installed while modifying the application code in a locally cloned 
+repository. Or, you may be bouncing between local versions of Ceedling to
+troubleshoot changes.
+
+Which Ceedling handling gives you options on what gets run.
+
+## Which Ceedling background
+
+Ceedling is usually packaged and installed as a Ruby Gem. This gem ends
+up installed in an appropriate place by the `gem` package installer.
+Inside the gem installation is the entire Ceedling project. The `ceedling`
+command line launcher lives in `bin/` while the Ceedling application lives
+in `lib/`. The code in `/bin` manages lots of startup details and base
+configuration. Ultimately, it then launches the main application code from
+`lib/`.
+
+The features and conventions controlling _which ceedling_ dictate which
+application code the `ceedling` command line handler launches.
+
+_Note:_ If you are a developer working on the code in Ceedling’s `bin/` 
+and want to run it while a gem is installed, you must take the additional 
+step of specifying the path to the `ceedling` launcher in your file system.
+
+In Unix-like systems, this will look like:
+`> my/ceedling/changes/bin/ceedling <args>`.
+
+On Windows systems, you may need to run:
+`> ruby my\ceedling\changes\bin\ceedling <args>`.
+
+## Which Ceedling options and precedence
+
+When Ceedling starts up, it evaluates a handful of conditions to determine
+which Ceedling location to launch.
+
+The following are evaluated in order:
+
+1. Environment variable `WHICH_CEEDLING`. If this environment variable is
+ set, its value is used.
+1. Configuration entry `:project` ↳ `:which_ceedling`. If this is set,
+ its value is used.
+1. The path `vendor/ceedling`. If this path exists in your working 
+ directory — typically because of a `--local` vendored installation at
+ project creation — its contents are used to launch Ceedling.
+1. If none of the above exist, the `ceedling` launcher defaults to using
+ the `lib/` directory next to the `bin/` directory from which the 
+ `ceedling` launcher is running. In the typical case this is the default 
+ gem installation.
+
+_Note:_ Configuration entry (2) does not make sense in some scenarios.
+When running `ceedling new`, `ceedling examples`, or `ceedling example` 
+there is no project file to read. Similarly, `ceedling upgrade` does not 
+load a project file; it merely works with the directory structure and 
+contets of a project. In these cases, the environment variable is your
+only option to set which Ceedling to launch.
+
+## Which Ceedling settings
+
+The environment variable and configuration entry for _Which Ceedling_ can
+contain two values:
+
+1. The value `gem` indicates that the command line `ceedling` launcher 
+ should run the application packaged alongside it in `lib/` (these 
+ paths are typically found in the gem installation location).
+1. A relative or absolute path in your file system. Such a path should 
+ point to the top-level directory that contains Ceedling’s `bin/` and 
+ `lib/` sub-directories.
+
+<br/>
+
 # Build Directive Macros
 
 ## Overview of Build Directive Macros

docs/Changelog.md

@@ -9,7 +9,7 @@ This changelog is complemented by two other documents:
 
 ---
 
-# [1.0.0 pre-release] — 2024-04-02
+# [1.0.0 pre-release] — 2024-04-22
 
 ## 🌟 Added
 
@@ -133,6 +133,14 @@ The most commonly reported bugs have been fixed:
 
 A handful of small bugs in using shell `echo` with the ASCII bell character have been fixed.
 
+### Which Ceedling handling includes new environment variable `WHICH_CEEDLING`
+
+A previously semi-documented feature allowed you to point to a version of Ceedling on disk to run from within your project file, `:project` ↳ `:which_ceedling`.
+
+This feature is primarily of use to Ceedling developers but can be useful in other specialized scenarios. See the documentation in _[CeedlingPacket](CeedlingPacket.md))_ for full deatils as this is an advanced feature.
+
+The existing feature has been improved with logging and validation as well as proper documentation. An environment variable `WHICH_CEEDLING` is now also supported. If set, this variable supersedes any other settings. In the case of `ceedling new` and `ceedling upgrade`, it is the only way to change which Ceedling is in use as a project file either does not exist for the former or is not loaded for the latter.
+
 ## ⚠️ Changed
 
 ### Preprocessing improvements