Documentation updates

README.md

@@ -1,111 +1,202 @@
-Ceedling ![CI](https://github.com/ThrowTheSwitch/Ceedling/workflows/CI/badge.svg)
-========
-Ceedling is a build system for C projects that is something of an extension 
-around Ruby’s Rake (make-ish) build system. Ceedling also makes TDD (Test-Driven Development) 
-in C a breeze by integrating [CMock](https://github.com/throwtheswitch/cmock), 
-[Unity](https://github.com/throwtheswitch/unity), and 
-[CException](https://github.com/throwtheswitch/cexception) -- 
-three other awesome open-source projects you can’t live without if you're creating awesomeness 
-in the C language. Ceedling is also extensible with a handy plugin mechanism.
+# Ceedling ![CI](https://github.com/ThrowTheSwitch/Ceedling/workflows/CI/badge.svg)
 
-Documentation
-=============
+Ceedling is a handy-dandy build system for C projects. Ceedling can build your 
+release artifact but is especially adept at building test suites.
 
-[Usage help](docs/CeedlingPacket.md), [release notes](docs/ReleaseNotes.md), integration guides, and more exists [in docs/](docs/).
+Ceedling works the way developers want to work. It is entirely command-line driven.
+All generated and framework code is easy to see and understand. Its features
+cater to low-level embedded development as well as enterprise-level software 
+systems.
 
-Getting Started
-===============
+Ceedling is the glue for bringing together three other awesome open-source 
+projects you can’t live without if you‘re creating awesomeness in the C language.
 
-First make sure Ruby is installed on your system (if it's not already). Then, from a command prompt:
+1. [Unity], an xUnit-style test framework.
+1. [CMock], a code generating, function mocking kit for interaction-based testing.
+1. [CException], a framework for adding simple exception handling to C projects
+   in the style of higher-order programming languages.
 
-    > gem install ceedling
+In its simplest form, Ceedling can build and test an entire project from just a
+few lines in a project configuration file.
 
-(Alternate Installation for Those Planning to Be Ceedling Developers)
-======================================================================
+Because it handles all the nitty-gritty of rebuilds and becuase of Unity and CMock,
+Ceedling makes TDD ([Test-Driven Development][tdd]) in C a breeze.
 
-    > git clone --recursive https://github.com/throwtheswitch/ceedling.git
-    > cd ceedling
-    > bundle install # Ensures you have all RubyGems needed
-    > git submodule update --init --recursive # Updates all submodules
-    > bundle exec rake # Run all Ceedling library tests
+Ceedling is also extensible with a simple plugin mechanism.
 
-If bundler isn't installed on your system or you run into problems, you might have to install it:
+[Unity]: https://github.com/throwtheswitch/unity
+[CMock]: https://github.com/throwtheswitch/cmock
+[CException]: https://github.com/throwtheswitch/cexception
+[tdd]: http://en.wikipedia.org/wiki/Test-driven_development
 
-    > sudo gem install bundler
+# Documentation
 
-If you run into trouble running bundler and get messages like this `can't find gem
-bundler (>= 0.a) with executable bundle (Gem::GemNotFoundException)`, you may
-need to install a different version of bundler. For this please reference the
-version in the Gemfile.lock. An example based on the current Gemfile.lock is as
-followed:
+[Usage help](docs/CeedlingPacket.md), [release notes](docs/ReleaseNotes.md), [breaking changes](docs/BreakingChanges.md), a variety of guides, and much more exists in [docs/](docs/).
 
-    > sudo gem install bundler -v 1.16.2
+# Getting Started
 
-Creating A Project
-==================
+**👀 See the _Quick Start_ guide in [CeedlingPacket](docs/CeedlingPacket.md).**
 
-Creating a project with Ceedling is easy. Simply tell ceedling the
-name of the project, and it will create a subdirectory called that
-name and fill it with a default directory structure and configuration.
+## The Basics
 
-    ceedling new YourNewProjectName
+1. Install Ruby. (Only Ruby 3+ supported.)
+1. Install Ceedling. (All other frameworks are included.)
+   ```shell
+   > gem install ceedling
+   ```
+1. Create an empty Ceedling project or add a Ceedling project file to
+   the root of your existing project.
+1. Run tasks like so:
+   ```shell
+   > ceedling test:all release
+   ```
 
-You can add files to your src and test directories and they will
+Example super-duper simple Ceedling configuration file:
+
+```yaml
+:project:
+  :build_root: project/build/
+  :release_build: TRUE
+
+:paths:
+  :test:
+    - tests/**
+  :source:
+    - source/**
+  :include:
+    - inc/**
+```
+
+## Creating A Project
+
+Creating a project with Ceedling is easy. Simply tell Ceedling the
+name of the project, and it will create a directory with that name
+and fill it with a default subdirectory structure and configuration 
+file.
+
+```shell
+ > ceedling new YourNewProjectName
+```
+
+You can add files to your `src/` and `test/` directories, and they will
 instantly become part of your test build. Need a different structure?
-You can start to tweak the `project.yml` file immediately with your new
-path or tool requirements.
+You can modify the `project.yml` file with your new path or tooling 
+setup.
 
 You can upgrade to the latest version of Ceedling at any time,
-automatically gaining access to the packaged Unity and CMock that
-come with it.
+automatically gaining access to any updates to Unity, CMock, and 
+CException that come with it.
 
-    gem update ceedling
+```shell
+ > gem update ceedling
+```
 
-Documentation
-=============
+## Documentation
 
 Are you just getting started with Ceedling? Maybe you'd like your
 project to be installed with some of its handy documentation? No problem!
 You can do this when you create a new project.
 
-    ceedling new --docs MyAwesomeProject
+```shell
+ > ceedling new --docs MyAwesomeProject
+```
 
-Bonding Your Tools And Project
-==============================
+## Attaching a Ceedling Version to Your Project
 
-Ceedling can deploy all of its guts into the project as well. This
-allows it to be used without having to worry about external dependencies.
-You don't have to worry about Ceedling changing for this particular
-project just because you updated your gems... no need to worry about
-changes in Unity or CMock breaking your build in the future. If you'd like
-to use Ceedling this way, tell it you want a local copy when you create
-your project:
+Ceedling can be installed as a globally available Ruby gem. Ceedling can 
+also deploy all of its guts into your project instead. This allows it to 
+be used without worrying about external dependencies. More importantly, 
+you don't have to worry about Ceedling changing outside of your project 
+just because you updated your gems. No need to worry about changes in 
+Unity or CMock breaking your build in the future.
 
-    ceedling new --local YourNewProjectName
+To use Ceedling this way, tell it you want a local copy when you create
+your project:
 
-This will install all of Unity, CMock, and Ceedling into a new folder
-named `vendor` inside your project `YourNewProjectName`. It will still create
-the simple directory structure for you with `src` and `test` folders.
+```shell
+ > ceedling new --local YourNewProjectName
+```
 
-SCORE!
+This will install all of Unity, CMock, CException, and Ceedling itsef 
+into a new folder `vendor/` inside your project `YourNewProjectName/`.
+It will still create a simple empty directory structure for you with
+`src/` and `test/` folders.
 
 If you want to force a locally installed version of Ceedling to upgrade
-to match your latest gem later, it's easy! Just issue the following command:
+to match your latest gem later, no problem. Just do the following:
+
+```shell
+ > ceedling upgrade --local YourNewProjectName
+```
+
+Just like with the `new` command, an `upgrade` should be executed from 
+from within the root directory of your project.
+
+Are you afraid of losing all your local changes when this happens? You 
+can prevent Ceedling from updating your project file by adding 
+`--no_configs`.
+
+```shell
+ > ceedling upgrade --local --no_configs YourSweetProject
+```
+
+## Git Integration
+
+Are you using Git? You might want Ceedling to create a `.gitignore` 
+file for you by adding `--gitignore` to your `new` call.
+
+```shell
+ > ceedling new --gitignore YourNewProjectName
+```
+
+# Ceedling Development
+
+## Alternate installation
+
+```shell
+ > git clone --recursive https://github.com/throwtheswitch/ceedling.git
+ > cd ceedling
+ > git submodule update --init --recursive
+ > bundle install
+```
+
+The Ceedling repository incorporates its supporting frameworks and some
+plugins via git submodules. A simple clone may not pull in the latest
+and greatest.
+
+The `bundle` tool ensures you have all needed Ruby gems installed. If 
+Bundler isn't installed on your system or you run into problems, you 
+might have to install it:
+
+```shell
+ > sudo gem install bundler
+```
+
+If you run into trouble running bundler and get messages like _can't 
+find gem bundler (>= 0.a) with executable bundle 
+(Gem::GemNotFoundException)_, you may need to install a different 
+version of Bundler. For this please reference the version in the 
+Gemfile.lock.
+
+```shell
+ > sudo gem install bundler -v <version in Gemfile.lock>
+```
 
-    ceedling upgrade --local YourNewProjectName
+## Running self-tests
 
-Just like the `new` command, it's called from the parent directory of your
-project.
+Ceedling uses [RSpec] for its tests.
 
-Are you afraid of losing all your local changes when this happens? You can keep
-Ceedling from updating your project file by issuing `no_configs`.
+To run all tests:
 
-    ceedling upgrade --local --no_configs TheProject
+```shell
+ > bundle exec rake
+```
 
-Git Integration
-===============
+To run individual test files and perform other tasks, use the 
+available Rake tasks. List those task like this:
 
-Are you using Git? You might want to automatically have Ceedling create a
-`gitignore` file for you by adding `--gitignore` to your `new` call.
+```shell
+ > rake -T
+```
 
-*HAPPY TESTING!*
+[RSpec]: https://rspec.info

docs/ReleaseNotes.md

@@ -32,7 +32,7 @@ Ceedling 0.32 introduces a new build pipeline that batches build steps breadth-f
 
 In previous versions of Ceedling each test executable was built with essentially the same global configuration. In the case of `#define`s and tool command line flags, individual files could be handled differently, but configuring Ceedling for doing so for all the files in any one test executable was tedious and error prone.
 
-Now Ceedling builds each test executable as a mini project where header file search paths, compilation `#define`s, and tool flags can be specified per test executable. That is, each file that ultimately comprises a test executable is handled with the same configuration as the other files that make up that test executable.
+Now Ceedling builds each test executable as a mini project where header file search paths, compilation `#define` symbols, and tool flags can be specified per test executable. That is, each file that ultimately comprises a test executable is handled with the same configuration as the other files that make up that test executable.
 
 Now you can have tests with quite different configurations and behaviors. Two tests need different mocks of the same header file? No problem. You want to test the same source file two different ways? We got you.
 
@@ -62,6 +62,8 @@ The [Ceedling user guide](CeedlingPacket.md) has been significantly revised and
 
 Many of the plugins have received documentation updates as well.
 
+There's more to be done, but Ceedling's documentation is more complete and accurate than it's ever been.
+
 ### Small Deal Highlights 🥉
 
 - Effort has been invested across the project to improve error messages, exception handling, and exit code processing. Noisy backtraces have been relegated to the verbosity level of DEBUG as <insert higher power> intended.

lib/ceedling/configurator.rb

@@ -397,8 +397,10 @@ def build_supplement(config_base, config_more)
   # Many of Configurator's dynamically attached collections are Rake FileLists.
   # Rake FileLists are not thread safe with respect to resolving patterns into specific file lists.
   # Unless forced, file patterns are resolved upon first access.
-  # This method forces resolving and can be called in the build process at a moment after
-  # file creation operations are complete but before first access inside a thread.
+  # This method forces resolving of all FileList-based collections and can be called in the build 
+  # process at a moment after any file creation operations are complete but before first access 
+  # inside a thread.
+  # TODO: Remove this once a thread-safe version of FileList has been brought into the project.
   def resolve_collections()
     collections = self.methods.select { |m| m =~ /^collection_/ }
     collections.each do |collection|

lib/ceedling/tasks_release.rake

@@ -12,6 +12,7 @@ task RELEASE_SYM => [:directories] do
 
     # FileList-based collections are not thread safe.
     # Force file pattern resolution before any FileList first accesses inside concurrent threads.
+    # TODO: Remove this once a thread-safe version of FileList has been brought into the project.
     @ceedling[:configurator].resolve_collections()
 
     core_objects  = []

lib/ceedling/test_invoker.rb

@@ -36,6 +36,7 @@ def setup_and_invoke(tests:, context:TEST_SYM, options:{})
     begin
       # FileList-based collections are not thread safe.
       # Force file pattern resolution before any FileList first accesses inside concurrent threads.
+      # TODO: Remove this once a thread-safe version of FileList has been brought into the project.
       @configurator.resolve_collections()
 
       # Begin fleshing out the testables data structure

license.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2023 Michael Karlesky, Mark VanderVoord, Greg Williams
+Copyright (c) Michael Karlesky, Mark VanderVoord, Greg Williams
 
 https://opensource.org/license/mit/