ceedling 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0610e698b34fe7dc61a65a1c455e28438cbe132bea10d85634b19fc791f5a293
-  data.tar.gz: 4f9b3d43150358c366de44a33697aa58460601fe372311524a303351b43eaba4
+  metadata.gz: ea37cd2499cbbf39a49993a77cd3e1fbe6a5e1777b70b8ba4ed1fff23823a446
+  data.tar.gz: 7dabe29c6ccc55ee156da20783cae2a52496e4efcee00ded8c5259b24128c57c
 SHA512:
-  metadata.gz: acac7be5ef1b0b19eac71e189d178a39834405372ca4349cb529720bb3bc4a3fadfdbecf5e5fc462f5c72617052b3eddd0f334bf99a23a71fb576e7f247175fb
-  data.tar.gz: 9da4d2e23f1a6c45392177449d633332389093ca75804e22af4bb29d5feed971c5783296513cc4e6bf49492f337f45a154efa991829b3753aecb448959886084
+  metadata.gz: 7990a5a91fbd7eb56b476f7c71236cc1774eb914d41a24e8774ba534ef56cf29155b8edd8e3968152899c1fdbe266258fe8c7e738502b79deb78b6c405b14c2a
+  data.tar.gz: 66de8b40c53aadb9ea483dd8d2c9a2deecbc6034ca4075720ac996b77220ea542c16845f019533b825fc243a95624dd7a314b9163939c1f8b4dd0dd37a9cfce1

data/GIT_COMMIT_SHA

@@ -1 +1 @@
-13a540f
+3b30ae3

data/README.md

