lib
/
EXODUS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Cloned SEACAS for EXODUS library with extra build files for internal package management.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1 Commit
1 Branch
0 Tags
19 MiB
Tag: Branch: Tree: 96dbec27e0
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '96dbec27e0'
${ noResults }
EXODUS/cmake/tribits/doc/guides/TribitsCoreDetailedReferenc...

938 lines
41 KiB
Raw Normal View History Unescape

Initial commit
2 years ago
TriBITS Detailed Reference Documentation
========================================
The following subsections contain detailed reference documentation for the
various TriBITS variables, functions, and macros that are used by TriBITS
projects that `TriBITS Project Developers`_ need to know about. Variables,
functions and macros that are used only internally in TriBITS are generally
not documented here (see the TriBITS ``*.cmake`` source files).
TriBITS Global Project Settings
-------------------------------
TriBITS defines a number of global project-level settings that can be set by
the user and can have their default determined by each individual TriBITS
project. If a given TriBITS project does not define its own default, a
reasonable default is set by the TriBITS system automatically. These options
are defined and are set, for the most part, in the internal TriBITS function
``tribits_define_global_options_and_define_extra_repos()`` in the TriBITS
CMake code file ``TribitsGlobalMacros.cmake`` which gets called inside of the
`tribits_project()`_ macro. That function and that file are the definitive
source the options that a TriBITS project takes and what the default values
are but we strive to document them here as well. Many of these global options
(i.e. cache variables) such as ``${PROJECT_NAME}_<SOME_OPTION>`` allow the
project to define a default by setting a local variable
``${PROJECT_NAME}_<SOME_OPTION>_DEFAULT`` as::
set(${PROJECT_NAME}_<SOME_OPTION>_DEFAULT <someDefault>)
either in its top-level ``CMakeLists.txt`` file or in its
``ProjectName.cmake`` file (depends on what variable it is as to where it
should be set). If ``${PROJECT_NAME}_<SOME_OPTION>_DEFAULT`` is not set by
the project, then TriBITS provides a reasonable default value. The TriBITS
code that uses these defaults for this looks like::
if ("${${PROJECT_NAME}_<SOME_OPTION>_DEFAULT}" STREQUAL "")
set(${PROJECT_NAME}_<SOME_OPTION>_DEFAULT <someDefault>)
endif()
advanced_set( ${PROJECT_NAME}_<SOME_OPTION>
${PROJECT_NAME}_<SOME_OPTION>_DEFAULT}
CACHE BOOL "[documentation]."
)
where ``<SOME_OPTION>`` is an option name, for example like
``TEST_CATEGORIES``, and ``<someDefault>`` is the default set by TriBITS if
the project does not define a default. In this way, if the project sets the
variable ``${PROJECT_NAME}_<SOME_OPTION>_DEFAULT`` before this code executes,
then ``${${PROJECT_NAME}_<SOME_OPTION>_DEFAULT}`` will be used as the default
for the cache variable ``${PROJECT_NAME}_<SOME_OPTION>`` which, of course, can
be overridden by the user when calling ``cmake`` in a number of ways.
Most of these global options that can be overridden externally by setting the
cache variable ``${PROJECT_NAME}_<SOME_OPTION>`` should be documented in the
`Project-Specific Build Reference`_ document. A generic version of this
document is found in `TribitsBuildReference`_. Some of the more unusual
options that might only be of interest to developers mentioned below may not
be documented in `TribitsBuildReference`_.
The global project-level TriBITS options for which defaults can be provided by
a given TriBITS project are:
* `${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE`_
* `${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES`_
* `${PROJECT_NAME}_C_Standard`_
* `${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`_
* `${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND`_
* `${PROJECT_NAME}_CPACK_SOURCE_GENERATOR`_
* `${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE`_
* `${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES`_
* `${PROJECT_NAME}_ELEVATE_ST_TO_PT`_
* `${PROJECT_NAME}_ENABLE_CPACK_PACKAGING`_
* `${PROJECT_NAME}_ENABLE_CXX`_
* `${PROJECT_NAME}_ENABLE_C`_
* `${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`_
* `${PROJECT_NAME}_ENABLE_Fortran`_
* `${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES`_
* `${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE`_
* `${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION`_
* `${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES`_
* `${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES`_
* `${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE`_
* `${PROJECT_NAME}_IMPORTED_NO_SYSTEM`_
* `${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS`_
* `${PROJECT_NAME}_MAKE_INSTALL_GROUP_READABLE`_
* `${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE`_
* `${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE`_
* `${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS`_
* `${PROJECT_NAME}_REQUIRES_PYTHON`_
* `${PROJECT_NAME}_SET_INSTALL_RPATH`_
* `${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME`_
* `${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`_
* `${PROJECT_NAME}_TEST_CATEGORIES`_
* `${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS`_
* `${PROJECT_NAME}_TRACE_ADD_TEST`_
* `${PROJECT_NAME}_USE_GNUINSTALLDIRS`_
* `${PROJECT_NAME}_USES_PYTHON`_
* `DART_TESTING_TIMEOUT`_
* `CMAKE_INSTALL_RPATH_USE_LINK_PATH`_
* `MPI_EXEC_MAX_NUMPROCS`_
* `PythonInterp_FIND_VERSION`_
* `TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE`_
These options are described below.
.. _${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE:
**${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE**
The CMake cache variable ``${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE`` is
used to define how some invalid TriBITS usage checks are handled. The valid
values include 'FATAL_ERROR', 'SEND_ERROR', 'WARNING', and 'IGNORE'. The
default value is 'FATAL_ERROR' for a project when
``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=ON``, which is best for
development mode for a project that currently has no invalid usage patterns.
The default is 'IGNORE' when
``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=OFF``. But a project with some
existing invalid usage patterns might want to set, for example, a default of
'WARNING' in order to allow for a smooth upgrade of TriBITS. To do so,
set::
set(${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT WARNING)
in the project's base `<projectDir>/ProjectName.cmake`_ file.
.. _${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES:
**${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES**
To set ``${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES`` a different default,
set::
set(${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES_DEFAULT <newDefault>)
in the project's base `<projectDir>/ProjectName.cmake`_ file, where
``<newDefault>`` can be ``FATAL_ERROR``, ``SEND_ERROR``, ``WARNING``,
``NOTICE`` or ``IGNORE``
Otherwise, the default is ``WARNING`` when
``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` is ``ON`` and if ``IGNORE`` if
``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` is ``OFF``.
.. _${PROJECT_NAME}_C_Standard:
**${PROJECT_NAME}_C_Standard**
The variable ``${PROJECT_NAME}_C_Standard`` is used define the C standard
pass to the compiler in ``--std=<cstd>`` for GCC builds of the project.
TriBITS sets the default as ``c99`` but the project can set a new default in
the project's base `<projectDir>/CMakeLists.txt`_ file with, for example::
set(${PROJECT_NAME}_C_Standard_DEFAULT c11)
.. _${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS:
**${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS**
The variable ``${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`` determines how
unparsed and otherwise ignored arguments are handled in TriBITS functions
that are called by the client TriBITS projects. These are arguments that
are left over from parsing input options to functions and macros that take
both positional arguments and keyword arguments/options handled with the
``cmake_parse_arguments()`` function. For example, for the a TriBITS
function declared like::
tribits_copy_files_to_binary_dir(
<targetName>
[SOURCE_FILES <file1> <file2> ...]
[SOURCE_DIR <sourceDir>]
...
)
the arguments ``SOURCE_FILES <file1> <file2> ...`` and those that follow are
parsed by the ``cmake_parse_arguments()`` function while the argument
``<targetName>`` is a positional argument. The problem is that any
arguments passed between the first ``<targetName>`` argument and the
specified keyword arguments like ``SOURCE_FILES`` and ``SOURCE_DIR`` are
returned as unparsed arguments and are basically ignored (which is what
happened in earlier versions of TriBITS). For example, calling the function
as::
tribits_copy_files_to_binary_dir( FooTestCopyFiles
ThisArgumentIsNotParsedAndIsIgnored
SOURCE_FILES file1.cpp file2.cpp ...
...
)
would result in the unparsed argument
``ThisArgumentIsNotParsedAndIsIgnored``.
The value of ``${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`` determines how
that ignored argument is handled. If the value is ``WARNING``, then it will
just result in a ``message(WARNING ...)`` command that states the warning
but configure is allowed to be completed. This would be the right value to
allow an old TriBITS project to keep configuring until the warnings can be
cleaned up. If the value is ``SEND_ERROR``, then ``message(SEND_ERROR
...)`` is called. This will result in the configure failing but will allow
configure to continue until the end (or a ``FATAL_ERROR`` is raised). This
would be the right value when trying to upgrade a TriBITS project where you
wanted to see all of the warnings when upgrading TriBITS (so you could fix
them all in one shot). Finally, the value of ``FATAL_ERROR`` will result in
``message(FATAL_ERROR ...)`` being called which will halt configure right
away. This is the best value when developing on a TriBITS project that is
already clean but you want to catch new developer-inserted errors right
away.
The default value for ``${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`` is
``WARNING``, so that it will be backward compatible for TriBITS projects
that might have previously undetected unparased and therefore ignored
argument . However, a project can change the default by setting, for
example::
set(${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS_DEFAULT FATAL_ERROR)
in the `<projectDir>/ProjectName.cmake`_ file.
The user of a TriBITS project should not be able to trigger this unparsed
arguments condition so this variable is not documented in the `TriBITS Build
Reference`_. But it is still a CMake cache var that is documented in the
CMakeCache.txt file and can be set by the user or developer if desired.
.. _${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND:
**${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND**
The variable ``${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND`` is used to
define the absolute path to a file (or a list of files) that should be
included after the files listed in
``${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE``. This variable can be used by
the TriBITS project to define, for example, a standard set of development
environments in the base `<projectDir>/CMakeLists.txt`_ file with::
set(${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND_DEFAULT
"${CMAKE_CURRENT_LIST_DIR}/cmake/StdDevEnvs.cmake")
**before** the `tribits_project()`_ command. By including this file(s)
after the file(s) listed in ``${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE``, the
user can override the variables set in this appended file(s). But it is
important that these variables best set after the users options have been
set but before the Package and TPL dependency analysis is done (because this
might enable or disable some TPLs).
.. _${PROJECT_NAME}_CPACK_SOURCE_GENERATOR:
**${PROJECT_NAME}_CPACK_SOURCE_GENERATOR**
The variable ``${PROJECT_NAME}_CPACK_SOURCE_GENERATOR`` determines the CPack
source generation types that are created when the ``package_source`` target
is run. The TriBITS default is set to ``TGZ``. However, this default can
be overridden by setting, for example::
set(${PROJECT_NAME}_CPACK_SOURCE_GENERATOR_DEFAULT "TGZ;TBZ2")
This variable should generally be set in the file::
<projectDir>/cmake/CallbackDefineProjectPackaging.cmake
instead of in the base-level ``CMakeLists.txt`` file so that it goes along
with rest of the project-specific CPack packaging options.
.. _${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE:
**${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE**
The variable ``${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE`` determines if the
CTest driver scripts using `tribits_ctest_driver()`_ configure, build, test
and submit results to CDash all-at-once for all of the packages being tested
or if instead is done package-by-package. Currently, the default is set to
``FALSE`` for the package-by-package mode (for historical reasons) but the
default can be set to ``TRUE`` by setting:
set(${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE_DEFAULT "TRUE")
in the project's `<projectDir>/ProjectName.cmake`_ file. (This default must
be changed in the ``<projectDir>/ProjectName.cmake`` file and **NOT** the
`<projectDir>/CMakeLists.txt`_ file because the latter is not directly
processed in CTest -S driver scripts using ``tribits_ctest_driver()``.)
In general, a project should change the default to ``TRUE`` when using a
newer CDash installation with CDash versions 3.0+ that can accommodate the
results coming from ctest -S and display them package-by-package very
nicely. Otherwise, most projects are better off with package-by-package
mode since it results in nicer display on CDash for older CDash versions.
.. _${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES:
**${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES**
If `${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=ON`_ (the TriBITS
default value), then any explicitly enabled packages that have disabled
`upstream`_ required packages or TPLs will be disabled. If
`${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=OFF`_, then an
configure error will occur. For more details also see
`TribitsBuildReference`_ and `Disables trump enables where there is a
conflict`_. A project can define a different default value by setting::
set(${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES_DEFAULT FALSE)
.. _${PROJECT_NAME}_ELEVATE_ST_TO_PT:
**${PROJECT_NAME}_ELEVATE_ST_TO_PT**
If ``${PROJECT_NAME}_ELEVATE_ST_TO_PT`` is set to ``ON``, then all ``ST``
packages will be elevated to ``PT`` packages. The TriBITS default is
obviously ``OFF``. The default can be changed by setting::
set(${PROJECT_NAME}_ELEVATE_ST_TO_PT_DEFAULT ON)
There are projects, especially meta-projects, where the distinction between
``PT`` and ``ST`` code is not helpful or the assignment of ``PT`` and ``ST``
packages in a repository is not appropriate with respect to the outer
meta-project. An example project like this CASL VERA. Changing the default
to ``ON`` allows any and packages to be considered in pre-push testing.
.. _${PROJECT_NAME}_ENABLE_CPACK_PACKAGING:
**${PROJECT_NAME}_ENABLE_CPACK_PACKAGING**
If ``${PROJECT_NAME}_ENABLE_CPACK_PACKAGING`` is ``ON``, then CPack support
is enabled and some TriBITS code is run that is needed to set up
data-structures that are used by the built-in CMake target
``package_source``. The TriBITS default is ``OFF`` with the idea that the
average developer or user will not be wanting to create source distributions
with CPack. However, this default can be changed by setting::
set(${PROJECT_NAME}_ENABLE_CPACK_PACKAGING_DEFAULT ON)
.. _${PROJECT_NAME}_ENABLE_CXX:
**${PROJECT_NAME}_ENABLE_CXX**
If ``${PROJECT_NAME}_ENABLE_CXX`` is ``ON``, then C++ language support for
the project will be enabled and the C++ compiler must be found. By default,
TriBITS sets this to ``ON`` for all systems. A project never requires C++
can set this to off by default by setting:
set(${PROJECT_NAME}_ENABLE_CXX_DEFAULT FALSE)
.. _${PROJECT_NAME}_ENABLE_C:
**${PROJECT_NAME}_ENABLE_C**
If ``${PROJECT_NAME}_ENABLE_C`` is ``ON``, then C language support for the
project will be enabled and the C compiler must be found. By default,
TriBITS sets this to ``ON`` for all systems. A project never requires C can
set this to off by default by setting:
set(${PROJECT_NAME}_ENABLE_C_DEFAULT FALSE)
If a project does not have any native C code a good default would be::
set(${PROJECT_NAME}_ENABLE_C_DEFAULT FALSE)
NOTE: It is usually not a good idea to always force off C, or any compiler,
because extra repositories and packages might be added by someone that might
require the compiler and we don't want to unnecessarily limit the generality
of a given TriBITS build. Setting the default for all platforms should be
sufficient.
.. _${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE:
.. _${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT:
**${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE**
The variable ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` switches the
TriBITS project from development mode to release mode. The default for this
variable ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT`` should be set
in the project's `<projectDir>/Version.cmake`_ file and switched from ``ON``
to ``OFF`` when creating a release (see `Project and Repository Versioning
and Release Mode`_). When ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE`` is
``ON``, several other variables are given defaults appropriate for
development mode. For example,
``${PROJECT_NAME}_ASSERT_DEFINED_DEPENDENCIES`` is set to ``FATAL_ERROR`` by
default in development mode but is set to ``IGNORE`` by default in release
mode. In addition, strong compiler warnings are enabled by default in
development mode but are disabled by default in release mode. This variable
also affects the behavior of `tribits_set_st_for_dev_mode()`_.
.. _${PROJECT_NAME}_ENABLE_Fortran:
**${PROJECT_NAME}_ENABLE_Fortran**
If ``${PROJECT_NAME}_ENABLE_Fortran`` is ``ON``, then Fortran support for
the project will be enabled and the Fortran compiler(s) must be found. By
default, TriBITS sets this to ``ON`` .
If a project does not have any native Fortran code a good default would be::
set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF)
This default can be set in `<projectDir>/ProjectName.cmake`_ or `<projectDir>/CMakeLists.txt`_.
On WIN32 systems, the default for ``${PROJECT_NAME}_ENABLE_Fortran_DEFAULT``
is set to ``OFF`` since it can be difficult to get a Fortran compiler for
native Windows.
Given that a native Fortran compiler is not supported by default on Windows
and on most Mac OSX systems, projects that have optional Fortran code may
decide to set the default depending on the platform by setting, for example::
if ( (WIN32 AND NOT CYGWIN) OR (CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin") )
message(STATUS "Warning: Setting ${PROJECT_NAME}_ENABLE_Fortran=OFF by default"
" because this is Windows (not cygwin) and we assume to not have Fortran!")
set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF)
else()
set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT ON)
endif()
NOTE: It is usually not a good idea to always force off Fortran, or any
compiler, because extra repositories and packages might be added by someone
that might require the compiler and we don't want to unnecessarily limit the
generality of a given TriBITS build. Setting the default for all platforms
should be sufficient.
.. _${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES:
**${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES**
If ``${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES`` is set to ``ON``,
then ``<PackageName>Config.cmake`` files are created at configure time in
the build tree and installed into the install tree. These files are used by
external CMake projects to pull in the list of compilers, compiler options,
include directories and libraries. The TriBITS default is ``OFF`` but a
project can change the default by setting, for example::
set(${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES_DEFAULT ON)
A project would want to leave off the creation and installation of
``<PackageName>Config.cmake`` files if it was only installing and providing
executables (see `${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS`_).
However, if it is wanting to provide libraries for other projects to use,
then it should turn on the default generation of these files.
.. _${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE:
**${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE**
If ``${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE`` is ``ON``, then packages
and subpackages marked as ``ST`` in the `<repoDir>/PackagesList.cmake`_ file
will be implicitly enabled along with the ``PT`` packages. Additional code
and tests may also be enabled using this option. The TriBITS default is
``OFF`` but this can be changed by setting::
set(${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE_DEFAULT ON)
in the `<projectDir>/ProjectName.cmake`_ file.
.. _${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION:
**${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION**
If ``${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION`` is
``TRUE``, then the directories for subpackages that are not enabled are left
out of the source tarball. This reduces the size of the tarball as much as
possible but does require that the TriBITS packages and subpackages be
properly set up to allow disabled subpackages from being excluded. The
TriBITS default is ``TRUE`` but this can be changed by setting::
set(${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION_DEFAULT FALSE)
.. _${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES:
**${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES**
If ``${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES`` is ``ON``, then the
data-structures needed to generate ``<PackageName>Config.cmake`` files are
created. These data structures are also needed in order to generate export
makefiles on demand using the function
`tribits_write_flexible_package_client_export_files()`_. The default in
TriBITS is to turn this ``ON`` automatically by default if
``${PROJECT_NAME}_ENABLE_INSTALL_CMAKE_CONFIG_FILES`` is ``ON``. Else, by
default, TriBITS sets this to ``OFF``. The only reason for the project to
override the default is to set it to ``ON`` as with::
set(${PROJECT_NAME}_GENERATE_EXPORT_FILE_DEPENDENCIES_DEFAULT ON)
is so that the necessary data-structures are generated in order to use the
function `tribits_write_flexible_package_client_export_files()`_.
.. _${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES:
**${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES**
If ``${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES`` is ``ON``, then the files
``VersionDate.cmake`` and ``<RepoName>_version_date.h`` will get generated
and the generated file ``<RepoName>_version_date.h`` will get installed for
each TriBITS version-controlled repository when the local directories are
git repositories. The default is ``OFF`` but the project can change that by
setting::
set(${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES ON)
in the `<projectDir>/ProjectName.cmake`_ file.
.. _${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE:
**${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE**
If ``${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE`` is ``ON``, then the file
``<Project>RepoVersion.txt`` will get generated as a byproduct of
configuring with CMake. See `Multi-Repository Support`_ and
`<Project>_GENERATE_REPO_VERSION_FILE`_. The default is ``OFF`` but the
project can change that by setting::
set(${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE_DEFAULT ON)
in the `<projectDir>/ProjectName.cmake`_ file.
Note that if a ``git`` exectauble cannot be found at configure time, then
the default ``${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE_DEFAULT`` will be
overridden to ``OFF``. But if the user sets
``${PROJECT_NAME}_GENERATE_REPO_VERSION_FILE=ON`` in the cache and ``git``
can't be found, then an configure-time error will occur.
.. _${PROJECT_NAME}_IMPORTED_NO_SYSTEM:
**${PROJECT_NAME}_IMPORTED_NO_SYSTEM**
By default, include directories from IMPORTED library targets from the
TriBITS project's installed ``<Package>Config.cmake`` files will be
considered ``SYSTEM`` headers and therefore be included on the compile lines
of downstream CMake projects with ``-isystem`` with most compilers.
However, if ``${PROJECT_NAME}_IMPORTED_NO_SYSTEM`` is set to ``ON`` (only
supported for CMake versions 3.23 or greater), then all of the IMPORTED
library targets exported into the set of installed ``<Package>Config.cmake``
files will have the ``IMPORTED_NO_SYSTEM`` property set. This will cause
downstream customer CMake projects to apply the include directories from
these IMPORTED library targets as non-system include directories. On most
compilers, that means that the include directories will be listed on the
compile lines with ``-I`` instead of with ``-isystem``. (See more details
in the TriBITS Build Reference for ``<Project>_IMPORTED_NO_SYSTEM``.)
The default value set by TriBITS itself is ``OFF`` but a TriBITS project can
change the default value to ``ON`` by adding::
if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.23)
set(${PROJECT_NAME}_IMPORTED_NO_SYSTEM_DEFAULT ON)
endif()
in the `<projectDir>/ProjectName.cmake`_ file. (NOTE: The above ``if()``
statement ensures that a configure error will not occur if a version of
CMake less than 3.23 is used. But if the TriBITS project minimum CMake
version is 3.23 or greater, then the above ``if()`` statement guard can be
removed.)
.. _${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS:
**${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS**
If ``${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS`` is set to ``ON``, then
any defined libraries or header files that are listed in calls to
`tribits_add_library()`_ or `tribits_install_headers()`_ will be installed
(unless options are passed into `tribits_add_library()`_ that disable
installs). If set to ``OFF``, then headers and libraries will *not* be
installed by default and only ``INSTALLABLE`` executables added with
`tribits_add_executable()`_ will be installed. However, as described in
`TribitsBuildReference`_, shared libraries will always be installed if
enabled since they are needed by the installed executables.
For a TriBITS project that is primarily delivering libraries
(e.g. Trilinos), then it makes sense to leave the TriBITS default which is
``ON`` or explicitly set::
set(${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS_DEFAULT ON)
For a TriBITS project that is primarily delivering executables (e.g. VERA),
then it makes sense to set the default to::
set(${PROJECT_NAME}_INSTALL_LIBRARIES_AND_HEADERS_DEFAULT OFF)
.. _${PROJECT_NAME}_MAKE_INSTALL_GROUP_READABLE:
.. _${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE:
.. _${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE:
**${PROJECT_NAME}_MAKE_INSTALL_GROUP_READABLE**
**${PROJECT_NAME}_MAKE_INSTALL_GROUP_WRITABLE**
**${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE**
Determines the permissions for directories and files created during the
execution of the of the ``install`` and ``isntall_package_by_package``
targets.
To make the created directories by only group readable for the project by
default, set::
set(${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE_DEFAULT TRUE)
To make the created directories by only group writable (and readable) for
the project by default, set::
set(${PROJECT_NAME}_MAKE_INSTALL_WORLD_WRITABLE_DEFAULT TRUE)
To make the created directories by world readable for the project by
default, set::
set(${PROJECT_NAME}_MAKE_INSTALL_WORLD_READABLE_DEFAULT TRUE)
On non-Windows systems, these set permissions for all files and directories
from the the user-set base directory
``${PROJECT_NAME}_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR`` on down.
For more details see `Installation considerations`_.
These defaults can be set in the `<projectDir>/ProjectName.cmake`_ file.
.. _${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS:
**${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS**
Determines if all of the libraries listed in ``<tplName>_LIBRARY_NAMES`` for
a given TPL must be found for each enabled TPL. By default, this is
``FALSE`` which means that the determination if all of the listed libs for a
TPL should be found is determined by the ``MUST_FIND_ALL_LIBS`` option to
the `tribits_tpl_find_include_dirs_and_libraries()`_ function in the TPL
find module. To change the default for this, set::
set(${PROJECT_NAME}_MUST_FIND_ALL_TPL_LIBS_DEFAULT TRUE)
in the `<projectDir>/ProjectName.cmake`_ file.
.. _${PROJECT_NAME}_REQUIRES_PYTHON:
**${PROJECT_NAME}_REQUIRES_PYTHON**
If the TriBITS project requires Python, set::
set(${PROJECT_NAME}_REQUIRES_PYTHON TRUE)
in the `<projectDir>/ProjectName.cmake`_ file (See `Python Support`_). The
default is implicitly ``FALSE``.
.. _${PROJECT_NAME}_SET_INSTALL_RPATH:
**${PROJECT_NAME}_SET_INSTALL_RPATH**
The cache variable ``${PROJECT_NAME}_SET_INSTALL_RPATH`` is used to define
the default RPATH mode for the TriBITS project (see `Setting install RPATH`_
for details). The TriBITS default is to set this to ``TRUE`` but the
TriBITS project can be set the default to ``FALSE`` by setting::
set(${PROJECT_NAME}_SET_INSTALL_RPATH_DEFAULT FALSE)
in the project's `<projectDir>/ProjectName.cmake`_ file (see `RPATH
Handling`_).
.. _${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME:
**${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME**
The cache variable ``${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME``
determines if the start and end date/time for each advanced test (i.e. added
with `tribits_add_advanced_test()`_) is printed or not with each test. If
set to ``TRUE`` this also causes in the timing for each ``TEST_<IDX>`` block
to be printed as well. The TriBITS default is ``OFF`` but a TriBITS project
can change this default by setting::
set(${PROJECT_NAME}_SHOW_TEST_START_END_DATE_TIME_DEFAULT ON)
The implementation of this feature currently uses ``execute_process(date)``
and therefore will work on many (but perhaps not all) Linux/Unix/Mac systems
and not on Windows systems.
NOTE: In a future version of CTest, this option may turn on start and end
date/time for regular tests added with `tribits_add_test()`_ (which uses a
raw command with ``add_test()``).
.. _${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES:
**${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES**
To change the default value of the
``${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES`` to ``TRUE``, for
example, for a TriBITS project, set::
set(${PROJECT_NAME}_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES_DEFAULT TRUE)
in the project's `<projectDir>/CMakeLists.txt`_ or
`<projectDir>/ProjectName.cmake`_ files.
.. _${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE:
**${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE**
The cache variable ``${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE`` is set in the
`<projectDir>/ProjectName.cmake`_ file as::
set(${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE TRUE)
for projects that don't have a
`<projectDir>/cmake/ExtraRepositoriesList.cmake`_ file. This variable needs
to be set when using the CTest driver script and does not need to be set for
the basic configure and build process.
.. _${PROJECT_NAME}_TEST_CATEGORIES:
.. _${PROJECT_NAME}_TEST_CATEGORIES_DEFAULT:
**${PROJECT_NAME}_TEST_CATEGORIES**
The cache variable ``${PROJECT_NAME}_TEST_CATEGORIES`` determines what tests
defined using `tribits_add_test()`_ and `tribits_add_advanced_test()`_ will
be added for ``ctest`` to run (see `Test Test Category`_). The TriBITS
default is ``NIGHTLY`` for a standard local build. The `checkin-test.py`_
tool sets this to ``BASIC`` by default. A TriBITS project can override the
default for a basic configure using, for example::
set(${PROJECT_NAME}_TEST_CATEGORIES_DEFAULT BASIC)
The justification for having the default `Test Test Category`_ be
``NIGHTLY`` instead of ``BASIC`` is that when someone is enabling a package
to develop on it or install it, we want them by default to be seeing the
full version of the test suite (shy of the `Test Test Category HEAVY`_
tests which can be very expensive) for the packages they are explicitly
enabling. Typically they will not be enabling forward/`downstream`_
dependent packages so the cost of running the test suite should not be too
prohibitive. This all depends on how good of a job the development teams do
in making their test suites run fast and keeping the cost of running the
tests down. See the section `TriBITS Automated Testing`_ for a more
detailed discussion.
.. _${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS:
.. _${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS_DEFAULT:
**${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS**
If ``${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS`` is set to ``TRUE``, then the
``SYSTEM`` flag will be passed into the ``include_directories()`` command
for TPL include directories for every TPL for every package, by default. On
some systems this will result in include directories being passed to the
compiler with ``-isystem`` instead of ``-I``. This helps to avoid compiler
warning coming from TPL header files for C and C++. However, with CMake
version 3.2 and less, this also results in ``-isystem`` being passed to the
Fortran compiler (e.g. gfortran) as well. This breaks the reading of
Fortran module files (perhaps a bug in gfortran). Because of this issue
with Fortran, the TriBITS default for this option is set to ``FALSE`` but a
project can override the default using::
set(${PROJECT_NAME}_TPL_SYSTEM_INCLUDE_DIRS_DEFAULT TRUE)
(This would be a good default if the project has not Fortran files or has
not Fortran files that use modules provided by TPLs).
However, if a package or subpackage sets::
set(${PACKAGE_NAME}_SKIP_TPL_SYSTEM_INCLUDE_DIRS TRUE)
in its ``CMakeLists.txt`` files before the ``tribits_add_library()`` or
``tribits_add_executable()`` commands are called in that package, then
``SYSTEM`` will **not** be passed into ``include_directories()`` for TPL
include dirs. This is how some TriBITS packages with Fortran files that use
Fortran modules avoid passing in ``-isystem`` to the Fortran compiles and
thereby avoid the defect with gfortran described above. If CMake version
3.3 or greater is used, this variable is not required.
NOTE: Currently, a TriBITS package must have a direct dependency on a TPL
to have ``-isystem`` added to a TPL's include directories on the compile
lines for that package. That is, the TPL must be listed in the
``LIB_REQUIRED_TPLS`` or ``LIB_OPTIONAL_TPLS`` arguments passed into the
`tribits_package_define_dependencies()`_ function in the package's
`<packageDir>/cmake/Dependencies.cmake`_ file. In addition, to have
``-isystem`` added to the include directories for a TPL when compiling the
tests for an package, it must be listed in the ``TEST_REQUIRED_TPLS`` or
``TEST_OPTIONAL_TPLS`` arguments. This is a limitation of the TriBITS
implementation that will be removed in a future version of TriBITS.
.. _${PROJECT_NAME}_TRACE_ADD_TEST:
.. _${PROJECT_NAME}_TRACE_ADD_TEST_DEFAULT:
**${PROJECT_NAME}_TRACE_ADD_TEST**
If ``${PROJECT_NAME}_TRACE_ADD_TEST`` is set to ``TRUE``, then a single line
will be printed for each call to `tribits_add_test()`_ and
`tribits_add_advanced_test()`_ for if the test is added or not and if not
then why. The default is set based on the value of
``${PROJECT_NAME}_VERBOSE_CONFIGURE`` but a project can override the default
by setting::
set(${PROJECT_NAME}_TRACE_ADD_TEST_DEFAULT TRUE)
.. _${PROJECT_NAME}_USE_GNUINSTALLDIRS:
**${PROJECT_NAME}_USE_GNUINSTALLDIRS**
If ``${PROJECT_NAME}_USE_GNUINSTALLDIRS`` is set to ``TRUE``, then the
default install paths will be determined by the standard CMake module
``GNUInstallDirs``. Otherwise, platform independent install paths are used
by default.
A project can use the paths given the cmake module ``GNUInstallDirs`` by
default by setting::
set(${PROJECT_NAME}_USE_GNUINSTALLDIRS_DEFAULT TRUE)
in the project's top-level `<projectDir>/CMakeLists.txt`_ file or its
`<projectDir>/ProjectName.cmake`_ file. The default is ``FALSE``.
.. _${PROJECT_NAME}_USES_PYTHON:
**${PROJECT_NAME}_USES_PYTHON**
If the TriBITS project can use Python, but does not require it, set::
set(${PROJECT_NAME}_USES_PYTHON TRUE)
in the `<projectDir>/ProjectName.cmake`_ file (see `Python Support`_). The
default for a TriBITS project is implicitly ``TRUE``. To explicitly state
that Python is never needed, set::
set(${PROJECT_NAME}_USES_PYTHON FALSE)
.. _DART_TESTING_TIMEOUT:
**DART_TESTING_TIMEOUT**
The cache variable ``DART_TESTING_TIMEOUT`` is a built-in CMake variable
that provides a default timeout for all tests (see `Setting test timeouts at
configure time`_). By default, TriBITS defines this to be 1500 seconds
(which is also the raw CMake default) but the project can change this
default, from 1500 to 300 for example, by setting the following in the
project's `<projectDir>/ProjectName.cmake`_ or
`<projectDir>/CMakeLists.txt`_ file::
set(DART_TESTING_TIMEOUT_DEFAULT 300)
.. _CMAKE_INSTALL_RPATH_USE_LINK_PATH:
**CMAKE_INSTALL_RPATH_USE_LINK_PATH**
The cache variable ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` is a built-in CMake
variable that determines if the paths for external libraries (i.e. from
TPLs) is put into the installed library RPATHS (see `RPATH Handling`_).
TriBITS sets the default for this to ``TRUE`` but a project can change the
default back to ``FALSE`` by setting the following in the project's
`<projectDir>/ProjectName.cmake`_ file::
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH_DEFAULT FALSE)
.. _MPI_EXEC_MAX_NUMPROCS:
**MPI_EXEC_MAX_NUMPROCS**
The variable ``MPI_EXEC_MAX_NUMPROCS`` gives the maximum number of processes
for an MPI test that will be allowed as defined by `tribits_add_test()`_ and
`tribits_add_advanced_test()`_. The TriBITS default is set to be ``4`` (for
no good reason really but it needs to stay that way for backward
compatibility). This default can be changed by setting::
set(MPI_EXEC_MAX_NUMPROCS_DEFAULT <newDefaultMax>)
While this default can be changed for the project as a whole on all
platforms, it is likely better to change this default on a
machine-by-machine basis to correspond to the load that can be accommodated
by a given machine (or class of machines). For example if a given machine
has 64 cores, a reasonable number for ``MPI_EXEC_MAX_NUMPROCS_DEFAULT`` is
64.
.. _PythonInterp_FIND_VERSION:
**PythonInterp_FIND_VERSION**
Determines the version of Python that is looked for. TriBITS requires at
least version "2.7". A particular TriBITS project can require a higher
version of TriBITS and this is set using, for example:
set(PythonInterp_FIND_VERSION_DEFAULT "3.5.2")
in the `<projectDir>/ProjectName.cmake`_ file (See `Python Support`_). The
default is version "2.7". The user can force a more recent version of
Python by configuring with, for example::
-D PythonInterp_FIND_VERSION="3.6.2"
.. _TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE:
**TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE**
Determines how the function `tribits_deprecated()`_ behaves. To change the
default behavor, such as call ``message(FATAL_ERROR ...)``, set::
set(TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE_DEFAULT FATAL_ERROR)
in the project's `<projectDir>/ProjectName.cmake`_ file, or
`<projectDir>/CMakeLists.txt`_ file, or on the individual package basis in
its `<packageDir>/CMakeLists.txt`_ file.
TriBITS Macros and Functions
----------------------------
The following subsections give detailed documentation for the CMake macros and
functions that make up the core TriBITS system. These are what are used by
TriBITS project developers in their ``CMakeLists.txt`` and other files. All
of these functions and macros should be automatically available when
processing the project's and package's variables files if used properly.
Therefore, no explicit ``include()`` statements should be needed other than
the initial include of the ``TriBITS.cmake`` file in the top-level
`<projectDir>/CMakeLists.txt`_ file so the command `tribits_project()`_ can be
executed.
.. include:: TribitsMacroFunctionDoc.rst
General Utility Macros and Functions
------------------------------------
The following subsections give detailed documentation for some CMake macros
and functions which are *not* a core part of the TriBITS system but are
included in the TriBITS source tree, are used inside of the TriBITS system,
and are provided as a convenience to TriBITS project developers. One will see
many of these functions and macros used throughout the implementation of
TriBITS and even in the ``CMakeLists.txt`` files for different projects that
use TriBITS.
These macros and functions are *not* prefixed with ``TRIBITS_``. However,
there is really not a large risk to defining and using these non-namespaces
utility functions and macros. It turns out that CMake allows one to redefine
any macro or function, even built-in ones, inside of one's project.
Therefore, even if CMake did add new commands that clashed with these names,
there would be no conflict. When overriding a built-in command,
e.g. ``some_builtin_command()``, one can always access the original built-in
command as ``_some_builtin_command()``.
.. include:: UtilsMacroFunctionDoc.rst
.. *** NOTE: This file is symlinked into users_guide/ and maintainers_guide/
.. *** and the symlinked file gets included in the top-level *.rst document.
.. *** This is so that the includes for the generated files
.. *** TribitsMacroFunctionDoc.rst and UtilsMacroFunctionDoc.rst in those
.. *** directories work correctly.