| 1 |
# TribitsExampleApp |
| 2 |
|
| 3 |
The example project `TribitsExampleApp` is a raw CMake project that pulls in |
| 4 |
libraries from packages from `TribitsExampleProject`. If `WithSubpackageC` |
| 5 |
subpackage or the `MixedLang` packages are built, then a Fortran compiler |
| 6 |
is required to build `TribitsExampleApp`. To build against all of the |
| 7 |
installed packages from an upstream `TribitsExampleProject`, configure, |
| 8 |
build, and run the tests with: |
| 9 |
|
| 10 |
``` |
| 11 |
cmake \ |
| 12 |
-DCMAKE_PREFIX_PATH=<upstreamInstallDir> \ |
| 13 |
<base-dir>/TribitsExampleApp |
| 14 |
|
| 15 |
make |
| 16 |
|
| 17 |
ctest |
| 18 |
``` |
| 19 |
|
| 20 |
That will call `find_package(TribitsExProj)` and will set the compilers |
| 21 |
pulled in from the found `TribitsExProjConfig.cmake` file. |
| 22 |
|
| 23 |
|
| 24 |
## Pulling in only a subset of packages |
| 25 |
|
| 26 |
To configure and build `TribitsExampleApp` against only a subset of the |
| 27 |
installed `TribitsExampleProject` packages, configure `TribitsExampleApp` |
| 28 |
using, for example: |
| 29 |
|
| 30 |
``` |
| 31 |
cmake \ |
| 32 |
-DCMAKE_PREFIX_PATH=<upstreamInstallDir> \ |
| 33 |
-DTribitsExApp_USE_COMPONENTS=SimpleCxx,WithSubpackages \ |
| 34 |
<base-dir>/TribitsExampleApp |
| 35 |
``` |
| 36 |
|
| 37 |
Internally, that that will call: |
| 38 |
|
| 39 |
``` |
| 40 |
find_package(TribitsExApp REQUIRED COMPONENTS ${TribitsExApp_USE_COMPONENTS}) |
| 41 |
``` |
| 42 |
|
| 43 |
(where `,` in `TribitsExApp_USE_COMPONENTS` is replaced with `;` internally to |
| 44 |
create a proper CMake list internally before calling `find_package()`). |
| 45 |
|
| 46 |
|
| 47 |
## Pulling in only a subset of packages by finding each package individually |
| 48 |
|
| 49 |
`TribitsExampleApp` is also set up to demonstrate finding the individual |
| 50 |
packages using separate calls to `find_package(<Package>)` by configuring |
| 51 |
with, for example: |
| 52 |
|
| 53 |
``` |
| 54 |
cmake \ |
| 55 |
-DCMAKE_PREFIX_PATH=<upstreamInstallDir> \ |
| 56 |
-DTribitsExApp_USE_COMPONENTS=SimpleCxx,WithSubpackages \ |
| 57 |
-DTribitsExApp_FIND_INDIVIDUAL_PACKAGES=ON \ |
| 58 |
<base-dir>/TribitsExampleApp |
| 59 |
``` |
| 60 |
|
| 61 |
That essentially results in calling: |
| 62 |
|
| 63 |
``` |
| 64 |
find_package(SimpleCxx REQUIRED) |
| 65 |
find_package(WithSubpackages REQUIRED) |
| 66 |
... |
| 67 |
target_link_libraries(app |
| 68 |
PRIVATE SimpleCxx::all_libs |
| 69 |
PRIVATE WithSubpackages::all_libs |
| 70 |
) |
| 71 |
``` |
| 72 |
|
| 73 |
(but does so with a loop and a list internally). |
| 74 |
|
| 75 |
|
| 76 |
## Pulling in packages from the build tree |
| 77 |
|
| 78 |
`TribitsExampleApp` is additionally set up to demonstrate finding the |
| 79 |
individual packages from the build directory (where `<upstreamBuildDir>` is |
| 80 |
the build directory for `TribitsExampleProject`) instead of the install tree |
| 81 |
using separate calls to `find_package(<Package>)` by configuring with, for |
| 82 |
example: |
| 83 |
|
| 84 |
``` |
| 85 |
cmake \ |
| 86 |
-DCMAKE_PREFIX_PATH=<upstreamBuildDir>/cmake_packages \ |
| 87 |
-DTribitsExApp_USE_COMPONENTS=SimpleCxx,WithSubpackages \ |
| 88 |
-DTribitsExApp_FIND_INDIVIDUAL_PACKAGES=ON \ |
| 89 |
<base-dir>/TribitsExampleApp |
| 90 |
``` |
| 91 |
|
| 92 |
This is identical to the case to finding the individual packages under the |
| 93 |
install tree except here the packages and libraries are found under the build |
| 94 |
tree and the include directories point into the source tree. (There is no |
| 95 |
need for an install directory in this case.) This is to simulate more |
| 96 |
advanced use cases such as where `TribitsExampleApp` and |
| 97 |
`TribitsExampleProject` may be part of a larger super-build that works out of |
| 98 |
the build tree without needing to install. |
| 99 |
|
| 100 |
NOTE: There is no `TribitsExProjConfig.cmake` file generated in the build tree |
| 101 |
to find so it is not possible to call `find_package(TribitsExProjConfig)` |
| 102 |
pointing into the build tree. |
| 103 |
|
| 104 |
|
| 105 |
## Tests demonstrating usage of TribitsExampleApp |
| 106 |
|
| 107 |
The TriBITS project contains automated tests that run the various use cases |
| 108 |
described above and check their result. These tests are shown defined |
| 109 |
[here](https://github.com/TriBITSPub/TriBITS/blob/master/test/core/ExamplesUnitTests/TribitsExampleApp_Tests.cmake) |
| 110 |
and are run locally with CTest and are submitted to |
| 111 |
[CDash](https://github.com/TriBITSPub/TriBITS/wiki/TriBITS-CDash-Dashboard) as |
| 112 |
part of regular testing. |