@@ -1,25 +1,58 @@
-Ceedling [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15117/badge)](https://www.bestpractices.dev/projects/15117) [![Docs](https://img.shields.io/badge/Docs-white?logo=materialformkdocs&link=https%3A%2F%2Fdocs.throwtheswitch.org%2FCeedling%2F)](https://docs.throwtheswitch.org/Ceedling/) [![Discourse](https://img.shields.io/badge/Discourse-purple?logo=discourse&link=https%3A%2F%2Fthrowtheswitch.discourse.group)](https://throwtheswitch.discourse.group) ![CI](https://github.com/ThrowTheSwitch/Ceedling/workflows/CI/badge.svg)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15117/badge)](https://www.bestpractices.dev/projects/15117) [![Docs](https://img.shields.io/badge/Docs-white?logo=materialformkdocs&link=https%3A%2F%2Fdocs.throwtheswitch.org%2FCeedling%2F)](https://docs.throwtheswitch.org/Ceedling/) [![Discourse](https://img.shields.io/badge/Discourse-purple?logo=discourse&link=https%3A%2F%2Fthrowtheswitch.discourse.group)](https://throwtheswitch.discourse.group) ![CI](https://github.com/ThrowTheSwitch/Ceedling/workflows/CI/badge.svg)
 ========
 
-**Ceedling 1.2.0** is the latest and greatest.
+# 🌱 Ceedling is a handy-dandy build system for C projects
+
+## Developer-friendly release _and_ test builds
 
-See [_Changelog_](docs/Changelog.md). [_Release Notes_][release-notes], 
-[_Breaking Changes_][breaking-changes], and [_Known Issues_][known-issues] are
-not yet updated.
+Ceedling can build your release artifact but is especially adept at building
+unit test suites for your C projects — even in tricky embedded systems.
 
-See [🚀 Getting Started](#-getting-started) for installation and new 
-project set up.
+⭐️ **Eager to just get going? Jump to 
+[📚 Documentation & Learning](#-documentation--learning) and
+[🚀 Getting Started](#-getting-started).**
+
+For a test suite project using the default toolchain `gcc`, Ceedling’s
+configuration file could be as simple as this:
+
+```yaml
+:project:
+  :build_root: project/build/
+
+:paths:
+  :test:
+    - tests/**
+  :source:
+    - source/**
+  :include:
+    - inc/**
+```
+
+To execute all your unit tests, you would run `ceedling test:all`. That‘s it!
+
+Ceedling works the way developers want to work. It is flexible and entirely
+command-line driven. It drives code generation and command line tools for you.
+All generated and framework code is easy to see and understand.
+
+Ceedling’s features support all types of C development from low-level embedded
+to enterprise systems. No tool is perfect, but Ceedling can do a whole lot to 
+help you and your team produce quality software.
+
+## Ceedling 1.2.2 is the latest and greatest
+
+See [_Changelog_](docs/Changelog.md), [_Release Notes_][release-notes], [_Breaking Changes_][breaking-changes], and [_Known Issues_][known-issues].
 
 **New goodies in 1.2.0:**
 * **[Delta builds][delta-builds]** have been restored after a temporary hiatus following a major refactoring for 1.0.0. A [delta build][delta-build-overview] is simply a build run that only performs regeneration, compilation, or linking as needed because of changed files. [Delta builds][delta-builds] are automatic with no configuration and complement [parallel builds][parallel-builds] introduced in 1.0.0 for build time speedups.
 * **`#include` relative paths & duplicate filename disambiguation**. Ceedling now fully supports [relative paths in `#include` directives][same-named-files] and [`TEST_SOURCE_FILE()` build directive macros][test-source-file]. Ceedling is now also able to distinguish files of the same name using paths in the preceding and [at the command line][test-path-task] to distinguish test files of the same name (e.g. `ceedling test:foo/file` vs. `ceedling test:bar/file`).
 * **Multiple file extensions per file type.** You may now provide a list of file types via [`:extensions`][extension-config] to gather files into your project’s build. For instance, the extensions `.c` and `.cc` can now both be used together to collect all source file in your project.
 * **Shuffled test order.** Ceedling now supports [Unity’s][unity-framework] randomized test case ordering (via a [`:unity` configuration setting][shuffle-tests]). [Delta builds][delta-builds] automatically adjust to always rerun test executables so test case ordering is shuffled.
-* The [`TEST_SOURCE_FILE()` build directive macro][test-source-file-subtractive] can now be used to remove source files from a test executable build. This can be handy in overriding [Ceedling’s conventions][header-source-convention] for associating source files with a test executable if your project structure does not match up with [Ceedling’s conventions][header-source-convention].
-* The [build warnings], [JUnit report], [IDE integration], [GoogleTest report], [module generator], and [dependencies] plugins all received numerous bug fixes and feature expansions.
-* [Bullseye code coverage plugin][bullseye-plugin] re-enabled and modernized (disabled since 1.0.0).
+* The **[`TEST_SOURCE_FILE()` build directive macro][test-source-file-subtractive]** can now be used to remove source files from a test executable build. This can be handy in overriding [Ceedling’s conventions][header-source-convention] for associating source files with a test executable if your project structure does not match up with Ceedling’s conventions.
+* The **new [Sanitize plugin][sanitize-plugin]** builds and runs tests with ASan, UBSan, and LeakSanitizer, naming each finding where a test fails and writing text, JSON, and SARIF reports.
+* The **[build warnings]**, **[JUnit report]**, **[IDE integration]**, **[GoogleTest report]**, **[module generator]**, and **[dependencies]** plugins all received numerous bug fixes and feature expansions.
+* **[Bullseye code coverage plugin][bullseye-plugin]** re-enabled and modernized (disabled since 1.0.0).
 * **Dedicated mocks and test runner generation build tasks.** It is now possible to run the test build pipeline only up through generating mocks or test runners without running the rest of a build using `ceedling gen:mocks:<test>` and `ceedling gen:test_runner:<test>` mirroring the convention of `test:` tasks.
-* Ceedling prerelease and release builds now automatically [generate Software Bills of Material][sbom-docs] (SBOMs) and attach them to GitHub pre/releases along with the final Ruby gem.
+* Ceedling prerelease and release builds now automatically **[generate Software Bills of Material][sbom-docs]** (SBOMs) and attach them to GitHub pre/releases along with the final Ruby gem.
 
 **Goodness introduced in 1.1.0:**
 * A [Partial][partials-docs] allows a test to mix mocked and real functions 
@@ -48,47 +81,11 @@ from the same source module in a single test file and enables testing of
 [GoogleTest report]: https://docs.throwtheswitch.org/Ceedling/1.2.0/plugins/report-tests-gtestlike-stdout/
 [module generator]: https://docs.throwtheswitch.org/Ceedling/1.2.0/plugins/module-generator/
 [dependencies]: https://docs.throwtheswitch.org/Ceedling/1.2.0/plugins/dependencies/
+[sanitize-plugin]: https://docs.throwtheswitch.org/Ceedling/1.2.0/plugins/sanitize/
 [bullseye-plugin]: https://docs.throwtheswitch.org/Ceedling/1.2.0/plugins/bullseye/
 [sbom-docs]: https://docs.throwtheswitch.org/Ceedling/latest/project/sbom/
-[partials-docs]: https://throwtheswitch.github.io/Ceedling/1.1.0/testing-guide/partials/
-[ceedling-docs-site]: https://throwtheswitch.github.io/Ceedling/
-
-# 🌱 Ceedling is a handy-dandy build system for C projects
-
-## Developer-friendly release _and_ test builds
-
-Ceedling can build your release artifact but is especially adept at building
-unit test suites for your C projects — even in tricky embedded systems.
-
-⭐️ **Eager to just get going? Jump to 
-[📚 Documentation & Learning](#-documentation--learning) and
-[🚀 Getting Started](#-getting-started).**
-
-For a test suite project using the default toolchain `gcc`, Ceedling’s
-configuration file could be as simple as this:
-
-```yaml
-:project:
-  :build_root: project/build/
-
-:paths:
-  :test:
-    - tests/**
-  :source:
-    - source/**
-  :include:
-    - inc/**
-```
-
-To execute all your unit tests, you would run `ceedling test:all`. That‘s it!
-
-Ceedling works the way developers want to work. It is flexible and entirely
-command-line driven. It drives code generation and command line tools for you.
-All generated and framework code is easy to see and understand.
-
-Ceedling’s features support all types of C development from low-level embedded
-to enterprise systems. No tool is perfect, but Ceedling can do a whole lot to 
-help you and your team produce quality software.
+[partials-docs]: https://docs.throwtheswitch.org/Ceedling/1.1.0/testing-guide/partials/
+[ceedling-docs-site]: https://docs.throwtheswitch.org/Ceedling/
 
 ## Supporting this work
 
@@ -674,11 +671,9 @@ of your choosing.
 #### Attaching a Ceedling version to your project
 
 Ceedling can be installed as a globally available Ruby gem. Ceedling can 
-also deploy all 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.
+also deploy all its guts into your project instead. Your project then keeps
+its own copy of Ceedling, Unity, and CMock, which updating your gems leaves
+alone. Ceedling itself still needs Ruby and the gems Ceedling depends on.
 
 To use Ceedling this way, tell it you want a local copy when you create
 your project:
@@ -692,6 +687,10 @@ into a new folder `vendor/` inside your project `YourNewProjectName/`.
 It will create the same simple empty directory structure for you with
 `src/` and `test/` folders as the standard `new` command.
 
+Run your project with `./ceedling` from its root (`.\ceedling.cmd` on
+Windows), or with the gem’s `ceedling` command. Either way, your project’s copy
+runs every command. The gem’s `ceedling` command hands off to it.
+
 ### Running build & plugin tasks
 
 You can view all the build and plugin tasks available to you thanks to your
@@ -731,11 +730,11 @@ If you want to force a vendored version of Ceedling inside your project to
 upgrade to match your latest gem, no problem. Just do the following…
 
 ```shell
- > ceedling upgrade --local YourNewProjectName
+ > ceedling upgrade YourProjectName
 ```
 
-Just like with the `new` command, an `upgrade` should be executed from 
-within the root directory of your project.
+`upgrade` takes the path to your project and copies the Ceedling you run
+into it, along with Unity and CMock.
 
 ### Git integration
 

data/Rakefile

@@ -523,7 +523,8 @@ task 'ci:summary' do
     jobs_path:     ENV['CI_SUMMARY_JOBS'],
     baseline_path: ENV['CI_SUMMARY_BASELINE'],
     diff_path:     ENV['CI_SUMMARY_DIFF'],
-    merge_base:    ENV['CI_SUMMARY_MERGE_BASE']
+    merge_base:    ENV['CI_SUMMARY_MERGE_BASE'],
+    todo_path:     ENV['CI_SUMMARY_RUBOCOP_TODO']
   )
 
   sha = ENV.fetch( 'CI_SUMMARY_SHA' )
@@ -948,10 +949,11 @@ namespace :docs do
     end
 
     namespace :release do
-      desc "Deploy release docs to Github Pages without and set it as 'latest'"
+      desc "Deploy release docs to Github Pages and set it as 'latest'"
       task :latest, [:version] => [:snapshot] do |t, args|
         version = args[:version] || raise("Version required: rake docs:deploy:release:latest[#.#.#]")
-        venv_sh "mike deploy --push #{version} latest"
+        # --update-aliases moves 'latest' off whichever version currently holds it
+        venv_sh "mike deploy --push --update-aliases #{version} latest"
       end
     end
   end

data/assets/features/ceedling

@@ -6,4 +6,4 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-ruby vendor/ceedling/bin/ceedling $*
+ruby vendor/ceedling/bin/ceedling "$@"

data/assets/fixtures/test_source_file_duplicate_basenames/test_calc_typo.c

@@ -0,0 +1,14 @@
+#include "unity.h"
+
+// Misspells alpha/calc.c on purpose, so no source file matches this entry.
+TEST_SOURCE_FILE("alpha/clac.c")
+
+extern int calc_value(void);
+
+void setUp(void) {}
+void tearDown(void) {}
+
+void test_calc_value_from_a_misspelled_source(void)
+{
+  TEST_ASSERT_EQUAL(111, calc_value());
+}

data/assets/fixtures/tests_with_duplicate_test_names/test_foo.c

@@ -0,0 +1,21 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include "unity.h"
+
+void setUp(void)
+{
+}
+
+void tearDown(void)
+{
+}
+
+void test_this_is_the_root_directory_test_foo(void)
+{
+  TEST_ASSERT_EQUAL(1, 1);
+}

data/bin/actionator.rb

@@ -36,6 +36,9 @@ class Actionator
 
   JUNK_FILE_EXCLUDE_REGEX = /(\.DS_Store)|(thumbs\.db)/
 
+  # A file or directory named with a leading dot stays out of a copy, and is never entered
+  HIDDEN = ->( name ) { name.start_with?( '.' ) }
+
   BOLD  = "\e[1m"
   CLEAR = "\e[0m"
 
@@ -93,19 +96,15 @@ class Actionator
   def copy_directory(source, destination, force: false, verbose: true,
                      exclude_pattern: JUNK_FILE_EXCLUDE_REGEX)
     # Trailing separators arrive from the vendored component paths in cli_helper.
-    # They would otherwise survive into the glob and into the rebasing below.
+    # They would otherwise survive into the rebasing below.
     src  = resolve_source( source ).sub( /\/+\z/, '' )
     dest = resolve_destination( destination )
 
     # Thor reported the destination directory itself ahead of its contents.
     make_directory( dest, verbose: verbose )
 
-    # FileWrapper#directory_listing does not escape glob metacharacters, and a
-    # Ceedling install path can contain them. See issue #104.
-    listing = @file_wrapper.directory_listing( File.join( escape_globs( src ), '**', '*' ) )
-
-    listing.each do |entry|
-      next if @file_wrapper.directory?( entry )
+    # The listing holds regular files only, in sorted path order
+    @file_wrapper.tree_files( src, skip: HIDDEN ).each do |entry|
       next if entry.match( exclude_pattern )
 
       copy_file( entry, rebase( entry, src, dest ), force: force, verbose: verbose )
@@ -198,11 +197,6 @@ class Actionator
   end
 
 
-  def escape_globs(path)
-    return path.gsub( /[*?{}\[\]]/ ) { |char| '\\' + char }
-  end
-
-
   def status(verb, path, verbose)
     return unless verbose
 

data/bin/app_cfg.rb

@@ -12,12 +12,21 @@ require "io/console"
 
 class CeedlingAppConfig
 
-  def initialize()
+  def initialize(argv: [])
     # Default installation location determined from the location of this file
     ceedling_root_path = File.join( File.dirname( __FILE__ ), '..' )
 
     # Create internal hash of needed values
     @app_cfg = {
+      # The command line as given, before Thor consumes it, for handing off to another installation
+      :argv => argv.dup().freeze(),
+
+      # Markers from a launcher that handed off to this process, or nil
+      :handoff => nil,
+
+      # Base path of the installation running this launcher, unchanged by #set_paths
+      :launcher_root_path => File.expand_path( ceedling_root_path ),
+
       # Base path of any Ceedling installation
       :ceedling_root_path => '',
 
@@ -61,6 +70,11 @@ class CeedlingAppConfig
       # Default to task categry other than build/plugin tasks
       :build_tasks? => false,
 
+      # Whether the tasks build tests (test:, gcov:, ...) or a release, which decides what
+      # build/vendor needs
+      :test_build_tasks? => false,
+      :release_build_tasks? => false,
+
       # Default to `exit(1)` upon failing test cases
       :tests_graceful_fail? => false,
 
@@ -78,6 +92,10 @@ class CeedlingAppConfig
     end
   end 
 
+  def set_handoff(markers)
+    @app_cfg[:handoff] = markers
+  end
+
   def set_project_config(config)
     @app_cfg[:project_config] = config
   end
@@ -106,6 +124,14 @@ class CeedlingAppConfig
     @app_cfg[:build_tasks?] = enable
   end
 
+  def set_test_build_tasks(enable)
+    @app_cfg[:test_build_tasks?] = enable
+  end
+
+  def set_release_build_tasks(enable)
+    @app_cfg[:release_build_tasks?] = enable
+  end
+
   def set_tests_graceful_fail(enable)
     @app_cfg[:tests_graceful_fail?] = enable
   end
@@ -129,6 +155,14 @@ class CeedlingAppConfig
     return @app_cfg[:build_tasks?]
   end
 
+  def test_build_tasks?()
+    return @app_cfg[:test_build_tasks?]
+  end
+
+  def release_build_tasks?()
+    return @app_cfg[:release_build_tasks?]
+  end
+
   def tests_graceful_fail?()
     return @app_cfg[:tests_graceful_fail?]
   end

data/bin/ceedling

@@ -16,11 +16,17 @@ $LOAD_PATH.unshift( ceedling_bin_path )
 
 # Pull in our startup configuration code in bin/
 require 'app_cfg'
-CEEDLING_APPCFG = CeedlingAppConfig.new()
+# The command line as given, before Thor consumes it
+CEEDLING_APPCFG = CeedlingAppConfig.new( argv: ARGV )
 
 # Add load paths for `require 'ceedling/*'` statements in bin/ code
 $LOAD_PATH.unshift( CEEDLING_APPCFG[:ceedling_lib_base_path] )
 
+# A launcher that handed off to this process left markers. Taking them here keeps any
+# subprocess of this build from inheriting them.
+require 'ceedling/handoff'
+CEEDLING_APPCFG.set_handoff( Handoff.take_markers( ENV ) )
+
 # Assumed installed via Ceedling gem dependencies
 require 'constructor'
 # Commonly needed modules
@@ -60,12 +66,16 @@ begin
   #  5. Remove all paths added to $LOAD_PATH
   #     (Main application will restore certain paths -- possibly updated by :which_ceedling)
   $LOAD_PATH.unshift(
-    # lib/ceedling for base of any require statements
-    CEEDLING_APPCFG[:ceedling_lib_path],
     # Add lib/ceedling/config to load configuration handling utils
     File.join( CEEDLING_APPCFG[:ceedling_lib_path], 'config' ),
+    # Add lib/ceedling/filesystem to load file and path handling code
+    File.join( CEEDLING_APPCFG[:ceedling_lib_path], 'filesystem' ),
     # Add lib/ceedling/rake_app to load Rake application handling code
     File.join( CEEDLING_APPCFG[:ceedling_lib_path], 'rake_app' ),
+    # lib/ceedling for base of any require statements. It follows its subdirectories, so a
+    # file an older Ceedling left directly in lib/ceedling/ never stands in for one that has
+    # moved below it.
+    CEEDLING_APPCFG[:ceedling_lib_path],
     # DIY vendored path
     diy_vendor_path
   )

data/bin/cli.rb

@@ -603,13 +603,16 @@ module CeedlingTasks
     ) )
     def docs(dest=nil)
       _dest = dest.dup() if !dest.nil?
-      @handler.docs( @app_cfg, _dest )
+      @handler.docs( ENV, @app_cfg, _dest )
     end
     # simplecov:enable line
 
 
     # simplecov:disable line
     desc "version", "Display version details of Ceedling components"
+    method_option :project, :type => :string, :default => nil, :lazy_default => CLI_MISSING_PARAMETER_DEFAULT, :aliases => ['-p'], :desc => DOC_PROJECT_FLAG
+    method_option :mixin, :type => :string, :default => [], :repeatable => true, :aliases => ['-m'], :desc => DOC_MIXIN_FLAG
+    method_option :debug, :type => :boolean, :default => false, :hide => true
     long_desc( CEEDLING_HANDOFF_OBJECTS[:loginator].sanitize(
       <<-LONGDESC
       `ceedling version` displays the version details of Ceedling and its supporting
@@ -620,9 +623,9 @@ module CeedlingTasks
       command line. The application runs your build and plugin tasks. The
       launcher hands off to the application. The two components are not
       necessarily from the same installation or of the same version. Local
-      vendoring options, the WHICH_CEEDLING environment variable, and more can
-      cause the Ceedling launcher to load a Ceedling application that is run
-      from a different path than the launcher.
+      vendoring options, the WHICH_CEEDLING environment variable, your project
+      configuration's :project ↳ :which_ceedling, and more can select a Ceedling
+      application at a different path than the launcher.
 
       If the launcher and application are from different locations, the version
       output lists details for both. If they are from the same location, only a 
@@ -630,14 +633,30 @@ module CeedlingTasks
 
       NOTES:
 
-      • `version` does not load your project file.
+      • `version` reads your project file, when one is available, to find the
+      Ceedling application it selects. A project file that cannot be loaded is
+      skipped unless you name it with --project.
+
+      • #{LONGDOC_MIXIN_FLAG}
 
       • The build frameworks Unity, CMock, and CException are always sourced from
       the Ceedling application.
       LONGDESC
     ) )
     def version()
-      @handler.version( ENV, @app_cfg )
+      @handler.validate_string_param(
+        options[:project],
+        CLI_MISSING_PARAMETER_DEFAULT,
+        "--project is missing a required filepath parameter"
+      )
+
+      # Get an unfrozen copy so we can add / modify
+      _options = options.dup()
+
+      _options[:verbosity] = Verbosity::ERRORS
+      CliOptionsTransform.apply_debug_flag( _options )
+
+      @handler.version( ENV, @app_cfg, _options )
     end
     # simplecov:enable line