ceedling 1.2.0 → 1.2.2

data/bin/cli_handler.rb

@@ -10,12 +10,13 @@ require 'mixins' # Built-in Mixins
 require 'ceedling/constants' # From Ceedling application
 require 'ceedling/rake_app/rake_task_registry' # From Ceedling application
 require 'versionator' # Outside DIY context
+require 'ceedling/installation'
 
 class CliHandler
 
   DOCS_SUBDIR = 'docs'
 
-  constructor :composinator, :projectinator, :cli_helper, :path_validator, :rake_task_registry, :actionator, :loginator
+  constructor :composinator, :projectinator, :cli_helper, :path_validator, :rake_task_registry, :actionator, :launchinator, :loginator
 
   # Override to prevent exception handling from walking & stringifying the object variables.
   # Object variables are lengthy and produce a flood of output.
@@ -44,6 +45,23 @@ class CliHandler
     verbosity = @helper.set_verbosity( options[:verbosity] )
     @helper.set_ruby_replacement( options[:ruby_replacement] )
 
+    # Help comes from the installation the project (if any) selects, so hand off before printing any
+    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
+    config, rakefile_path = nil, nil
+    if @projectinator.config_available?( filepath:options[:project], env:env )
+      begin
+        # Silent Ceedling loading unless debug verbosity
+        config, rakefile_path = load_project_and_launch( env:env, app_cfg:app_cfg, options:options, silent:!(verbosity == Verbosity::DEBUG) )
+      rescue StandardError
+        # Help for one command needs no project, so a project that fails to load does not block it
+        raise if command.nil?
+
+        @launchinator.launch( env:env, app_cfg:app_cfg, config:{} )
+      end
+    else
+      @launchinator.launch( env:env, app_cfg:app_cfg, config:{} )
+    end
+
     # If help requested for a command, show it and skip listing build tasks
     if !command.nil?
       # Block handler
@@ -55,16 +73,8 @@ class CliHandler
     yield( command ) if block_given?
 
     # If project configuration is available, also display Rake tasks
-    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
-    if @projectinator.config_available?( filepath:options[:project], env:env )
-      list_rake_tasks(
-        env:env,
-        app_cfg: app_cfg,
-        filepath: options[:project],
-        mixins: options[:mixin],
-        # Silent Ceedling loading unless debug verbosity
-        silent: !(verbosity == Verbosity::DEBUG)
-      )
+    if !config.nil?
+      list_rake_tasks( app_cfg:app_cfg, config:config, rakefile_path:rakefile_path )
     else
       # If no project configuration is available then note why we aren't displaying more
       msg = "Run help commands in a directory with a project file to list additional options\n\n"
@@ -81,13 +91,18 @@ class CliHandler
   def rake_help(env:, app_cfg:)
     @helper.set_verbosity( Verbosity::ERRORS )
 
-    list_rake_tasks( env:env, app_cfg:app_cfg )
+    config, rakefile_path = load_project_and_launch( env:env, app_cfg:app_cfg, options:{:project => nil, :mixin => []} )
+
+    list_rake_tasks( app_cfg:app_cfg, config:config, rakefile_path:rakefile_path )
   end
 
 
   def new_project(env, app_cfg, ceedling_tag, options, dest)
     @helper.set_verbosity( options[:verbosity] )
 
+    # The selected installation creates the project with its own code and contents
+    @launchinator.launch( env:env, app_cfg:app_cfg )
+
     dest = @path_validator.standardize_paths( dest ).first
 
     # If destination is nil, assume it's the working directory
@@ -101,9 +116,6 @@ class CliHandler
       raise msg
     end unless options[:force]
 
-    # Update app_cfg paths (ignore return values)
-    @helper.which_ceedling?( env:env, app_cfg:app_cfg )
-
     # Source paths for project tasks resolve in relation to this path
     @actions.source_root = app_cfg[:ceedling_root_path]
 
@@ -143,18 +155,21 @@ class CliHandler
 
     path, options[:project] = @path_validator.standardize_paths( path, options[:project] )
 
