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