Debian Codegraph @

cmake/tribits/core/package_arch/TribitsSystemDataStructuresMacrosFunctions.rst

raw
1 TriBITS System Data Structures
2 ------------------------------
3
4 This section describes the global CMake variables that make up the
5 data-structures and the macros/functions that create them that define the
6 TriBITS package dependency system. All of these variables all exist at the
7 base project-level ``CMakeLists.txt`` file and are typically not cache
8 variables (and therefore are recomputed on every reconfigure and can therefore
9 accommodate changing enables/disables without a full reconfigure from
10 scratch). These variables define a graph of external packages/TPLs
11 (i.e. pre-built and found out on the system) and internal packages
12 (i.e. buildable CMake packages). This information is meant for maintainers of
13 the TriBITS system itself and should **not** need to be known by `TriBITS
14 Project Developers`_ or even `TriBITS Project Architects`_.
15
16
17 TriBITS naming conventions
18 ++++++++++++++++++++++++++
19
20 Before describing the TriBITS package architecture data-structures and the
21 macros/functions that create and manipulate those data-structures in detail,
22 first we define some naming conventions for TriBITS macros/function and
23 variables.
24
25 First, the term "Package" is overloaded in the context of TriBITS (and in
26 CMake for that matter). In the context of TriBITS, here are the **different
27 types of entities called a "Package"**:
28
29 * **TriBITS External packages/TPLs** listed in the `<repoDir>/TPLsList.cmake`_
30 file and require a `<tplDefsDir>/FindTPL<tplName>.cmake`_ file.
31
32 * **TriBITS Top-level internal packages** directly listed in the
33 `<repoDir>/PackagesList.cmake`_ file
34
35 * **TriBITS Subpackages** for a top-level package (defined by the
36 ``SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS`` argument in
37 `tribits_package_define_dependencies()`_ command called in the
38 `<packageDir>/cmake/Dependencies.cmake`_ file)
39
40 * **Native CMake packages** which are found using ``find_package()`` and
41 require a ``<Package>Config.cmake`` package config file or a
42 ``Find<Package>.cmake`` find module file
43
44 * **CMake Packaging** of a CMake project which means breaking it into
45 components and provide various source and binary distributions. (A TriBITS
46 top-level package maps to a CMake packaging "component".)
47
48 Also, there are the collection of all three of the TriBITS-related "packages".
49
50 To try to avoid ambiguity, we define the following identifiers that appear in
51 TriBITS variable, macro, and function names:
52
53 * **TPL** or **EXTERNAL_PACKAGE**: Variable or function specifically for
54 processing TriITS external packages/TPLs.
55
56 * **TOPLEVEL_PACKAGE**: Variable or a function specifically for a top-level
57 package (or sometimes if there is no ambiguity just **PACKAGE**).
58
59 * **SUBPACKAGE**: Variable or a function specifically for a subpackage (and
60 **SUBPACKAGE_FULLNAME** if it is the full name of a subpackage which
61 includes the top-level parent package name
62 ``${PARENT_PACKAGE_NAME}${SUBPACKAGE}``).
63
64 * **PACKAGE**: Variable or function that could pertain to an external
65 package/TPL, or a top-level package, or a subpackage.
66
67 TriBITS uses the follow general case naming conventions for variables, macros,
68 functions and module files:
69
70 * ``ProperNoun_UPPER_CASE`` is generally used for global and cache variables.
71 The proper nouns using CamelCase include the names of TriBITS entities like
72 Projects, Repositories, and Packages. UPPER_CASE is used for non-proper
73 nouns. (E.g. ``Trilinos_SOURCE_DIR``)
74
75 * ``camelCaseVariableName`` or ``lower_case_variable_name`` is generally used
76 for local variable names.
77
78 * ``tribits_lower_case_name()`` is generally used for TriBITS functions and
79 macros. (E.g. ``trilinos_package_define_dependencies()``)
80
81 * ``TribitsModuleName.cmake`` is generally used for TriBITS CMake module file
82 names. (E.g. ``TribitsAddTest.cmake``)
83
84
85 User-level TriBITS Project, Repository, Package and Subpackage Variables
86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
87
88 The user-level variables that define a TriBITS Project, Repository, Package
89 and Subpackage are listed in:
90
91 * `TriBITS Project Core Variables`_
92 * `TriBITS Repository Core Variables`_
93 * `TriBITS Package Core Variables`_
94 * `TriBITS Subpackage Core Variables`_
95 * `TriBITS External Package/TPL Core Variables`_
96
97 These are variables that can be accessed by `TriBITS Project Developers`_ but
98 are also used in the internal implementation of TriBITS functionality.
99
100
101 Lists of external and internal packages
102 +++++++++++++++++++++++++++++++++++++++
103
104 List of non-cache top-level project variables:
105
106 * `${PROJECT_NAME}_DEFINED_TPLS`_: List of all defined external packages/TPLs
107
108 * Size `${PROJECT_NAME}_NUM_DEFINED_TPLS`_
109
110 * `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_: List of all defined
111 internal top-level packages
112
113 * Size `${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_
114
115 * `${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES`_: List of all defined external
116 packages/TPLs and top-level internal packages
117
118 * Size `${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES`_
119
120 * `${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES`_: List of all defined internal
121 top-level packages and subpackages
122
123 * Size `${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES`_
124
125 * `${PROJECT_NAME}_DEFINED_PACKAGES`_: List of all defined external
126 packages/TPLs, internal top-level packages, and subpackages (size
127 `${PROJECT_NAME}_NUM_DEFINED_PACKAGES`_)
128
129 * Size ${PROJECT_NAME}_NUM_DEFINED_PACKAGES
130
131 * `${PROJECT_NAME}_ENABLED_PACKAGES`_: Subset of all enabled packages from
132 ``${PROJECT_NAME}_DEFINED_PACKAGES``
133
134 * Size `${PROJECT_NAME}_NUM_ENABLED_PACKAGES`_
135
136 All of the above list variables are sorted in a valid dependency ordering in
137 that any upstream dependent packages are listed before a given package in
138 these lists. After these variables have been set in the macro
139 `tribits_read_all_project_deps_files_create_deps_graph()`_, they should
140 considered to be constant and **not** modified.
141
142 These variables are described in more detail below.
143
144 .. _${PROJECT_NAME}_DEFINED_TPLS:
145
146 The original list of all defined external packages (TPLs) read from the
147 processed `<repoDir>/TPLsList.cmake`_ files is given in the list variable::
148
149 ${PROJECT_NAME}_DEFINED_TPLS
150
151 .. _${PROJECT_NAME}_NUM_DEFINED_TPLS:
152
153 with size::
154
155 ${PROJECT_NAME}_NUM_DEFINED_TPLS
156
157 .. _${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES:
158
159 The original list of all defined internal top-level packages read in from the
160 processed `<repoDir>/PackagesList.cmake`_ files is given in the list
161 variable::
162
163 ${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES
164
165 .. _${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES:
166
167 with size::
168
169 ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_TOPLEVEL_PACKAGES
170
171 In this list, a defined internal TriBITS Package (i.e. a package that can be
172 built from source) will have `${PACKAGE_NAME}_SOURCE_DIR`_ ``!= ""`` while a
173 defined external package/TPL will have a non-empty `${PACKAGE_NAME}_FINDMOD`_
174 ``!= ""``.
175
176 .. _${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES:
177
178 The full list of defined external packages/TPLs and top-level internal
179 packages (i.e. TriBITS top-level packages) (**not** including subpackages) is
180 stored in the project-level non-cache list variable::
181
182 ${PROJECT_NAME}_DEFINED_TOPLEVEL_PACKAGES
183
184 .. _${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES:
185
186 with size::
187
188 ${PROJECT_NAME}_NUM_DEFINED_TOPLEVEL_PACKAGES
189
190 The first set of elements in this list are the defined external packages/TPLs
191 that are read in from the `<repoDir>/TPLsList.cmake`_ files from each
192 processed TriBITS repository, in order. This is followed by the set of
193 internal packages (TriBITS packages) that are defined in the
194 `<repoDir>/PackagesList.cmake`_ files from each processed TriBITS repository,
195 read in order. This list does **not** include any subpackages.
196
197 Note that some of the packages listed in
198 `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ may actually be treated
199 as external packages and not build from source code and instead will be found
200 on the system as pre-built/pre-installed packages using
201 ``find_package(<PackageName>)``. The final decision for if a package is
202 treated as an internal or external package is determined by the variable::
203
204 ${PACKAGE_NAME}_PACKAGE_BUILD_STATUS=[INTERNAL|EXTERNAL]
205
206 which gets set using various criteria as described in section `Determining if
207 a package is internal or external`_. This variable determines what
208 pre-built/pre-installed packages must be found out on the system if enabled
209 and what internal packages need to be built if enabled.
210
211 The set of external packages, internal top-level packages, and internal
212 sub-packages are just called the list of "Packages". When the term "Packages"
213 is used without an adjective, it is usually meant in this more general
214 context.
215
216 .. _${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES:
217
218 The set of all of the defined internal top-level packages **and subpackages**
219 is given by the non-cache project-level list variable::
220
221 ${PROJECT_NAME}_DEFINED_INTERNAL_PACKAGES
222
223 .. _${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES:
224
225 with the size::
226
227 ${PROJECT_NAME}_NUM_DEFINED_INTERNAL_PACKAGES
228
229 .. _${PROJECT_NAME}_DEFINED_PACKAGES:
230
231 The set of all of the defined external packages/TPLs, internal top-level
232 packages **and subpackages** is given by the non-cache project-level list
233 variable::
234
235 ${PROJECT_NAME}_DEFINED_PACKAGES
236
237 .. _${PROJECT_NAME}_NUM_DEFINED_PACKAGES:
238
239 with the size::
240
241 ${PROJECT_NAME}_NUM_DEFINED_PACKAGES
242
243 These data-structures as well as the package dependencies graph is built up in
244 the macro `tribits_read_all_project_deps_files_create_deps_graph()`_ with the
245 call graph described in the section `Function call tree for constructing
246 package dependency graph`_. These data-structures don't consider what
247 packages are actually enabled or disabled.
248
249 The enable/disable logic (given an initial set of enables and disables) is
250 applied in the macro `tribits_adjust_package_enables()`_. Once all of this
251 logic has been applied, several lists of enabled and non-enabled packages are
252 computed.
253
254 The list of enabled internal **top-level** packages is given in the non-cache
255 project-level list variable::
256
257 ${PROJECT_NAME}_ENABLED_INTERNAL_TOPLEVEL_PACKAGES
258
259 with size::
260
261 ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES
262
263 The list of enabled external packages/TPLs and internal **top-level** packages
264 is given in the non-cache project-level list variable::
265
266 ${PROJECT_NAME}_ENABLED_TOPLEVEL_PACKAGES
267
268 with size::
269
270 ${PROJECT_NAME}_NUM_ENABLED_TOPLEVEL_PACKAGES
271
272 .. _${PROJECT_NAME}_ENABLED_PACKAGES:
273
274 The list of enabled external packages/TPLs, internal **top-level and
275 subpackages** is given in the non-cache project-level list variable::
276
277 ${PROJECT_NAME}_ENABLED_PACKAGES
278
279 .. _${PROJECT_NAME}_NUM_ENABLED_PACKAGES:
280
281 with size::
282
283 ${PROJECT_NAME}_NUM_ENABLED_PACKAGES
284
285
286 Variables defining the package dependencies graph
287 +++++++++++++++++++++++++++++++++++++++++++++++++
288
289 TriBITS sets up the following project-level non-cache variables that define
290 the dependencies for each external package/TPL and internal package:
291
292 .. _${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES:
293
294 ``${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES``
295
296 The list of all **defined direct** required and optional upstream external
297 package/TPL and internal package dependencies, regardless if they are
298 enabled or not. To determine if a given direct upstream package
299 ``<depPkg>`` in this list is enabled or not for this package
300 ``${PACKAGE_NAME}``, check the value of
301 ``${PACKAGE_NAME}_ENABLE_<depPkg>``. NOTE: The variables
302 ``${PACKAGE_NAME}_ENABLE_<depPkg>`` will be set even for required upstream
303 packages to allow for uniform loops involving required and optional
304 upstream dependencies. (And for a parent package with subpackages, it is
305 possible for a required subpackage to **not** be enabled and for
306 ``${PACKAGE_NAME}_ENABLE_<depPkg>`` to be ``OFF`` as explained in
307 `Subpackage enable does not auto-enable the parent package`_.) This list
308 will be set regardless of if the package ``${PACKAGE_NAME}`` is enabled or
309 not.
310
311 .. _${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES:
312
313 ``${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES``
314
315 List of all **enabled direct** required and optional upstream external
316 package/TPL and internal package dependencies. This is strict subset of
317 `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ (i.e. all of the ``<depPkg>``
318 items in this list will have ``${PACKAGE_NAME}_ENABLE_<depPkg>`` set to
319 ``ON``).
320
321 .. _${PACKAGE_NAME}_LIB_DEP_REQUIRED_<depPkg>:
322
323 ``${PACKAGE_NAME}_LIB_DEP_REQUIRED_<depPkg>``
324
325 Is ``TRUE`` if the entry ``<depPkg>`` in
326 `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ or
327 `${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`_ is a required LIB dependency
328 and is ``FALSE`` if it is only an optional LIB dependency.
329
330 .. _${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES:
331
332 ``${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES``
333
334 This list of all **define direct** extra package test required and
335 optional upstream external package/TPL and internal package dependencies.
336 This list is set regardless if the package ``${PACKAGE_NAME}`` is enabled
337 or not. NOTE: This list does **not** contain the items in the list
338 `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ (but those are implicitly also
339 required/optional test dependencies as well).
340
341 .. _${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES:
342
343 ``${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES``
344
345 The list of all **enabled direct** extra required and optional upstream
346 external package/TPL and internal package dependencies. This is a strict
347 subset of `${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_.
348
349 .. _${PACKAGE_NAME}_TEST_DEP_REQUIRED_<depPkg>:
350
351 ``${PACKAGE_NAME}_TEST_DEP_REQUIRED_<depPkg>``
352
353 Is ``TRUE`` if the entry ``<depPkg>`` in
354 `${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_ or
355 `${PACKAGE_NAME}_TEST_ENABLED_DEPENDENCIES`_ is a required TEST dependency
356 and is ``FALSE`` if it is only an optional TEST dependency. For the sake
357 of simplicity and generality,
358 ``${PACKAGE_NAME}_TEST_DEP_REQUIRED_<depPkg>`` will also be set to
359 ``TRUE`` or ``FALSE`` for ``<depPkg>`` in the lists
360 `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ or
361 `${PACKAGE_NAME}_LIB_ENABLED_DEPENDENCIES`_ because a LIB dependency is
362 also implicitly a TEST dependency.
363
364 NOTE: The same upstream package ``<depPkg>`` can be included in both the lists
365 `${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES`_ and
366 `${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES`_ if ``<depPkg>`` is optional in
367 the former but required in the latter (which is a valid situation if you think
368 about it as a package that may be optional for the lib(s) of a package is
369 required by the tests for a package). (Otherwise, duplicate entries will be
370 removed from the list ``${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES``.)
371
372 NOTE: Having flat lists containing both optional and required dependencies
373 with the bool variables ``${PACKAGE_NAME}_[LIB|TEST]_DEP_REQUIRED_<depPkg>``
374 defining which entries are required or optional is modeled after the CMake
375 standard for handing the ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` arguments
376 to ``find_package()`` in that it passes that info to the
377 ``<Package>Config.cmake`` file as the single list variable
378 ``${CMAKE_FIND_PACKAGE_NAME}_FIND_COMPONENTS`` and the bool vars
379 ``${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED_<comp>``.
380
381 Given the above upstream dependency list variables, the following derived list
382 variables are then constructed which provide navigation from a package to its
383 downstream/forward dependent packages:
384
385 .. _${PACKAGE_NAME}_FORWARD_LIB_DEFINED_DEPENDENCIES:
386
387 ``${PACKAGE_NAME}_FORWARD_LIB_DEFINED_DEPENDENCIES``
388
389 For a given package ``${PACKAGE_NAME}``, lists the names of all of the
390 forward packages ``<fwdDepPkg>`` that list this package in their
391 ``<fwdDepPkg>_LIB_DEFINED_PACKAGES`` variables.
392
393 .. _${PACKAGE_NAME}_FORWARD_TEST_DEFINED_DEPENDENCIES:
394
395 ``${PACKAGE_NAME}_FORWARD_TEST_DEFINED_DEPENDENCIES``
396
397 For a given package ``${PACKAGE_NAME}``, lists the names of all of the
398 forward packages ``<fwdDepPkg>`` that list this package in their
399 ``<fwdDepPkg>_TEST_DEFINED_PACKAGES`` variables.
400
401
402 User enable/disable cache variables
403 +++++++++++++++++++++++++++++++++++
404
405 The following variables can be set by the user to determine what packages get
406 enabled or disabled::
407
408 ${PROJECT_NAME}_ENABLE_ALL_PACKAGES
409
410 ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES
411
412 ${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES
413
414 ${PROJECT_NAME}_ENABLE_${PACKAGE_NAME}
415
416 ${PROJECT_NAME}_ENABLE_TESTS
417
418 ${PROJECT_NAME}_ENABLE_EXAMPLES
419
420 ${PACKAGE_NAME}_ENABLE_${OPTIONAL_DEP_PACKAGE_NAME}
421
422 ${PACKAGE_NAME}_ENABLE_TESTS
423
424 ${PACKAGE_NAME}_ENABLE_EXAMPLES
425
426 according to the rules described in `Package Dependencies and Enable/Disable
427 Logic`_.
428
429
430 Determining if a package is internal or external
431 ++++++++++++++++++++++++++++++++++++++++++++++++
432
433 As mentioned above, some subset of initially internal packages listed in
434 `${PROJECT_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES`_ (which all have
435 ``${PACKAGE_NAME}_SOURCE_DIR != ""``) may be chosen to be external packages.
436 Packages that could be built internally may be chosen to be treated as
437 external packages (and therefore located on the system using
438 ``find_package()``) by setting::
439
440 -D TPL_ENABLE_<PackageTreatedAsExternal>=ON
441
442 .. _${PACKAGE_NAME}_PACKAGE_BUILD_STATUS:
443 .. _${TPL_NAME}_PACKAGE_BUILD_STATUS:
444
445 The final status of whether a package is treated as an internal package or an
446 external package is provided by the variable::
447
448 ${PACKAGE_NAME}_PACKAGE_BUILD_STATUS=[INTERNAL|EXTERNAL]
449
450 (NOT: The value of ``${PACKAGE_NAME}_PACKAGE_BUILD_STATUS`` is only changed
451 after all of the enable/disable dependency logic is complete.)
452
453 As a result, every other package upstream from any of these
454 ``<PackageTreatedAsExternal>`` packages must therefore also be treated as
455 external packages automatically and will have
456 ``${PACKAGE_NAME}_PACKAGE_BUILD_STATUS=EXTERNAL`` set accordingly. Also, if
457 any subpackage is determined to be EXTERNAL, then the parent package of that
458 subpackage and every other peer subpackage will also be set to EXTERNAL.
459
460
461 Processing of external packages/TPLs and TriBITS-compliant external packages
462 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
463
464 The processing of external packages/TPLs is influenced by whether the external
465 package is a regular TriBITS TPL (i.e with a ``FindTPL<tplName>.cmake``
466 modules) or is a TriBITS-compliant external package. Here, a
467 **TriBITS-Compliant External Package** has a ``<tplName>Config.cmake`` file
468 that satisfies the following properties:
469
470 * Has the target ``<tplName>::all_libs`` which is a fully specified modern
471 CMake target.
472 * Calls ``find_dependency()`` or the equivalent for all upstream packages that
473 it depends on.
474 * Every upstream dependent package ``<UpstreamTpl>`` has the target
475 ``<UpstreamTpl>::all_libs``. (But a minimally TriBITS-compliant external
476 package need not define this for all of its upstream dependencies.)
477
478 That means that when calling ``find_package()`` for a fully TriBITS-compliant
479 external package, there is no need to worry about finding any of its upstream
480 dependent external packages. That means that any external packages/TPLs
481 defined a TriBITS project which is upstream from a TriBITS-compliant external
482 package will be uniquely defined by calling ``find_package()`` on the most
483 downstream TriBITS-compliant external package that depends on it. Therefore,
484 defining the external packages and their targets in this set of external
485 packages just involves calling ``find_package()`` on the terminal
486 TriBITS-compliant external packages (i.e. TriBITS-compliant external packages
487 that don't have any downstream dependencies that are external packages). Then
488 the remaining subset of external packages/TPLs that don't have a downstream
489 TriBITS-compliant external package dependency will be defined as usual.
490 (However, as mentioned above, some of these are not fully TriBITS compliant and
491 don't fully define the ``<UpstreamTpl>::all_libs`` for all of their upstream
492 dependencies (see below).)
493
494 By having all fully TriBITS-compliant external packages, an external
495 dependency is never found more than once.
496
497 The variables that are set internally to define these different subsets of
498 external packages/TPLs are:
499
500 * ``<Package>_IS_TRIBITS_COMPLIANT``: Set the ``TRUE`` if the package
501 ``<Package>`` provides the ``<Package>::all_libs`` by just calling
502 ``find_package(<Package> CONFIG REQUIRED)``.
503
504 * ``<Package>_PROCESSED_BY_DOWNSTREAM_TRIBITS_EXTERNAL_PACKAGE``: Set to
505 ``TRUE`` if the external package/TPL should be (or was after the fact)
506 defined by a downstream TriBITS-compliant external package.
507
508 An external package with ``<Package>_IS_TRIBITS_COMPLIANT=TRUE`` **AND**
509 ``<Package>_PROCESSED_BY_DOWNSTREAM_TRIBITS_EXTERNAL_PACKAGE=FALSE`` is the
510 one for which ``find_package(<Package> CONFIG REQUIRED)`` will be called and
511 does not have any downstream packages that are being treated as external
512 packages. Also, ``find_package(<Package> CONFIG REQUIRED)`` will be called on
513 TriBITS-compliant external packages if ``<Package>::all_libs`` was not defined
514 by a downstream non fully TriBITS-compliant external package.
515
516 The variable ``<Package>_IS_TRIBITS_COMPLIANT`` is set right when the packages
517 are initially defined by reading in the various input files. That is, all
518 initially internal packages that are listed in a
519 `<repoDir>/PackagesList.cmake`_ file will have
520 ``<Package>_IS_TRIBITS_COMPLIANT=TRUE`` set while all external packages/TPLs
521 listed in a `<repoDir>/TPLsList.cmake`_ file will have
522 ``<Package>_IS_TRIBITS_COMPLIANT=FALSE`` set (except for those tagged with
523 ``TRIBITS_PKG`` which will have ``<Package>_IS_TRIBITS_COMPLIANT=FALSE`` set).
524
525 The processing of external packages/TPLs is done in two loops:
526
527 * The first loop over external packages/TPLs will be those external
528 packages/TPLs that have ``<Package>_IS_TRIBITS_COMPLIANT=TRUE`` **OR**
529 ``<Package>_PROCESSED_BY_DOWNSTREAM_TRIBITS_EXTERNAL_PACKAGE=TRUE``. And we
530 only call ``find_package()`` for those TriBITS-compliant external packages
531 that have ``<Package>_IS_TRIBITS_COMPLIANT=TRUE`` **AND** don't have
532 ``<Package>::all_libs`` already defined. This is a reverse loop to give an
533 opportunity for downstream TriBITS-compliant external packages to define
534 their upstream external packages/TPLs. NOTE: If
535 ``<Package>_PROCESSED_BY_DOWNSTREAM_TRIBITS_EXTERNAL_PACKAGE`` was set to
536 ``TRUE`` before this loop starts, it will be set to ``FALSE`` for
537 non-TriBITS-compliant external packages
538 (i.e. ``<Package>_IS_TRIBITS_COMPLIANT=FALSE``).
539
540 * The second loop processes remaining external packages/TPLs that where not
541 defined by a downstream TriBITS-compliant external package in the first
542 loop. These are all TriBITS TPLs for which
543 ``<Package>_IS_TRIBITS_COMPLIANT=FALSE`` **AND**
544 ``<Package>_PROCESSED_BY_DOWNSTREAM_TRIBITS_EXTERNAL_PACKAGE=FALSE`` **AND**
545 for which ``<Package>_FINDMOD`` is not empty and is not ``TRIBITS_PKG``.
546
547 For more details, see the implementation in `tribits_process_enabled_tpls()`_.
548
549
550 Other package-related variables
551 +++++++++++++++++++++++++++++++
552
553 The following global internal cache variables are used to provide more
554 information about a given internal package:
555
556 ``${PACKAGE_NAME}_LIBRARIES``
557
558 Defines list of *only* the libraries associated with the given
559 (sub)package and does *not* list libraries in upstream packages. Linkages
560 to upstream packages is taken care of with calls to
561 target_link_libraries(...) and the dependency management system in CMake
562 takes care of adding these to various link lines as needed (this is what
563 CMake does well). However, when a package has no libraries of its own
564 (which is often the case for packages that have subpackages, for example),
565 then this list of libraries will contain the libraries to the direct
566 dependent upstream packages in order to allow the chain of dependencies to
567 be handled correctly in downstream packages and executables in the same
568 package. In this case, ${PACKAGE_NAME}_HAS_NATIVE_LIBRARIES will be
569 false. The primary purpose of this variable is to passe to
570 target_link_libraries(...) by downstream libraries and executables.
571
572 ``${PACKAGE_NAME}_HAS_NATIVE_LIBRARIES``
573
574 Will be true if a package has native libraries. Otherwise, it will be
575 false. This information is used to build export makefiles to avoid
576 duplicate libraries on the link line.
577
578 ``${PACKAGE_NAME}_FULL_ENABLED_DEP_PACKAGES``
579
580 Lists out, in order, all of the enabled upstream packages that the given
581 package depends on and support that package is enabled in the given
582 package. This is only computed if
583 ${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES=ON. NOTE: This list
584 does *not* include the package itself. This list is created after all of
585 the enable/disable logic is applied.
586
587 ``${PARENT_PACKAGE_NAME}_LIB_TARGETS``
588
589 Lists all of the library targets for this package only that are as part of
590 this package added by the `tribits_add_library()`_ function. This is used
591 to define a target called ${PACKAGE_NAME}_libs that is then used by
592 `tribits_ctest_driver()`_ in the package-by-package mode. If a package
593 has no libraries, then the library targets for all of the immediate
594 upstream direct dependent packages will be added. This is needed for the
595 chain of dependencies to work correctly. Note that subpackages don't have
596 this variable defined for them.
597
598 ``${PARENT_PACKAGE_NAME}_ALL_TARGETS``
599
600 Lists all of the targets associated with this package. This includes all
601 libraries and tests added with `tribits_add_library()`_ and
602 `tribits_add_executable()`_. If this package has no targets (no libraries
603 or executables) this this will have the dependency only on
604 ${PARENT_PACKAGE_NAME}_libs. Note that subpackages don't have this
605 variable defined for them.
606
607
608 Function call tree for constructing package dependency graph
609 ------------------------------------------------------------
610
611 Below is the CMake macro and function call graph for constructing the packages
612 lists and dependency data-structures described above.
613
614 | `tribits_read_all_project_deps_files_create_deps_graph()`_
615 | `tribits_read_defined_external_and_internal_toplevel_packages_lists()`_
616 | Foreach ``<repoDir>`` in ``${PROJECT_NAME}_ALL_REPOSITORIES``:
617 | ``include(`` `<repoDir>/TPLsList.cmake`_ ``)``
618 | `tribits_process_tpls_lists()`_
619 | ``include(`` `<repoDir>/PackagesList.cmake`_ ``)``
620 | `tribits_process_packages_and_dirs_lists()`_
621 | `tribits_read_deps_files_create_deps_graph()`_
622 | `tribits_process_all_repository_deps_setup_files()`_
623 | Foreach ``<repoDir>`` in ``${PROJECT_NAME}_ALL_REPOSITORIES``:
624 | ``include(`` `<repoDir>/cmake/RepositoryDependenciesSetup.cmake`_ ``)``
625 | `tribits_process_project_dependency_setup_file()`_
626 | ``include(`` `<projectDir>/cmake/ProjectDependenciesSetup.cmake`_ ``)``
627 | `tribits_read_all_package_deps_files_create_deps_graph()`_
628 | Foreach ``EXTERNAL_PACKAGE`` in ``${PROJECT_NAME}_DEFINED_TPLS``:
629 | `tribits_read_external_package_deps_files_add_to_graph()`_
630 | Foreach ``TOPLEVEL_PACKAGE`` in ``${PACKAGE_NAME}_DEFINED_INTERNAL_TOPLEVEL_PACKAGES``:
631 | `tribits_read_toplevel_package_deps_files_add_to_graph()`_
632 | `tribits_prep_to_read_dependencies()`_
633 | ``include(`` `<packageDir>/cmake/Dependencies.cmake`_ ``)``
634 | `tribits_assert_read_dependency_vars()`_
635 | `tribits_save_off_dependency_vars()`_
636 | `tribits_parse_subpackages_append_packages_add_options()`_
637 | `tribits_read_package_subpackage_deps_files_add_to_graph()`_
638 | Foreach ``SUBPACKAGE``:
639 | `tribits_read_subpackage_deps_file_add_to_graph()`_
640 | `tribits_prep_to_read_dependencies()`_
641 | ``include(`` `<packageDir>/<spkgDir>/cmake/Dependencies.cmake`_ ``)``
642 | `tribits_assert_read_dependency_vars()`_
643 | `tribits_process_package_dependencies_lists()`_
644 | See same call stack for this macro as shown below
645 | `tribits_read_back_dependencies_vars()`_
646 | `tribits_process_package_dependencies_lists()`_
647 | `tribits_set_dep_packages()`_
648 | `tribits_abort_on_self_dep()`_
649 | `tribits_abort_on_missing_package()`_
650 | `tribits_append_forward_dep_packages()`_
651 | `tribits_abort_on_missing_package()`_
652
653 .. LocalWords: acyclic TriBITS SUBPACKAGES CTEST subpackages buildable TPLs TPLS
654 .. LocalWords: Subpackage CMake CMakeLists