Debian Codegraph @

cmake/tribits/doc/guides/TribitsCoreDetailedReference.rst

raw
1 TriBITS Detailed Reference Documentation
2 ========================================
3
4 The following subsections contain detailed reference documentation for the
5 various TriBITS variables, functions, and macros that are used by TriBITS
6 projects that `TriBITS Project Developers`_ need to know about. Variables,
7 functions and macros that are used only internally in TriBITS are generally
8 not documented here (see the TriBITS ``*.cmake`` source files).
9
10
11 TriBITS Global Project Settings
12 -------------------------------
13
14 TriBITS defines a number of global project-level settings that can be set by
15 the user and can have their default determined by each individual TriBITS
16 project. If a given TriBITS project does not define its own default, a
17 reasonable default is set by the TriBITS system automatically. These options
18 are defined and are set, for the most part, in the internal TriBITS function
19 ``tribits_define_global_options_and_define_extra_repos()`` in the TriBITS
20 CMake code file ``TribitsGlobalMacros.cmake`` which gets called inside of the
21 `tribits_project()`_ macro. That function and that file are the definitive
22 source the options that a TriBITS project takes and what the default values
23 are but we strive to document them here as well. Many of these global options
24 (i.e. cache variables) such as ``${PROJECT_NAME}_<SOME_OPTION>`` allow the
25 project to define a default by setting a local variable
26 ``${PROJECT_NAME}_<SOME_OPTION>_DEFAULT`` as::
27
28 set(${PROJECT_NAME}_<SOME_OPTION>_DEFAULT <someDefault>)
29
30 either in its top-level ``CMakeLists.txt`` file or in its
31 ``ProjectName.cmake`` file (depends on what variable it is as to where it
32 should be set). If ``${PROJECT_NAME}_<SOME_OPTION>_DEFAULT`` is not set by
33 the project, then TriBITS provides a reasonable default value. The TriBITS
34 code that uses these defaults for this looks like::
35
36 if ("${${PROJECT_NAME}_<SOME_OPTION>_DEFAULT}" STREQUAL "")
37 set(${PROJECT_NAME}_<SOME_OPTION>_DEFAULT <someDefault>)
38 endif()
39
40 advanced_set( ${PROJECT_NAME}_<SOME_OPTION>
41 ${PROJECT_NAME}_<SOME_OPTION>_DEFAULT}
42 CACHE BOOL "[documentation]."
43 )
44
45 where ``<SOME_OPTION>`` is an option name, for example like
46 ``TEST_CATEGORIES``, and ``<someDefault>`` is the default set by TriBITS if
47 the project does not define a default. In this way, if the project sets the
48 variable ``${PROJECT_NAME}_<SOME_OPTION>_DEFAULT`` before this code executes,
49 then ``${${PROJECT_NAME}_<SOME_OPTION>_DEFAULT}`` will be used as the default
50 for the cache variable ``${PROJECT_NAME}_<SOME_OPTION>`` which, of course, can
51 be overridden by the user when calling ``cmake`` in a number of ways.
52
53 Most of these global options that can be overridden externally by setting the
54 cache variable ``${PROJECT_NAME}_<SOME_OPTION>`` should be documented in the
55 `Project-Specific Build Reference`_ document. A generic version of this
56 document is found in `TribitsBuildReference`_. Some of the more unusual
57 options that might only be of interest to developers mentioned below may not
58 be documented in `TribitsBuildReference`_.
59
60 The global project-level TriBITS options for which defaults can be provided by
61 a given TriBITS project are:
62
63 * `${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE`_
64 * `${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES`_
65 * `${PROJECT_NAME}_C_Standard`_
66 * `${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`_
67 * `${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND`_
68 * `${PROJECT_NAME}_CPACK_SOURCE_GENERATOR`_
69 * `${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE`_
70 * `${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES`_
71 * `${PROJECT_NAME}_ELEVATE_ST_TO_PT`_
72 * `${PROJECT_NAME}_ENABLE_CPACK_PACKAGING`_
73 * `${PROJECT_NAME}_ENABLE_CXX`_
74 * `${PROJECT_NAME}_ENABLE_C`_
75 * `${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`_
76 * `${PROJECT_NAME}_ENABLE_Fortran`_
77 * `${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES`_
78 * `${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE`_
79 * `${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION`_
80 * `${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES`_
81 * `${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES`_
82 * `${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE`_
83 * `${PROJECT_NAME}_IMPORTED_NO_SYSTEM`_
84 * `${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS`_
85 * `${PROJECT_NAME}_MAKE_INSTALL_GROUP_READABLE`_
86 * `${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE`_
87 * `${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE`_
88 * `${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS`_
89 * `${PROJECT_NAME}_Python3_FIND_VERSION`_
90 * `${PROJECT_NAME}_REQUIRES_PYTHON`_
91 * `${PROJECT_NAME}_SET_INSTALL_RPATH`_
92 * `${PROJECT_NAME}_SHOW_GIT_COMMIT_PARENTS`_
93 * `${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME`_
94 * `${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`_
95 * `${PROJECT_NAME}_TEST_CATEGORIES`_
96 * `${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS`_
97 * `${PROJECT_NAME}_TRACE_ADD_TEST`_
98 * `${PROJECT_NAME}_USE_GNUINSTALLDIRS`_
99 * `${PROJECT_NAME}_USES_PYTHON`_
100 * `DART_TESTING_TIMEOUT`_
101 * `CMAKE_INSTALL_RPATH_USE_LINK_PATH`_
102 * `MPI_EXEC_MAX_NUMPROCS`_
103 * `TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE`_
104
105 These options are described below.
106
107 .. _${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE:
108
109 **${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE**
110
111 The CMake cache variable ``${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE`` is
112 used to define how some invalid TriBITS usage checks are handled. The valid
113 values include 'FATAL_ERROR', 'SEND_ERROR', 'WARNING', and 'IGNORE'. The
114 default value is 'FATAL_ERROR' for a project when
115 ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=ON``, which is best for
116 development mode for a project that currently has no invalid usage patterns.
117 The default is 'IGNORE' when
118 ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=OFF``. But a project with some
119 existing invalid usage patterns might want to set, for example, a default of
120 'WARNING' in order to allow for a smooth upgrade of TriBITS. To do so,
121 set::
122
123 set(${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT WARNING)
124
125 in the project's base `<projectDir>/ProjectName.cmake`_ file.
126
127
128 .. _${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES:
129
130 **${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES**
131
132 To set ``${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES`` a different default,
133 set::
134
135 set(${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES_DEFAULT <newDefault>)
136
137 in the project's base `<projectDir>/ProjectName.cmake`_ file, where
138 ``<newDefault>`` can be ``FATAL_ERROR``, ``SEND_ERROR``, ``WARNING``,
139 ``NOTICE`` or ``IGNORE``
140
141 Otherwise, the default is ``WARNING`` when
142 ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` is ``ON`` and if ``IGNORE`` if
143 ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` is ``OFF``.
144
145
146 .. _${PROJECT_NAME}_C_Standard:
147
148 **${PROJECT_NAME}_C_Standard**
149
150 The variable ``${PROJECT_NAME}_C_Standard`` is used define the C standard
151 pass to the compiler in ``--std=<cstd>`` for GCC builds of the project.
152 TriBITS sets the default as ``c99`` but the project can set a new default in
153 the project's base `<projectDir>/CMakeLists.txt`_ file with, for example::
154
155 set(${PROJECT_NAME}_C_Standard_DEFAULT c11)
156
157 .. _${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS:
158
159 **${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS**
160
161 The variable ``${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`` determines how
162 unparsed and otherwise ignored arguments are handled in TriBITS functions
163 that are called by the client TriBITS projects. These are arguments that
164 are left over from parsing input options to functions and macros that take
165 both positional arguments and keyword arguments/options handled with the
166 ``cmake_parse_arguments()`` function. For example, for the a TriBITS
167 function declared like::
168
169 tribits_copy_files_to_binary_dir(
170 <targetName>
171 [SOURCE_FILES <file1> <file2> ...]
172 [SOURCE_DIR <sourceDir>]
173 ...
174 )
175
176 the arguments ``SOURCE_FILES <file1> <file2> ...`` and those that follow are
177 parsed by the ``cmake_parse_arguments()`` function while the argument
178 ``<targetName>`` is a positional argument. The problem is that any
179 arguments passed between the first ``<targetName>`` argument and the
180 specified keyword arguments like ``SOURCE_FILES`` and ``SOURCE_DIR`` are
181 returned as unparsed arguments and are basically ignored (which is what
182 happened in earlier versions of TriBITS). For example, calling the function
183 as::
184
185 tribits_copy_files_to_binary_dir( FooTestCopyFiles
186 ThisArgumentIsNotParsedAndIsIgnored
187 SOURCE_FILES file1.cpp file2.cpp ...
188 ...
189 )
190
191 would result in the unparsed argument
192 ``ThisArgumentIsNotParsedAndIsIgnored``.
193
194 The value of ``${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`` determines how
195 that ignored argument is handled. If the value is ``WARNING``, then it will
196 just result in a ``message(WARNING ...)`` command that states the warning
197 but configure is allowed to be completed. This would be the right value to
198 allow an old TriBITS project to keep configuring until the warnings can be
199 cleaned up. If the value is ``SEND_ERROR``, then ``message(SEND_ERROR
200 ...)`` is called. This will result in the configure failing but will allow
201 configure to continue until the end (or a ``FATAL_ERROR`` is raised). This
202 would be the right value when trying to upgrade a TriBITS project where you
203 wanted to see all of the warnings when upgrading TriBITS (so you could fix
204 them all in one shot). Finally, the value of ``FATAL_ERROR`` will result in
205 ``message(FATAL_ERROR ...)`` being called which will halt configure right
206 away. This is the best value when developing on a TriBITS project that is
207 already clean but you want to catch new developer-inserted errors right
208 away.
209
210 The default value for ``${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`` is
211 ``WARNING``, so that it will be backward compatible for TriBITS projects
212 that might have previously undetected unparased and therefore ignored
213 argument . However, a project can change the default by setting, for
214 example::
215
216 set(${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS_DEFAULT FATAL_ERROR)
217
218 in the `<projectDir>/ProjectName.cmake`_ file.
219
220 The user of a TriBITS project should not be able to trigger this unparsed
221 arguments condition so this variable is not documented in the `TriBITS Build
222 Reference`_. But it is still a CMake cache var that is documented in the
223 CMakeCache.txt file and can be set by the user or developer if desired.
224
225 .. _${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND:
226
227 **${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND**
228
229 The variable ``${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND`` is used to
230 define the absolute path to a file (or a list of files) that should be
231 included after the files listed in
232 ``${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE``. This variable can be used by
233 the TriBITS project to define, for example, a standard set of development
234 environments in the base `<projectDir>/CMakeLists.txt`_ file with::
235
236 set(${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND_DEFAULT
237 "${CMAKE_CURRENT_LIST_DIR}/cmake/StdDevEnvs.cmake")
238
239 **before** the `tribits_project()`_ command. By including this file(s)
240 after the file(s) listed in ``${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE``, the
241 user can override the variables set in this appended file(s). But it is
242 important that these variables best set after the users options have been
243 set but before the Package and TPL dependency analysis is done (because this
244 might enable or disable some TPLs).
245
246 .. _${PROJECT_NAME}_CPACK_SOURCE_GENERATOR:
247
248 **${PROJECT_NAME}_CPACK_SOURCE_GENERATOR**
249
250 The variable ``${PROJECT_NAME}_CPACK_SOURCE_GENERATOR`` determines the CPack
251 source generation types that are created when the ``package_source`` target
252 is run. The TriBITS default is set to ``TGZ``. However, this default can
253 be overridden by setting, for example::
254
255 set(${PROJECT_NAME}_CPACK_SOURCE_GENERATOR_DEFAULT "TGZ;TBZ2")
256
257 This variable should generally be set in the file::
258
259 <projectDir>/cmake/CallbackDefineProjectPackaging.cmake
260
261 instead of in the base-level ``CMakeLists.txt`` file so that it goes along
262 with rest of the project-specific CPack packaging options.
263
264 .. _${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE:
265
266 **${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE**
267
268 The variable ``${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE`` determines if the
269 CTest driver scripts using `tribits_ctest_driver()`_ configure, build, test
270 and submit results to CDash all-at-once for all of the packages being tested
271 or if instead is done package-by-package. Currently, the default is set to
272 ``FALSE`` for the package-by-package mode (for historical reasons) but the
273 default can be set to ``TRUE`` by setting:
274
275 set(${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE_DEFAULT "TRUE")
276
277 in the project's `<projectDir>/ProjectName.cmake`_ file. (This default must
278 be changed in the ``<projectDir>/ProjectName.cmake`` file and **NOT** the
279 `<projectDir>/CMakeLists.txt`_ file because the latter is not directly
280 processed in CTest -S driver scripts using ``tribits_ctest_driver()``.)
281
282 In general, a project should change the default to ``TRUE`` when using a
283 newer CDash installation with CDash versions 3.0+ that can accommodate the
284 results coming from ctest -S and display them package-by-package very
285 nicely. Otherwise, most projects are better off with package-by-package
286 mode since it results in nicer display on CDash for older CDash versions.
287
288 .. _${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES:
289
290 **${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES**
291
292 If `${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=ON`_ (the TriBITS
293 default value), then any explicitly enabled packages that have disabled
294 `upstream`_ required packages or TPLs will be disabled. If
295 `${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=OFF`_, then an
296 configure error will occur. For more details also see
297 `TribitsBuildReference`_ and `Disables trump enables where there is a
298 conflict`_. A project can define a different default value by setting::
299
300 set(${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES_DEFAULT FALSE)
301
302 .. _${PROJECT_NAME}_ELEVATE_ST_TO_PT:
303
304 **${PROJECT_NAME}_ELEVATE_ST_TO_PT**
305
306 If ``${PROJECT_NAME}_ELEVATE_ST_TO_PT`` is set to ``ON``, then all ``ST``
307 packages will be elevated to ``PT`` packages. The TriBITS default is
308 obviously ``OFF``. The default can be changed by setting::
309
310 set(${PROJECT_NAME}_ELEVATE_ST_TO_PT_DEFAULT ON)
311
312 There are projects, especially meta-projects, where the distinction between
313 ``PT`` and ``ST`` code is not helpful or the assignment of ``PT`` and ``ST``
314 packages in a repository is not appropriate with respect to the outer
315 meta-project. An example project like this CASL VERA. Changing the default
316 to ``ON`` allows any and packages to be considered in pre-push testing.
317
318 .. _${PROJECT_NAME}_ENABLE_CPACK_PACKAGING:
319
320 **${PROJECT_NAME}_ENABLE_CPACK_PACKAGING**
321
322 If ``${PROJECT_NAME}_ENABLE_CPACK_PACKAGING`` is ``ON``, then CPack support
323 is enabled and some TriBITS code is run that is needed to set up
324 data-structures that are used by the built-in CMake target
325 ``package_source``. The TriBITS default is ``OFF`` with the idea that the
326 average developer or user will not be wanting to create source distributions
327 with CPack. However, this default can be changed by setting::
328
329 set(${PROJECT_NAME}_ENABLE_CPACK_PACKAGING_DEFAULT ON)
330
331 .. _${PROJECT_NAME}_ENABLE_CXX:
332
333 **${PROJECT_NAME}_ENABLE_CXX**
334
335 If ``${PROJECT_NAME}_ENABLE_CXX`` is ``ON``, then C++ language support for
336 the project will be enabled and the C++ compiler must be found. By default,
337 TriBITS sets this to ``ON`` for all systems. A project never requires C++
338 can set this to off by default by setting:
339
340 set(${PROJECT_NAME}_ENABLE_CXX_DEFAULT FALSE)
341
342 .. _${PROJECT_NAME}_ENABLE_C:
343
344 **${PROJECT_NAME}_ENABLE_C**
345
346 If ``${PROJECT_NAME}_ENABLE_C`` is ``ON``, then C language support for the
347 project will be enabled and the C compiler must be found. By default,
348 TriBITS sets this to ``ON`` for all systems. A project never requires C can
349 set this to off by default by setting:
350
351 set(${PROJECT_NAME}_ENABLE_C_DEFAULT FALSE)
352
353 If a project does not have any native C code a good default would be::
354
355 set(${PROJECT_NAME}_ENABLE_C_DEFAULT FALSE)
356
357 NOTE: It is usually not a good idea to always force off C, or any compiler,
358 because extra repositories and packages might be added by someone that might
359 require the compiler and we don't want to unnecessarily limit the generality
360 of a given TriBITS build. Setting the default for all platforms should be
361 sufficient.
362
363 .. _${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE:
364 .. _${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT:
365
366 **${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE**
367
368 The variable ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` switches the
369 TriBITS project from development mode to release mode. The default for this
370 variable ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT`` should be set
371 in the project's `<projectDir>/Version.cmake`_ file and switched from ``ON``
372 to ``OFF`` when creating a release (see `Project and Repository Versioning
373 and Release Mode`_). When ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` is
374 ``ON``, several other variables are given defaults appropriate for
375 development mode. For example,
376 ``${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES`` is set to ``FATAL_ERROR`` by
377 default in development mode but is set to ``IGNORE`` by default in release
378 mode. In addition, strong compiler warnings are enabled by default in
379 development mode but are disabled by default in release mode. This variable
380 also affects the behavior of `tribits_set_st_for_dev_mode()`_.
381
382 .. _${PROJECT_NAME}_ENABLE_Fortran:
383
384 **${PROJECT_NAME}_ENABLE_Fortran**
385
386 If ``${PROJECT_NAME}_ENABLE_Fortran`` is ``ON``, then Fortran support for
387 the project will be enabled and the Fortran compiler(s) must be found. By
388 default, TriBITS sets this to ``ON`` .
389
390 If a project does not have any native Fortran code a good default would be::
391
392 set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF)
393
394 This default can be set in `<projectDir>/ProjectName.cmake`_ or `<projectDir>/CMakeLists.txt`_.
395
396 On WIN32 systems, the default for ``${PROJECT_NAME}_ENABLE_Fortran_DEFAULT``
397 is set to ``OFF`` since it can be difficult to get a Fortran compiler for
398 native Windows.
399
400 Given that a native Fortran compiler is not supported by default on Windows
401 and on most Mac OSX systems, projects that have optional Fortran code may
402 decide to set the default depending on the platform by setting, for example::
403
404 if ( (WIN32 AND NOT CYGWIN) OR (CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin") )
405 message(STATUS "Warning: Setting ${PROJECT_NAME}_ENABLE_Fortran=OFF by default"
406 " because this is Windows (not cygwin) and we assume to not have Fortran!")
407 set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF)
408 else()
409 set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT ON)
410 endif()
411
412 NOTE: It is usually not a good idea to always force off Fortran, or any
413 compiler, because extra repositories and packages might be added by someone
414 that might require the compiler and we don't want to unnecessarily limit the
415 generality of a given TriBITS build. Setting the default for all platforms
416 should be sufficient.
417
418 .. _${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES:
419
420 **${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES**
421
422 If ``${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES`` is set to ``ON``,
423 then ``<PackageName>Config.cmake`` files are created at configure time in
424 the build tree and installed into the install tree. These files are used by
425 external CMake projects to pull in the list of compilers, compiler options,
426 include directories and libraries. The TriBITS default is ``OFF`` but a
427 project can change the default by setting, for example::
428
429 set(${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES_DEFAULT ON)
430
431 A project would want to leave off the creation and installation of
432 ``<PackageName>Config.cmake`` files if it was only installing and providing
433 executables (see `${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS`_).
434 However, if it is wanting to provide libraries for other projects to use,
435 then it should turn on the default generation of these files.
436
437 .. _${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE:
438
439 **${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE**
440
441 If ``${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE`` is ``ON``, then packages
442 and subpackages marked as ``ST`` in the `<repoDir>/PackagesList.cmake`_ file
443 will be implicitly enabled along with the ``PT`` packages. Additional code
444 and tests may also be enabled using this option. The TriBITS default is
445 ``OFF`` but this can be changed by setting::
446
447 set(${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE_DEFAULT ON)
448
449 in the `<projectDir>/ProjectName.cmake`_ file.
450
451 .. _${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION:
452
453 **${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION**
454
455 If ``${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION`` is
456 ``TRUE``, then the directories for subpackages that are not enabled are left
457 out of the source tarball. This reduces the size of the tarball as much as
458 possible but does require that the TriBITS packages and subpackages be
459 properly set up to allow disabled subpackages from being excluded. The
460 TriBITS default is ``TRUE`` but this can be changed by setting::
461
462 set(${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION_DEFAULT FALSE)
463
464 .. _${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES:
465
466 **${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES**
467
468 If ``${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES`` is ``ON``, then the
469 data-structures needed to generate ``<PackageName>Config.cmake`` files are
470 created. These data structures are also needed in order to generate export
471 makefiles on demand using the function
472 `tribits_write_flexible_package_client_export_files()`_. The default in
473 TriBITS is to turn this ``ON`` automatically by default if
474 ``${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES`` is ``ON``. Else, by
475 default, TriBITS sets this to ``OFF``. The only reason for the project to
476 override the default is to set it to ``ON`` as with::
477
478 set(${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES_DEFAULT ON)
479
480 is so that the necessary data-structures are generated in order to use the
481 function `tribits_write_flexible_package_client_export_files()`_.
482
483 .. _${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES:
484
485 **${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES**
486
487 If ``${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES`` is ``ON``, then the files
488 ``VersionDate.cmake`` and ``<RepoName>_version_date.h`` will get generated
489 and the generated file ``<RepoName>_version_date.h`` will get installed for
490 each TriBITS version-controlled repository when the local directories are
491 git repositories. The default is ``OFF`` but the project can change that by
492 setting::
493
494 set(${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES ON)
495
496 in the `<projectDir>/ProjectName.cmake`_ file.
497
498 .. _${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE:
499
500 **${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE**
501
502 If ``${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE`` is ``ON``, then the file
503 ``<Project>RepoVersion.txt`` will get generated as a byproduct of
504 configuring with CMake. See `Multi-Repository Support`_ and
505 `<Project>_GENERATE_REPO_VERSION_FILE`_. The default is ``OFF`` but the
506 project can change that by setting::
507
508 set(${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE_DEFAULT ON)
509
510 in the `<projectDir>/ProjectName.cmake`_ file.
511
512 Note that if a ``git`` exectauble cannot be found at configure time, then
513 the default ``${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE_DEFAULT`` will be
514 overridden to ``OFF``. But if the user sets
515 ``${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE=ON`` in the cache and ``git``
516 can't be found, then an configure-time error will occur.
517
518
519 .. _${PROJECT_NAME}_IMPORTED_NO_SYSTEM:
520
521 **${PROJECT_NAME}_IMPORTED_NO_SYSTEM**
522
523 By default, include directories from IMPORTED library targets from the
524 TriBITS project's installed ``<Package>Config.cmake`` files will be
525 considered ``SYSTEM`` headers and therefore be included on the compile lines
526 of downstream CMake projects with ``-isystem`` with most compilers.
527 However, if ``${PROJECT_NAME}_IMPORTED_NO_SYSTEM`` is set to ``ON`` (only
528 supported for CMake versions 3.23 or greater), then all of the IMPORTED
529 library targets exported into the set of installed ``<Package>Config.cmake``
530 files will have the ``IMPORTED_NO_SYSTEM`` property set. This will cause
531 downstream customer CMake projects to apply the include directories from
532 these IMPORTED library targets as non-system include directories. On most
533 compilers, that means that the include directories will be listed on the
534 compile lines with ``-I`` instead of with ``-isystem``. (See more details
535 in the TriBITS Build Reference for ``<Project>_IMPORTED_NO_SYSTEM``.)
536
537 The default value set by TriBITS itself is ``OFF`` but a TriBITS project can
538 change the default value to ``ON`` by adding::
539
540 if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.23)
541 set(${PROJECT_NAME}_IMPORTED_NO_SYSTEM_DEFAULT ON)
542 endif()
543
544 in the `<projectDir>/ProjectName.cmake`_ file. (NOTE: The above ``if()``
545 statement ensures that a configure error will not occur if a version of
546 CMake less than 3.23 is used. But if the TriBITS project minimum CMake
547 version is 3.23 or greater, then the above ``if()`` statement guard can be
548 removed.)
549
550
551 .. _${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS:
552
553 **${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS**
554
555 If ``${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS`` is set to ``ON``, then
556 any defined libraries or header files that are listed in calls to
557 `tribits_add_library()`_ or `tribits_install_headers()`_ will be installed
558 (unless options are passed into `tribits_add_library()`_ that disable
559 installs). If set to ``OFF``, then headers and libraries will *not* be
560 installed by default and only ``INSTALLABLE`` executables added with
561 `tribits_add_executable()`_ will be installed. However, as described in
562 `TribitsBuildReference`_, shared libraries will always be installed if
563 enabled since they are needed by the installed executables.
564
565 For a TriBITS project that is primarily delivering libraries
566 (e.g. Trilinos), then it makes sense to leave the TriBITS default which is
567 ``ON`` or explicitly set::
568
569 set(${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS_DEFAULT ON)
570
571 For a TriBITS project that is primarily delivering executables (e.g. VERA),
572 then it makes sense to set the default to::
573
574 set(${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS_DEFAULT OFF)
575
576 .. _${PROJECT_NAME}_MAKE_INSTALL_GROUP_READABLE:
577
578 .. _${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE:
579
580 .. _${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE:
581
582 **${PROJECT_NAME}_MAKE_INSTALL_GROUP_READABLE**
583 **${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE**
584 **${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE**
585
586 Determines the permissions for directories and files created during the
587 execution of the of the ``install`` and ``isntall_package_by_package``
588 targets.
589
590 To make the created directories by only group readable for the project by
591 default, set::
592
593 set(${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE_DEFAULT TRUE)
594
595 To make the created directories by only group writable (and readable) for
596 the project by default, set::
597
598 set(${PROJECT_NAME}_MAKE_INSTALL_WORLD_WRITABLE_DEFAULT TRUE)
599
600 To make the created directories by world readable for the project by
601 default, set::
602
603 set(${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE_DEFAULT TRUE)
604
605 On non-Windows systems, these set permissions for all files and directories
606 from the the user-set base directory
607 ``${PROJECT_NAME}_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR`` on down.
608 For more details see `Installation considerations`_.
609
610 These defaults can be set in the `<projectDir>/ProjectName.cmake`_ file.
611
612 .. _${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS:
613
614 **${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS**
615
616 Determines if all of the libraries listed in ``<tplName>_LIBRARY_NAMES`` for
617 a given TPL must be found for each enabled TPL. By default, this is
618 ``FALSE`` which means that the determination if all of the listed libs for a
619 TPL should be found is determined by the ``MUST_FIND_ALL_LIBS`` option to
620 the `tribits_tpl_find_include_dirs_and_libraries()`_ function in the TPL
621 find module. To change the default for this, set::
622
623 set(${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS_DEFAULT TRUE)
624
625 in the `<projectDir>/ProjectName.cmake`_ file.
626
627
628 .. _${PROJECT_NAME}_Python3_FIND_VERSION:
629
630 **${PROJECT_NAME}_Python3_FIND_VERSION**
631
632 Determines the version of Python that is looked for. TriBITS requires at
633 least version "3.6". A particular TriBITS project can require a higher
634 version of TriBITS and this is set using, for example:
635
636 set(${PROJECT_NAME}_Python3_FIND_VERSION_DEFAULT "3.8")
637
638 in the `<projectDir>/ProjectName.cmake`_ file (See `Python Support`_). The
639 user can force a more recent version of Python by configuring with, for
640 example::
641
642 -D <Project>_Python3_FIND_VERSION="3.8"
643
644
645 .. _${PROJECT_NAME}_REQUIRES_PYTHON:
646
647 **${PROJECT_NAME}_REQUIRES_PYTHON**
648
649 If the TriBITS project requires Python, set::
650
651 set(${PROJECT_NAME}_REQUIRES_PYTHON TRUE)
652
653 in the `<projectDir>/ProjectName.cmake`_ file (See `Python Support`_). The
654 default is implicitly ``FALSE``.
655
656
657 .. _${PROJECT_NAME}_SET_INSTALL_RPATH:
658
659 **${PROJECT_NAME}_SET_INSTALL_RPATH**
660
661 The cache variable ``${PROJECT_NAME}_SET_INSTALL_RPATH`` is used to define
662 the default RPATH mode for the TriBITS project (see `Setting install RPATH`_
663 for details). The TriBITS default is to set this to ``TRUE`` but the
664 TriBITS project can be set the default to ``FALSE`` by setting::
665
666 set(${PROJECT_NAME}_SET_INSTALL_RPATH_DEFAULT FALSE)
667
668 in the project's `<projectDir>/ProjectName.cmake`_ file (see `RPATH
669 Handling`_).
670
671
672 .. _${PROJECT_NAME}_SHOW_GIT_COMMIT_PARENTS:
673
674 **${PROJECT_NAME}_SHOW_GIT_COMMIT_PARENTS**
675
676 The cache variable ``${PROJECT_NAME}_SHOW_GIT_COMMIT_PARENTS`` results in
677 the repo version file showing the parent commits for each repo commit. By
678 default, this variable is set to ``OFF`` but projects can set to to ``ON``
679 by default by setting::
680
681 set(${PROJECT_NAME}_SHOW_GIT_COMMIT_PARENTS_DEFAULT ON)
682
683 in the project's ``ProjectName.cmake`` file. (That way, it will also impact
684 ``cmake -P`` scripts don't configure the project itself to be built.)
685
686
687 .. _${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME:
688
689 **${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME**
690
691 The cache variable ``${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME``
692 determines if the start and end date/time for each advanced test (i.e. added
693 with `tribits_add_advanced_test()`_) is printed or not with each test. If
694 set to ``TRUE`` this also causes in the timing for each ``TEST_<IDX>`` block
695 to be printed as well. The TriBITS default is ``OFF`` but a TriBITS project
696 can change this default by setting::
697
698 set(${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME_DEFAULT ON)
699
700 The implementation of this feature currently uses ``execute_process(date)``
701 and therefore will work on many (but perhaps not all) Linux/Unix/Mac systems
702 and not on Windows systems.
703
704 NOTE: In a future version of CTest, this option may turn on start and end
705 date/time for regular tests added with `tribits_add_test()`_ (which uses a
706 raw command with ``add_test()``).
707
708 .. _${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES:
709
710 **${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES**
711
712 To change the default value of the
713 ``${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`` to ``TRUE``, for
714 example, for a TriBITS project, set::
715
716 set(${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES_DEFAULT TRUE)
717
718 in the project's `<projectDir>/CMakeLists.txt`_ or
719 `<projectDir>/ProjectName.cmake`_ files.
720
721 .. _${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE:
722
723 **${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE**
724
725 The cache variable ``${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE`` is set in the
726 `<projectDir>/ProjectName.cmake`_ file as::
727
728 set(${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE TRUE)
729
730 for projects that don't have a
731 `<projectDir>/cmake/ExtraRepositoriesList.cmake`_ file. This variable needs
732 to be set when using the CTest driver script and does not need to be set for
733 the basic configure and build process.
734
735 .. _${PROJECT_NAME}_TEST_CATEGORIES:
736 .. _${PROJECT_NAME}_TEST_CATEGORIES_DEFAULT:
737
738 **${PROJECT_NAME}_TEST_CATEGORIES**
739
740 The cache variable ``${PROJECT_NAME}_TEST_CATEGORIES`` determines what tests
741 defined using `tribits_add_test()`_ and `tribits_add_advanced_test()`_ will
742 be added for ``ctest`` to run (see `Test Test Category`_). The TriBITS
743 default is ``NIGHTLY`` for a standard local build. The `checkin-test.py`_
744 tool sets this to ``BASIC`` by default. A TriBITS project can override the
745 default for a basic configure using, for example::
746
747 set(${PROJECT_NAME}_TEST_CATEGORIES_DEFAULT BASIC)
748
749 The justification for having the default `Test Test Category`_ be
750 ``NIGHTLY`` instead of ``BASIC`` is that when someone is enabling a package
751 to develop on it or install it, we want them by default to be seeing the
752 full version of the test suite (shy of the `Test Test Category HEAVY`_
753 tests which can be very expensive) for the packages they are explicitly
754 enabling. Typically they will not be enabling forward/`downstream`_
755 dependent packages so the cost of running the test suite should not be too
756 prohibitive. This all depends on how good of a job the development teams do
757 in making their test suites run fast and keeping the cost of running the
758 tests down. See the section `TriBITS Automated Testing`_ for a more
759 detailed discussion.
760
761 .. _${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS:
762 .. _${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS_DEFAULT:
763
764 **${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS**
765
766 If ``${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS`` is set to ``TRUE``, then the
767 ``SYSTEM`` flag will be passed into the ``include_directories()`` command
768 for TPL include directories for every TPL for every package, by default. On
769 some systems this will result in include directories being passed to the
770 compiler with ``-isystem`` instead of ``-I``. This helps to avoid compiler
771 warning coming from TPL header files for C and C++. However, with CMake
772 version 3.2 and less, this also results in ``-isystem`` being passed to the
773 Fortran compiler (e.g. gfortran) as well. This breaks the reading of
774 Fortran module files (perhaps a bug in gfortran). Because of this issue
775 with Fortran, the TriBITS default for this option is set to ``FALSE`` but a
776 project can override the default using::
777
778 set(${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS_DEFAULT TRUE)
779
780 (This would be a good default if the project has not Fortran files or has
781 not Fortran files that use modules provided by TPLs).
782
783 However, if a package or subpackage sets::
784
785 set(${PACKAGE_NAME}_SKIP_TPL_SYSTEM_INCLUDE_DIRS TRUE)
786
787 in its ``CMakeLists.txt`` files before the ``tribits_add_library()`` or
788 ``tribits_add_executable()`` commands are called in that package, then
789 ``SYSTEM`` will **not** be passed into ``include_directories()`` for TPL
790 include dirs. This is how some TriBITS packages with Fortran files that use
791 Fortran modules avoid passing in ``-isystem`` to the Fortran compiles and
792 thereby avoid the defect with gfortran described above. If CMake version
793 3.3 or greater is used, this variable is not required.
794
795 NOTE: Currently, a TriBITS package must have a direct dependency on a TPL
796 to have ``-isystem`` added to a TPL's include directories on the compile
797 lines for that package. That is, the TPL must be listed in the
798 ``LIB_REQUIRED_TPLS`` or ``LIB_OPTIONAL_TPLS`` arguments passed into the
799 `tribits_package_define_dependencies()`_ function in the package's
800 `<packageDir>/cmake/Dependencies.cmake`_ file. In addition, to have
801 ``-isystem`` added to the include directories for a TPL when compiling the
802 tests for an package, it must be listed in the ``TEST_REQUIRED_TPLS`` or
803 ``TEST_OPTIONAL_TPLS`` arguments. This is a limitation of the TriBITS
804 implementation that will be removed in a future version of TriBITS.
805
806 .. _${PROJECT_NAME}_TRACE_ADD_TEST:
807 .. _${PROJECT_NAME}_TRACE_ADD_TEST_DEFAULT:
808
809 **${PROJECT_NAME}_TRACE_ADD_TEST**
810
811 If ``${PROJECT_NAME}_TRACE_ADD_TEST`` is set to ``TRUE``, then a single line
812 will be printed for each call to `tribits_add_test()`_ and
813 `tribits_add_advanced_test()`_ for if the test is added or not and if not
814 then why. The default is set based on the value of
815 ``${PROJECT_NAME}_VERBOSE_CONFIGURE`` but a project can override the default
816 by setting::
817
818 set(${PROJECT_NAME}_TRACE_ADD_TEST_DEFAULT TRUE)
819
820 .. _${PROJECT_NAME}_USE_GNUINSTALLDIRS:
821
822 **${PROJECT_NAME}_USE_GNUINSTALLDIRS**
823
824 If ``${PROJECT_NAME}_USE_GNUINSTALLDIRS`` is set to ``TRUE``, then the
825 default install paths will be determined by the standard CMake module
826 ``GNUInstallDirs``. Otherwise, platform independent install paths are used
827 by default.
828
829 A project can use the paths given the cmake module ``GNUInstallDirs`` by
830 default by setting::
831
832 set(${PROJECT_NAME}_USE_GNUINSTALLDIRS_DEFAULT TRUE)
833
834 in the project's top-level `<projectDir>/CMakeLists.txt`_ file or its
835 `<projectDir>/ProjectName.cmake`_ file. The default is ``FALSE``.
836
837 .. _${PROJECT_NAME}_USES_PYTHON:
838
839 **${PROJECT_NAME}_USES_PYTHON**
840
841 If the TriBITS project can use Python, but does not require it, set::
842
843 set(${PROJECT_NAME}_USES_PYTHON TRUE)
844
845 in the `<projectDir>/ProjectName.cmake`_ file (see `Python Support`_). The
846 default for a TriBITS project is implicitly ``TRUE``. To explicitly state
847 that Python is never needed, set::
848
849 set(${PROJECT_NAME}_USES_PYTHON FALSE)
850
851 .. _DART_TESTING_TIMEOUT:
852
853 **DART_TESTING_TIMEOUT**
854
855 The cache variable ``DART_TESTING_TIMEOUT`` is a built-in CMake variable
856 that provides a default timeout for all tests (see `Setting test timeouts at
857 configure time`_). By default, TriBITS defines this to be 1500 seconds
858 (which is also the raw CMake default) but the project can change this
859 default, from 1500 to 300 for example, by setting the following in the
860 project's `<projectDir>/ProjectName.cmake`_ or
861 `<projectDir>/CMakeLists.txt`_ file::
862
863 set(DART_TESTING_TIMEOUT_DEFAULT 300)
864
865 .. _CMAKE_INSTALL_RPATH_USE_LINK_PATH:
866
867 **CMAKE_INSTALL_RPATH_USE_LINK_PATH**
868
869 The cache variable ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` is a built-in CMake
870 variable that determines if the paths for external libraries (i.e. from
871 TPLs) is put into the installed library RPATHS (see `RPATH Handling`_).
872 TriBITS sets the default for this to ``TRUE`` but a project can change the
873 default back to ``FALSE`` by setting the following in the project's
874 `<projectDir>/ProjectName.cmake`_ file::
875
876 set(CMAKE_INSTALL_RPATH_USE_LINK_PATH_DEFAULT FALSE)
877
878 .. _MPI_EXEC_MAX_NUMPROCS:
879
880 **MPI_EXEC_MAX_NUMPROCS**
881
882 The variable ``MPI_EXEC_MAX_NUMPROCS`` gives the maximum number of processes
883 for an MPI test that will be allowed as defined by `tribits_add_test()`_ and
884 `tribits_add_advanced_test()`_. The TriBITS default is set to be ``4`` (for
885 no good reason really but it needs to stay that way for backward
886 compatibility). This default can be changed by setting::
887
888 set(MPI_EXEC_MAX_NUMPROCS_DEFAULT <newDefaultMax>)
889
890 While this default can be changed for the project as a whole on all
891 platforms, it is likely better to change this default on a
892 machine-by-machine basis to correspond to the load that can be accommodated
893 by a given machine (or class of machines). For example if a given machine
894 has 64 cores, a reasonable number for ``MPI_EXEC_MAX_NUMPROCS_DEFAULT`` is
895 64.
896
897 .. _TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE:
898
899 **TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE**
900
901 Determines how the function `tribits_deprecated()`_ behaves. To change the
902 default behavior, such as call ``message(FATAL_ERROR ...)``, set::
903
904 set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT FATAL_ERROR)
905
906 in the project's `<projectDir>/ProjectName.cmake`_ file, or
907 `<projectDir>/CMakeLists.txt`_ file, or on the individual package basis in
908 its `<packageDir>/CMakeLists.txt`_ file.
909
910
911 TriBITS Macros and Functions
912 ----------------------------
913
914 The following subsections give detailed documentation for the CMake macros and
915 functions that make up the core TriBITS system. These are what are used by
916 TriBITS project developers in their ``CMakeLists.txt`` and other files. All
917 of these functions and macros should be automatically available when
918 processing the project's and package's variables files if used properly.
919 Therefore, no explicit ``include()`` statements should be needed other than
920 the initial include of the ``TriBITS.cmake`` file in the top-level
921 `<projectDir>/CMakeLists.txt`_ file so the command `tribits_project()`_ can be
922 executed.
923
924 .. include:: TribitsMacroFunctionDoc.rst
925
926
927 General Utility Macros and Functions
928 ------------------------------------
929
930 The following subsections give detailed documentation for some CMake macros
931 and functions which are *not* a core part of the TriBITS system but are
932 included in the TriBITS source tree, are used inside of the TriBITS system,
933 and are provided as a convenience to TriBITS project developers. One will see
934 many of these functions and macros used throughout the implementation of
935 TriBITS and even in the ``CMakeLists.txt`` files for different projects that
936 use TriBITS.
937
938 These macros and functions are *not* prefixed with ``TRIBITS_``. However,
939 there is really not a large risk to defining and using these non-namespaces
940 utility functions and macros. It turns out that CMake allows one to redefine
941 any macro or function, even built-in ones, inside of one's project.
942 Therefore, even if CMake did add new commands that clashed with these names,
943 there would be no conflict. When overriding a built-in command,
944 e.g. ``some_builtin_command()``, one can always access the original built-in
945 command as ``_some_builtin_command()``.
946
947 .. include:: UtilsMacroFunctionDoc.rst
948
949
950 .. *** NOTE: This file is symlinked into users_guide/ and maintainers_guide/
951 .. *** and the symlinked file gets included in the top-level *.rst document.
952 .. *** This is so that the includes for the generated files
953 .. *** TribitsMacroFunctionDoc.rst and UtilsMacroFunctionDoc.rst in those
954 .. *** directories work correctly.