+    # The source is the Ceedling running or WHICH_CEEDLING. A detected vendor/ceedling/ is
+    # likely the very copy being replaced. A source that is that copy is refused before any
+    # hand-off, since an older copy would delete itself.
+    source = @launchinator.resolve( env:env, app_cfg:app_cfg, detect_vendor:false )
+    if source == Installation.new( File.join( path, 'vendor', 'ceedling' ) )
+      raise CeedlingException.new( "Cannot upgrade #{source.root}/ from itself. Run `upgrade` with the Ceedling to upgrade to, or set WHICH_CEEDLING." )
+    end
+    @launchinator.proceed( target:source, app_cfg:app_cfg )
+
     # Check for existing project
     if !@helper.project_exists?( path, :&, options[:project], 'vendor/ceedling/lib/version.rb' )
       msg = "Could not find an existing project at #{path}/."
       raise msg
     end
 
-    which, _ = @helper.which_ceedling?( env:env, app_cfg:app_cfg )
-    if (which == :gem)
-      msg = "Project configuration specifies the Ceedling gem, not vendored Ceedling"
-      @loginator.console( msg, LogLabels::NOTICE )
-    end
-
     # Source paths for project tasks resolve in relation to this path
     @actions.source_root = app_cfg[:ceedling_root_path]
 
@@ -163,12 +178,11 @@ class CliHandler
     @actions.remove_directory( vendor_path )
     @helper.vendor_tools( app_cfg[:ceedling_root_path], path )
 
-    # Recreate documentation if we find docs/ subdirectory
-    docs_path = File.join( path, 'docs' )
-    founds_docs = @helper.project_exists?( path, :&, File.join( 'docs', 'CeedlingPacket.md' ) )
-    if founds_docs
-      @actions.remove_directory( docs_path )
-      @helper.copy_docs( app_cfg[:ceedling_root_path], File.join( path, DOCS_SUBDIR ) )
+    # Refresh documentation an export wrote, leaving the project's own files in docs/
+    docs_path = File.join( path, DOCS_SUBDIR )
+    if @helper.exported_docs?( docs_path )
+      @helper.remove_exported_docs( docs_path, keep_bundle: !@helper.docs_bundle?( app_cfg[:ceedling_root_path] ) )
+      @helper.copy_docs( app_cfg[:ceedling_root_path], docs_path )
     end
 
     @loginator.console( "\nUpgraded project at #{path}/\n", LogLabels::TITLE )
@@ -182,10 +196,9 @@ class CliHandler
     @helper.set_verbosity( _verbosity, override: false )
     @helper.set_ruby_replacement( options[:ruby_replacement] )
 
-    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
     options[:logfile] = @path_validator.standardize_paths( options[:logfile] ).first
 
-    _, config = @composinator.loadinate( builtin_load_paths:BUILTIN_MIXIN_LOAD_PATHS, filepath:options[:project], mixins:options[:mixin], env:env )
+    config, rakefile_path = load_project_and_launch( env:env, app_cfg:app_cfg, options:options )
 
     @cli_helper.log_project_name( config )
 
@@ -234,12 +247,16 @@ class CliHandler
     )
 
     # Look up if any tasks we will execute are build tasks
-    build_tasks = @helper.build_task?( tasks: (tasks.empty? ? default_tasks : tasks ) )
+    requested = (tasks.empty? ? default_tasks : tasks)
+    build_tasks = @helper.build_task?( tasks: requested )
 
     # Enable setup / operations duration logging in Rake context if build tasks are being invoked
     app_cfg.set_build_tasks( build_tasks )
 
