Merge branch 'test/preprocessing_improvements' into test/ceedling_0_3…

…2_rc

.github/workflows/main.yml

@@ -50,16 +50,15 @@ jobs:
         with:
           submodules: recursive
 
-      # Setup Ruby Testing Tools to do tests on multiple ruby version
-      - name: Setup Ruby Testing Tools
+      # Setup Ruby to run test & build steps on multiple ruby versions
+      - name: Setup Ruby Version Matrix
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
 
-      # Install Ruby Testing Tools (Bundler version should match the one in Gemfile.lock)
-      - name: Install Ruby Testing Tools
+      # Install Gem Depdencies (Bundler version should match the one in Gemfile.lock)
+      - name: Install Gem Dependencies for Testing and Ceedling Gem Builds
         run: |
-          gem install rspec
           gem install rubocop -v 0.57.2
           gem install bundler -v "$(grep -A 1 "BUNDLED WITH" Gemfile.lock | tail -n 1)"
           bundle update
@@ -90,8 +89,8 @@ jobs:
         run: |
           rake ci
 
-      # Build & Install Gem
-      - name: Build and Install Gem
+      # Build & Install Ceedling Gem
+      - name: Build and Install Ceedling Gem
         run: |
           gem build ceedling.gemspec
           gem install --local ceedling-*.gem
@@ -104,21 +103,21 @@ jobs:
           cd ../..
 
       # Run FFF Plugin Tests
-      - name: Run Tests on FFF Plugin
+      - name: "Run Tests on Ceedling Plugin: FFF"
         run: |
           cd plugins/fff
           rake
           cd ../..
 
       # Run Module Generator Plugin Tests
-      - name: Run Tests on Module Generator Plugin
+      - name: "Run Tests on Ceedling Plugin: Module Generator"
         run: |
           cd plugins/module_generator
           rake
           cd ../..
 
       # Run Dependencies Plugin Tests
-      - name: Run Tests on Dependencies Plugin
+      - name: "Run Tests on Ceedling Plugin: Dependencies"
         run: |
           cd plugins/dependencies
           rake
@@ -147,30 +146,28 @@ jobs:
         with:
           submodules: recursive
 
-      # Setup Ruby Testing Tools to do tests on multiple ruby version
-      - name: Set Up Ruby Testing Tools
+      # Setup Ruby to run test & build steps on multiple ruby versions
+      - name: Setup Ruby Version Matrix
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
 
-      # Install Ruby Testing Tools
-      # Bundler version should match the one in Gemfile.lock
-      - name: Install Ruby Testing Tools
+      # Install Gem Depdencies (Bundler version should match the one in Gemfile.lock)
+      - name: Install Gem Dependencies for Testing and Ceedling Gem Builds
         shell: bash
         run: |
-          gem install rspec
           gem install rubocop -v 0.57.2
           gem install bundler -v "$(grep -A 1 "BUNDLED WITH" Gemfile.lock | tail -n 1)"
           bundle update
           bundle install
 
       # Install GCovr for Gcov plugin test
-      - name: Install GCovr for Gcov Plugin Tests
+      - name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
         run: |
           pip install gcovr
 
       # Install ReportGenerator for Gcov plugin test
-      - name: Install ReportGenerator for Gcov Plugin Tests
+      - name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
         run: |
           dotnet tool install --global dotnet-reportgenerator-globaltool
 
@@ -180,7 +177,7 @@ jobs:
           rake ci
 
       # Build & Install Gem
-      - name:  Build and Install Gem
+      - name:  Build and Install Ceedling Gem
         run: |
           gem build ceedling.gemspec
           gem install --local ceedling-*.gem
@@ -193,21 +190,21 @@ jobs:
           cd ../..
 
       # Run FFF Plugin Tests
-      - name: Run Tests on FFF Plugin
+      - name: "Run Tests on Ceedling Plugin: FFF"
         run: |
           cd plugins/fff
           rake
           cd ../..
 
       # Run Module Generator Plugin Tests
