From 6487e53bd8dd4c2f08025c5aa742c9912b0101a9 Mon Sep 17 00:00:00 2001
From: Jonathan Hyry <3676933+eljonny@users.noreply.github.com>
Date: Sun, 17 Mar 2024 00:54:33 -0700
Subject: [PATCH] Update README.md

Significantly expanded the README to include additional information about building, testing, and packaging the library.
Fixed a spelling error.
---
 README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 75 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index cb7ecf8..0db818d 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,14 @@ To build within the CodeLite IDE:
  - Right click on the TestFramework project
  - Move to the Custom Targets... context menu option
  - Click cmake
+In the Custom Targets... context menu option there are also ctest
+ and cpack targets, which will, respectively:
+ - Run the test suite for the library and (if the Debug
+   configuration is selected) generate code coverage reports for
+   the library code.
+ - Create binary and/or source packages (depending on the build
+   configuration selected), and if you're on a Linux distro that
+   supports building RPM and/or DEB packages, will build those too.
 
 To build outside of the CodeLite IDE, you can run the following
  commands, after cloning the repo, for the debug build:
@@ -119,6 +127,11 @@ To build outside of the CodeLite IDE, you can run the following
     cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=1
     make
 ```
+The Debug configuration supports testing and code coverage. To enable
+ those in the build, add one or both of the following flags to the cmake
+ command:
+ - For testing: `-DCMAKE_TEST_ENABLED=1`
+ - For code coverage: `-DCMAKE_COVERAGE_ENABLED=1`
 
 For the release build:
 ```
@@ -128,11 +141,46 @@ For the release build:
     cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1
     make
 ```
+The Release configuration supports testing. To enable generation of the
+ test target in the build, add the following flag to the cmake command:
+ - `-DCMAKE_TEST_ENABLED=1`
+The Release configuration does not support code coverage because of the
+ compiler optimizations used.
+
+# Testing and Code Coverage
+
+If you would like to test the framework after building it, ensure the
+ test flag was passed to CMake when you built it then run the following
+ command from the build-debug or build-release directory:
+```
+ctest --progress --verbose
+```
+
+If you would like to generate code coverage reports from the tests,
+ ensure that the code coverage flag was passed to CMake when you built
+ it and that you built it using GCC and with the Debug configuration
+ then run the following commands after running the tests (running the
+ tests generates the raw coverage data):
+```
+mkdir -p coverage && cd coverage
+find .. -name '*.gcda' | xargs gcov -abcfmu
+find . -type f -not -name 'Test*.gcov' | xargs rm
+```
+These commands do the following:
+ - create and enter a directory for storing the coverage reports
+ - collect all the raw coverage data files generated by the
+   GCC compiler (gcov does not work with clang as far as I
+   understand, and the toolchain is generally not present when
+   building with cl on Windows)
+ - Pass the list of files to gcov to process the raw data and
+   output human-readable code coverage reports
+ - Remove all the coverage data for non-project code
+The GitHub repo is linked to Codecov which visualizes this data.
 
 # Installing
 
-After building, run the variant of the commands that aligns with your
- build configuration (starting from the project directory).
+After building, run the variant of the commands that align with
+ your build configuration (starting from the project directory).
 For the debug build:
 ```
     cd build-debug
@@ -145,14 +193,35 @@ For the release build:
     sudo cmake --install .
 ```
 
+# Packaging
+
+The project is configured to use CPack, if you would like to
+ create your own binary and/or source distribution of the
+ project.
+To create basic binary packages that can be used on the
+ target OS and architecture (I believe this is based on what
+ type of system you run the build process), run the following
+ command from the CMake build directory (either build-debug
+ or build-release):
+ - `cpack --config CPackConfig.cmake`
+To create source packages, run the following command from the
+ CMake build directory (either build-debug or build-release):
+ - `cpack --config CPackSourceConfig.cmake`
+If you are building on Linux, the build supports generating
+ deb and rpm packages. To build those, run the following
+ respective commands from the CMake build directory (either
+ build-debug or build-release):
+ - `cpack -G DEB`
+ - `cpack -G RPM`
+
 # Issues
 
 I'm more than willing to work on issues as they come up.
-Please submit and issue on the repo if there are problems building
- or using the framework.
+Please submit an issue on the repo if there are problems
+ building, testing, or using the framework.
 
 # Development
 
 I am semi-actively developing this library/framework, if
- anyone would like to contribute please do so by submitting
- pull requests on GitHub.
+ anyone would like to contribute please do so by
+ submitting pull requests on GitHub.