-    _, path = @helper.which_ceedling?( env:env, config:config, app_cfg:app_cfg )
+    # Only a build populates build/vendor, so a command that only reads the project leaves a
+    # concurrent build's vendored files alone
+    app_cfg.set_test_build_tasks( @helper.test_task?( tasks: requested ) )
+    app_cfg.set_release_build_tasks( @helper.release_task?( tasks: requested ) )
 
     # Log Ceedling Application version information
     _version = Versionator.new(
@@ -266,7 +283,7 @@ class CliHandler
 
     @helper.load_ceedling(
       config: config,
-      rakefile_path: path,
+      rakefile_path: rakefile_path,
       default_tasks: default_tasks
     )
 
@@ -283,9 +300,9 @@ class CliHandler
     @helper.set_ruby_replacement( options[:ruby_replacement] )
 
     filepath = @path_validator.standardize_paths( filepath ).first
-    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
 
-    _, config = @composinator.loadinate( builtin_load_paths:BUILTIN_MIXIN_LOAD_PATHS, filepath:options[:project], mixins:options[:mixin], env:env )
+    # Even without --app, the selected installation merges the configuration by its own rules
+    config, rakefile_path = load_project_and_launch( env:env, app_cfg:app_cfg, options:options )
 
     # A nil filepath means --stdout was set -- the YAML itself is the only thing
     # that may reach stdout in that case, for a consuming tool to parse cleanly,
@@ -304,11 +321,9 @@ class CliHandler
         app_cfg.set_project_config( config )
         app_cfg.set_logging_path( @helper.process_logging_path( config ) )
 
-        _, path = @helper.which_ceedling?( env:env, config:config, app_cfg:app_cfg )
-
         config = @helper.load_ceedling(
           config: config,
-          rakefile_path: path,
+          rakefile_path: rakefile_path,
           default_tasks: default_tasks
         )
       else
@@ -327,9 +342,7 @@ class CliHandler
     @helper.set_verbosity( options[:verbosity] )
     @helper.set_ruby_replacement( options[:ruby_replacement] )
 
-    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
-
-    _, config = @composinator.loadinate( builtin_load_paths:BUILTIN_MIXIN_LOAD_PATHS, filepath:options[:project], mixins:options[:mixin], env:env )
+    config, rakefile_path = load_project_and_launch( env:env, app_cfg:app_cfg, options:options )
 
     @cli_helper.log_project_name( config )
 
@@ -340,12 +353,10 @@ class CliHandler
     app_cfg.set_logging_path( @helper.process_logging_path( config ) )
     app_cfg.set_log_filepath( '' )
 
-    _, path = @helper.which_ceedling?( env:env, config:config, app_cfg:app_cfg )
-
     begin
       @helper.load_ceedling(
         config: config,
-        rakefile_path: path,
+        rakefile_path: rakefile_path,
         default_tasks: default_tasks
       )
     ensure
@@ -358,9 +369,7 @@ class CliHandler
     @helper.set_verbosity( options[:verbosity] )
     @helper.set_ruby_replacement( options[:ruby_replacement] )
 
-    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
-
-    _, config = @composinator.loadinate( builtin_load_paths:BUILTIN_MIXIN_LOAD_PATHS, filepath:options[:project], mixins:options[:mixin], env:env )
+    config, rakefile_path = load_project_and_launch( env:env, app_cfg:app_cfg, options:options )
 
     @cli_helper.console_project_name( config )
 
@@ -368,11 +377,9 @@ class CliHandler
     app_cfg.set_project_config( config )
     app_cfg.set_logging_path( @helper.process_logging_path( config ) )
 
-    _, path = @helper.which_ceedling?( env:env, config:config, app_cfg:app_cfg )
-
     config = @helper.load_ceedling(
       config: config,
-      rakefile_path: path
+      rakefile_path: rakefile_path
     )
 
     env_list = []
@@ -411,8 +418,8 @@ class CliHandler
   def list_examples(env, app_cfg, options)
     @helper.set_verbosity( options[:verbosity] )
 
-    # Process which_ceedling for app_cfg modifications but ignore return values
-    @helper.which_ceedling?( env:env, app_cfg:app_cfg )
+    # The selected installation lists its own examples
+    @launchinator.launch( env:env, app_cfg:app_cfg )
 
     examples = @helper.lookup_example_projects( app_cfg[:ceedling_examples_path] )
 
@@ -437,10 +444,10 @@ class CliHandler
   def create_example(env, app_cfg, options, name, dest)
     @helper.set_verbosity( options[:verbosity] )
 
-    dest = @path_validator.standardize_paths( dest ).first
+    # The selected installation creates the example with its own code and contents
+    @launchinator.launch( env:env, app_cfg:app_cfg )
 
-    # Process which_ceedling for app_cfg modifications but ignore return values
-    @helper.which_ceedling?( env:env, app_cfg:app_cfg )
+    dest = @path_validator.standardize_paths( dest ).first
 
     examples = @helper.lookup_example_projects( app_cfg[:ceedling_examples_path] )
 
@@ -485,7 +492,19 @@ class CliHandler
   end
 
 
-  def docs(app_cfg, dest)
+  def docs(env, app_cfg, dest)
+    # The selected installation exports its own documentation, if it has any to export
+    target = @launchinator.resolve( env:env, app_cfg:app_cfg )
+    launcher = Installation.new( app_cfg[:launcher_root_path] )
+    if target == launcher or @helper.docs_bundle?( target.root )
+      @launchinator.proceed( target:target, app_cfg:app_cfg )
+    else
+      app_cfg.set_paths( launcher.root )
+      msg = "#{target.describe()} holds no documentation bundle to export. " +
+            "Exporting the documentation of #{launcher.describe( 'Ceedling launcher' )} instead."
+      @loginator.console( msg, LogLabels::NOTICE )
+    end
+
     # File operations require an anchored source root
     @actions.source_root = app_cfg[:ceedling_root_path]
 
@@ -497,16 +516,17 @@ class CliHandler
   end
 
 
-  def version(env, app_cfg)
+  def version(env, app_cfg, options={})
     # Versionator is not needed to persist. So, it's not built in the DIY collection.
 
-    @helper.set_verbosity( Verbosity::ERRORS )
+    @helper.set_verbosity( options[:verbosity] || Verbosity::ERRORS )
 
     # Ceedling bootloader
-    launcher = Versionator.new( app_cfg[:ceedling_root_path] )
+    launcher = Versionator.new( app_cfg[:launcher_root_path] )
 
-    # This call updates Ceedling paths in app_cfg if which Ceedling has been modified
-    @helper.which_ceedling?( env:env, app_cfg:app_cfg )
+    # This call updates Ceedling paths in app_cfg if the project or environment selects another Ceedling
+    config = version_project_config( env, options )
+    @launchinator.resolve( env:env, app_cfg:app_cfg, config:config )
 
     # Ceedling application
     application = @helper.manufacture_app_version( app_cfg )
@@ -515,7 +535,7 @@ class CliHandler
     ceedling = nil
 
     # A simple Ceedling version block because launcher and application are the same
-    if launcher.ceedling_install_path == application.ceedling_install_path
+    if Installation.new( launcher.ceedling_install_path ) == Installation.new( application.ceedling_install_path )
       ceedling = <<~CEEDLING
       Ceedling => #{application.ceedling_build}
       ----------------------
@@ -560,6 +580,25 @@ class CliHandler
 
   private
 
+  # The project configuration `version` resolves which Ceedling from. A --project or
+  # --mixin the user names must load. The default project file is read only when it
+  # loads cleanly, so `version` still answers for a broken or absent project.
+  def version_project_config(env, options)
+    project, mixins = standardize_project_and_mixins( options[:project], options[:mixin] || [] )
+    explicit = !project.nil? || !mixins.empty?
+
+    return {} if !explicit and !@projectinator.config_available?( env:env )
+
+    begin
+      _, config = @composinator.loadinate( builtin_load_paths:BUILTIN_MIXIN_LOAD_PATHS, filepath:project, mixins:mixins, env:env, silent:true )
+    rescue StandardError
+      raise if explicit
+      config = {}
+    end
+
+    return config
+  end
+
   # Standardizes a project filepath and a mixins list together. PathValidator's
   # standardize_paths() returns new values rather than updating its arguments in
   # place, so the mixins list can't just be passed through it directly -- inline
@@ -580,25 +619,32 @@ class CliHandler
     return _project, _mixins
   end
 
-  def list_rake_tasks(env:, app_cfg:, filepath:nil, mixins:[], silent:false)
-    _, config = 
-      @composinator.loadinate(
-        builtin_load_paths:BUILTIN_MIXIN_LOAD_PATHS,
-        filepath: filepath,
-        mixins: mixins,
-        env: env,
-        silent: silent
-      )
+  # Loads the project configuration, then runs this command in the installation it selects.
+  # Returns the configuration and the rakefile to load, unless another installation took over.
+  def load_project_and_launch(env:, app_cfg:, options:, silent:false)
+    options[:project], options[:mixin] = standardize_project_and_mixins( options[:project], options[:mixin] )
 
+    _, config = @composinator.loadinate(
+      builtin_load_paths: BUILTIN_MIXIN_LOAD_PATHS,
+      filepath: options[:project],
+      mixins: options[:mixin],
+      env: env,
+      silent: silent
+    )
+
+    rakefile_path = @launchinator.launch( env:env, app_cfg:app_cfg, config:config )
+
+    return config, rakefile_path
+  end
+
+  def list_rake_tasks(app_cfg:, config:, rakefile_path:)
     # Save reference to loaded configuration
     app_cfg.set_project_config( config )
     app_cfg.set_logging_path( @helper.process_logging_path( config ) )
 
-    _, path = @helper.which_ceedling?( env:env, config:config, app_cfg:app_cfg )
-
     @helper.load_ceedling(
       config: config,
-      rakefile_path: path,
+      rakefile_path: rakefile_path,
       default_tasks: app_cfg[:default_tasks]
     )
 

data/bin/cli_helper.rb

@@ -11,10 +11,24 @@ require 'app_cfg'
 require 'ceedling/constants'
 require 'ceedling/exceptions'
 require 'ceedling/rake_app/rakefile_component_resolver'
+require 'ceedling/filesystem/project_paths'
+require 'ceedling/config/build_root_policy'
 require 'versionator' # Outside DIY context
 
 class CliHelper
 
+  # Where a documentation export writes the HTML bundle, within a project's docs/
+  DOCS_BUNDLE_DIR = 'ceedling'
+
+  # Directories a documentation export writes into a project's docs/, beside Ceedling's license
+  EXPORTED_DOCS_DIRS = [DOCS_BUNDLE_DIR, 'unity', 'cmock', 'c_exception'].freeze
+
+  # What a 1.0.x export also wrote into docs/: Ceedling's own pages, and its plugins' pages
+  LEGACY_EXPORTED_DOCS = %w[
+    BreakingChanges.md CODE_OF_CONDUCT.md CONTRIBUTING.md CeedlingPacket.md CeedlingUpgrade.md
+    Changelog.md PluginDevelopmentGuide.md ReleaseNotes.md ThrowTheSwitchCodingStandard.md plugins
+  ].freeze
+
   constructor :file_wrapper, :actionator, :config_walkinator, :path_validator, :rake_task_registry, :loginator, :reportinator, :system_wrapper, :ruby_expandinator
 
   def setup
@@ -106,84 +120,12 @@ class CliHelper
   end
 
 
-  # Returns two value: (1) symbol :gem or :path and (2) path for Ceedling installation
-  def which_ceedling?(env:, config:{}, app_cfg:)
-    # Determine which Ceedling we're running (in priority)
-    #  1. If there's an environment variable set, validate it, and return :gem or a path
-    #  2. If :project ↳ :which_ceedling exists in the config, validate it, and return :gem or a path
-    #  3. If there's a vendor/ceedling/ path in our working directory, return it as a path
-    #  4. If nothing is set, default to :gem and return it
-    #  5. Update app_cfg paths if not the gem
-
-    # Nil for prioritized case checking logic blocks that follow
-    which_ceedling = nil
-
-    # Environment variable
-    if !env['WHICH_CEEDLING'].nil?
-      @loginator.console( " > Set which Ceedling using environment variable WHICH_CEEDLING" ) 
-      which_ceedling = env['WHICH_CEEDLING'].strip()
-      which_ceedling = :gem if (which_ceedling.casecmp( 'gem' ) == 0)
-    end
-
-    # Configuration file
-    if which_ceedling.nil?
-      value, _ = @config_walkinator.fetch_value( :project, :which_ceedling, hash:config )
-      if !value.nil?
-        which_ceedling = value.strip()
-        @loginator.lazy( Verbosity::OBNOXIOUS ) { " > Set which Ceedling from config :project ↳ :which_ceedling => #{which_ceedling}" }
-        which_ceedling = :gem if (which_ceedling.casecmp( 'gem' ) == 0)
-      end
-    end
-
-    # Working directory
-    if which_ceedling.nil?
-      if @file_wrapper.directory?( 'vendor/ceedling' )
-        which_ceedling = 'vendor/ceedling'
-        @loginator.log( " > Set which Ceedling to be vendored installation", Verbosity::OBNOXIOUS )
-      end
-    end
-
-    # Default to gem
-    if which_ceedling.nil?
-      which_ceedling = :gem
-      @loginator.log( " > Defaulting to running Ceedling from Gem", Verbosity::OBNOXIOUS )
-    end
-
-    # If we're launching from the gem, return :gem and initial Rakefile path
-    if which_ceedling == :gem
-      @loginator.log( " > Launching Ceedling from #{app_cfg[:ceedling_root_path]}/", Verbosity::OBNOXIOUS )
-      return which_ceedling, app_cfg[:ceedling_rakefile_filepath]
-    end
-
-    # Otherwise, handle which_ceedling as a base path
-    ceedling_path = which_ceedling.dup()
-    @path_validator.standardize_paths( ceedling_path )
-    if !@file_wrapper.directory?( ceedling_path )
-      raise "Configured Ceedling launch path #{ceedling_path}/ does not exist"
-    end
-
-    # Update Ceedling installation paths
-    app_cfg.set_paths( ceedling_path )
-
-    # Check updated Ceedling paths
-    if !@file_wrapper.exist?( app_cfg[:ceedling_rakefile_filepath] )
-      raise "Configured Ceedling launch path #{ceedling_path}/ contains no Ceedling installation"
-    end
-
-    # Update variable to full application start path
-    ceedling_path = app_cfg[:ceedling_rakefile_filepath]
-    
-    @loginator.log( " > Launching Ceedling from #{app_cfg[:ceedling_root_path]}/", Verbosity::OBNOXIOUS )
-
-    return :path, ceedling_path
-  end
-
-
   def build_rake_task_registry(config:)
     paths = RakefileComponentResolver.resolve(
       config,
       CEEDLING_APPCFG[:ceedling_lib_path],
-      CEEDLING_APPCFG[:ceedling_plugins_path]
+      CEEDLING_APPCFG[:ceedling_plugins_path],
+      expand: ->(path) { @ruby_expandinator.expand( path, source: ":plugins ↳ :load_paths" ) }
     )
 
     @registry.register_test_tasks( paths )
@@ -276,6 +218,11 @@ class CliHelper
 
     return '' if build_root.nil?
 
+    # Read as configuration reads it, after inline Ruby string expansion. One that expands to
+    # nothing would put the logs at the filesystem root, so it is refused here already.
+    build_root = ProjectPaths.standardize( @ruby_expandinator.expand( build_root.to_s, source: ':project ↳ :build_root' ) )
+    raise CeedlingException.new( BuildRootPolicy.message( build_root, 'names no directory' ) ) if build_root.empty?
+
     return File.join( build_root, DEFAULT_BUILD_LOGS_PATH )
   end
 
@@ -329,6 +276,11 @@ class CliHelper
   end
 
 
+  def release_task?(tasks:)
+    return tasks.any? { |task| @registry.task_is?( task, RakeTaskRegistry::TAG_RELEASE ) }
+  end
+
+
   def print_rake_tasks()
     # This all required digging into Rake internals a bit.
 
@@ -486,7 +438,7 @@ class CliHelper
 
 
   def copy_docs(ceedling_root, dest)
-    docs_path_ceedling = File.join( dest, 'ceedling' )
+    docs_path_ceedling = File.join( dest, DOCS_BUNDLE_DIR )
 
     # Hash that will hold documentation copy paths
     #  - Key: (modified) destination documentation path
@@ -532,9 +484,8 @@ class CliHelper
     end
 
     # If present copy internl HTML documentation bundle (site-local/) to docs/ceedling/
-    site_local_path = File.join( ceedling_root, DOCS_SITE_LOCAL_PATH )
-    if @file_wrapper.directory?( site_local_path )
-      @actions.copy_directory( site_local_path, docs_path_ceedling, force: true )
+    if docs_bundle?( ceedling_root )
+      @actions.copy_directory( File.join( ceedling_root, DOCS_SITE_LOCAL_PATH ), docs_path_ceedling, force: true )
     else
       @loginator.console( "Internal HTML documentation bundle not found", LogLabels::WARNING )
       return
@@ -551,6 +502,32 @@ class CliHelper
   end
 
 
+  # Whether an installation holds the HTML documentation bundle. A `--local` copy carries none.
+  def docs_bundle?(ceedling_root)
+    return @file_wrapper.directory?( File.join( ceedling_root, DOCS_SITE_LOCAL_PATH ) )
+  end
+
+
+  # Whether a project's docs/ holds documentation an export wrote, in the layout of 1.1.0
+  # and later or of 1.0.x
+  def exported_docs?(docs_path)
+    return (EXPORTED_DOCS_DIRS + ['CeedlingPacket.md']).any? { |entry| @file_wrapper.exist?( File.join( docs_path, entry ) ) }
+  end
+
+
+  # Removes what an export wrote into a project's docs/, leaving everything else. An HTML
+  # bundle the source cannot replace is kept. The export overwrites its own license, so a
+  # license file here, which may be the project's, stays.
+  def remove_exported_docs(docs_path, keep_bundle:)
+    entries = EXPORTED_DOCS_DIRS + LEGACY_EXPORTED_DOCS
+    entries -= [DOCS_BUNDLE_DIR] if keep_bundle
+
+    entries.map { |entry| File.join( docs_path, entry ) }.each do |path|
+      @actions.remove_directory( path ) if @file_wrapper.exist?( path )
+    end
+  end
+
+
   def vendor_tools(ceedling_root, dest)
     vendor_path = File.join( dest, 'vendor', 'ceedling' )
 
@@ -575,6 +552,7 @@ class CliHelper
       'vendor/diy/lib/',         
       'vendor/unity/auto/',     
       'vendor/unity/src/',      
+      'vendor/unity/test/targets/', # Built-in mixins, which the vendored launcher validates
     ]
 
     # Copy necessary subcomponent dirs into project

