Debian Codegraph @

cmake/tribits/examples/TribitsExampleApp/README.md

raw
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.