-      - name: Run Tests on Module Generator Plugin
+      - name: "Run Tests on Ceedling Plugin: Module Generator"
         run: |
           cd plugins/module_generator
           rake
           cd ../..
 
       # Run Dependencies Plugin Tests
-      - name: Run Tests on Dependencies Plugin
+      - name: "Run Tests on Ceedling Plugin: Dependencies"
         run: |
           cd plugins/dependencies
           rake

Gemfile

@@ -8,15 +8,19 @@
 source "http://rubygems.org/"
 
 gem "bundler", "~> 2.5"
-gem "rake"
+
+# Testing tools
 gem "rspec", "~> 3.8"
-gem "require_all"
-gem "constructor"
-gem "diy"
+gem "rake", ">= 12", "< 14"
 gem "rr"
-gem "thor"
-gem "deep_merge"
-gem "unicode-display_width"
+gem "require_all"
+
+# Ceedling dependencies
+gem "diy", "~> 1.1"
+gem "constructor", "~> 2"
+gem "thor", "~> 1.3"
+gem "deep_merge", "~> 1.2"
+gem "unicode-display_width", "~> 3.1"
 
 #these will be used if present, but ignored otherwise
 #gem "curses"

Gemfile.lock

@@ -8,22 +8,24 @@ GEM
       constructor (>= 1.0.0)
     rake (13.2.1)
     require_all (3.0.0)
-    rr (3.1.0)
+    rr (3.1.1)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.0)
+    rspec-core (3.13.2)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.1)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    thor (1.3.1)
-    unicode-display_width (2.5.0)
+    thor (1.3.2)
+    unicode-display_width (3.1.2)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
 
 PLATFORMS
   ruby
@@ -34,15 +36,15 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.5)
-  constructor
-  deep_merge
-  diy
-  rake
+  constructor (~> 2)
+  deep_merge (~> 1.2)
+  diy (~> 1.1)
+  rake (>= 12, < 14)
   require_all
   rr
   rspec (~> 3.8)
-  thor
-  unicode-display_width
+  thor (~> 1.3)
+  unicode-display_width (~> 3.1)
 
 BUNDLED WITH
-   2.5.10
+   2.5.23

README.md