data/bin/installation_selector.rb

@@ -0,0 +1,81 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/constants'
+require 'ceedling/installation'
+
+# Decides which Ceedling installation runs a command, and points app_cfg's paths at it
+class InstallationSelector
+
+  VENDOR_PATH = 'vendor/ceedling'
+
+  constructor :file_wrapper, :config_walkinator, :path_validator, :loginator
+
+  # Precedence:
+  #  1. The WHICH_CEEDLING environment variable
+  #  2. :project ↳ :which_ceedling in the configuration
+  #  3. A vendor/ceedling/ directory in the working directory, unless detect_vendor is off
+  #  4. The launcher's own installation
+  # Each is a path to an installation or `gem`, meaning the launcher's own.
+  def select(env:, app_cfg:, config: {}, detect_vendor: true)
+    which = from_environment( env ) || from_config( config )
+    which ||= from_vendor_directory() if detect_vendor
+
+    if which.nil? or which.casecmp?( 'gem' )
+      @loginator.log( " > Defaulting to running Ceedling from Gem", Verbosity::OBNOXIOUS ) if which.nil?
+      return use( app_cfg[:launcher_root_path], app_cfg )
+    end
+
+    return use( validate( which ), app_cfg )
+  end
+
+  private
+
+  def from_environment(env)
+    return nil if env['WHICH_CEEDLING'].nil?
+
+    @loginator.log( " > Set which Ceedling using environment variable WHICH_CEEDLING", Verbosity::OBNOXIOUS )
+    return env['WHICH_CEEDLING'].strip()
+  end
+
+  def from_config(config)
+    value, _ = @config_walkinator.fetch_value( :project, :which_ceedling, hash:config )
+    return nil if value.nil?
+
+    @loginator.lazy( Verbosity::OBNOXIOUS ) { " > Set which Ceedling from config :project ↳ :which_ceedling => #{value.strip()}" }
+    return value.strip()
+  end
+
+  def from_vendor_directory()
+    return nil if !@file_wrapper.directory?( VENDOR_PATH )
+
+    @loginator.log( " > Set which Ceedling to be vendored installation", Verbosity::OBNOXIOUS )
+    return VENDOR_PATH
+  end
+
+  # Returns the standardized path of an installation, raising if it holds none
+  def validate(which)
+    path = @path_validator.standardize_paths( which ).first
+    if !@file_wrapper.directory?( path )
+      raise "Configured Ceedling launch path #{path}/ does not exist"
+    end
+
+    if !@file_wrapper.exist?( Installation.new( path ).rakefile_path )
+      raise "Configured Ceedling launch path #{path}/ contains no Ceedling installation"
+    end
+
+    return path
+  end
+
+  def use(root, app_cfg)
+    app_cfg.set_paths( root )
+    @loginator.log( " > Launching Ceedling from #{app_cfg[:ceedling_root_path]}/", Verbosity::OBNOXIOUS )
+
+    return Installation.new( root )
+  end
+
+end