feat(cmake)!: improve code coverage module

CMakeLists.txt

@@ -9,6 +9,7 @@ block (SCOPE_FOR VARIABLES) # Setting internal variables
   message(TRACE "Setting internal variables")
   set(IXM_FILES_DIR "${CMAKE_BINARY_DIR}/.ixm" CACHE INTERNAL "")
   set(IXM_ROOT_DIR "${CMAKE_CURRENT_LIST_DIR}" CACHE INTERNAL "IXM Root Directory")
+  set(IXM_TEMPLATES_DIR "${IXM_ROOT_DIR}/templates" CACHE INTERNAL "IXM Templates Directory")
 endblock()
 
 block (SCOPE_FOR VARIABLES) # Setting global variables

docs/packages/coverage/gnu.md

@@ -8,5 +8,41 @@ title: GNU
 More information can be found in `gcov`'s
 [documentation](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html)
 
-> [!CAUTION]
-> Support for gcov is not yet implemented.
+> [!IMPORTANT]
+> This component is *always* found as long as `gcov` can be found, but the
+> `IMPORTED` library target it provides will have *no effect* unless you are
+> using `Clang`, `AppleClang`, or `GNU` for the `OBJCXX`, `OBJC`, `CXX`, or `C`
+> languages.
+>
+> This was done to speed up "finding" the component. Support for conditional
+> flag detection might be added in the future. Additional compilers might be
+> added or supported as well under some circumstances.
+
+## Targets
+
+The following `IMPORTED` targets are created when the GNU component is found.
+
+`Coverage::GNU` {#coverage-gnu}
+: Provides gcov compiler and linker options.
+: This target is *always* available if the `gcov` tool is found, but only
+affects dependents if the language for a given source file is `OBJCXX`, `OBJC`,
+`CXX`, or `C` and if the `CMAKE_<LANG>_COMPILER_ID` is `GNU`, `AppleClang`, or
+`Clang`.
+
+`Coverage::GNU::Tool` {#coverage-gnu-tool}
+: The `gcov` executable
+: *Type*: PROGRAM
+: *Required*: YES
+
+## Properties
+
+Some properties allow the modification of some code coverage information.
+
+`COVERAGE_GNU_ABSOLUTE_PATHS`
+: Pass `-fprofile-abs-path` to the compiler.
+: By default, gcov uses relative paths from when the source code was compiled.
+  With this flag enabled full filesystem paths are placed into the generated
+  output.
+: *Type*: `boolean`
+: *Scopes*: `TARGET`
+: Default: `NO`

docs/packages/coverage/index.md

@@ -34,5 +34,92 @@ Each component provides its own target, as well as some additional binary
 targets that might be necessary for tooling. See each component's documentation
 page for more information.
 
+## Commands
+
+### `add_coverage_target`
+
+This creates a target that can be referred to directly with `set_property` and,
+when built will collate raw profiling data into a format used by the selected
+implementation.
+
+> [!NOTE]
+> This command uses `add_custom_target` internally, which does not permit
+> creating alias targets, nor does it permit creating "scoped" targets (e.g.,
+> `${PROJECT_NAME}::coverage`). As a result *all targets* passed to this
+> command must be globally unique.
+
+#### Required Parameters {#add_coverage_target/required}
+
+`name`
+: name of the target to create
+
+#### Keyword Parameters {#add_coverage_target/keyword}
+
+`LLVM`
+: Use the LLVM Source-Based code coverage implementation
+
+`GNU`
+: Use the gcov code coverage implementation
+
+`OUTPUT`
+: Name of the final file generated at the end of the target's build step.
+
+`FORMAT`
+: File format to use for the given implementation.
+: > [!TIP]
+  > This can vary wildly between what tool might be used to merge and export
+  > the coverage information.
+
+### `target_coverage`
+
+#### Required Parameters {#target_coverage/required}
+
+`target`
+: Target created with `add_coverage_target` to add dependencies to.
+
+#### Keyword Parameters {#target_coverage/keyword}
+
+#### Example
+
+```cmake
+add_coverage_target(coverage LLVM)
+add_library(${PROJECT_NAME})
+add_executable(${PROJECT_NAME}-cli)
+target_coverage(coverage PRIVATE ${PROJECT_NAME} ${PROJECT_NAME}-cli)
+```
+
+## Properties
+
+There are multiple properties provided to users that allow them to tweak either
+the LLVM or GNU operations. These can be directly *on* a given build target
+from the user (e.g., adding `-fcoverage-mcdc`) or modify the execution of the
+coverage target itself.
+
+`COVERAGE_LLVM_COVERAGE_PREFIX_MAP`
+: Remap file source paths from `<old>` to `<new>` in coverage mapping. If there
+  are multiple options, prefix replacement is applied in reverse order starting
+  from the last one.
+: *Type*: `list`
+: *Default*: `$<TARGET_PROPERTY:SOURCE_DIR>=.`
+: *Context*: Coverage Target
+
+`COVERAGE_LLVM_MCDC`
+: Pass [`-fcoverage-mcdc`][mcdc] to the compiler
+: *Type*: `boolean`
+: *Context*: User Target
+: *Default*: `<empty>`
+
+`COVERAGE_LLVM_MERGE_FAILURE_MODE` {#property/coverage-llvm-merge-failure-mode}
+: `llvm-profdata`'s failure mode when merging `.profraw` files into a
+  `.profdata` file.
+: *Type*: `enum`
+: *Values*: `warn`, `any`, `all`
+: *Default*: `any`
+: *Context*: Coverage Target
+
+
+
 [1]: https://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html
 [2]: https://clang.llvm.org/docs/SourceBasedCodeCoverage.html
+
+[mcdc]: https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#mc-dc-instrumentation

docs/packages/coverage/llvm.md

@@ -116,44 +116,3 @@ endforeach()
 
 Some properties need to be mentioned directly on targets that will link against
 a given target, others are specifically for a *coverage* target.
-
-`LLVM_MODIFIED_CONDITION_DECISION_COVERAGE`
-: Pass [`-fcoverage-mcdc`][] to the compiler
-: *Type*: `boolean`
-: *Scopes*: `TARGET`
-: *Default*: `<empty>`
-
-`LLVM_COVERAGE_PREFIX_MAP`
-: Remap file source paths `<old>` to `<new>` in coverage mapping. If there are
-  multiple options, prefix replacement is applied in reverse order starting
-  from the last one
-: *Type*: `list`
-: *Default*: `<empty>`
-
-`LLVM_PROFRAW_SOURCES` {#property/llvm-profraw-sources}
-: TODO
-
-`LLVM_TEST_EXECUTABLES` {#property/llvm-test-executables}
-: TODO
-
-`LLVM_IGNORE_FILENAME_REGEX` {#property/llvm-ignore-filename-regex}
-: TODO
-
-`LLVM_PROFILE_FILENAME` {#property/llvm-profile-filename}
-: TODO
-
-
-`LLVM_MERGE_FAILURE_MODE` {#property/llvm-merge-failure-mode}
-: `llvm-profdata`'s failure mode when merging `.profraw` files into a
-  `.profdata` file.
-: *Type*: `enum`
-: *Values*: `warn`, `any`, `all`
-: *Default*: `any`
-
-`LLVM_SOURCES` {#property/llvm-sources}
-: Source files to be read from when exporting coverage information.
-: *Type*: `list`
-: *Scope*: `TARGET`
-: *Default*: `$<TARGET_PROPERTY:SOURCES>`
-
-[`-fcoverage-mcdc`]: https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#mc-dc-instrumentation