ceedling 1.1.9 → 1.2.0

data/spec/integration/partials_symbol_linkage_spec.rb

@@ -0,0 +1,371 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Whether a Partial's mutated symbols survive to the link, and with the linkage intended.
+#
+# Partials exists to reach inside a module, and it does that by removing the very thing that
+# kept a name private. A file-scope `static` loses its storage class; a function-scoped
+# `static` is renamed and promoted to module scope; a `static` function has `static` stripped
+# from its signature. Every one of those changes what the linker sees, and none of it is
+# observable from a syntax-only compile -- a declaration that compiles is not proof a
+# definition survived relocation.
+#
+# So these cases compile real object files and link them against a stand-in translation unit
+# that takes the address of each symbol, forcing the linker to resolve it. `undefined
+# reference to` and `multiple definition of` are the two diagnostics this file exists to
+# provoke or to rule out.
+#
+# Accurate preprocessing is assumed throughout; what fallback cannot resolve belongs to
+# partials_fallback_preprocessing_spec.rb.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'partials_generation_integration_helper'
+
+describe 'Partial symbol linkage' do
+
+  include_context 'requires gcc'
+  before { skip 'directives-only preprocessing is unavailable' unless directives_only_supported? }
+
+  after(:each) { cleanup_dir( @dir ) }
+
+  # ---------------------------------------------------------------------------
+  context 'a function the Partial exposes' do
+  # ---------------------------------------------------------------------------
+
+    it 'links a static function whose storage class was stripped' do
+      result = generate_partial(
+        module_name: 'engine',
+        header: "#ifndef ENGINE_H\n#define ENGINE_H\n#endif\n",
+        source: "#include \"engine.h\"\nstatic int engine_step(int v) { return v + 1; }\n",
+        source_includes: ['engine.h']
+      )
+      @dir = result.dir
+
+      expect( result.impl_h ).to include('int engine_step(int v);')
+      expect( result.impl_h ).not_to include('static int engine_step')
+
+      link = link_partial( result, references: ['engine_step'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+
+    # An inline function carries no external definition of its own in C99, so exposing one
+    # has to produce a definition the linker can find rather than only a declaration.
+    it 'links an inline function the Partial exposes' do
+      result = generate_partial(
+        module_name: 'scaler',
+        header: "#ifndef SCALER_H\n#define SCALER_H\n#endif\n",
+        source: "#include \"scaler.h\"\nstatic inline int scaler_twice(int v) { return v * 2; }\n",
+        source_includes: ['scaler.h']
+      )
+      @dir = result.dir
+
+      link = link_partial( result, references: ['scaler_twice'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  context 'a file-scope variable the Partial exposes' do
+  # ---------------------------------------------------------------------------
+
+    it 'links a stripped static from a separate object' do
+      result = generate_partial(
+        module_name: 'ticker',
+        header: "#ifndef TICKER_H\n#define TICKER_H\n#endif\n",
+        source: "#include \"ticker.h\"\nstatic int tick_count;\n",
+        source_includes: ['ticker.h']
+      )
+      @dir = result.dir
+
+      expect( result.impl_h ).to include('extern int tick_count;')
+      expect( result.impl_c ).to include('int tick_count;')
+      expect( result.impl_c ).not_to include('static int tick_count;')
+
+      expect( compile_objects( result ).ok ).to be(true)
+
+      link = link_partial( result, references: ['tick_count'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+
+    # The extern and the definition must agree on the whole type, qualifiers included. A
+    # disagreement is a compile error in the one translation unit holding both, which is
+    # exactly the unit the generated source becomes.
+    it 'keeps qualifiers on both the extern and the definition' do
+      result = generate_partial(
+        module_name: 'regs',
+        header: "#ifndef REGS_H\n#define REGS_H\n#endif\n",
+        source: "#include \"regs.h\"\nstatic volatile int regs_flag;\nstatic const int regs_limit = 7;\n",
+        source_includes: ['regs.h']
+      )
+      @dir = result.dir
+
+      expect( result.impl_h ).to include('extern volatile int regs_flag;')
+      expect( result.impl_h ).to include('extern const int regs_limit;')
+
+      link = link_partial( result, references: ['regs_flag', 'regs_limit'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+
+    it 'links an exposed array with its dimension intact' do
+      result = generate_partial(
+        module_name: 'window',
+        header: "#ifndef WINDOW_H\n#define WINDOW_H\n#define DEPTH 4\n#endif\n",
+        source: "#include \"window.h\"\nstatic int window_samples[DEPTH];\n",
+        source_includes: ['window.h']
+      )
+      @dir = result.dir
+
+      expect( result.impl_h ).to include('extern int window_samples[DEPTH];')
+
+      link = link_partial( result, references: ['window_samples'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  context 'a function-scoped static the Partial promotes' do
+  # ---------------------------------------------------------------------------
+
+    it 'links the promoted variable under its generated name' do
+      result = generate_partial(
+        module_name: 'counter',
+        header: "#ifndef COUNTER_H\n#define COUNTER_H\n#endif\n",
+        source: "#include \"counter.h\"\nint counter_next(void) { static int calls; calls++; return calls; }\n",
+        source_includes: ['counter.h']
+      )
+      @dir = result.dir
+
+      expect( result.impl_h ).to include('extern int partial_counter_next_calls;')
+      expect( result.impl_c ).to include('int partial_counter_next_calls;')
+
+      link = link_partial( result, references: ['counter_next', 'partial_counter_next_calls'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+
+    # The generated name is qualified by the function it came from, so two functions in one
+    # module may each keep a static of the same spelling without colliding.
+    it 'keeps two same-named statics distinct across two functions' do
+      result = generate_partial(
+        module_name: 'dual',
+        header: "#ifndef DUAL_H\n#define DUAL_H\n#endif\n",
+        source: <<~C,
+          #include "dual.h"
+          int dual_first(void) { static int calls; calls++; return calls; }
+          int dual_second(void) { static int calls; calls++; return calls; }
+        C
+        source_includes: ['dual.h']
+      )
+      @dir = result.dir
+
+      link = link_partial(
+        result,
+        references: ['partial_dual_first_calls', 'partial_dual_second_calls']
+      )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  context 'a module both tested and mocked in one test file' do
+  # ---------------------------------------------------------------------------
+
+    # The implementation header arrives directly and the interface header arrives the way
+    # CMock's generated mock brings it, so both land in one translation unit. Defining each
+    # type once is a compile claim; exposing each symbol once is a link claim.
+    it 'compiles and links with one definition of each exposed symbol' do
+      result = generate_partial(
+        module_name: 'relay',
+        header: <<~C,
+          #ifndef RELAY_H
+          #define RELAY_H
+          typedef struct { int pin; } relay_cfg_t;
+          void relay_open(void);
+          #endif
+        C
+        source: "#include \"relay.h\"\nvoid relay_open(void) {}\nstatic int relay_state;\n",
+        source_includes: ['relay.h']
+      )
+      @dir = result.dir
+
+      # Which file each type lands in is partials_header_composition_spec's claim. What only a
+      # link can show is that one definition of each exposed symbol reaches the linker.
+      compile = compile_both_headers( result )
+      expect( compile.ok ).to be(true), "expected a clean compile, got: #{compile.first_error}"
+
+      link = link_partial( result, references: ['relay_open', 'relay_state'] )
+      expect( link.ok ).to be(true), "expected a clean link, got: #{link.first_diagnostic}"
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  context 'a module tested at one visibility and mocked at another' do
+  # ---------------------------------------------------------------------------
+
+    # The common real-world pairing: TEST_PARTIAL_PUBLIC_MODULE beside
+    # MOCK_PARTIAL_PRIVATE_MODULE, which tests a module's public surface while mocking the
+    # private helpers that surface calls. It splits one module's own content across two
+    # generated files, and that split is the shape a single-visibility case cannot reach.
+    #
+    # wondrous_forest's ForestMonitor is exactly this, and a refactor that dropped the module's
+    # own interface header from its generated source left a private function undeclared at
+    # compile time with nothing below the system tier to catch it.
+
+    # A module's own config is part of the partials hash the remaps receive, which is what tells
+    # the source remap to carry this module's interface header alongside its implementation.
+    it 'carries its own interface header in its generated source' do
+      @result = generate_partial( **split_visibility_module )
+      @dir = @result.dir
+
+      carried = @result.includes( :impl_c ).join( "\n" )
+      expect( carried ).to include('ceedling_partial_gauge_impl.h')
+      expect( carried ).to include('ceedling_partial_gauge_interface.h')
+    end
+
+    # The interface header includes the types header, so carrying the interface back into the
+    # types header would fold its declarations into that file instead.
+    it 'never carries its own interface header into the types header' do
+      @result = generate_partial( **split_visibility_module )
+      @dir = @result.dir
+
+      expect( @result.types_h_includes.join( "\n" ) )
+        .not_to include('ceedling_partial_gauge_interface.h')
+    end
+
+    it 'declares the public functions in the implementation header and the private ones in the interface' do
+      @result = generate_partial( **split_visibility_module )
+      @dir = @result.dir
+
+      expect( @result.impl_h ).to include('int gauge_read(void);')
+      expect( @result.impl_h ).not_to include('gauge_scale')
+
+      expect( @result.interface_h ).to include('int gauge_scale(int raw);')
+      expect( @result.interface_h ).not_to include('gauge_read')
+    end
+
+    # The failure mode the regression produced: a public body calls a private helper declared
+    # only in the interface header, so the generated source compiles only if it reaches both.
+    it 'compiles a public body that calls a private helper' do
+      @result = generate_partial( **split_visibility_module )
+      @dir = @result.dir
+
+      compile = compile_objects( @result )
+      expect( compile.ok ).to be(true), "expected a clean compile, got: #{compile.first_error}"
+      expect( compile.stderr ).not_to match(/implicit declaration/)
+    end
+
+    it 'links the public surface, with the private helper left for a mock to satisfy' do
+      @result = generate_partial( **split_visibility_module )
+      @dir = @result.dir
+
+      # gauge_scale is deliberately absent: a mocked private function is satisfied by CMock's
+      # generated definition in a real build, so the Partial must not also define it.
+      expect( @result.impl_c ).not_to include('int gauge_scale(int raw)')
+
+      link = link_partials( [@result], references: ['gauge_read'] )
+      expect( link.ok ).to be(false)
+      # Linkers disagree on the wording -- GNU ld reports an undefined reference, Apple's
+      # reports undefined symbols for an architecture -- but both name the symbol.
+      expect( link.stderr ).to include('gauge_scale')
+    end
+
+    # The whole chain at once: split visibility, a carried type dependency, and exposed
+    # file-scope data.
+    it 'resolves a carried type dependency across the split' do
+      @result = generate_partial(
+        tests_expose: Partials::PUBLIC,
+        mocks_expose: Partials::PRIVATE,
+        module_name: 'gauge',
+        header: <<~C,
+          #ifndef GAUGE_H
+          #define GAUGE_H
+          #include "units.h"
+          typedef struct { Celsius limit; } gauge_cfg_t;
+          int gauge_read(void);
+          #endif
+        C
+        source: <<~C,
+          #include "gauge.h"
+          static gauge_cfg_t config = { 0 };
+          static int gauge_scale(int raw) { return raw; }
+          int gauge_read(void) { return gauge_scale(config.limit); }
+        C
+        header_includes: ['units.h'],
+        source_includes: ['gauge.h'],
+        extra: { 'units.h' => "#ifndef UNITS_H\n#define UNITS_H\ntypedef signed short Celsius;\n#endif\n" }
+      )
+      @dir = @result.dir
+
+      expect( @result.type_names( :types_h ) ).to include('gauge_cfg_t')
+      expect( @result.types_h_includes.join( "\n" ) ).to include('units.h')
+      expect( @result.impl_h ).to include('extern gauge_cfg_t config;')
+
+      standalone = compile_types_header_alone( @result )
+      expect( standalone.ok ).to be(true), "expected the types header to stand alone, got: #{standalone.first_error}"
+
+      compile = compile_objects( @result )
+      expect( compile.ok ).to be(true), "expected a clean compile, got: #{compile.first_error}"
+    end
+  end
+
+  # A module whose public function calls a private helper, tested publicly and mocked privately.
+  def split_visibility_module
+    {
+      tests_expose: Partials::PUBLIC,
+      mocks_expose: Partials::PRIVATE,
+      module_name: 'gauge',
+      header: "#ifndef GAUGE_H\n#define GAUGE_H\nint gauge_read(void);\n#endif\n",
+      source: <<~C,
+        #include "gauge.h"
+        static int reading = 7;
+        static int gauge_scale(int raw) { return raw * 2; }
+        int gauge_read(void) { return gauge_scale(reading); }
+      C
+      source_includes: ['gauge.h']
+    }
+  end
+
+  # ---------------------------------------------------------------------------
+  context 'two partialized modules sharing a file-scope name' do
+  # ---------------------------------------------------------------------------
+
+    # Characterization, not a requirement. Exposing file-scope data is the point of Partials,
+    # and the consequence is that a name chosen to be module-private now participates in
+    # link-time resolution. Two modules that each keep a `shared_count` therefore collide once
+    # both are partialized. This case pins that behavior so a future change to it is deliberate
+    # rather than silent.
+    #
+    # Both definitions are initialized on purpose. An uninitialized file-scope variable is a
+    # tentative definition, which some toolchains still merge as a common symbol rather than
+    # rejecting -- the collision would then appear on one platform and not another. An
+    # initialized definition is a strong symbol everywhere, so the collision is the fixture's
+    # property rather than the linker's.
+    it 'collides at link time, which is the behavior today' do
+      @dir = shared_partials_dir
+
+      alpha = generate_partial(
+        module_name: 'alpha', dir: @dir,
+        header: "#ifndef ALPHA_H\n#define ALPHA_H\n#endif\n",
+        source: "#include \"alpha.h\"\nstatic int shared_count = 1;\n",
+        source_includes: ['alpha.h']
+      )
+      beta = generate_partial(
+        module_name: 'beta', dir: @dir,
+        header: "#ifndef BETA_H\n#define BETA_H\n#endif\n",
+        source: "#include \"beta.h\"\nstatic int shared_count = 2;\n",
+        source_includes: ['beta.h']
+      )
+
+      link = link_partials( [alpha, beta], references: ['shared_count'] )
+
+      expect( link.ok ).to be(false)
+      # GNU ld reports a multiple definition, Apple's a duplicate symbol. Both name it.
+      expect( link.stderr ).to include('shared_count')
+    end
+  end
+
+end

data/spec/integration/preprocessing_transient_io_retry_spec.rb

@@ -0,0 +1,135 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Integration coverage for Fix 3 (Stage 2 of the concurrency/file-presence work):
+# does FileWrapper#open_with_retry actually let Preprocessinator ride out a
+# transient failure to open the gcc output it just produced, end to end against
+# real gcc -- and does a fault that never clears still surface as a clear,
+# file-naming CeedlingException rather than a raw Errno?
+#
+# This is the committed version of the fact-finding phase's Experiment C: a real
+# Preprocessinator + real PreprocessinatorCommentStripper/Reconstructor + real gcc,
+# with a FileWrapper subclass that controls exactly one underlying #open call (matched
+# by exact path) so the fault is deterministic rather than a flaky, timing-dependent
+# reproduction. Faulting at #open rather than #open_with_retry itself matters here --
+# open_with_retry's own internal retry loop (already proven exhaustively in
+# file_wrapper_spec.rb) is exactly the mechanism this spec needs to actually run.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'ceedling/preprocess/preprocessinator_comment_stripper'
+require 'ceedling/preprocess/preprocessinator_reconstructor'
+require 'ceedling/preprocess/c_comment_scanner'
+require 'ceedling/parsing_parcels'
+
+describe 'Preprocessing transient I/O retry (integration)' do
+  include_context 'requires gcc'
+
+  include IntegrationSpecHelpers
+
+  # A real FileWrapper whose #open raises for `fault_path` the first `raises_left`
+  # times it's called, then behaves normally -- every other path is untouched. Real
+  # FileWrapper#open_with_retry (inherited, not overridden) is what actually retries.
+  class FaultingFileWrapper < FileWrapper
+    def initialize(fault_path:, raises_left: 1, error: Errno::EACCES, **kwargs)
+      super(**kwargs)
+      @fault_path = fault_path
+      @raises_left = raises_left
+      @error = error
+    end
+
+    def open(filepath, flags)
+      if filepath == @fault_path && @raises_left > 0
+        @raises_left -= 1
+        raise @error, "simulated transient sharing violation on #{filepath}"
+      end
+      super
+    end
+  end
+
+  # Builds a real Preprocessinator wired to `file_wrapper`, real gcc, and a real
+  # comment stripper/reconstructor -- everything generate_directives_only_output
+  # actually touches, per Preprocessinator#generate_directives_only_output.
+  def build_preprocessinator(dir, file_wrapper)
+    cfg = IntegrationSpecHelpers::StubConfigurator.new
+    tool_exec = IntegrationSpecHelpers::ShellingToolExecutor.new
+    fpu = IntegrationSpecHelpers::ScratchFilePathUtils.new(dir)
+
+    comment_stripper = PreprocessinatorCommentStripper.new(
+      c_comment_scanner: CCommentScanner.new, file_wrapper: file_wrapper
+    )
+    reconstructor = PreprocessinatorReconstructor.new(
+      parsing_parcels: ParsingParcels.new, file_wrapper: file_wrapper
+    )
+
+    preprocessinator = Preprocessinator.new(
+      preprocessinator_includes_handler: IntegrationSpecHelpers::NULL,
+      preprocessinator_comment_stripper: comment_stripper,
+      preprocessinator_file_assembler:   IntegrationSpecHelpers::NULL,
+      preprocessinator_reconstructor:    reconstructor,
+      file_path_utils: fpu,
+      file_wrapper:    file_wrapper,
+      tool_executor:   tool_exec,
+      plugin_manager:  IntegrationSpecHelpers::NULL,
+      configurator:    cfg,
+      loginator:       IntegrationSpecHelpers::NULL,
+      reportinator:    IntegrationSpecHelpers::NULL
+    )
+    preprocessinator.setup
+    [preprocessinator, fpu]
+  end
+
+  it 'recovers from a transient open failure on its own output instead of crashing the build' do
+    with_source_tree('widget.c' => "int w(void) { return 1; }\n") do |dir|
+      src = File.join(dir, 'widget.c')
+      # Determine the real output path first (same formula the faulted run below
+      # will compute), so the fault can be targeted at the exact right file.
+      fpu = IntegrationSpecHelpers::ScratchFilePathUtils.new(dir)
+      raw_path = fpu.form_preprocessed_file_raw_directives_only_filepath(src, 'it')
+
+      # Exactly one raw failure, well within open_with_retry's own retry budget --
+      # the file is otherwise 100% fine, gcc writes it for real either way.
+      faulting_fw = FaultingFileWrapper.new(
+        fault_path: raw_path, raises_left: 1,
+        loginator: IntegrationSpecHelpers::NULL, verbosinator: IntegrationSpecHelpers::NULL
+      )
+      preprocessinator, = build_preprocessinator(dir, faulting_fw)
+
+      result = nil
+      expect {
+        result = preprocessinator.generate_directives_only_output(
+          filepath: src, test: 'it', flags: [], include_paths: [dir], vendor_paths: [], defines: []
+        )
+      }.not_to raise_error
+
+      expect(result).to eq(raw_path)
+      expect(File.exist?(raw_path)).to be true
+    end
+  end
+
+  it 'still raises a clear, file-naming CeedlingException when the fault never clears' do
+    with_source_tree('widget.c' => "int w(void) { return 1; }\n") do |dir|
+      src = File.join(dir, 'widget.c')
+      fpu = IntegrationSpecHelpers::ScratchFilePathUtils.new(dir)
+      raw_path = fpu.form_preprocessed_file_raw_directives_only_filepath(src, 'it')
+
+      # More raises than open_with_retry's own retry budget (initial attempt + 4
+      # retries) -- every attempt fails, so the fault genuinely never clears.
+      permanently_faulting_fw = FaultingFileWrapper.new(
+        fault_path: raw_path, raises_left: 999,
+        loginator: IntegrationSpecHelpers::NULL, verbosinator: IntegrationSpecHelpers::NULL
+      )
+      preprocessinator, = build_preprocessinator(dir, permanently_faulting_fw)
+
+      expect {
+        preprocessinator.generate_directives_only_output(
+          filepath: src, test: 'it', flags: [], include_paths: [dir], vendor_paths: [], defines: []
+        )
+      }.to raise_error(CeedlingException, /#{Regexp.escape(raw_path)}/)
+    end
+  end
+end

data/spec/integration/quote_include_isolator_spec.rb

@@ -0,0 +1,167 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Integration coverage for QuoteIncludeIsolator, which stages a copy of a file alone in a
+# fresh directory.
+#
+# A quote-include (`#include "..."`) always checks its own file's directory before
+# consulting any -I search path. Staging a copy with nothing else beside it forces that
+# lookup through -I instead, which is how a mock or a Partial reaches a compile whose
+# real header sits next to the file including it.
+#
+# The directory this creates, the bytes it copies, and what a compiler makes of a staged
+# copy are filesystem and toolchain facts. A doubled file layer records only that a copy
+# was requested, so a real FileWrapper runs against a real temp directory here. The unit
+# spec at spec/units/quote_include_isolator_spec.rb owns everything observable through
+# injected doubles alone.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'fileutils'
+require 'tmpdir'
+require 'open3'
+require 'ceedling/file_wrapper'
+require 'ceedling/quote_include_isolator'
+require 'ceedling/constants'
+
+describe 'QuoteIncludeIsolator (integration)' do
+  before(:each) do
+    @loginator    = double('loginator')
+    @verbosinator = double('verbosinator')
+    allow(@loginator).to receive(:log)
+    allow(@verbosinator).to receive(:should_output?).and_return(false)
+
+    file_wrapper = FileWrapper.new({ :loginator => @loginator, :verbosinator => @verbosinator })
+    @isolator    = QuoteIncludeIsolator.new({ :file_wrapper => file_wrapper, :loginator => @loginator })
+
+    @parent   = Dir.mktmpdir
+    @source_a = File.join( @parent, 'source_a.h' )
+    @source_b = File.join( @parent, 'nested', 'source_b.h' )
+
+    FileUtils.mkdir_p( File.dirname( @source_b ) )
+    File.write( @source_a, 'a' )
+    File.write( @source_b, 'b' )
+  end
+
+  after(:each) do
+    FileUtils.rm_rf( @parent )
+  end
+
+  it 'creates a new directory nested inside parent' do
+    isolation = @isolator.isolate( parent: @parent, files: [@source_a] )
+
+    expect( File.directory?( isolation.dir ) ).to be true
+    expect( isolation.dir ).to start_with( @parent )
+  end
+
+  # Named by basename alone, since the point is a directory holding nothing but these
+  # files. A nested source and a flat one land side by side.
+  it 'copies every given file into that directory, named by basename alone' do
+    isolation = @isolator.isolate( parent: @parent, files: [@source_a, @source_b] )
+
+    expect( File.read( File.join( isolation.dir, 'source_a.h' ), encoding: 'UTF-8' ) ).to eq( 'a' )
+    expect( File.read( isolation.copy_of( @source_b ), encoding: 'UTF-8' ) ).to eq( 'b' )
+  end
+
+  it 'stages nothing but an empty directory when given no files' do
+    isolation = @isolator.isolate( parent: @parent, files: [] )
+
+    expect( Dir.children( isolation.dir ) ).to eq( [] )
+  end
+
+  it 'removes the staged directory when the block of #within ends' do
+    dir = nil
+    @isolator.within( parent: @parent, files: [@source_a] ) { |isolation| dir = isolation.dir }
+
+    expect( File.directory?( dir ) ).to be false
+  end
+
+  # Every byte after the #line directive is the original's, line endings included.
+  it 'writes a location-preserving copy as the #line directive followed by the original bytes' do
+    original = File.join( @parent, 'crlf.c' )
+    File.binwrite( original, "int a;\r\nint b;\r\n" )
+
+    isolation = @isolator.isolate( parent: @parent, files: [original], preserve_location: true )
+
+    expect( File.binread( isolation.copy_of( original ) ) ).to eq( "#line 1 \"#{original}\"\nint a;\r\nint b;\r\n".b )
+  end
+
+  it 'rewrites a real dependency file so it names the original' do
+    original  = File.join( @parent, 'gpio.c' )
+    File.write( original, '' )
+    isolation = @isolator.isolate( parent: @parent, files: [original] )
+    deps      = File.join( @parent, 'gpio.d' )
+    File.write( deps, "gpio.o: #{isolation.copy_of( original )} gpio.h\n" )
+
+    @isolator.restore_dependencies( isolation, deps )
+
+    expect( File.read( deps ) ).to eq( "gpio.o: #{original} gpio.h\n" )
+  end
+
+  # The end-to-end claim the isolator exists for: a real compiler, handed a
+  # location-preserving copy, reaches the header first on the search path rather than the
+  # real one beside the original, yet reports the original file throughout.
+  context 'compiling a location-preserving copy with a real gcc' do
+    include_context 'requires gcc'
+
+    def compile(tree)
+      with_source_tree(tree) do |dir|
+        source    = File.join( dir, 'src', 'gpio.c' )
+        object    = File.join( dir, 'gpio.o' )
+        deps      = File.join( dir, 'gpio.d' )
+        program   = File.join( dir, 'gpio' )
+        isolation = @isolator.isolate( parent: dir, files: [source], preserve_location: true )
+
+        search = ['-I', File.join( dir, 'shadow' ), '-I', File.join( dir, 'src' )]
+        _, status = Open3.capture2e( 'gcc', *search, '-MMD', '-MF', deps, '-c', isolation.copy_of( source ), '-o', object )
+        raise 'compile failed' unless status.success?
+
+        @isolator.restore_dependencies( isolation, deps )
+        Open3.capture2e( 'gcc', object, '-o', program )
+        run, = Open3.capture2e( program )
+
+        @isolator.release( isolation.dir )
+        yield source, run, File.read( deps ), isolation.dir
+      end
+    end
+
+    let(:tree) do
+      {
+        'src/gpio.c'    => %(#include <stdio.h>\n#include "board.h"\n#include "gpio.h"\n) +
+                           %(int main(void) { printf("%s %d %d\\n", __FILE__, BOARD, GPIO); return 0; }\n),
+        'src/board.h'   => %(#define BOARD 1\n),
+        'src/gpio.h'    => %(#define GPIO 7\n),
+        'shadow/board.h' => %(#define BOARD 2\n)
+      }
+    end
+
+    it 'reaches the header first on the search path instead of the one beside the original' do
+      compile( tree ) do |_, run|
+        expect( run.split[1] ).to eq( '2' )
+      end
+    end
+
+    it 'still resolves the original directory through the search path appended last' do
+      compile( tree ) do |_, run|
+        expect( run.split[2] ).to eq( '7' )
+      end
+    end
+
+    it 'reports the original file as __FILE__' do
+      compile( tree ) do |source, run|
+        expect( run.split[0] ).to eq( source )
+      end
+    end
+
+    it 'leaves the restored dependency file naming the original, never the copy' do
+      compile( tree ) do |source, _, deps, staged_dir|
+        expect( deps ).to include( source )
+        expect( deps ).to_not include( staged_dir )
+      end
+    end
+  end
+end