📝 TEST_SOURCE_FILE() subtractive paths

Author: mkarlesky

README.md

@@ -15,6 +15,7 @@ project set up.
 * **`#include` relative paths & duplicate filename disambiguation**. Ceedling now fully supports relative paths in `#include` directives and `TEST_SOURCE_FILE()` build directive macros. Ceedling is now also able to distinguish files of the same name using paths in the preceding and at the command line 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` 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.
 * **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.
+* The `TEST_SOURCE_FILE()` build directive macro can now be used to remove source files from a test executable build. This can be handy in overriding Ceedling’s conventions for associating source files with a test executable if your project structure does not match up with Ceedling’s conventions.
 
 # 🌱 Ceedling is a handy-dandy build system for C projects
 

docs/Changelog.md

@@ -43,6 +43,9 @@ Tasks mirroring command line `test:` task invocation but with an early terminati
 
 Like with command line `test:` tasks, `<test>` can be `all`, a test file name, or a source file name that has a corresponding test file.
 
+### Subtractive paths in `TEST_SOURCE_FILE()`
+The `TEST_SOURCE_FILE()` build directive macro can now be used to remove source files from a test executable build using the same `-:` filepath decorator as available in `:paths` project configuration (ex. `TEST_SOURCE_FILE("-:foo/bar/file.c")`). This can be handy in overriding Ceedling’s conventions for associating source files with a test executable if your project structure does not match up with Ceedling’s conventions.
+
 ### Filepath limit checks
 Platform filepath limits (especially Windows) can lead to mysterious build failures, especially in CI where deep project subdirectories can occur. To help track down funny business, filepaths are intercepted and their lengths logged if they are nearing or exceed the platform limit.
 

docs/mkdocs/configuration/reference/paths.md

@@ -275,7 +275,7 @@ Subtractive paths may be simple paths or globs just like any other path entry.
     paths with Mixins to your heart’s content. The subtractive paths are not
     removed until all Mixins have been merged.
 
-!!! tip "The same `+:`/`-:` convention is available in test files"
+!!! tip "The same `+:` / `-:` convention is available in test files"
     The [`TEST_SOURCE_FILE()` build directive macro][test-source-file-subtractive]
     supports this identical notation for removing a specific source file from
     a test executable’s own compile/link list.

docs/mkdocs/testing-guide/build-directives.md

@@ -84,26 +84,28 @@ conventions.
 
 A `TEST_SOURCE_FILE()` entry can also be prefixed with `-:` to remove a
 named file from a test executable’s compile/link list outright, rather
-than add one. This uses the same `+:`/`-:` convention available for
+than add one. This uses the same `+:` / `-:` convention available for
 [`:paths` list entries](../configuration/reference/paths.md#subtractive-entries).
 
-Unlike the override behavior above — which only cancels the one file the
-header/source convention would otherwise have matched to a same-named
-`#include` — a `-:` entry applies to the fully assembled list for a test,
-after every other source has already been added to it. It removes the
-named file regardless of how that file got there: the implicit
-header/source convention, a positive `TEST_SOURCE_FILE()` entry, or a
-[Partial](partials/index.md).
+Unlike the override behavior above that only modifies the header/source 
+convention for same-named files, a `-:` decorated entry applies to the fully 
+assembled list for a test. It removes the named file regardless of how 
+that file was added to the list and acts only after every other source 
+has already been added to the list.
 
 This is useful whenever Ceedling’s convention of compiling and linking any
 `.c` file matching an `#include`d header’s name pulls in a file that
-shouldn’t be part of a particular test executable — for instance, a
-same-named file elsewhere in the project that defines a conflicting
-symbol and would otherwise break the link.
+should not be part of a particular test executable. Certain splits of 
+headers, source, and arranging of symbols can lead to duplicate symbols
+if Ceedling’s convention operates without intervention.
 
 As with the override behavior, Ceedling logs an informational notice
 naming the removed file, so a `-:` entry is never silent.
 
+Like in `:paths` entries, a `+:` decorator is assumed. That is omitting any
+decorator yields an additive file path. The `+:` decorator is available
+solely for formatting or self-documentation purposes.
+
 ### `TEST_SOURCE_FILE()` Example
 
 ```c

docs/mkdocs/testing-guide/conventions.md

@@ -62,14 +62,6 @@ above, this override is logged with an informational notice naming the winning
 `TEST_SOURCE_FILE()` entry and the `#include` it overrode, so the substitution
 is not silent either.
 
-A `TEST_SOURCE_FILE()` entry prefixed with `-:` goes further still, removing
-a named file from a test's compile/link list outright rather than winning an
-override — and, unlike the override above, it applies to the fully assembled
-list regardless of how a file arrived there (the header/source convention, a
-positive `TEST_SOURCE_FILE()` entry, or a Partial), not only to a same-basename
-match. See [`TEST_SOURCE_FILE()` Subtractive Notation][test-source-file-subtractive]
-for the full discussion.
-
 ### Test files (CLI test tasks)
 
 Execute [`ceedling test:` tasks][ceedling-test] at the command line with an
@@ -231,6 +223,13 @@ directive macro `TEST_SOURCE_FILE(...)` to tell Ceedling to compile
 and link the desired source file into the test executable (see 
 [macro documentation](build-directives.md)).
 
+Conversely, sometimes you may need to remove from a test executable 
+build a source file that corresponds to an `#include` directive in your
+test file. A `TEST_SOURCE_FILE()` entry prefixed with a `-:` decorator 
+removes a named file from a test‘s compile/link list. See 
+[`TEST_SOURCE_FILE()` Subtractive Notation][test-source-file-subtractive]
+for the full discussion.
+
 That was a lot of information and many clauses in a very few 
 sentences; the commented example test file code that follows in a 
 bit will make it clearer.