Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Add information about the CMake structure and variables that can be used to modify what is built and how it is built.
Add information on pending Conan package.
Organized it a little better.
  • Loading branch information
eljonny authored Mar 18, 2024
1 parent 117d328 commit aa04386
Showing 1 changed file with 89 additions and 8 deletions.
97 changes: 89 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ Features of the test framework are very minimal and include:

## Acquiring the Library

### Including after manual installation

As of 0.1.0-beta.1 this library can be included in a CMake build
using the `find_package` CMake function after installing, like
so:
Expand All @@ -62,19 +64,44 @@ Then add it to your test executable target through
)
```

As of 0.1.0-beta.1, you can also include it in your `vcpkg` project
by running the following in the root of your project (pending
vcpkg PR approval that I have in right now
https://github.com/microsoft/vcpkg/pull/37471):
### vcpkg

As of 0.1.0-beta.1, you might soon be able to also include it
in your `vcpkg` project by running the following in the root of
your project (pending vcpkg PR approval that I have in right
now https://github.com/microsoft/vcpkg/pull/37471):
```
vcpkg add port testcpp
```

### Conan

As of 0.1.1-beta.2, you might soon be able to also include it
in your `conan` project (pending approval from the Conan
community).
First add it as a dependency to your project in conanfile.txt:
```
[requires]
...
testcpp/0.1.1-beta.2
```

Then installing TestCPP into your project by running the
following in the root of your project (pending Conan Center
PR approval):
```
conan install . --output-folder=build --build=missing
```

### GitHub Releases on the TestCPP repo

You can get binary packages from the Releases page on the GitHub
repo, or get them directly from the latest successful build on
the Actions page from the multi-platform or linux-package
workflows on the repo.
Currently binaries are generated for Linux and Windows.
Currently binaries are generated by the workflows for 64-bit
Linux and Windows, and the 32-bit packages are generated
elsewhere (my local dev machine currently).

## Writing Tests

Expand Down Expand Up @@ -120,6 +147,11 @@ Test failures are handled through a range of exceptions and

# Building

The project can be built in a couple ways.
Whether you prefer an IDE or a terminal, you're covered here.

## Building in CodeLite

I developed this project in the [CodeLite IDE](https://codelite.org/),
for which there is a workspace and project in this repository.
In the project, there are CMake targets defined for Release and Debug
Expand All @@ -144,6 +176,52 @@ In the Custom Targets... context menu option there are also ctest
configuration selected), and if you're on a Linux distro that
supports building RPM and/or DEB packages, will build those too.

## CMake build structure and variables

The CMake build is split into components that get included into the
main build file to make modifying each piece more logical and
manageable.

- Variable Checks:
Checking the variables to enable or disable certain sections of the
build (VarChecks.cmake).
Variables that are checked:
- CMAKE_COVERAGE_ENABLED
If set to 1, enables code coverage with gcov if testing is also
enabled. If undefined or set to 0, coverage will be disabled
even if testing is enabled.
- CMAKE_DEMO_ENABLED
If set to 1, enables the demo target, which builds a small
executable that runs some contrived tests to verify compilation
and runtime. If undefined or set to 0, the demo target will not
be built. The name of the demo target is ${PROJECT_NAME}_run.
- CMAKE_TEST_ENABLED
If set to 1, CTest is included and the test targets are enabled.
If undefined or set to 0, testing for the library will be
disabled.
- Build Targets Configuration:
Setting up the build targets (Targets.cmake).
- Build Type Handling:
Handling the build type which sets compile options for the platform
on which the build is being run based on the build type (Debug,
Release, I still need to work on getting RelWithDebugInfo
configured properly) (BuildTypeHandling.cmake).
- Target Includes:
Which includes should be applied to which targets (Includes.cmake).
- Target Link Libraries:
Which libraries need to be linked in which build targets, based on
the result of VarChecks in terms of code coverage (Linking.cmake).
- Testing:
Testing configuration, based on the result of VarChecks
(Testing.cmake).
- Installing:
Configuring installation of the library (Installing.cmake).
- Packaging:
Configuring library packaging parameters, enable CPack
(Packing.cmake).

## Building outside the IDE

To build outside of the CodeLite IDE, you can run the following
commands, after cloning the repo, for the debug build:
```
Expand All @@ -154,8 +232,7 @@ To build outside of the CodeLite IDE, you can run the following
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:
those in the build, add one or both of the following flags to `cmake`:
- For testing: `-DCMAKE_TEST_ENABLED=1`
- For code coverage: `-DCMAKE_COVERAGE_ENABLED=1`

Expand All @@ -168,12 +245,16 @@ For the release build:
make
```
The Release configuration supports testing. To enable generation of the
test target in the build, add the following flag to the cmake command:
test target in the build, add the following flag to `cmake`:
- `-DCMAKE_TEST_ENABLED=1`

The Release configuration does not support code coverage because of the
compiler optimizations used.

Both Release and Debug configurations support building the demo app,
which you can enable by adding the following flag to `cmake`:
- `-DCMAKE_DEMO_ENABLED`

# Testing and Code Coverage

The library is tested using itself.
Expand Down

0 comments on commit aa04386

Please sign in to comment.