gcov: example to generate coverage

1 files changed, 60 insertions, 0 deletions

diff --git a/src/development/gcov.md b/src/development/gcov.md
new file mode 100644
index 0000000..c97a1b0
--- /dev/null
+++ b/src/development/gcov.md
@@ -0,0 +1,60 @@
+# gcov(1)
+
+Generate code coverage reports in text format.
+
+Compile the source files of interest and link the final binary with the
+following flags:
+- `-fprofile-arcs` instruments the generated code such that it writes a `.gcda`
+  file when being executed with details about which branches are taken
+- `-ftest-coverage` writes a `.gcno` notes file which is used by `gcov` during
+  generation of the coverage report
+
+Depending on the build environment one may also set `-fprofile-abs-path` to
+generate absolute path names into the `.gcno` note files, this can ease setups
+where compilations are done in different directories to the source directory.
+
+> `gcc` / `clang` also support an alias flag `--coverage` which during
+> compilation time is equivalent to `-fprofile-arcs -ftest-coverage` and during
+> link time `-lgcov`.
+
+After running the instrumented binary, the human readable report can then be
+generated for a single file for example such as
+```shell
+gcov <SRC FILE | OBJ FILE>
+```
+
+## Example
+```cpp
+{{#include gcov/cov.cc:3:}}
+```
+
+The `gcov` coverage report can be generated as follows for `gcc` or `clang`.
+```make
+{{#include gcov/Makefile:3:}}
+```
+
+The will generate a report similar to the following.
+```text
+cat cov.cc.gcov
+        -:    0:Source:cov.cc
+        -:    0:Graph:cov.gcno
+        -:    0:Data:cov.gcda
+        -:    0:Runs:1
+        -:    1:// Copyright (C) 2023 johannst
+        -:    2:
+        -:    3:#include <cstdio>
+        -:    4:
+        2:    5:void tell_me(int desc) {
+        2:    6:  if (desc & 1) {
+        2:    7:    std::puts("this");
+        -:    8:  } else {
+    #####:    9:    std::puts("that");
+        -:   10:  }
+        2:   11:}
+        -:   12:
+        1:   13:int main(int argc, char *argv[]) {
+        1:   14:  tell_me(argc);
+        1:   15:  tell_me(argc);
+        1:   16:  return 0;
+        -:   17:}
+```