@@ -1,7 +1,7 @@
 Ceedling ![CI](https://github.com/ThrowTheSwitch/Ceedling/workflows/CI/badge.svg)
 ========
 
-_October 29, 2024_ 🚚 **Ceedling 1.0.0** is a release candidate and will be
+_November 28, 2024_ 🚚 **Ceedling 1.0.0** is a release candidate and will be
 shipping very soon. See the [Release Notes](docs/ReleaseNotes.md) for an overview
 of all that’s new since 0.31.1 plus links to the detailed Changelog and list of 
 Breaking Changes.
@@ -334,6 +334,11 @@ Training and support contracts are available through **_[Ceedling Pro][ceedling-
 
 [TTS-help]: https://www.throwtheswitch.org/#help-section
 
+The [Agile Embedded Podcast][ae-podcast] includes an [episode on Ceedling][ceedling-episode]!
+
+[ae-podcast]: https://agileembeddedpodcast.com/
+[ceedling-episode]: https://agileembeddedpodcast.com/episodes/ceedling
+
 ## Ceedling docs
 
 * **_[Ceedling Packet][ceedling-packet]_** is Ceedling’s user manual. It also references and links to the documentation of the projects, _Unity_, _CMock_, and _CException_, that it weaves together into your test and release builds.

ceedling.gemspec

@@ -39,11 +39,12 @@ Ceedling projects are created with a YAML configuration file. A variety of conve
 
   s.required_ruby_version = ">= 3.0.0"
 
-  s.add_dependency "thor", ">= 0.14"
+  s.add_dependency "thor", "~> 1.3"
   s.add_dependency "rake", ">= 12", "< 14"
   s.add_dependency "deep_merge", "~> 1.2"
+  s.add_dependency "diy", "~> 1.1"
   s.add_dependency "constructor", "~> 2"
-  s.add_dependency "unicode-display_width", "~> 2.5"
+  s.add_dependency "unicode-display_width", "~> 3.1"
 
   # Files needed from submodules
   s.files         = []

config/test_environment.rb

@@ -9,8 +9,6 @@
 [ 
   'lib',
   'test',
-  'vendor/behaviors/lib',
-  'vendor/hardmock/lib',
 ].each do |dir|
   $LOAD_PATH.unshift( File.join( File.expand_path(File.dirname(__FILE__) + "/../"), dir) )
 end

docs/BreakingChanges.md

@@ -7,7 +7,7 @@ These breaking changes are complemented by two other documents:
 
 ---
 
-# [1.0.0 pre-release] — 2024-10-31
+# [1.0.0 pre-release] — 2024-11-28
 
 ## Explicit `:paths` ↳ `:include` entries in the project file
 
@@ -60,17 +60,15 @@ In place of `true` or `false`, `:use_test_preprocessing` now accepts:
 
 The previously undocumented `TEST_FILE()` build directive macro (#796) available within test files has been renamed and is now officially documented.
 
-## Preprocessing is temporarily unable to handle `TEST_CASE()`, `TEST_RANGE()`, `TEST_SOURCE_FILE()`, and `TEST_INCLUDE_PATH()`
+## Preprocessing is unable to handle Unity’s `TEST_CASE()` and `TEST_RANGE()` and has limits for `TEST_INCLUDE_PATH()`
 
-Ceedling’s preprocessing abilities have been nearly entirely rewritten. In the process of doing so Ceedling has temporarily lost the ability to preprocess a test file but properly handle directive macros including Unity’s parameterized test case macros and test file build diretive macros.
+Ceedling’s preprocessing abilities have been nearly entirely rewritten. The one case Ceedling cannot yet handle is preprocessing test files that contain Unity’s parameterized test case macros.
 
-`TEST_CASE()` and `TEST_RANGE()` are Unity macros that effectively disappear when Ceedling uses the GNU preprocessor to expand a test file into raw code to extract details with text parsing. After preprocessing, these macros no longer exist in the test file that is then compiled.
+`TEST_CASE()` and `TEST_RANGE()` are Unity macros that are positional in a file in relation to the test case functions they modify. While Ceedling's test preprocessing can preserve these macro calls, their position cannot be preserved.
 
-You may have need to wrap `TEST_SOURCE_FILE()` and `TEST_INCLUDE_PATH()` in conditional compilation preprocessor statements (e.g. `#ifdef`). This will not work as you expect. These macros are used as markers for advanced abilities discovered by Ceedling parsing a test file as plain text. Whether or not Ceedling preprocessing is enabled, Ceedling will always discover these marker macros in the plain text of a test file.
+You may want to wrap `TEST_INCLUDE_PATH()` in conditional compilation preprocessor statements (e.g. `#ifdef`). This will not work as you expect. This macro “marker” must be discovered at the beginning of a test build by Ceedling parsing a test file as plain text. Cyclical dependencies related to preprocessing prevent anything more sophisticated.
 
-In future revisions of Ceedling, support for these macros in preprocessing scenarios will be brought back (very likely without a dedicated configuration option — hopefully, we’ll get it to just work).
-
-Note: `:project` ↳ `:use_test_preprocessor` is no longer a binary setting (`true`/`false`). Mockable header file preprocessing can now be enabled with a `:mocks` setting while test files are left untouched by preprocessing. This should support the majority of advanced use cases for preprocessing.
+Note: `:project` ↳ `:use_test_preprocessor` is no longer a binary setting (`true`/`false`). Mockable header file preprocessing can now be enabled with a `:mocks` setting while test files are left untouched by preprocessing. This can allow test preprocessing in the common cases of sophtisticate mockable headers while Unity’s `TEST_CASE()` and `TEST_RANGE()` are utilized in a test file untouched by preprocessing.
 
 ## Quoted executables in tool definitions
 
@@ -243,3 +241,10 @@ The above subproject definition will now look like the following:
         - DEFINE_JUST_FOR_THIS_FILE
         - AND_ANOTHER
 ```
+
+## Undocumented `:project` ↳ `:debug` has been removed
+
+This project setting existed from Ceedling’s earliest days and was a crude stand-in for command line debug verbosity handling.
+
+It has been removed as it was rarely if ever utilized and needlessly complicated internal mechanisms for verbosity handling and project validation.
+

docs/CeedlingPacket.md

@@ -1538,30 +1538,48 @@ The sections that follow flesh out the details of the bulleted list above.
 
 #### Preprocessing gotchas
 
-**_NOTE:_ As of Ceedling 1.0.0, Ceedling’s preprocessing feature has a 
-limitation that affects Unity features triggered by the following macros:**
+**_IMPORTANT:_ As of Ceedling 1.0.0, Ceedling’s test preprocessing feature 
+has a limitation that affects Unity features triggered by the following macros.**
 
 * `TEST_CASE()`
 * `TEST_RANGE()`
 
-With Ceedling’s preprocessing enabled, Unity’s `TEST_CASE()` and `TEST_RANGE()`
-in your test files will effectively vanish before test compilation is able to 
-process them. That is, Ceedling’s preprocessing and these Unity features are 
-not presently compatible. (Note that it is possible to enable preprocessing for
-mockable header files apart from enabling it for test files.)
+`TEST_CASE()` and `TEST_RANGE()` are Unity macros that are positional in a file 
+in relation to the test case functions they modify. While Ceedling's test file
+preprocessing can preserve these macro calls, their position cannot be preserved.
+
+That is, Ceedling’s preprocessing and these Unity features are not presently 
+compatible. Note that it _is_ possible to enable preprocessing for mockable 
+header files apart from enabling it for test files. See the documentation for
+`:project` ↳ `:use_test_preprocessing`. This can allow test preprocessing in the 
+common cases of sophtisticate mockable headers while Unity’s `TEST_CASE()` and 
+`TEST_RANGE()` are utilized in a test file untouched by preprocessing.
+
+**_IMPORTANT:_ The following new build directive macro `TEST_INCLUDE_PATH()` 
+available in Ceedling 1.0.0 is incompatible with enclosing conditional 
+compilation C preprocessing statements:**
+
+Wrapping `TEST_INCLUDE_PATH()` in conditional compilation statements 
+(e.g. `#ifdef`) will not behave as you expect. This macro is used as a marker
+for advanced abilities discovered by Ceedling parsing a test file as plain text.
+Whether or not Ceedling preprocessing is enabled, Ceedling will always discover 
+this marker macro in the plain text of a test file.
+
+Why is `TEST_INCLUDE_PATH()` incompatible with `#ifdef`? Well, it’s because of
+a cyclical dependency that cannot be resolved. In order to perform test 
+preprocessing, we need a full complement of `#include` search paths. These 
+could be provided, in part, by `TEST_INCLUDE_PATH()`. But, if we allow 
+`TEST_INCLUDE_PATH()` to be placed within conditional compilation C 
+preprocessing statements, our search paths may be different after test 
+preprocessing! The only solution is to disallow this and scan a test file as
+plain text looking for this macro at the beginning of a test build.
 
-**_NOTE:_ The following new build directive macros available in Ceedling 1.0.0
-are incompatible with enclosing conditional compilation C preprocessing 
-statements:**
-
-* `TEST_SOURCE_FILE()`
-* `TEST_INCLUDE_PATH()`
+**_Notes:_**
 
-Wrapping `TEST_SOURCE_FILE()` and `TEST_INCLUDE_PATH()` in conditional 
-compilation statements (e.g. `#ifdef`) will not behave as you expect. These 
-macros are used as markers for advanced abilities discovered by Ceedling parsing 
-a test file as plain text. Whether or not Ceedling preprocessing is enabled, 
-Ceedling will always discover these marker macros in the plain text of a test file.
+* `TEST_SOURCE_FILE()` _can_ be placed within conditional compilation
+  C preprocessing statements.
+* `TEST_INCLUDE_PATH()` & `TEST_SOURCE_FILE()` can be “hidden” from Ceedling’s
+  text scanning with traditional C comments.
 
 ### Preprocessing of your test files