Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Significantly expanded the README to include additional information about building, testing, and packaging the library.
Fixed a spelling error.
  • Loading branch information
eljonny authored Mar 17, 2024
1 parent 6cff26c commit 6487e53
Showing 1 changed file with 75 additions and 6 deletions.
81 changes: 75 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
```
Expand All @@ -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
Expand All @@ -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.

0 comments on commit 6487e53

Please sign in to comment.