Debian Codegraph @

cmake/tribits/examples/TribitsExampleApp2/README.md

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