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