Debian Codegraph @

cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst

raw
1 .. Common references to other documents
2
3 .. _TriBITS Users Guide and Reference: TribitsUsersGuide.html
4
5 .. _Package Dependencies and Enable/Disable Logic: TribitsUsersGuide.html#package-dependencies-and-enable-disable-logic
6
7 .. _TriBITS Dependency Handling Behaviors: TribitsUsersGuide.html#tribits-dependency-handling-behaviors
8
9 .. _tribits_tpl_find_include_dirs_and_libraries(): TribitsUsersGuide.html#tribits-tpl-find-include-dirs-and-libraries
10
11 .. _tribits_ctest_driver(): TribitsUsersGuide.html#tribits-ctest-driver
12
13 .. _Ninja: https://ninja-build.org
14
15 .. _CMake Ninja Fortran Support: https://cmake.org/cmake/help/latest/generator/Ninja.html
16
17 .. _CTest Resource Allocation System: https://cmake.org/cmake/help/latest/manual/ctest.1.html#resource-allocation
18
19 .. _CTest Resource Specification File: https://cmake.org/cmake/help/latest/manual/ctest.1.html#ctest-resource-specification-file
20
21 .. _CTest Resource Allocation Environment Variables: https://cmake.org/cmake/help/latest/manual/ctest.1.html#environment-variables
22
23 .. _RESOURCE_GROUPS: https://cmake.org/cmake/help/latest/prop_test/RESOURCE_GROUPS.html#prop_test:RESOURCE_GROUPS
24
25
26
27 Getting set up to use CMake
28 ===========================
29
30 Before one can configure <Project> to be built, one must first obtain a
31 version of CMake on the system newer than <MinCMakeVer> This guide assumes
32 that once CMake is installed that it will be in the default path with the name
33 ``cmake``.
34
35
36 Installing a binary release of CMake [casual users]
37 ---------------------------------------------------
38
39 Download and install the binary (version <MinCMakeVer> or greater is
40 recommended) from:
41
42 http://www.cmake.org/cmake/resources/software.html
43
44
45 Installing CMake from source [developers and experienced users]
46 ---------------------------------------------------------------
47
48 If you have access to the <Project> git repositories (which which includes a
49 snapshot of TriBITS), then install CMake with::
50
51 $ cd <some-scratch-space>/
52 $ TRIBITS_BASE_DIR=<project-base-dir>/cmake/tribits
53 $ $TRIBITS_BASE_DIR/devtools_install/install-cmake.py \
54 --install-dir-base=<INSTALL_BASE_DIR> --cmake-version=X.Y.Z \
55 --do-all
56
57 This will result in cmake and related CMake tools being installed in
58 ``<INSTALL_BASE_DIR>/cmake-X.Y.Z/bin/`` (see the instructions printed at the
59 end on how to update your ``PATH`` env var).
60
61 To get help for installing CMake with this script use::
62
63 $ $TRIBITS_BASE_DIR/devtools_install/install-cmake.py --help
64
65 NOTE: You will want to read the help message about how to install CMake to
66 share with other users and maintainers and how to install with sudo if needed.
67
68
69 Installing Ninja from Source
70 ----------------------------
71
72 The `Ninja`_ tool allows for much faster parallel builds for some large CMake
73 projects and performs much faster dependency analysis than the Makefiles
74 back-end build system. It also provides some other nice features like ``ninja
75 -n -d explain`` to show why the build system decides to (re)build the targets
76 that it decides to build.
77
78 As of Ninja 1.10+, Fortran support is part of the official GitHub version of
79 Ninja as can be obtained from:
80
81 https://github.com/ninja-build/ninja/releases
82
83 (see `CMake Ninja Fortran Support`_).
84
85 Ninja is easy to install from source on almost any machine. On Unix/Linux
86 systems it is as simple as ``configure --prefix=<dir>``, ``make`` and ``make
87 install``.
88
89
90 Getting CMake Help
91 ==================
92
93
94 Finding CMake help at the website
95 ---------------------------------
96
97 http://www.cmake.org
98
99
100 Building CMake help locally
101 ---------------------------
102
103 To get help on CMake input options, run::
104
105 $ cmake --help
106
107 To get help on a single CMake function, run::
108
109 $ cmake --help-command <command>
110
111 To generate the entire documentation at once, run::
112
113 $ cmake --help-full cmake.help.html
114
115 (Open your web browser to the file cmake.help.html)
116
117
118 Configuring (Makefile, Ninja and other Generators)
119 ===================================================
120
121 CMake supports a number of different build generators (e.g. Ninja, Eclipse,
122 XCode, MS Visual Studio, etc.) but the primary generator most people use on
123 Unix/Linux system is ``make`` (using the default cmake option ``-G"Unix
124 Makefiles"``) and CMake generated Makefiles. Another (increasingly) popular
125 generator is Ninja (using cmake option ``-GNinja``). Most of the material in
126 this section applies to all generators but most experience is for the
127 Makefiles and Ninja generators.
128
129
130 Setting up a build directory
131 ----------------------------
132
133 In order to configure, one must set up a build directory. <Project> does
134 **not** support in-source builds so the build tree must be separate from the
135 source tree. The build tree can be created under the source tree such as
136 with::
137
138 $ cd <src-dir>/
139 $ mkdir <build-dir>
140 $ cd <build-dir>/
141
142 but it is generally recommended to create a build directory parallel from the
143 source tree such as with::
144
145 <some-base-dir>/
146 <src-dir>/
147 <build-dir>/
148
149 NOTE: If you mistakenly try to configure for an in-source build (e.g. with
150 'cmake .') you will get an error message and instructions on how to resolve
151 the problem by deleting the generated CMakeCache.txt file (and other generated
152 files) and then follow directions on how to create a different build directory
153 as shown above.
154
155
156 Basic configuration
157 -------------------
158
159 A few different approaches for configuring are given below.
160
161 * `Create a do-configure script [Recommended]`_
162 * `Create a *.cmake file and point to it [Most Recommended]`_
163 * `Using the QT CMake configuration GUI`_
164
165 .. _Create a do-configure script [Recommended]:
166
167 a) Create a 'do-configure' script such as [Recommended]::
168
169 #!/bin/bash
170 cmake \
171 -D CMAKE_BUILD_TYPE=DEBUG \
172 -D <Project>_ENABLE_TESTS=ON \
173 "$@" \
174 ${SOURCE_BASE}
175
176 and then run it with::
177
178 ./do-configure [OTHER OPTIONS] -D<Project>_ENABLE_<TRIBITS_PACKAGE>=ON
179
180 where ``<TRIBITS_PACKAGE>`` is a valid Package name (see above), etc. and
181 ``SOURCE_BASE`` is set to the <Project> source base directory (or your can
182 just give it explicitly in the script).
183
184 See ``<Project>/sampleScripts/*`` for examples of real ``do-configure``
185 scripts for different platforms.
186
187 NOTE: If one has already configured once and one needs to configure from
188 scratch (needs to wipe clean defaults for cache variables, updates
189 compilers, other types of changes) then one will want to delete the local
190 CMakeCache.txt and other CMake-generated files before configuring again (see
191 `Reconfiguring completely from scratch`_).
192
193 .. _<Project>_CONFIGURE_OPTIONS_FILE:
194
195 .. _Create a *.cmake file and point to it [Most Recommended]:
196
197 b) Create a ``*.cmake`` file and point to it [Most Recommended].
198
199 Create a do-configure script like::
200
201 #!/bin/bash
202 cmake \
203 -D <Project>_CONFIGURE_OPTIONS_FILE=MyConfigureOptions.cmake \
204 -D <Project>_ENABLE_TESTS=ON \
205 "$@" \
206 ${SOURCE_BASE}
207
208 where MyConfigureOptions.cmake (in the current working directory) might look
209 like::
210
211 set(CMAKE_BUILD_TYPE DEBUG CACHE STRING "Set in MyConfigureOptions.cmake")
212 set(<Project>_ENABLE_CHECKED_STL ON CACHE BOOL "Set in MyConfigureOptions.cmake")
213 set(BUILD_SHARED_LIBS ON CACHE BOOL "Set in MyConfigureOptions.cmake")
214 ...
215
216 Using a configuration fragment ``*.cmake`` file allows for better reuse of
217 configure options across different configure scripts and better version
218 control of configure options. Using the comment ``"Set in
219 MyConfigureOptions.cmake"`` makes it easy see where that variable got set
220 when looking an the generated ``CMakeCache.txt`` file. Also, when this
221 ``*.cmake`` fragment file changes, CMake will automatically trigger a
222 reconfigure during a make (because it knows about the file and will check its
223 time stamp, unlike when using ``-C <file-name>.cmake``, see below).
224
225 One can use the ``FORCE`` option in the ``set()`` commands shown above and
226 that will override any value of the options that might already be set (but
227 when using ``-C`` to include this forced ``set(<var> ... FORCE)`` will only
228 override the value if the file with the ``set()`` is listed after the
229 ``-D<var>=<val>`` command-line option). However, that will not allow the
230 user to override the options on the CMake command-line using
231 ``-D<VAR>=<value>`` so it is generally **not** desired to use ``FORCE``.
232
233 One can also pass in a list of configuration fragment files separated by
234 commas ``','`` which will be read in the order they are given as::
235
236 -D <Project>_CONFIGURE_OPTIONS_FILE=<file0>.cmake,<file1>.cmake,...
237
238 One can read in configure option files under the project source directory by
239 using the type ``STRING`` such as with::
240
241 -D <Project>_CONFIGURE_OPTIONS_FILE:STRING=cmake/MpiConfig1.cmake
242
243 In this case, the relative paths will be with respect to the project base
244 source directory, not the current working directory (unlike when using ``-C
245 <file-name>.cmake``, see below). (By specifying the type ``STRING``, one
246 turns off CMake interpretation as a ``FILEPATH``. Otherwise, the type
247 ``FILEPATH`` causes CMake to always interpret relative paths with respect to
248 the current working directory and set the absolute path).
249
250 Note that CMake options files can also be read in using the built-in CMake
251 argument ``-C <file>.cmake`` as::
252
253 cmake -C <file0>.cmake -C <file1>.cmake ... [other options] \
254 ${SOURCE_BASE}
255
256 However, there are some differences to using
257 ``<Project>_CONFIGURE_OPTIONS_FILE`` vs. ``-C`` to read in ``*.cmake`` files
258 to be aware of as described below:
259
260 1) One can use
261 ``-D<Project>_CONFIGURE_OPTIONS_FILE:STRING=<rel-path>/<file-name>.cmake``
262 with a relative path w.r.t. to the source tree to make it easier to point to
263 options files in the project source. Using ``cmake -C
264 <abs-path>/<file-name>.cmake`` would require having to give the absolute
265 path ``<abs-path>`` or a longer relative path from the build directory back
266 to the source directory. Having to give the absolute path to files in the
267 source tree complicates configure scripts in some cases (i.e. where the
268 project source directory location may not be known or easy to get).
269
270 2) When configuration files are read in using
271 ``<Project>_CONFIGURE_OPTIONS_FILE``, they will get reprocessed on every
272 reconfigure (such as when reconfigure happens automatically when running
273 ``make``). That means that if options change in those included ``*.cmake``
274 files from the initial configure, then those updated options will get
275 automatically picked up in a reconfigure. But when processing ``*.cmake``
276 files using the built-in ``-C <frag>.cmake`` argument, updated options will
277 not get set. Therefore, if one wants to have the ``*.cmake`` files
278 automatically be reprocessed, then one should use
279 ``<Project>_CONFIGURE_OPTIONS_FILE``. But if one does not want to have the
280 contents of the ``<frag>.cmake`` file reread on reconfigures, then one would
281 want to use ``-C <frag>.cmake``.
282
283 3) When using ``<Project>_CONFIGURE_OPTIONS_FILE``, one can create and use
284 parameterized ``*.cmake`` files that can be used with multiple TriBITS
285 projects. For example, one can have set statements like
286 ``set(${PROJECT_NAME}_ENABLE_Fortran OFF ...)`` since ``PROJECT_NAME`` is
287 known before the file is included. One cannot do that with ``-C`` and
288 instead would have to provide the full variables names specific for a given
289 TriBITS project.
290
291 4) When using ``<Project>_CONFIGURE_OPTIONS_FILE``, non-cache project-level
292 variables can be set in a ``*.cmake`` file that will impact the
293 configuration. When using the ``-C`` option, only variables set with
294 ``set(<varName> <val> CACHE <TYPE> ...)`` will impact the configuration.
295
296 5) Cache variables forced set with ``set(<varName> <val> CACHE <TYPE>
297 "<doc>" FORCE)`` in a ``<frag>.cmake`` file pulled in with ``-C
298 <frag>.cmake`` will only override a cache variable ``-D<varName>=<val2>``
299 passed on the command-line if the ``-C <frag>.cmake`` argument comes
300 **after** the ``-D<varName>=<val2>`` argument (i.e. ``cmake
301 -D<varName>=<val2> -C <frag>.cmake``). Otherwise, if the order of the
302 ``-D`` and ``-C`` arguments is reversed (i.e. ``cmake -C <frag>.cmake
303 -D<varName>=<val2>``) then the forced ``set()`` statement **WILL NOT**
304 override the cache var set on the command-line with ``-D<varName>=<val2>``.
305 However, note that a forced ``set()`` statement **WILL** override other
306 cache vars set with non-forced ``set()`` statements ``set(<varName> <val1>
307 CACHE <TYPE> "<doc>")`` in the same ``*.cmake`` file or in previously read
308 ``-C <frag2>.cmake`` files included on the command-line before the file ``-C
309 <frag>.cmake``. Alternatively, if the file is pulled in with
310 ``-D<Project>_CONFIGURE_OPTIONS_FILE=<frag>.cmake``, then a ``set(<varName>
311 <val> CACHE <TYPE> "<doc>" FORCE)`` statement in a ``<frag>.cmake`` **WILL**
312 override a cache variable passed in on the command-line
313 ``-D<varName>=<val2>`` no matter the order of the arguments
314 ``-D<Project>_CONFIGURE_OPTIONS_FILE=<frag>.cmake`` and
315 ``-D<varName>=<val2>``. (This is because the file ``<frag>.cmake`` is
316 included as part of the processing of the project's top-level
317 ``CMakeLists.txt`` file.)
318
319 6) However, the ``*.cmake`` files specified by
320 ``<Project>_CONFIGURE_OPTIONS_FILE`` will only get read in **after** the
321 project's ``ProjectName.cmake`` and other ``set()`` statements are called at
322 the top of the project's top-level ``CMakeLists.txt`` file. So any CMake
323 cache variables that are set in this early CMake code will override cache
324 defaults set in the included ``*.cmake`` file. (This is why TriBITS
325 projects must be careful **not** to set default values for cache variables
326 directly like this but instead should set indirect
327 ``<Project>_<VarName>_DEFAULT`` non-cache variables.) But when a
328 ``*.cmake`` file is read in using ``-C``, then the ``set()`` statements in
329 those files will get processed before any in the project's
330 ``CMakeLists.txt`` file. So be careful about this difference in behavior
331 and carefully watch cache variable values actually set in the generated
332 ``CMakeCache.txt`` file.
333
334 In other words, the context and impact of what get be set from a ``*.cmake``
335 file read in through the built-in CMake ``-C`` argument is more limited
336 while the code listed in the ``*.cmake`` file pulled in with
337 ``-D<Project>_CONFIGURE_OPTIONS_FILE=<frag>.cmake`` behaves just like
338 regular CMake statements executed in the project's top-level
339 ``CMakeLists.txt`` file. In addition, any forced set statements in a
340 ``*.cmake`` file pulled in with ``-C`` **may or may not** override cache
341 vars sets on the command-line with ``-D<varName>=<val>`` depending on the
342 order of the ``-C`` and ``-D`` options. (There is no order dependency for
343 ``*.cmake`` files passed in through
344 ``-D<Project>_CONFIGURE_OPTIONS_FILE=<frag>.cmake``.)
345
346 .. _Using the QT CMake configuration GUI:
347
348 c) Using the QT CMake configuration GUI:
349
350 On systems where the QT CMake GUI is installed (e.g. Windows) the CMake GUI
351 can be a nice way to configure <Project> (or just explore options) if you
352 are a user. To make your configuration easily repeatable, you might want to
353 create a fragment file and just load it by setting
354 `<Project>_CONFIGURE_OPTIONS_FILE`_ in the GUI.
355
356 Likely the most recommended approach to manage complex configurations is to
357 use ``*.cmake`` fragment files passed in through the
358 `<Project>_CONFIGURE_OPTIONS_FILE`_ option. This offers the greatest
359 flexibility and the ability to version-control the configuration settings.
360
361
362 Selecting the list of packages to enable
363 ----------------------------------------
364
365 The <Project> project is broken up into a set of packages that can be enabled
366 (or disabled). For details and generic examples, see `Package Dependencies and
367 Enable/Disable Logic`_ and `TriBITS Dependency Handling Behaviors`_.
368
369 See the following use cases:
370
371 * `Determine the list of packages that can be enabled`_
372 * `Print package dependencies`_
373 * `Enable a set of packages`_
374 * `Enable or disable tests for specific packages`_
375 * `Enable to test all effects of changing a given package(s)`_
376 * `Enable all packages (and optionally all tests)`_
377 * `Disable a package and all its dependencies`_
378 * `Remove all package enables in the cache`_
379 * `Speed up debugging dependency handling`_
380
381
382 Determine the list of packages that can be enabled
383 ++++++++++++++++++++++++++++++++++++++++++++++++++
384
385 In order to see the list of available <Project> Packages to enable, just
386 run a basic CMake configure, enabling nothing, and then grep the output to see
387 what packages are available to enable. The full set of defined packages is
388 contained the lines starting with ``'Final set of enabled packages'`` and
389 ``'Final set of non-enabled packages'``. If no packages are enabled by
390 default (which is base behavior), the full list of packages will be listed on
391 the line ``'Final set of non-enabled packages'``. Therefore, to see the
392 full list of defined packages, run::
393
394 ./do-configure 2>&1 | grep "Final set of .*enabled packages"
395
396 Any of the packages shown on those lines can potentially be enabled using ``-D
397 <Project>_ENABLE_<TRIBITS_PACKAGE>=ON`` (unless they are set to disabled
398 for some reason, see the CMake output for package disable warnings).
399
400 Another way to see the full list of packages that can be enabled is to
401 configure with `<Project>_DUMP_PACKAGE_DEPENDENCIES`_ = ``ON`` and then grep
402 for ``<Project>_INTERNAL_PACKAGES`` using, for example::
403
404 ./do-configure 2>&1 | grep "<Project>_INTERNAL_PACKAGES: "
405
406
407 Print package dependencies
408 ++++++++++++++++++++++++++
409
410 .. _<Project>_DUMP_PACKAGE_DEPENDENCIES:
411
412 The set of package dependencies can be printed in the ``cmake`` STDOUT by
413 setting the configure option::
414
415 -D <Project>_DUMP_PACKAGE_DEPENDENCIES=ON
416
417 This will print the basic forward/upstream dependencies for each package.
418 To find this output, look for the line::
419
420 Printing package dependencies ...
421
422 and the dependencies are listed below this for each package in the form::
423
424 -- <PKG>_LIB_DEFINED_DEPENDENCIES: <PKG0>[O] <[PKG1>[R] ...
425 -- <PKG>_TEST_DEFINED_DEPENDENCIES: <PKG6>[R] <[PKG8>[R] ...
426
427 (Dependencies that don't exist are left out of the output. For example, if
428 there are no extra test dependencies, then ``<PKG>_TEST_DEFINED_DEPENDENCIES``
429 will not be printed.)
430
431 To also see the direct forward/downstream dependencies for each package,
432 also include::
433
434 -D <Project>_DUMP_FORWARD_PACKAGE_DEPENDENCIES=ON
435
436 These dependencies are printed along with the backward/upstsream dependencies
437 as described above.
438
439 Both of these variables are automatically enabled when
440 `<Project>_VERBOSE_CONFIGURE`_ = ``ON``.
441
442
443 Enable a set of packages
444 ++++++++++++++++++++++++
445
446 .. _<Project>_ENABLE_ALL_OPTIONAL_PACKAGES:
447
448 .. _<Project>_ENABLE_TESTS:
449
450 To enable a package ``<TRIBITS_PACKAGE>`` (and optionally also its tests and
451 examples), configure with::
452
453 -D <Project>_ENABLE_<TRIBITS_PACKAGE>=ON \
454 -D <Project>_ENABLE_ALL_OPTIONAL_PACKAGES=ON \
455 -D <Project>_ENABLE_TESTS=ON \
456
457 This set of arguments allows a user to turn on ``<TRIBITS_PACKAGE>`` as well
458 as all packages that ``<TRIBITS_PACKAGE>`` can use. All of the package's
459 optional "can use" upstream dependent packages are enabled with
460 ``-D<Project>_ENABLE_ALL_OPTIONAL_PACKAGES=ON``. However,
461 ``-D<Project>_ENABLE_TESTS=ON`` will only enable tests and examples for
462 ``<TRIBITS_PACKAGE>`` (and any other packages explicitly enabled).
463
464 If a TriBITS package ``<TRIBITS_PACKAGE>`` has subpackages (e.g. subpackages
465 ``<A>``, ``<B>``, ...), then enabling the package is equivalent to enabling
466 all of the required **and optional** subpackagses::
467
468 -D <Project>_ENABLE_<TRIBITS_PACKAGE><A>=ON \
469 -D <Project>_ENABLE_<TRIBITS_PACKAGE><B>=ON \
470 ...
471
472 (In this case, the parent package's optional subpackages are enabled
473 regardless the value of ``<Project>_ENABLE_ALL_OPTIONAL_PACKAGES``.)
474
475 However, a TriBITS subpackage will only be enabled if it is not already
476 disabled either explicitly or implicitly.
477
478 NOTE: The CMake cache variable type for all ``XXX_ENABLE_YYY`` variables is
479 actually ``STRING`` and not ``BOOL``. That is because these enable variables
480 take on the string enum values of ``"ON"``, ``"OFF"``, end empty ``""``. An
481 empty enable means that the TriBITS dependency system is allowed to decide if
482 an enable should be turned on or off based on various logic. The CMake GUI
483 will enforce the values of ``"ON"``, ``"OFF"``, and empty ``""`` but it will
484 not enforce this if you set the value on the command line or in a ``set()``
485 statement in an input ```*.cmake`` options files. However, setting
486 ``-DXXX_ENABLE_YYY=TRUE`` and ``-DXXX_ENABLE_YYY=FALSE`` is allowed and will
487 be interpreted correctly..
488
489
490 Enable or disable tests for specific packages
491 +++++++++++++++++++++++++++++++++++++++++++++
492
493 The enable tests for explicitly enabled packages, configure with::
494
495 -D <Project>_ENABLE_<TRIBITS_PACKAGE_1>=ON \
496 -D <Project>_ENABLE_<TRIBITS_PACKAGE_2>=ON \
497 -D <Project>_ENABLE_TESTS=ON \
498
499 This will result in the enable of the test suites for any package that
500 explicitly enabled with ``-D <Project>_ENABLE_<TRIBITS_PACKAGE>=ON``. Note
501 that his will **not** result in the enable of the test suites for any packages
502 that may only be implicitly enabled in order to build the explicitly enabled
503 packages.
504
505 .. _<TRIBITS_PACKAGE>_ENABLE_TESTS:
506
507 If one wants to enable a package along with the enable of other packages, but
508 not the test suite for that package, then one can use a "exclude-list"
509 approach to disable the tests for that package by configuring with, for
510 example::
511
512 -D <Project>_ENABLE_<TRIBITS_PACKAGE_1>=ON \
513 -D <Project>_ENABLE_<TRIBITS_PACKAGE_2>=ON \
514 -D <Project>_ENABLE_<TRIBITS_PACKAGE_3>=ON \
515 -D <Project>_ENABLE_TESTS=ON \
516 -D <TRIBITS_PACKAGE_2>_ENABLE_TESTS=OFF \
517
518 The above will enable the package test suites for ``<TRIBITS_PACKGE_1>`` and
519 ``<TRIBITS_PACKGE_3>`` but **not** for ``<TRIBITS_PACKAGE_2>`` (or any other
520 packages that might get implicitly enabled). One might use this approach if
521 one wants to build and install package ``<TRIBITS_PACKAGE_2>`` but does not
522 want to build and run the test suite for that package.
523
524 Alternatively, one can use an "include-list" approach to enable packages and
525 only enable tests for specific packages, for example, configuring with::
526
527 -D <Project>_ENABLE_<TRIBITS_PACKAGE_1>=ON \
528 -D <TRIBITS_PACKAGE_1>_ENABLE_TESTS=ON \
529 -D <Project>_ENABLE_<TRIBITS_PACKAGE_2>=ON \
530 -D <Project>_ENABLE_<TRIBITS_PACKAGE_3>=ON \
531 -D <TRIBITS_PACKAGE_3>_ENABLE_TESTS=ON \
532
533 That will have the same result as using the "exclude-list" approach above.
534
535 **NOTE:** Setting ``<TRIBITS_PACKAGE>_ENABLE_TESTS=ON`` will set
536 ``<TRIBITS_PACKAGE>_ENABLE_EXAMPLES=ON`` by default. Also, setting
537 ``<TRIBITS_PACKAGE>_ENABLE_TESTS=ON`` will result in setting
538 ``<TRIBITS_PACKAGE><SP>_ENABLE_TESTS=ON`` for all subpackages in a parent
539 package that are explicitly enabled or are enabled in the forward sweep as a
540 result of `<Project>_ENABLE_ALL_FORWARD_DEP_PACKAGES`_ being set to ``ON``.
541
542 These and other options give the user complete control of what packages get
543 enabled or disabled and what package test suites are enabled or disabled.
544
545
546 Enable to test all effects of changing a given package(s)
547 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
548
549 .. _<Project>_ENABLE_ALL_FORWARD_DEP_PACKAGES:
550
551 To enable a package ``<TRIBITS_PACKAGE>`` to test it and all of its
552 down-stream packages, configure with::
553
554 -D <Project>_ENABLE_<TRIBITS_PACKAGE>=ON \
555 -D <Project>_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON \
556 -D <Project>_ENABLE_TESTS=ON \
557
558 The above set of arguments will result in package ``<TRIBITS_PACKAGE>`` and
559 all packages that depend on ``<TRIBITS_PACKAGE>`` to be enabled and have all
560 of their tests turned on. Tests will not be enabled in packages that do not
561 depend (at least implicitly) on ``<TRIBITS_PACKAGE>`` in this case. This
562 speeds up and robustifies testing for changes in specific packages (like in
563 per-merge testing in a continuous integration process).
564
565 NOTE: setting ``<Project>_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON`` also
566 automatically sets and overrides `<Project>_ENABLE_ALL_OPTIONAL_PACKAGES`_ to
567 be ``ON`` as well. (It makes no sense to want to enable forward dependent
568 packages for testing purposes unless you are enabling all optional packages.)
569
570
571 Enable all packages (and optionally all tests)
572 ++++++++++++++++++++++++++++++++++++++++++++++
573
574 To enable all defined packages, add the configure option::
575
576 -D <Project>_ENABLE_ALL_PACKAGES=ON \
577
578 To also optionally enable the tests and examples in all of those enabled
579 packages, add the configure option::
580
581 -D <Project>_ENABLE_TESTS=ON \
582
583 Specific packages can be disabled (i.e. "exclude-listed") by adding
584 ``<Project>_ENABLE_<TRIBITS_PACKAGE>=OFF``. This will also disable all
585 packages that depend on ``<TRIBITS_PACKAGE>``.
586
587 Note, all examples are also enabled by default when setting
588 ``<Project>_ENABLE_TESTS=ON``.
589
590 By default, setting ``<Project>_ENABLE_ALL_PACKAGES=ON`` only enables primary
591 tested (PT) packages and code. To have this also enable all secondary tested
592 (ST) packages and ST code in PT packages code, one must also set::
593
594 -D <Project>_ENABLE_SECONDARY_TESTED_CODE=ON \
595
596 NOTE: If this project is a "meta-project", then
597 ``<Project>_ENABLE_ALL_PACKAGES=ON`` may not enable *all* the packages but
598 only the project's primary meta-project packages. See `Package Dependencies
599 and Enable/Disable Logic`_ and `TriBITS Dependency Handling Behaviors`_ for
600 details.
601
602
603 Disable a package and all its dependencies
604 ++++++++++++++++++++++++++++++++++++++++++
605
606 To disable a package and all of the packages that depend on it, add the
607 configure option::
608
609 -D <Project>_ENABLE_<TRIBITS_PACKAGE>=OFF
610
611 For example::
612
613 -D <Project>_ENABLE_<TRIBITS_PACKAGE_A>=ON \
614 -D <Project>_ENABLE_ALL_OPTIONAL_PACKAGES=ON \
615 -D <Project>_ENABLE_<TRIBITS_PACKAGE_B>=OFF \
616
617 will enable ``<TRIBITS_PACKAGE_A>`` and all of the packages that it depends on
618 except for ``<TRIBITS_PACKAGE_B>`` and all of its forward dependencies.
619
620 If a TriBITS package ``<TRIBITS_PACKAGE>`` has subpackages (e.g. a parent
621 package with subpackages ``<A>``, ``<B>``, ...), then disabling the parent
622 package is equivalent to disabling all of the required and optional
623 subpackages::
624
625 -D <Project>_ENABLE_<TRIBITS_PACKAGE><A>=OFF \
626 -D <Project>_ENABLE_<TRIBITS_PACKAGE><B>=OFF \
627 ...
628
629 The disable of the subpackages in this case will override any enables.
630
631 .. _<Project>_DISABLE_ENABLED_FORWARD_DEP_PACKAGES:
632
633 If a disabled package is a required dependency of some explicitly enabled
634 downstream package, then the configure will error out if::
635
636 -D <Project>_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=OFF \
637
638 is set. Otherwise, if ``<Project>_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=ON``,
639 a ``NOTE`` will be printed and the downstream package will be disabled and
640 configuration will continue.
641
642
643 Remove all package enables in the cache
644 +++++++++++++++++++++++++++++++++++++++
645
646 To wipe the set of package enables in the ``CMakeCache.txt`` file so they can
647 be reset again from scratch, re-configure with::
648
649 $ cmake -D <Project>_UNENABLE_ENABLED_PACKAGES=TRUE .
650
651 This option will set to empty '' all package enables, leaving all other cache
652 variables as they are. You can then reconfigure with a new set of package
653 enables for a different set of packages. This allows you to avoid more
654 expensive configure time checks (like the standard CMake compiler checks) and
655 to preserve other cache variables that you have set and don't want to loose.
656 For example, one would want to do this to avoid more expensive compiler and
657 TPL checks.
658
659
660 Speed up debugging dependency handling
661 +++++++++++++++++++++++++++++++++++++++
662
663 To speed up debugging the package enable/disable dependency handling, set the
664 cache variable::
665
666 -D <Project>_TRACE_DEPENDENCY_HANDLING_ONLY=ON
667
668 This will result in only performing the package enable/disable dependency
669 handling logic and tracing what would be done to configure the compilers and
670 configure the various enabled packages but not actually do that work. This
671 can greatly speed up the time to complete the ``cmake`` configure command when
672 debugging the dependency handling (or when creating tests that check that
673 behavior).
674
675
676 Selecting compiler and linker options
677 -------------------------------------
678
679 The compilers for C, C++, and Fortran will be found by default by CMake if
680 they are not otherwise specified as described below (see standard CMake
681 documentation for how default compilers are found). The most direct way to
682 set the compilers are to set the CMake cache variables::
683
684 -D CMAKE_<LANG>_COMPILER=<path-to-compiler>
685
686 The path to the compiler can be just a name of the compiler
687 (e.g. ``-DCMAKE_C_COMPILER=gcc``) or can be an absolute path
688 (e.g. ``-DCMAKE_C_COMPILER=/usr/local/bin/cc``). The safest and more direct
689 approach to determine the compilers is to set the absolute paths using, for
690 example, the cache variables::
691
692 -D CMAKE_C_COMPILER=/opt/my_install/bin/gcc \
693 -D CMAKE_CXX_COMPILER=/opt/my_install/bin/g++ \
694 -D CMAKE_Fortran_COMPILER=/opt/my_install/bin/gfortran
695
696 or if ``TPL_ENABLE_MPI=ON`` (see `Configuring with MPI support`_) something
697 like::
698
699 -D CMAKE_C_COMPILER=/opt/my_install/bin/mpicc \
700 -D CMAKE_CXX_COMPILER=/opt/my_install/bin/mpicxx \
701 -D CMAKE_Fortran_COMPILER=/opt/my_install/bin/mpif90
702
703 If these the CMake cache variables are not set, then CMake will use the
704 compilers specified in the environment variables ``CC``, ``CXX``, and ``FC``
705 for C, C++ and Fortran, respectively. If one needs to drill down through
706 different layers of scripts, then it can be useful to set the compilers using
707 these environment variables. But in general is it recommended to be explicit
708 and use the above CMake cache variables to set the absolute path to the
709 compilers to remove all ambiguity.
710
711 If absolute paths to the compilers are not specified using the CMake cache
712 variables or the environment variables as described above, then in MPI mode
713 (i.e. ``TPL_ENABLE_MPI=ON``) TriBITS performs its own search for the MPI
714 compiler wrappers that will find the correct compilers for most MPI
715 distributions (see `Configuring with MPI support`_). However, if in serial
716 mode (i.e. ``TPL_ENABLE_MPI=OFF``), then CMake will do its own default
717 compiler search. The algorithm by which raw CMake finds these compilers is
718 not precisely documented (and seems to change based on the platform).
719 However, on Linux systems, the observed algorithm appears to be:
720
721 1. Search for the C compiler first by looking in ``PATH`` (or the equivalent
722 on Windows), starting with a compiler with the name ``cc`` and then moving
723 on to other names like ``gcc``, etc. This first compiler found is set to
724 ``CMAKE_C_COMPILER``.
725
726 2. Search for the C++ compiler with names like ``c++``, ``g++``, etc., but
727 restrict the search to the same directory specified by base path to the C
728 compiler given in the variable ``CMAKE_C_COMPILER``. The first compiler
729 that is found is set to ``CMAKE_CXX_COMPILER``.
730
731 3. Search for the Fortran compiler with names like ``f90``, ``gfortran``,
732 etc., but restrict the search to the same directory specified by base path
733 to the C compiler given in the variable ``CMAKE_C_COMPILER``. The first
734 compiler that is found is set to ``CMAKE_Fortran_COMPILER``.
735
736 **WARNING:** While this built-in CMake compiler search algorithm may seems
737 reasonable, it fails to find the correct compilers in many cases for a non-MPI
738 serial build. For example, if a newer version of GCC is installed and is put
739 first in ``PATH``, then CMake will fail to find the updated ``gcc`` compiler
740 and will instead find the default system ``cc`` compiler (usually under
741 ``/usr/bin/cc`` on Linux may systems) and will then only look for the C++ and
742 Fortran compilers under that directory. This will fail to find the correct
743 updated compilers because GCC does not install a C compiler named ``cc``!
744 Therefore, if you want to use the default CMake compiler search to find the
745 updated GCC compilers, you can set the CMake cache variable::
746
747 -D CMAKE_C_COMPILER=gcc
748
749 or can set the environment variable ``CC=gcc``. Either one of these will
750 result in CMake finding the updated GCC compilers found first in ``PATH``.
751
752 Once one has specified the compilers, one can also set the compiler flags, but
753 the way that CMake does this is a little surprising to many people. But the
754 <Project> TriBITS CMake build system offers the ability to tweak the built-in
755 CMake approach for setting compiler flags. First some background is in order.
756 When CMake creates the object file build command for a given source file, it
757 passes in flags to the compiler in the order::
758
759 ${CMAKE_<LANG>_FLAGS} ${CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>}
760
761 where ``<LANG>`` = ``C``, ``CXX``, or ``Fortran`` and ``<CMAKE_BUILD_TYPE>`` =
762 ``DEBUG`` or ``RELEASE``. Note that the options in
763 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` come after and override those in
764 ``CMAKE_<LANG>_FLAGS``! The flags in ``CMAKE_<LANG>_FLAGS`` apply to all
765 build types. Optimization, debug, and other build-type-specific flags are set
766 in ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>``. CMake automatically provides a
767 default set of debug and release optimization flags for
768 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` (e.g. ``CMAKE_CXX_FLAGS_DEBUG`` is
769 typically ``"-g -O0"`` while ``CMAKE_CXX_FLAGS_RELEASE`` is typically
770 ``"-O3"``). This means that if you try to set the optimization level with
771 ``-DCMAKE_CXX_FLAGS="-04"``, then this level gets overridden by the flags
772 specified in ``CMAKE_<LANG>_FLAGS_BUILD`` or ``CMAKE_<LANG>_FLAGS_RELEASE``.
773
774 TriBITS will set defaults for ``CMAKE_<LANG>_FLAGS`` and
775 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>``, which may be different that what
776 raw CMake would set. TriBITS provides a means for project and package
777 developers and users to set and override these compiler flag variables
778 globally and on a package-by-package basis. Below, the facilities for
779 manipulating compiler flags is described.
780
781 To see that the full set of compiler flags one has to actually build a target
782 by running, for example, ``make VERBOSE=1 <target_name>`` (see `Building with
783 verbose output without reconfiguring`_). (NOTE: One can also see the exact
784 set of flags used for each target in the generated ``build.ninja`` file when
785 using the Ninja generator.) One cannot just look at the cache variables for
786 ``CMAKE_<LANG>_FLAGS`` and ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` in the
787 file ``CMakeCache.txt`` and see the full set of flags are actually being used.
788 These variables can override the cache variables by TriBITS as project-level
789 local non-cache variables as described below (see `Overriding CMAKE_BUILD_TYPE
790 debug/release compiler options`_).
791
792 The <Project> TriBITS CMake build system will set up default compile flags for
793 GCC ('GNU') in development mode
794 (i.e. ``<Project>_ENABLE_DEVELOPMENT_MODE=ON``) on order to help produce
795 portable code. These flags set up strong warning options and enforce language
796 standards. In release mode (i.e. ``<Project>_ENABLE_DEVELOPMENT_MODE=OFF``),
797 these flags are not set. These flags get set internally into the variables
798 ``CMAKE_<LANG>_FLAGS`` (when processing packages, not at the global cache
799 variable level) but the user can append flags that override these as described
800 below.
801
802
803 Configuring to build with default debug or release compiler flags
804 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
805
806 .. _CMAKE_BUILD_TYPE:
807
808 To build a debug version, pass into 'cmake'::
809
810 -D CMAKE_BUILD_TYPE=DEBUG
811
812 This will result in debug flags getting passed to the compiler according to
813 what is set in ``CMAKE_<LANG>_FLAGS_DEBUG``.
814
815 To build a release (optimized) version, pass into 'cmake'::
816
817 -D CMAKE_BUILD_TYPE=RELEASE
818
819 This will result in optimized flags getting passed to the compiler according
820 to what is in ``CMAKE_<LANG>_FLAGS_RELEASE``.
821
822 The default build type is typically ``CMAKE_BUILD_TYPE=RELEASE`` unless ``-D
823 USE_XSDK_DEFAULTS=TRUE`` is set in which case the default build type is
824 ``CMAKE_BUILD_TYPE=DEBUG`` as per the xSDK configure standard.
825
826
827 Adding arbitrary compiler flags but keeping default build-type flags
828 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
829
830 To append arbitrary compiler flags to ``CMAKE_<LANG>_FLAGS`` (which may be
831 set internally by TriBITS) that apply to all build types, configure with::
832
833 -D CMAKE_<LANG>_FLAGS="<EXTRA_COMPILER_OPTIONS>"
834
835 where ``<EXTRA_COMPILER_OPTIONS>`` are your extra compiler options like
836 ``"-DSOME_MACRO_TO_DEFINE -funroll-loops"``. These options will get
837 appended to (i.e. come after) other internally defined compiler option and
838 therefore override them. The options are then pass to the compiler in the
839 order::
840
841 <DEFAULT_TRIBITS_LANG_FLAGS> <EXTRA_COMPILER_OPTIONS> \
842 ${CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>}
843
844 This that setting ``CMAKE_<LANG>_FLAGS`` can override the default flags that
845 TriBITS will set for ``CMAKE_<LANG>_FLAGS`` but will **not** override flags
846 specified in ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>``.
847
848 Instead of directly setting the CMake cache variables ``CMAKE_<LANG>_FLAGS``
849 one can instead set environment variables ``CFLAGS``, ``CXXFLAGS`` and
850 ``FFLAGS`` for ``CMAKE_C_FLAGS``, ``CMAKE_CXX_FLAGS`` and
851 ``CMAKE_Fortran_FLAGS``, respectively.
852
853 In addition, if ``-DUSE_XSDK_DEFAULTS=TRUE`` is set, then one can also pass
854 in Fortran flags using the environment variable ``FCFLAGS`` (raw CMake does
855 not recognize ``FCFLAGS``). But if ``FFLAGS`` and ``FCFLAGS`` are both set,
856 then they must be the same or a configure error will occur.
857
858 Options can also be targeted to a specific TriBITS package using::
859
860 -D <TRIBITS_PACKAGE>_<LANG>_FLAGS="<PACKAGE_EXTRA_COMPILER_OPTIONS>"
861
862 The package-specific options get appended **after** those already in
863 ``CMAKE_<LANG>_FLAGS`` and therefore override (but not replace) those set
864 globally in ``CMAKE_<LANG>_FLAGS`` (either internally in the CMakeLists.txt
865 files or by the user in the cache).
866
867 In addition, flags can be targeted to a specific TriBITS subpackage using the
868 same syntax::
869
870 -D <TRIBITS_SUBPACKAGE>_<LANG>_FLAGS="<SUBPACKAGE_EXTRA_COMPILER_OPTIONS>"
871
872 If top-level package-specific flags and subpackage-specific flags are both set
873 for the same parent package such as with::
874
875 -D SomePackage_<LANG>_FLAGS="<Package-flags>" \
876 -D SomePackageSpkgA_<LANG>_FLAGS="<Subpackage-flags>" \
877
878 then the flags for the subpackage ``SomePackageSpkgA`` will be listed after
879 those for its parent package ``SomePackage`` on the compiler command-line as::
880
881 <Package-flags> <SubPackage-flags>
882
883 That way, compiler options for a subpackage override flags set for the parent
884 package.
885
886 NOTES:
887
888 1) Setting ``CMAKE_<LANG>_FLAGS`` as a cache variable by the user on input be
889 listed after and therefore override, but will not replace, any internally set
890 flags in ``CMAKE_<LANG>_FLAGS`` defined by the <Project> CMake system. To get
891 rid of these project/TriBITS set compiler flags/options, see the below items.
892
893 2) Given that CMake passes in flags in
894 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` after those in
895 ``CMAKE_<LANG>_FLAGS`` means that users setting the ``CMAKE_<LANG>_FLAGS``
896 and ``<TRIBITS_PACKAGE>_<LANG>_FLAGS`` will **not** override the flags in
897 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` which come after on the compile
898 line. Therefore, setting ``CMAKE_<LANG>_FLAGS`` and
899 ``<TRIBITS_PACKAGE>_<LANG>_FLAGS`` should only be used for options that will
900 not get overridden by the debug or release compiler flags in
901 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>``. However, setting
902 ``CMAKE_<LANG>_FLAGS`` will work well for adding extra compiler defines
903 (e.g. -DSOMETHING) for example.
904
905 WARNING: Any options that you set through the cache variable
906 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` will get overridden in the
907 <Project> CMake system for GNU compilers in development mode so don't try to
908 manually set ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` directly! To
909 override those options, see
910 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>_OVERRIDE`` below.
911
912
913 Overriding CMAKE_BUILD_TYPE debug/release compiler options
914 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
915
916 To override the default CMake-set options in
917 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>``, use::
918
919 -D CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>_OVERRIDE="<OPTIONS_TO_OVERRIDE>"
920
921 For example, to default debug options use::
922
923 -D CMAKE_C_FLAGS_DEBUG_OVERRIDE="-g -O1" \
924 -D CMAKE_CXX_FLAGS_DEBUG_OVERRIDE="-g -O1"
925 -D CMAKE_Fortran_FLAGS_DEBUG_OVERRIDE="-g -O1"
926
927 and to override default release options use::
928
929 -D CMAKE_C_FLAGS_RELEASE_OVERRIDE="-O3 -funroll-loops" \
930 -D CMAKE_CXX_FLAGS_RELEASE_OVERRIDE="-03 -funroll-loops"
931 -D CMAKE_Fortran_FLAGS_RELEASE_OVERRIDE="-03 -funroll-loops"
932
933 NOTES: The TriBITS CMake cache variable
934 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>_OVERRIDE`` is used and not
935 ``CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>`` because is given a default
936 internally by CMake and the new variable is needed to make the override
937 explicit.
938
939
940 Turning off strong warnings for individual packages
941 +++++++++++++++++++++++++++++++++++++++++++++++++++
942
943 .. _<TRIBITS_PACKAGE>_DISABLE_STRONG_WARNINGS:
944
945 To turn off strong warnings (for all languages) for a given TriBITS package,
946 set::
947
948 -D <TRIBITS_PACKAGE>_DISABLE_STRONG_WARNINGS=ON
949
950 This will only affect the compilation of the sources for
951 ``<TRIBITS_PACKAGES>``, not warnings generated from the header files in
952 downstream packages or client code.
953
954 Note that strong warnings are only enabled by default in development mode
955 (``<Project>_ENABLE_DEVELOPMENT_MODE==ON``) but not release mode
956 (``<Project>_ENABLE_DEVELOPMENT_MODE==ON``). A release of <Project> should
957 therefore not have strong warning options enabled.
958
959
960 Overriding all (strong warnings and debug/release) compiler options
961 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
962
963 To override all compiler options, including both strong warning options
964 and debug/release options, configure with::
965
966 -D CMAKE_C_FLAGS="-O3 -funroll-loops" \
967 -D CMAKE_CXX_FLAGS="-03 -fexceptions" \
968 -D CMAKE_BUILD_TYPE=NONE \
969 -D <Project>_ENABLE_STRONG_C_COMPILE_WARNINGS=OFF \
970 -D <Project>_ENABLE_STRONG_CXX_COMPILE_WARNINGS=OFF \
971 -D <Project>_ENABLE_SHADOW_WARNINGS=OFF \
972 -D <Project>_ENABLE_COVERAGE_TESTING=OFF \
973 -D <Project>_ENABLE_CHECKED_STL=OFF \
974
975 NOTE: Options like ``<Project>_ENABLE_SHADOW_WARNINGS``,
976 ``<Project>_ENABLE_COVERAGE_TESTING``, and ``<Project>_ENABLE_CHECKED_STL``
977 do not need to be turned off by default but they are shown above to make it
978 clear what other CMake cache variables can add compiler and link arguments.
979
980 NOTE: By setting ``CMAKE_BUILD_TYPE=NONE``, then ``CMAKE_<LANG>_FLAGS_NONE``
981 will be empty and therefore the options set in ``CMAKE_<LANG>_FLAGS`` will
982 be all that is passed in.
983
984
985 Enable and disable shadowing warnings for all <Project> packages
986 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
987
988 To enable shadowing warnings for all <Project> packages (that don't already
989 have them turned on) then use::
990
991 -D <Project>_ENABLE_SHADOW_WARNINGS=ON
992
993 To disable shadowing warnings for all <Project> packages (even those that
994 have them turned on by default) then use::
995
996 -D <Project>_ENABLE_SHADOW_WARNINGS=OFF
997
998 NOTE: The default value is empty '' which lets each <Project> package
999 decide for itself if shadowing warnings will be turned on or off for that
1000 package.
1001
1002
1003 Removing warnings as errors for CLEANED packages
1004 ++++++++++++++++++++++++++++++++++++++++++++++++
1005
1006 To remove the ``-Werror`` flag (or some other flag that is set) from being
1007 applied to compile CLEANED packages (like the Trilinos package Teuchos), set
1008 the following when configuring::
1009
1010 -D <Project>_WARNINGS_AS_ERRORS_FLAGS=""
1011
1012
1013 Adding debug symbols to the build
1014 +++++++++++++++++++++++++++++++++
1015
1016 To get the compiler to add debug symbols to the build, configure with::
1017
1018 -D <Project>_ENABLE_DEBUG_SYMBOLS=ON
1019
1020 This will add ``-g`` on most compilers. NOTE: One does **not** generally need
1021 to create a full debug build to get debug symbols on most compilers.
1022
1023
1024 Printing out compiler flags for each package
1025 ++++++++++++++++++++++++++++++++++++++++++++
1026
1027 To print out the exact ``CMAKE_<LANG>_FLAGS`` that will be used for each
1028 package, set::
1029
1030 -D <Project>_PRINT_PACKAGE_COMPILER_FLAGS=ON
1031
1032 That will print lines in STDOUT that are formatted as::
1033
1034 <TRIBITS_SUBPACKAGE>: CMAKE_<LANG>_FLAGS="<exact-flags-usedy-by-package>"
1035 <TRIBITS_SUBPACKAGE>: CMAKE_<LANG>_FLAGS_<BUILD_TYPE>="<build-type-flags>"
1036
1037 This will print the value of the ``CMAKE_<LANG>_FLAGS`` and
1038 ``CMAKE_<LANG>_FLAGS_<BUILD_TYPE>`` variables that are used as each package is
1039 being processed and will contain the flags in the exact order they are applied
1040 by CMake
1041
1042
1043 Appending arbitrary libraries and link flags every executable
1044 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1045
1046 In order to append any set of arbitrary libraries and link flags to your
1047 executables use::
1048
1049 -D<Project>_EXTRA_LINK_FLAGS="<EXTRA_LINK_LIBRARIES>" \
1050 -DCMAKE_EXE_LINKER_FLAGS="<EXTRA_LINK_FLAGG>"
1051
1052 Above, you can pass any type of library and they will always be the last
1053 libraries listed, even after all of the TPLs.
1054
1055 NOTE: This is how you must set extra libraries like Fortran libraries and
1056 MPI libraries (when using raw compilers). Please only use this variable
1057 as a last resort.
1058
1059 NOTE: You must only pass in libraries in ``<Project>_EXTRA_LINK_FLAGS`` and
1060 *not* arbitrary linker flags. To pass in extra linker flags that are not
1061 libraries, use the built-in CMake variable ``CMAKE_EXE_LINKER_FLAGS``
1062 instead. The TriBITS variable ``<Project>_EXTRA_LINK_FLAGS`` is badly named
1063 in this respect but the name remains due to backward compatibility
1064 requirements.
1065
1066
1067 Enabling support for Ninja
1068 --------------------------
1069
1070 The `Ninja`_ build tool can be used as the back-end build tool instead of
1071 Makefiles by adding::
1072
1073 -GNinja
1074
1075 to the CMake configure line (the default on most Linux and OSX platforms is
1076 ``-G"Unix Makefiles"``). This instructs CMake to create the back-end
1077 ``ninja`` build files instead of back-end Makefiles (see `Building (Ninja
1078 generator)`_).
1079
1080 .. _<Project>_WRITE_NINJA_MAKEFILES:
1081
1082 In addition, the TriBITS build system will, by default, generate Makefiles in
1083 every binary directory where there is a CMakeLists.txt file in the source
1084 tree. These Makefiles have targets scoped to that subdirectory that use
1085 ``ninja`` to build targets in that subdirectory just like with the native
1086 CMake recursive ``-G "Unix Makefiles"`` generator. This allows one to ``cd``
1087 into any binary directory and type ``make`` to build just the targets in that
1088 directory. These TriBITS-generated Ninja makefiles also support ``help`` and
1089 ``help-objects`` targets making it easy to build individual executables,
1090 libraries and object files in any binary subdirectory.
1091
1092 **WARNING:** Using ``make -j<N>`` with these TriBITS-generated Ninja Makefiles
1093 will **not** result in using ``<N>`` processes to build in parallel and will
1094 instead use **all** of the free cores to build on the machine! To control the
1095 number of processes used, run ``make NP=<N>`` instead! See `Building in
1096 parallel with Ninja`_.
1097
1098 The generation of these Ninja makefiles can be disabled by setting::
1099
1100 -D<Project>_WRITE_NINJA_MAKEFILES=OFF
1101
1102 (But these Ninja Makefiles get created very quickly even for a very large
1103 CMake project so there is usually little reason to not generate them.)
1104
1105
1106 Limiting parallel compile and link jobs for Ninja builds
1107 --------------------------------------------------------
1108
1109 When the CMake generator Ninja is used (i.e. ``-GNinja``), one can limit the
1110 number of parallel jobs that are used for compiling object files by setting::
1111
1112 -D <Project>_PARALLEL_COMPILE_JOBS_LIMIT=<N>
1113
1114 and/or limit the number of parallel jobs that are used for linking libraries
1115 and executables by setting::
1116
1117 -D <Project>_PARALLEL_LINK_JOBS_LIMIT=<M>
1118
1119 where ``<N>`` and ``<M>`` are integers like ``20`` and ``4``. If these are
1120 not set, then the number of parallel jobs will be determined by the ``-j<P>``
1121 argument passed to ``ninja -j<P>`` or by ninja automatically according to
1122 machine load when running ``ninja``.
1123
1124 Limiting the number of link jobs can be useful, for example, for certain
1125 builds of large projects where linking many jobs in parallel can consume all
1126 of the RAM on a given system and crash the build.
1127
1128 NOTE: These options are ignored when using Makefiles or other CMake
1129 generators. They only work for the Ninja generator.
1130
1131
1132 Disabling explicit template instantiation for C++
1133 -------------------------------------------------
1134
1135 By default, support for optional explicit template instantiation (ETI) for C++
1136 code is enabled. To disable support for optional ETI, configure with::
1137
1138 -D <Project>_ENABLE_EXPLICIT_INSTANTIATION=OFF
1139
1140 When ``OFF``, all packages that have templated C++ code will use implicit
1141 template instantiation (unless they have hard-coded usage of ETI).
1142
1143 ETI can be enabled (``ON``) or disabled (``OFF``) for individual packages
1144 with::
1145
1146 -D <TRIBITS_PACKAGE>_ENABLE_EXPLICIT_INSTANTIATION=[ON|OFF]
1147
1148 The default value for ``<TRIBITS_PACKAGE>_ENABLE_EXPLICIT_INSTANTIATION`` is
1149 set by ``<Project>_ENABLE_EXPLICIT_INSTANTIATION``.
1150
1151 For packages that support it, explicit template instantiation can massively
1152 reduce the compile times for the C++ code involved and can even avoid compiler
1153 crashes in some cases. To see what packages support explicit template
1154 instantiation, just search the CMakeCache.txt file for variables with
1155 ``ENABLE_EXPLICIT_INSTANTIATION`` in the name.
1156
1157
1158 Disabling the Fortran compiler and all Fortran code
1159 ---------------------------------------------------
1160
1161 To disable the Fortran compiler and all <Project> code that depends on Fortran
1162 set::
1163
1164 -D <Project>_ENABLE_Fortran=OFF
1165
1166 NOTE: The Fortran compiler may be disabled automatically by default on systems
1167 like MS Windows.
1168
1169 NOTE: Most Apple Macs do not come with a compatible Fortran compiler by
1170 default so you must turn off Fortran if you don't have a compatible Fortran
1171 compiler.
1172
1173
1174 Enabling runtime debug checking
1175 -------------------------------
1176
1177 a) Enabling <Project> ifdefed runtime debug checking:
1178
1179 To turn on optional ifdefed runtime debug checking, configure with::
1180
1181 -D <Project>_ENABLE_DEBUG=ON
1182
1183 This will result in a number of ifdefs to be enabled that will perform a
1184 number of runtime checks. Nearly all of the debug checks in <Project> will
1185 get turned on by default by setting this option. This option can be set
1186 independent of ``CMAKE_BUILD_TYPE`` (which sets the compiler debug/release
1187 options).
1188
1189 NOTES:
1190
1191 * The variable ``CMAKE_BUILD_TYPE`` controls what compiler options are
1192 passed to the compiler by default while ``<Project>_ENABLE_DEBUG``
1193 controls what defines are set in config.h files that control ifdefed debug
1194 checks.
1195
1196 * Setting ``-DCMAKE_BUILD_TYPE=DEBUG`` will automatically set the
1197 default ``<Project>_ENABLE_DEBUG=ON``.
1198
1199 b) Enabling checked STL implementation:
1200
1201 To turn on the checked STL implementation set::
1202
1203 -D <Project>_ENABLE_CHECKED_STL=ON
1204
1205 NOTES:
1206
1207 * By default, this will set -D_GLIBCXX_DEBUG as a compile option for all C++
1208 code. This only works with GCC currently.
1209
1210 * This option is disabled by default because to enable it by default can
1211 cause runtime segfaults when linked against C++ code that was compiled
1212 without -D_GLIBCXX_DEBUG.
1213
1214
1215 Configuring with MPI support
1216 ----------------------------
1217
1218 To enable MPI support you must minimally set::
1219
1220 -D TPL_ENABLE_MPI=ON
1221
1222 There is built-in logic to try to find the various MPI components on your
1223 system but you can override (or make suggestions) with::
1224
1225 -D MPI_BASE_DIR="path"
1226
1227 (Base path of a standard MPI installation which has the subdirs 'bin', 'libs',
1228 'include' etc.)
1229
1230 or::
1231
1232 -D MPI_BIN_DIR="path1;path2;...;pathn"
1233
1234 which sets the paths where the MPI executables (e.g. mpiCC, mpicc, mpirun,
1235 mpiexec) can be found. By default this is set to ``${MPI_BASE_DIR}/bin`` if
1236 ``MPI_BASE_DIR`` is set.
1237
1238 **NOTE:** TriBITS uses the MPI compiler wrappers (e.g. mpiCC, mpicc, mpic++,
1239 mpif90, etc.) which is more standard with other builds systems for HPC
1240 computing using MPI (and the way that MPI implementations were meant to be
1241 used). But directly using the MPI compiler wrappers as the direct compilers
1242 is inconsistent with the way that the standard CMake module ``FindMPI.cmake``
1243 which tries to "unwrap" the compiler wrappers and grab out the raw underlying
1244 compilers and the raw compiler and linker command-line arguments. In this
1245 way, TriBITS is more consistent with standard usage in the HPC community but
1246 is less consistent with CMake (see "HISTORICAL NOTE" below).
1247
1248 There are several different different variations for configuring with MPI
1249 support:
1250
1251 a) **Configuring build using MPI compiler wrappers:**
1252
1253 The MPI compiler wrappers are turned on by default. There is built-in logic
1254 in TriBITS that will try to find the right MPI compiler wrappers. However,
1255 you can specifically select them by setting, for example::
1256
1257 -D MPI_C_COMPILER:FILEPATH=mpicc \
1258 -D MPI_CXX_COMPILER:FILEPATH=mpic++ \
1259 -D MPI_Fortan_COMPILER:FILEPATH=mpif77
1260
1261 which gives the name of the MPI C/C++/Fortran compiler wrapper executable.
1262 In this case, just the names of the programs are given and absolute path of
1263 the executables will be searched for under ``${MPI_BIN_DIR}/`` if the cache
1264 variable ``MPI_BIN_DIR`` is set, or in the default path otherwise. The
1265 found programs will then be used to set the cache variables
1266 ``CMAKE_[C,CXX,Fortran]_COMPILER``.
1267
1268 One can avoid the search and just use the absolute paths with, for example::
1269
1270 -D MPI_C_COMPILER:FILEPATH=/opt/mpich/bin/mpicc \
1271 -D MPI_CXX_COMPILER:FILEPATH=/opt/mpich/bin/mpic++ \
1272 -D MPI_Fortan_COMPILER:FILEPATH=/opt/mpich/bin/mpif77
1273
1274 However, you can also directly set the variables
1275 ``CMAKE_[C,CXX,Fortran]_COMPILER`` with, for example::
1276
1277 -D CMAKE_C_COMPILER:FILEPATH=/opt/mpich/bin/mpicc \
1278 -D CMAKE_CXX_COMPILER:FILEPATH=/opt/mpich/bin/mpic++ \
1279 -D CMAKE_Fortan_COMPILER:FILEPATH=/opt/mpich/bin/mpif77
1280
1281 **WARNING:** If you set just the compiler names and not the absolute paths
1282 with ``CMAKE_<LANG>_COMPILER`` in MPI mode, then a search will not be done
1283 and these will be expected to be in the path at build time. (Note that his
1284 is inconsistent the behavior of raw CMake in non-MPI mode described in
1285 `Selecting compiler and linker options`_). If both
1286 ``CMAKE_<LANG>_COMPILER`` and ``MPI_<LANG>_COMPILER`` are set, however, then
1287 ``CMAKE_<LANG>_COMPILER`` will be used and ``MPI_<LANG>_COMPILER`` will be
1288 ignored.
1289
1290 Note that when ``USE_XSDK_DEFAULTS=FALSE`` (see `xSDK Configuration
1291 Options`_), then the environment variables ``CC``, ``CXX`` and ``FC`` are
1292 ignored. But when ``USE_XSDK_DEFAULTS=TRUE`` and the CMake cache variables
1293 ``CMAKE_[C,CXX,Fortran]_COMPILER`` are not set, then the environment
1294 variables ``CC``, ``CXX`` and ``FC`` will be used for
1295 ``CMAKE_[C,CXX,Fortran]_COMPILER``, even if the CMake cache variables
1296 ``MPI_[C,CXX,Fortran]_COMPILER`` are set! So if one wants to make sure and
1297 set the MPI compilers irrespective of the xSDK mode, then one should set
1298 cmake cache variables ``CMAKE_[C,CXX,Fortran]_COMPILER`` to the absolute
1299 path of the MPI compiler wrappers.
1300
1301 **HISTORICAL NOTE:** The TriBITS system has its own custom MPI integration
1302 support and does not (currently) use the standard CMake module
1303 ``FindMPI.cmake``. This custom support for MPI was added to TriBITS in 2008
1304 when it was found the built-in ``FindMPI.cmake`` module was not sufficient
1305 for the needs of Trilinos and the approach taken by the module (still in use
1306 as of CMake 3.4.x) which tries to unwrap the raw compilers and grab the list
1307 of include directories, link libraries, etc, was not sufficiently portable
1308 for the systems where Trilinos needed to be used. But earlier versions of
1309 TriBITS used the ``FindMPI.cmake`` module and that is why the CMake cache
1310 variables ``MPI_[C,CXX,Fortran]_COMPILER`` are defined and still supported.
1311
1312 b) **Configuring to build using raw compilers and flags/libraries:**
1313
1314 While using the MPI compiler wrappers as described above is the preferred
1315 way to enable support for MPI, you can also just use the raw compilers and
1316 then pass in all of the other information that will be used to compile and
1317 link your code.
1318
1319 To turn off the MPI compiler wrappers, set::
1320
1321 -D MPI_USE_COMPILER_WRAPPERS=OFF
1322
1323 You will then need to manually pass in the compile and link lines needed to
1324 compile and link MPI programs. The compile flags can be set through::
1325
1326 -D CMAKE_[C,CXX,Fortran]_FLAGS="$EXTRA_COMPILE_FLAGS"
1327
1328 The link and library flags must be set through::
1329
1330 -D <Project>_EXTRA_LINK_FLAGS="$EXTRA_LINK_FLAGS"
1331
1332 Above, you can pass any type of library or other linker flags in and they
1333 will always be the last libraries listed, even after all of the TPLs.
1334
1335 NOTE: A good way to determine the extra compile and link flags for MPI is to
1336 use::
1337
1338 export EXTRA_COMPILE_FLAGS="`$MPI_BIN_DIR/mpiCC --showme:compile`"
1339
1340 export EXTRA_LINK_FLAGS="`$MPI_BIN_DIR/mpiCC --showme:link`"
1341
1342 where ``MPI_BIN_DIR`` is set to your MPI installations binary directory.
1343
1344 c) **Setting up to run MPI programs:**
1345
1346 In order to use the ctest program to run MPI tests, you must set the mpi
1347 run command and the options it takes. The built-in logic will try to find
1348 the right program and options but you will have to override them in many
1349 cases.
1350
1351 MPI test and example executables are passed to CTest ``add_test()`` as::
1352
1353 add_test(NAME <testName> COMMAND
1354 ${MPI_EXEC} ${MPI_EXEC_PRE_NUMPROCS_FLAGS}
1355 ${MPI_EXEC_NUMPROCS_FLAG} <NP>
1356 ${MPI_EXEC_POST_NUMPROCS_FLAGS}
1357 <TEST_EXECUTABLE_PATH> <TEST_ARGS> )
1358
1359 where ``<TEST_EXECUTABLE_PATH>``, ``<TEST_ARGS>``, and ``<NP>`` are specific
1360 to the test being run.
1361
1362 The test-independent MPI arguments are::
1363
1364 -D MPI_EXEC:FILEPATH="exec_name"
1365
1366 (The name of the MPI run command (e.g. mpirun, mpiexec) that is used to run
1367 the MPI program. This can be just the name of the program in which case
1368 the full path will be looked for in ``${MPI_BIN_DIR}`` as described above.
1369 If it is an absolute path, it will be used without modification.)
1370
1371 ::
1372
1373 -D MPI_EXEC_DEFAULT_NUMPROCS=4
1374
1375 (The default number of processes to use when setting up and running
1376 MPI test and example executables. The default is set to '4' and only
1377 needs to be changed when needed or desired.)
1378
1379 ::
1380
1381 -D MPI_EXEC_MAX_NUMPROCS=4
1382
1383 (The maximum number of processes to allow when setting up and running MPI
1384 tests and examples that use MPI. The default is set to '4' but should be
1385 set to the largest number that can be tolerated for the given machine or the
1386 most cores on the machine that you want the test suite to be able to use.
1387 Tests and examples that require more processes than this are excluded from
1388 the CTest test suite at configure time. ``MPI_EXEC_MAX_NUMPROCS`` is also
1389 used to exclude tests in a non-MPI build (i.e. ``TPL_ENABLE_MPI=OFF``) if
1390 the number of required cores for a given test is greater than this value.)
1391
1392 ::
1393
1394 -D MPI_EXEC_NUMPROCS_FLAG=-np
1395
1396 (The command-line option just before the number of processes to use
1397 ``<NP>``. The default value is based on the name of ``${MPI_EXEC}``, for
1398 example, which is ``-np`` for OpenMPI.)
1399
1400 ::
1401
1402 -D MPI_EXEC_PRE_NUMPROCS_FLAGS="arg1;arg2;...;argn"
1403
1404 (Other command-line arguments that must come *before* the numprocs
1405 argument. The default is empty "".)
1406
1407 ::
1408
1409 -D MPI_EXEC_POST_NUMPROCS_FLAGS="arg1;arg2;...;argn"
1410
1411 (Other command-line arguments that must come *after* the numprocs
1412 argument. The default is empty "".)
1413
1414 NOTE: Multiple arguments listed in ``MPI_EXEC_PRE_NUMPROCS_FLAGS`` and
1415 ``MPI_EXEC_POST_NUMPROCS_FLAGS`` must be quoted and separated by ``';'`` as
1416 these variables are interpreted as CMake arrays.
1417
1418
1419 Configuring for OpenMP support
1420 ------------------------------
1421
1422 To enable OpenMP support, one must set::
1423
1424 -D <Project>_ENABLE_OpenMP=ON
1425
1426 Note that if you enable OpenMP directly through a compiler option (e.g.,
1427 ``-fopenmp``), you will NOT enable OpenMP inside <Project> source code.
1428
1429 To skip adding flags for OpenMP for ``<LANG>`` = ``C``, ``CXX``, or
1430 ``Fortran``, use::
1431
1432 -D OpenMP_<LANG>_FLAGS_OVERRIDE=" "
1433
1434 The single space " " will result in no flags getting added. This is needed
1435 since one can't set the flags ``OpenMP_<LANG>_FLAGS`` to an empty string or
1436 the ``find_package(OpenMP)`` command will fail. Setting the variable
1437 ``-DOpenMP_<LANG>_FLAGS_OVERRIDE= " "`` is the only way to enable OpenMP but
1438 skip adding the OpenMP flags provided by ``find_package(OpenMP)``.
1439
1440
1441 Building shared libraries
1442 -------------------------
1443
1444 .. _BUILD_SHARED_LIBS:
1445
1446 To configure to build shared libraries, set::
1447
1448 -D BUILD_SHARED_LIBS=ON
1449
1450 The above option will result in all shared libraries to be build on all
1451 systems (i.e., ``.so`` on Unix/Linux systems, ``.dylib`` on Mac OS X, and
1452 ``.dll`` on Windows systems).
1453
1454 NOTE: If the project has ``USE_XSDK_DEFAULTS=ON`` set, then this will set
1455 ``BUILD_SHARED_LIBS=TRUE`` by default. Otherwise, the default is
1456 ``BUILD_SHARED_LIBS=FALSE``
1457
1458 Many systems support a feature called ``RPATH`` when shared libraries are used
1459 that embeds the default locations to look for shared libraries when an
1460 executable is run. By default on most systems, CMake will automatically add
1461 RPATH directories to shared libraries and executables inside of the build
1462 directories. This allows running CMake-built executables from inside the
1463 build directory without needing to set ``LD_LIBRARY_PATH`` on any other
1464 environment variables. However, this can be disabled by setting::
1465
1466 -D CMAKE_SKIP_BUILD_RPATH=TRUE
1467
1468 but it is hard to find a use case where that would be useful.
1469
1470
1471 Building static libraries and executables
1472 -----------------------------------------
1473
1474 To build static libraries, turn off the shared library support::
1475
1476 -D BUILD_SHARED_LIBS=OFF
1477
1478 Some machines, such as the Cray XT5, require static executables. To build
1479 <Project> executables as static objects, a number of flags must be set::
1480
1481 -D BUILD_SHARED_LIBS=OFF \
1482 -D TPL_FIND_SHARED_LIBS=OFF \
1483 -D <Project>_LINK_SEARCH_START_STATIC=ON
1484
1485 The first flag tells cmake to build static versions of the <Project>
1486 libraries. The second flag tells cmake to locate static library versions of
1487 any required TPLs. The third flag tells the auto-detection routines that
1488 search for extra required libraries (such as the mpi library and the gfortran
1489 library for gnu compilers) to locate static versions.
1490
1491 The TPL_FIND_SHARED_LIBS setting can also be set per-TPL, in the case that
1492 the desire is to find shared libraries for one TPL, but static libraries for
1493 all others::
1494
1495 -D TPL_FIND_SHARED_LIBS=OFF \
1496 -D <TPLNAME>_FIND_SHARED_LIBS=ON
1497
1498
1499 Changing include directories in downstream CMake projects to non-system
1500 -----------------------------------------------------------------------
1501
1502 By default, include directories from IMPORTED library targets from the
1503 <Project> project's installed ``<Package>Config.cmake`` files will be
1504 considered ``SYSTEM`` headers and therefore will be included on the compile
1505 lines of downstream CMake projects with ``-isystem`` with most compilers.
1506 However, when using CMake 3.23+, by configuring with::
1507
1508 -D <Project>_IMPORTED_NO_SYSTEM=ON
1509
1510 then all of the IMPORTED library targets in the set of installed
1511 ``<Package>Config.cmake`` files will have the ``IMPORTED_NO_SYSTEM`` target
1512 property set. This will cause downstream customer CMake projects to apply the
1513 include directories from these IMPORTED library targets as non-SYSTEM include
1514 directories. On most compilers, that means that the include directories will
1515 be listed on the compile lines with ``-I`` instead of with ``-isystem`` (for
1516 compilers that support the ``-isystem`` option). (Changing from ``-isystem
1517 <incl-dir>`` to ``-I <incl-dir>`` moves ``<incl-dir>`` forward in the
1518 compiler's include directory search order and could also result in the found
1519 header files emitting compiler warnings that would other otherwise be silenced
1520 when the headers were found in include directories pulled in with
1521 ``-isystem``.)
1522
1523 **NOTE:** Setting ``<Project>_IMPORTED_NO_SYSTEM=ON`` when using a CMake
1524 version less than 3.23 will result in a fatal configure error (so don't do
1525 that).
1526
1527 **A workaround for CMake versions less than 3.23** is for **downstream
1528 customer CMake projects** to set the native CMake cache variable::
1529
1530 -D CMAKE_NO_SYSTEM_FROM_IMPORTED=TRUE
1531
1532 This will result in **all** include directories from **all** IMPORTED library
1533 targets used in the downstream customer CMake project to be listed on the
1534 compile lines using ``-I`` instead of ``-isystem``, and not just for the
1535 IMPORTED library targets from this <Project> project's installed
1536 ``<Package>Config.cmake`` files!
1537
1538 **NOTE:** Setting ``CMAKE_NO_SYSTEM_FROM_IMPORTED=TRUE`` in the <Project>
1539 CMake configure will **not** result in changing how include directories from
1540 <Project>'s IMPORTED targets are handled in a downstream customer CMake
1541 project! It will only change how include directories from upstream package's
1542 IMPORTED targets are handled in the <Project> CMake project build itself.
1543
1544
1545 Enabling the usage of resource files to reduce length of build lines
1546 --------------------------------------------------------------------
1547
1548 When using the ``Unix Makefile`` generator and the ``Ninja`` generator, CMake
1549 supports some very useful (undocumented) options for reducing the length of
1550 the command-lines used to build object files, create libraries, and link
1551 executables. Using these options can avoid troublesome "command-line too
1552 long" errors, "Error 127" library creation errors, and other similar errors
1553 related to excessively long command-lines to build various targets.
1554
1555 When using the ``Unix Makefile`` generator, CMake responds to the three cache
1556 variables ``CMAKE_CXX_USE_RESPONSE_FILE_FOR_INCLUDES``,
1557 ``CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS`` and
1558 ``CMAKE_CXX_USE_RESPONSE_FILE_FOR_LIBRARIES`` described below.
1559
1560 To aggregate the list of all of the include directories (e.g. ``'-I
1561 <full_path>'``) into a single ``*.rsp`` file for compiling object files, set::
1562
1563 -D CMAKE_CXX_USE_RESPONSE_FILE_FOR_INCLUDES=ON
1564
1565 To aggregate the list of all of the object files (e.g. ``'<path>/<name>.o'``)
1566 into a single ``*.rsp`` file for creating libraries or linking executables,
1567 set::
1568
1569 -D CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS=ON
1570
1571 To aggregate the list of all of the libraries (e.g. ``'<path>/<libname>.a'``)
1572 into a single ``*.rsp`` file for creating shared libraries or linking
1573 executables, set::
1574
1575 -D CMAKE_CXX_USE_RESPONSE_FILE_FOR_LIBRARIES=ON
1576
1577 When using the ``Ninja`` generator, CMake only responds to the single option::
1578
1579 -D CMAKE_NINJA_FORCE_RESPONSE_FILE=ON
1580
1581 which turns on the usage of ``*.rsp`` response files for include directories,
1582 object files, and libraries (and therefore is equivalent to setting the above
1583 three ``Unix Makefiles`` generator options to ``ON``).
1584
1585 This feature works well on most standard systems but there are problems in
1586 some situations and therefore these options can only be safely enabled on
1587 case-by-case basis -- experimenting to ensure they are working correctly.
1588 Some examples of some known problematic cases (as of CMake 3.11.2) are:
1589
1590 * CMake will only use resource files with static libraries created with GNU
1591 ``ar`` (e.g. on Linux) but not BSD ``ar`` (e.g. on MacOS). With BSD ``ar``,
1592 CMake may break up long command-lines (i.e. lots of object files) with
1593 multiple calls to ``ar`` but that may only work with the ``Unix Makefiles``
1594 generator, not the ``Ninja`` generator.
1595
1596 * Some versions of ``gfortran`` do not accept ``*.rsp`` files.
1597
1598 * Some versions of ``nvcc`` (e.g. with CUDA 8.044) do not accept ``*.rsp``
1599 files for compilation or linking.
1600
1601 Because of problems like these, TriBITS cannot robustly automatically turn on
1602 these options. Therefore, it is up to the user to try these options out to
1603 see if they work with their specific version of CMake, compilers, and OS.
1604
1605 NOTE: When using the ``Unix Makefiles`` generator, one can decide to set any
1606 combination of these three options based on need and preference and what
1607 actually works with a given OS, version of CMake, and provided compilers. For
1608 example, on one system ``CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS=ON`` may work
1609 but ``CMAKE_CXX_USE_RESPONSE_FILE_FOR_INCLUDES=ON`` may not (which is the case
1610 for ``gfortran`` mentioned above). Therefore, one should experiment carefully
1611 and inspect the build lines using ``make VERBOSE=1 <target>`` as described in
1612 `Building with verbose output without reconfiguring`_ when deciding which of
1613 these options to enable.
1614
1615 NOTE: Newer versions of CMake may automatically determine when these options
1616 need to be turned on so watch for that in looking at the build lines.
1617
1618
1619 External Packages/Third-Party Library (TPL) support
1620 ---------------------------------------------------
1621
1622 A set of external packages/third-party libraries (TPL) can be enabled and
1623 disabled and the locations of those can be specified at configure time (if
1624 they are not found in the default path).
1625
1626
1627 Enabling support for an optional Third-Party Library (TPL)
1628 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1629
1630 To enable a given external packages/TPL, set::
1631
1632 -D TPL_ENABLE_<TPLNAME>=ON
1633
1634 where ``<TPLNAME>`` = ``BLAS``, ``LAPACK`` ``Boost``, ``Netcdf``, etc.
1635 (Requires TPLs for enabled package will automatically be enabled.)
1636
1637 The full list of TPLs that is defined and can be enabled is shown by doing a
1638 configure with CMake and then grepping the configure output for ``Final set of
1639 .* TPLs``. The set of TPL names listed in ``'Final set of enabled external
1640 packages/TPLs'`` and ``'Final set of non-enabled external packages/TPLs'``
1641 gives the full list of TPLs that can be enabled (or disabled).
1642
1643 Optional package-specific support for a TPL can be turned off by setting::
1644
1645 -D <TRIBITS_PACKAGE>_ENABLE_<TPLNAME>=OFF
1646
1647 This gives the user full control over what TPLs are supported by which package
1648 independent of whether the TPL is enabled or not.
1649
1650 Support for an optional TPL can also be turned on implicitly by setting::
1651
1652 -D <TRIBITS_PACKAGE>_ENABLE_<TPLNAME>=ON
1653
1654 where ``<TRIBITS_PACKAGE>`` is a TriBITS package that has an optional
1655 dependency on ``<TPLNAME>``. That will result in setting
1656 ``TPL_ENABLE_<TPLNAME>=ON`` internally (but not set in the cache) if
1657 ``TPL_ENABLE_<TPLNAME>=OFF`` is not already set.
1658
1659
1660 Specifying the location of the parts of an enabled external package/TPL
1661 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1662
1663 Once an external package/TPL is enabled, the parts of that TPL must be found.
1664 For many external packages/TPLs, this will be done automatically by searching
1665 the environment paths.
1666
1667 Some external packages/TPLs are specified with a call to
1668 ``find_package(<externalPkg>)`` (see CMake documentation for
1669 ``find_package()``). Many other external packages/TPLs use a legacy TriBITS
1670 system that locates the parts using the CMake commands ``find_file()`` and
1671 ``find_library()`` as described below.
1672
1673 Every defined external package/TPL uses a specification provided in a
1674 ``FindTPL<TPLNAME>.cmake`` module file. This file describes how the package
1675 is found in a way that provides modern CMake IMPORTED targets (including the
1676 ``<TPLNAME>::all_libs`` target) that is used by the downstream packages.
1677
1678 Some TPLs require only libraries (e.g. Fortran libraries like BLAS or LAPACK),
1679 some TPL require only include directories, and some TPLs require both.
1680
1681 For ``FindTPL<TPLNAME>.cmake`` files using the legacy TriBITS TPL system, a
1682 TPL is fully specified through the following cache variables:
1683
1684 * ``TPL_<TPLNAME>_INCLUDE_DIRS:PATH``: List of paths to header files for the
1685 TPL (if the TPL supplies header files).
1686
1687 * ``TPL_<TPLNAME>_LIBRARIES:PATH``: List of (absolute) paths to libraries,
1688 ordered as they will be on the link line (of the TPL supplies libraries).
1689
1690 These variables are the only variables are used to create IMPORTED CMake
1691 targets for the TPL. One can set these two variables as CMake cache
1692 variables, for ``SomeTPL`` for example, with::
1693
1694 -D TPL_SomeTPL_INCLUDE_DIRS="${LIB_BASE}/include/a;${LIB_BASE}/include/b" \
1695 -D TPL_SomeTPL_LIBRARIES="${LIB_BASE}/lib/liblib1.so;${LIB_BASE}/lib/liblib2.so" \
1696
1697 Using this approach, one can be guaranteed that these libraries and these
1698 include directories and will used in the compile and link lines for the
1699 packages that depend on this TPL ``SomeTPL``.
1700
1701 **NOTE:** When specifying ``TPL_<TPLNAME>_INCLUDE_DIRS`` and/or
1702 ``TPL_<TPLNAME>_LIBRARIES``, the build system will use these without question.
1703 It will **not** check for the existence of these directories or files so make
1704 sure that these files and directories exist before these are used in the
1705 compiles and links. (This can actually be a feature in rare cases the
1706 libraries and header files don't actually get created until after the
1707 configure step is complete but before the build step.)
1708
1709 **NOTE:** It is generally *not recommended* to specify the TPLs libraries as
1710 just a set of link options as, for example::
1711
1712 TPL_SomeTPL_LIBRARIES="-L/some/dir;-llib1;-llib2;..."
1713
1714 But this is supported as long as this link line contains only link library
1715 directories and library names. (Link options that are not order-sensitive are
1716 also supported like ``-mkl``.)
1717
1718 When the variables ``TPL_<TPLNAME>_INCLUDE_DIRS`` and
1719 ``TPL_<TPLNAME>_LIBRARIES`` are not specified, then most
1720 ``FindTPL<TPLNAME>.cmake`` modules use a default find operation. Some will
1721 call ``find_package(<externalPkg>)`` internally by default and some may
1722 implement the default find in some other way. To know for sure, see the
1723 documentation for the specific external package/TPL (e.g. looking in the
1724 ``FindTPL<TPLNAME>.cmake`` file to be sure). NOTE: if a given
1725 ``FindTPL<TPLNAME>.cmake`` will use ``find_package(<externalPkg>)`` by
1726 default, this can be disabled by configuring with::
1727
1728 -D<TPLNAME>_ALLOW_PACKAGE_PREFIND=OFF
1729
1730 (Not all ``FindTPL<TPLNAME>.cmake`` files support this option.)
1731
1732 Many ``FindTPL<TPLNAME>.cmake`` files, use the legacy TriBITS TPL system for
1733 finding include directories and/or libraries based on the function
1734 `tribits_tpl_find_include_dirs_and_libraries()`_. These simple standard
1735 ``FindTPL<TPLNAME>.cmake`` modules specify a set of header files and/or
1736 libraries that must be found. The directories where these header files and
1737 library files are looked for are specified using the CMake cache variables:
1738
1739 * ``<TPLNAME>_INCLUDE_DIRS:PATH``: List of paths to search for header files
1740 using ``find_file()`` for each header file, in order.
1741
1742 * ``<TPLNAME>_LIBRARY_NAMES:STRING``: List of unadorned library names, in the
1743 order of the link line. The platform-specific prefixes (e.g.. 'lib') and
1744 postfixes (e.g. '.a', '.lib', or '.dll') will be added automatically by
1745 CMake. For example, the library ``libblas.so``, ``libblas.a``, ``blas.lib``
1746 or ``blas.dll`` will all be found on the proper platform using the name
1747 ``blas``.
1748
1749 * ``<TPLNAME>_LIBRARY_DIRS:PATH``: The list of directories where the library
1750 files will be searched for using ``find_library()``, for each library, in
1751 order.
1752
1753 Most of these ``FindTPL<TPLNAME>.cmake`` modules will define a default set of
1754 libraries to look for and therefore ``<TPLNAME>_LIBRARY_NAMES`` can typically
1755 be left off.
1756
1757 Therefore, to find the same set of libraries for ``SimpleTPL`` shown
1758 above, one would specify::
1759
1760 -D SomeTPL_LIBRARY_DIRS="${LIB_BASE}/lib"
1761
1762 and if the set of libraries to be found is different than the default, one can
1763 override that using::
1764
1765 -D SomeTPL_LIBRARY_NAMES="lib1;lib2"
1766
1767 Therefore, this is in fact the preferred way to specify the libraries for
1768 these legacy TriBITS TPLs.
1769
1770 In order to allow a TPL that normally requires one or more libraries to ignore
1771 the libraries, one can set ``<TPLNAME>_LIBRARY_NAMES`` to empty, for example::
1772
1773 -D <TPLNAME>_LIBRARY_NAMES=""
1774
1775 If all the parts of a TPL are not found on an initial configure, the configure
1776 will error out with a helpful error message. In that case, one can change the
1777 variables ``<TPLNAME>_INCLUDE_DIRS``, ``<TPLNAME>_LIBRARY_NAMES``, and/or
1778 ``<TPLNAME>_LIBRARY_DIRS`` in order to help fund the parts of the TPL. One
1779 can do this over and over until the TPL is found. By reconfiguring, one avoids
1780 a complete configure from scratch which saves time. Or, one can avoid the
1781 find operations by directly setting ``TPL_<TPLNAME>_INCLUDE_DIRS`` and
1782 ``TPL_<TPLNAME>_LIBRARIES`` as described above.
1783
1784 **TPL Example 1: Standard BLAS Library**
1785
1786 Suppose one wants to find the standard BLAS library ``blas`` in the
1787 directory::
1788
1789 /usr/lib/
1790 libblas.so
1791 libblas.a
1792 ...
1793
1794 The ``FindTPLBLAS.cmake`` module should be set up to automatically find the
1795 BLAS TPL by simply enabling BLAS with::
1796
1797 -D TPL_ENABLE_BLAS=ON
1798
1799 This will result in setting the CMake cache variable ``TPL_BLAS_LIBRARIES`` as
1800 shown in the CMake output::
1801
1802 -- TPL_BLAS_LIBRARIES='/user/lib/libblas.so'
1803
1804 (NOTE: The CMake ``find_library()`` command that is used internally will
1805 always select the shared library by default if both shared and static
1806 libraries are specified, unless told otherwise. See `Building static
1807 libraries and executables`_ for more details about the handling of shared and
1808 static libraries.)
1809
1810 However, suppose one wants to find the ``blas`` library in a non-default
1811 location, such as in::
1812
1813 /projects/something/tpls/lib/libblas.so
1814
1815 In this case, one could simply configure with::
1816
1817 -D TPL_ENABLE_BLAS=ON \
1818 -D BLAS_LIBRARY_DIRS=/projects/something/tpls/lib \
1819
1820 That will result in finding the library shown in the CMake output::
1821
1822 -- TPL_BLAS_LIBRARIES='/projects/something/tpls/libblas.so'
1823
1824 And if one wants to make sure that this BLAS library is used, then one can
1825 just directly set::
1826
1827 -D TPL_BLAS_LIBRARIES=/projects/something/tpls/libblas.so
1828
1829 **TPL Example 2: Intel Math Kernel Library (MKL) for BLAS**
1830
1831 There are many cases where the list of libraries specified in the
1832 ``FindTPL<TPLNAME>.cmake`` module is not correct for the TPL that one wants to
1833 use or is present on the system. In this case, one will need to set the CMake
1834 cache variable ``<TPLNAME>_LIBRARY_NAMES`` to tell the
1835 `tribits_tpl_find_include_dirs_and_libraries()`_ function what libraries to
1836 search for, and in what order.
1837
1838 For example, the Intel Math Kernel Library (MKL) implementation for the BLAS
1839 is usually given in several libraries. The exact set of libraries needed
1840 depends on the version of MKL, whether 32bit or 64bit libraries are needed,
1841 etc. Figuring out the correct set and ordering of these libraries for a given
1842 platform may be non-trivial. But once the set and the order of the libraries
1843 is known, then one can provide the correct list at configure time.
1844
1845 For example, suppose one wants to use the threaded MKL libraries listed in the
1846 directories::
1847
1848 /usr/local/intel/Compiler/11.1/064/mkl/lib/em64t/
1849 /usr/local/intel/Compiler/11.1/064/lib/intel64/
1850
1851 and the list of libraries being searched for is ``mkl_intel_lp64``,
1852 ``mkl_intel_thread``, ``mkl_core`` and ``iomp5``.
1853
1854 In this case, one could specify this with the following do-configure script::
1855
1856 #!/bin/bash
1857
1858 INTEL_DIR=/usr/local/intel/Compiler/11.1/064
1859
1860 cmake \
1861 -D TPL_ENABLE_BLAS=ON \
1862 -D BLAS_LIBRARY_DIRS="${INTEL_DIR}/em64t;${INTEL_DIR}/intel64" \
1863 -D BLAS_LIBRARY_NAMES="mkl_intel_lp64;mkl_intel_thread;mkl_core;iomp5" \
1864 ...
1865 ${PROJECT_SOURCE_DIR}
1866
1867 This would call ``find_library()`` on each of the listed library names in
1868 these directories and would find them and list them in::
1869
1870 -- TPL_BLAS_LIBRARIES='/usr/local/intel/Compiler/11.1/064/em64t/libmkl_intel_lp64.so;...'
1871
1872 (where ``...`` are the rest of the found libraries.)
1873
1874 NOTE: When shared libraries are used, one typically only needs to list the
1875 direct libraries, not the indirect libraries, as the shared libraries are
1876 linked to each other.
1877
1878 In this example, one could also play it super safe and manually list out the
1879 libraries in the right order by configuring with::
1880
1881 -D TPL_BLAS_LIBRARIES="${INTEL_DIR}/em64t/libmkl_intel_lp64.so;..."
1882
1883 (where ``...`` are the rest of the libraries found in order).
1884
1885
1886 Adjusting upstream dependencies for a Third-Party Library (TPL)
1887 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1888
1889 Some TPLs have dependencies on one or more upstream TPLs. These dependencies
1890 must be specified correctly for the compile and links to work correctly. The
1891 <Project> Project already defines these dependencies for the average situation
1892 for all of these TPLs. However, there may be situations where the
1893 dependencies may need to be tweaked to match how these TPLs were actually
1894 installed on some systems. To redefine what dependencies a TPL can have (if
1895 the upstream TPLs are enabled), set::
1896
1897 -D <TPLNAME>_LIB_DEFINED_DEPENDENCIES="<tpl_1>;<tpl_2>;..."
1898
1899 A dependency on an upstream TPL ``<tpl_i>`` will be set if the an upstream TPL
1900 ``<tpl_i>`` is actually enabled.
1901
1902 If any of the specified dependent TPLs ``<tpl_i>`` are listed after
1903 ``<TPLNAME>`` in the ``TPLsList.cmake`` file (or are not listed at all), then
1904 a configure-time error will occur.
1905
1906 To take complete control over what dependencies an TPL has, set::
1907
1908 -D <TPLNAME>_LIB_ENABLED_DEPENDENCIES="<tpl_1>;<tpl_2>;..."
1909
1910 If the upstream TPLs listed here are not defined upstream and enabled TPLs,
1911 then a configure-time error will occur.
1912
1913
1914 Disabling support for a Third-Party Library (TPL)
1915 +++++++++++++++++++++++++++++++++++++++++++++++++
1916
1917 Disabling a TPL explicitly can be done using::
1918
1919 -D TPL_ENABLE_<TPLNAME>=OFF
1920
1921 This will result in the disabling of any direct or indirect downstream
1922 packages that have a required dependency on ``<TPLNAME>`` as described in
1923 `Disable a package and all its dependencies`_.
1924
1925 NOTE: If a disabled TPL is a required dependency of some explicitly enabled
1926 downstream package, then the configure will error out if
1927 `<Project>_DISABLE_ENABLED_FORWARD_DEP_PACKAGES`_ ``= OFF``. Otherwise, a
1928 NOTE will be printed and the downstream package will be disabled and
1929 configuration will continue.
1930
1931
1932 Disabling tentatively enabled TPLs
1933 ++++++++++++++++++++++++++++++++++
1934
1935 To disable a tentatively enabled TPL, set::
1936
1937 -D TPL_ENABLE_<TPLNAME>=OFF
1938
1939 where ``<TPLNAME>`` = ``BinUtils``, ``Boost``, etc.
1940
1941 NOTE: Some TPLs in <Project> are always tentatively enabled (e.g. BinUtils
1942 for C++ stacktracing) and if all of the components for the TPL are found
1943 (e.g. headers and libraries) then support for the TPL will be enabled,
1944 otherwise it will be disabled. This is to allow as much functionality as
1945 possible to get automatically enabled without the user having to learn about
1946 the TPL, explicitly enable the TPL, and then see if it is supported or not
1947 on the given system. However, if the TPL is not supported on a given
1948 platform, then it may be better to explicitly disable the TPL (as shown
1949 above) so as to avoid the output from the CMake configure process that shows
1950 the tentatively enabled TPL being processes and then failing to be enabled.
1951 Also, it is possible that the enable process for the TPL may pass, but the
1952 TPL may not work correctly on the given platform. In this case, one would
1953 also want to explicitly disable the TPL as shown above.
1954
1955
1956 Require all TPL libraries be found
1957 ++++++++++++++++++++++++++++++++++
1958
1959 By default, some TPLs don't require that all of the libraries listed in
1960 ``<tplName>_LIBRARY_NAMES`` be found. To change this behavior so that all
1961 libraries for all enabled TPLs be found, one can set::
1962
1963 -D <Project>_MUST_FIND_ALL_TPL_LIBS=TRUE
1964
1965 This makes the configure process catch more mistakes with the env.
1966
1967
1968 Disable warnings from TPL header files
1969 ++++++++++++++++++++++++++++++++++++++
1970
1971 To disable warnings coming from included TPL header files for C and C++ code,
1972 set::
1973
1974 -D<Project>_TPL_SYSTEM_INCLUDE_DIRS=TRUE
1975
1976 On some systems and compilers (e.g. GNU), that will result is include
1977 directories for all TPLs to be passed in to the compiler using ``-isystem``
1978 instead of ``-I``.
1979
1980 WARNING: On some systems this will result in build failures involving gfortran
1981 and module files. Therefore, don't enable this if Fortran code in your
1982 project is pulling in module files from TPLs.
1983
1984
1985 Building against pre-installed packages
1986 ---------------------------------------
1987
1988 The <Project> project can build against any pre-installed packages defined in
1989 the project and ignore the internally defined packages. To trigger the enable
1990 of a pre-installed internal package treated as an external package, configure
1991 with::
1992
1993 -D TPL_ENABLE_<TRIBITS_PACKAGE>=ON
1994
1995 That will cause the <Project> CMake project to pull in the pre-installed
1996 package ``<TRIBITS_PACKAGE>`` as an external package using
1997 ``find_package(<TRIBITS_PACKAGE>)`` instead of configuring and building the
1998 internally defined ``<TRIBITS_PACKAGE>`` package.
1999
2000 Configuring and building against a pre-installed package treated as an
2001 external packages has several consequences:
2002
2003 * Any internal packages that are upstream from ``<TRIBITS_PACKAGE>`` from an
2004 enabled set of dependencies will also be treated as external packages (and
2005 therefore must be pre-installed as well).
2006
2007 * The TriBITS package ``Dependencies.cmake`` files for the
2008 ``<TRIBITS_PACKAGE>`` package and all of its upstream packages must still
2009 exist and will still be read in by the <Project> CMake project and the same
2010 enable/disable logic will be performed as if the packages were being treated
2011 internal. (However, the base ``CMakeLists.txt`` and all of other files for
2012 these internally defined packages being treated as external packages can be
2013 missing and will be ignored.)
2014
2015 * The same set of enabled and disabled upstream dependencies must be specified
2016 to the <Project> CMake project that was used to pre-build and pre-install
2017 these internally defined packages being treated as external packages.
2018 (Otherwise, a configure error will result from the mismatch.)
2019
2020 * The definition of any TriBITS external packages/TPLs that are enabled
2021 upstream dependencies from any of these external packages should be defined
2022 automatically and will **not** be found again. (But there can be exceptions
2023 for minimally TriBITS-compliant external packages; see the section
2024 "TriBITS-Compliant External Packages" in the "TriBITS Users Guide".)
2025
2026 The logic for treating internally defined packages as external packages will
2027 be printed in the CMake configure output in the section ``Adjust the set of
2028 internal and external packages`` with output like::
2029
2030 Adjust the set of internal and external packages ...
2031
2032 -- Treating internal package <PKG2> as EXTERNAL because TPL_ENABLE_<PKG2>=ON
2033 -- Treating internal package <PKG1> as EXTERNAL because downstream package <PKG2> being treated as EXTERNAL
2034 -- NOTE: <TPL2> is indirectly downstream from a TriBITS-compliant external package
2035 -- NOTE: <TPL1> is indirectly downstream from a TriBITS-compliant external package
2036
2037 All of these internally defined being treated as external (and all of their
2038 upstream dependencies) are processed in a loop over these just these
2039 TriBITS-compliant external packages and ``find_package()`` is only called on
2040 the terminal TriBITS-compliant external packages. This is shown in the CMake
2041 output in the section ``Getting information for all enabled TriBITS-compliant
2042 or upstream external packages/TPLs`` and looks like::
2043
2044 Getting information for all enabled TriBITS-compliant or upstream external packages/TPLs in reverse order ...
2045
2046 Processing enabled external package/TPL: <PKG2> (...)
2047 -- Calling find_package(<PKG2> for TriBITS-compliant external package
2048 Processing enabled external package/TPL: <PKG1> (...)
2049 -- The external package/TPL <PKG1> was defined by a downstream TriBITS-compliant external package already processed
2050 Processing enabled external package/TPL: <TPL2> (...)
2051 -- The external package/TPL <TPL2> was defined by a downstream TriBITS-compliant external package already processed
2052 Processing enabled external package/TPL: <TPL1> (...)
2053 -- The external package/TPL <TPL1> was defined by a downstream TriBITS-compliant external package already processed
2054
2055 In the above example ``<TPL1>``, ``<TPL2>`` and ``<PKG1>`` are all direct or
2056 indirect dependencies of ``<PKG2>`` and therefore calling just
2057 ``find_package(<PKG2>)`` fully defines those TriBITS-compliant external
2058 packages as well.
2059
2060 All remaining TPLs that are not defined in that first reverse loop are defined
2061 in a second forward loop over regular TPLs::
2062
2063 Getting information for all remaining enabled external packages/TPLs ...
2064
2065 NOTE: The case is also supported where a TriBITS-compliant external package
2066 like ``<PKG2>`` does not define all of it upstream dependencies (i.e. does not
2067 define the ``<TPL2>::all_libs`` target) and these external packages/TPLs will
2068 be found again. This allows the possibility of finding different/inconsistent
2069 upstream dependencies but this is allowed to accommodate some packages with
2070 non-TriBITS CMake build systems that don't create fully TriBITS-compliant
2071 external packages.
2072
2073
2074 xSDK Configuration Options
2075 --------------------------
2076
2077 The configure of <Project> will adhere to the `xSDK Community Package
2078 Policies`_ simply by setting the CMake cache variable::
2079
2080 -D USE_XSDK_DEFAULTS=TRUE
2081
2082 Setting this will have the following impact:
2083
2084 * ``BUILD_SHARED_LIBS`` will be set to ``TRUE`` by default instead of
2085 ``FALSE``, which is the default for raw CMake projects (see `Building shared
2086 libraries`_).
2087
2088 * ``CMAKE_BUILD_TYPE`` will be set to ``DEBUG`` by default instead of
2089 ``RELEASE`` which is the standard TriBITS default (see `CMAKE_BUILD_TYPE`_).
2090
2091 * The compilers in MPI mode ``TPL_ENABLE_MPI=ON`` or serial mode
2092 ``TPL_ENABLE_MPI=OFF`` will be read from the environment variables ``CC``,
2093 ``CXX`` and ``FC`` if they are set but the cmake cache variables
2094 ``CMAKE_C_COMPILER``, ``CMAKE_C_COMPILER`` and ``CMAKE_C_COMPILER`` are not
2095 set. Otherwise, the TriBITS default behavior is to ignore these environment
2096 variables in MPI mode.
2097
2098 * The Fortran flags will be read from environment variable ``FCFLAGS`` if the
2099 environment variable ``FFLAGS`` and the CMake cache variable
2100 ``CMAKE_Fortran_FLAGS`` are empty. Otherwise, raw CMake ignores ``FCFLAGS``
2101 (see `Adding arbitrary compiler flags but keeping default build-type
2102 flags`_).
2103
2104 The rest of the required xSDK configure standard is automatically satisfied by
2105 every TriBITS CMake project, including the <Project> project.
2106
2107
2108 Generating verbose output
2109 -------------------------
2110
2111 There are several different ways to generate verbose output to debug problems
2112 when they occur:
2113
2114 .. _<Project>_TRACE_FILE_PROCESSING:
2115
2116 a) **Trace file processing during configure:**
2117
2118 ::
2119
2120 -D <Project>_TRACE_FILE_PROCESSING=ON
2121
2122 This will cause TriBITS to print out a trace for all of the project's,
2123 repository's, and package's files get processed on lines using the prefix
2124 ``File Trace:``. This shows what files get processed and in what order they
2125 get processed. To get a clean listing of all the files processed by TriBITS
2126 just grep out the lines starting with ``-- File Trace:``. This can be
2127 helpful in debugging configure problems without generating too much extra
2128 output.
2129
2130 Note that `<Project>_TRACE_FILE_PROCESSING`_ is set to ``ON`` automatically
2131 when `<Project>_VERBOSE_CONFIGURE`_ = ``ON``.
2132
2133 .. _<Project>_VERBOSE_CONFIGURE:
2134
2135 b) **Getting verbose output from TriBITS configure:**
2136
2137 To do a complete debug dump for the TriBITS configure process, use::
2138
2139 -D <Project>_VERBOSE_CONFIGURE=ON
2140
2141 However, this produces a *lot* of output so don't enable this unless you are
2142 very desperate. But this level of details can be very useful when debugging
2143 configuration problems.
2144
2145 To just view the package and TPL dependencies, it is recommended to use
2146 ``-D`` `<Project>_DUMP_PACKAGE_DEPENDENCIES`_ ``= ON``.
2147
2148 To just print the link libraries for each library and executable created,
2149 use::
2150
2151 -D <Project>_DUMP_LINK_LIBS=ON
2152
2153 Of course ``<Project>_DUMP_PACKAGE_DEPENDENCIES`` and
2154 ``<Project>_DUMP_LINK_LIBS`` can be used together. Also, note that
2155 ``<Project>_DUMP_PACKAGE_DEPENDENCIES`` and ``<Project>_DUMP_LINK_LIBS``
2156 both default t ``ON`` when ``<Project>_VERBOSE_CONFIGURE=ON`` on the first
2157 configure.
2158
2159
2160 c) **Getting verbose output from the makefile:**
2161
2162 ::
2163
2164 -D CMAKE_VERBOSE_MAKEFILE=TRUE
2165
2166 NOTE: It is generally better to just pass in ``VERBOSE=`` when directly
2167 calling ``make`` after configuration is finished. See `Building with
2168 verbose output without reconfiguring`_.
2169
2170 d) **Getting very verbose output from configure:**
2171
2172 ::
2173
2174 -D <Project>_VERBOSE_CONFIGURE=ON --debug-output --trace
2175
2176 NOTE: This will print a complete stack trace to show exactly where you are.
2177
2178
2179 Enabling/disabling deprecated warnings
2180 --------------------------------------
2181
2182 To turn off all deprecated warnings, set::
2183
2184 -D <Project>_SHOW_DEPRECATED_WARNINGS=OFF
2185
2186 This will disable, by default, all deprecated warnings in packages in
2187 <Project>. By default, deprecated warnings are enabled.
2188
2189 To enable/disable deprecated warnings for a single <Project> package, set::
2190
2191 -D <TRIBITS_PACKAGE>_SHOW_DEPRECATED_WARNINGS=OFF
2192
2193 This will override the global behavior set by
2194 ``<Project>_SHOW_DEPRECATED_WARNINGS`` for individual package
2195 ``<TRIBITS_PACKAGE>``.
2196
2197
2198 Adjusting CMake DEPRECATION warnings
2199 ------------------------------------
2200
2201 By default, deprecated TriBITS features being used in the project's CMake
2202 files will result in CMake deprecation warning messages (issued by calling
2203 ``message(DEPRECATION ...)`` internally). The handling of these deprecation
2204 warnings can be changed by setting the CMake cache variable
2205 ``TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE``. For example, to remove all
2206 deprecation warnings, set::
2207
2208 -D TRIBITS_HANDLE_TRIBITS_DEPRECATED_CODE=IGNORE
2209
2210 Other valid values include:
2211
2212 * ``DEPRECATION``: Issue a CMake ``DEPRECATION`` message and continue (default).
2213 * ``AUTHOR_WARNING``: Issue a CMake ``AUTHOR_WARNING`` message and continue.
2214 * ``SEND_ERROR``: Issue a CMake ``SEND_ERROR`` message and continue.
2215 * ``FATAL_ERROR``: Issue a CMake ``FATAL_ERROR`` message and exit.
2216
2217
2218 Disabling deprecated code
2219 -------------------------
2220
2221 To actually disable and remove deprecated code from being included in
2222 compilation, set::
2223
2224 -D <Project>_HIDE_DEPRECATED_CODE=ON
2225
2226 and a subset of deprecated code will actually be removed from the build. This
2227 is to allow testing of downstream client code that might otherwise ignore
2228 deprecated warnings. This allows one to certify that a downstream client code
2229 is free of calling deprecated code.
2230
2231 To hide deprecated code for a single <Project> package set::
2232
2233 -D <TRIBITS_PACKAGE>_HIDE_DEPRECATED_CODE=ON
2234
2235 This will override the global behavior set by
2236 ``<Project>_HIDE_DEPRECATED_CODE`` for individual package
2237 ``<TRIBITS_PACKAGE>``.
2238
2239
2240 Setting or disabling Python
2241 ----------------------------
2242
2243 To set which Python interpreter is used, configure with::
2244
2245 -D Python3_EXECUTABLE=<python-path>
2246
2247 Otherwise, Python will be found automatically by default using
2248 ``find_python(Python3)`` internally (see `FindPython3.cmake`_).
2249
2250 To disable the finding and usage of Python, configure with (empty)::
2251
2252 -D Python3_EXECUTABLE=
2253
2254
2255 Outputting package dependency information
2256 -----------------------------------------
2257
2258 .. _<Project>_DEPS_DEFAULT_OUTPUT_DIR:
2259
2260 To generate the various XML and HTML package dependency files, one can set the
2261 output directory when configuring using::
2262
2263 -D <Project>_DEPS_DEFAULT_OUTPUT_DIR:FILEPATH=<SOME_PATH>
2264
2265 This will generate, by default, the output files
2266 ``<Project>PackageDependencies.xml``,
2267 ``<Project>PackageDependenciesTable.html``, and
2268 ``CDashSubprojectDependencies.xml``. If ``<Project>_DEPS_DEFAULT_OUTPUT_DIR``
2269 is not set, then the individual output files can be specified as described below.
2270
2271 .. _<Project>_DEPS_XML_OUTPUT_FILE:
2272
2273 The filepath for <Project>PackageDependencies.xml can be overridden (or set
2274 independently) using::
2275
2276 -D <Project>_DEPS_XML_OUTPUT_FILE:FILEPATH=<SOME_FILE_PATH>
2277
2278 .. _<Project>_DEPS_HTML_OUTPUT_FILE:
2279
2280 The filepath for ``<Project>PackageDependenciesTable.html`` can be overridden
2281 (or set independently) using::
2282
2283 -D <Project>_DEPS_HTML_OUTPUT_FILE:FILEPATH=<SOME_FILE_PATH>
2284
2285 .. _<Project>_CDASH_DEPS_XML_OUTPUT_FILE:
2286
2287 The filepath for CDashSubprojectDependencies.xml can be overridden (or set
2288 independently) using::
2289
2290 -D <Project>_CDASH_DEPS_XML_OUTPUT_FILE:FILEPATH=<SOME_FILE_PATH>
2291
2292 NOTES:
2293
2294 * One must start with a clean CMake cache for all of these defaults to work.
2295
2296 * The files ``<Project>PackageDependenciesTable.html`` and
2297 ``CDashSubprojectDependencies.xml`` will only get generated if support for
2298 Python is enabled.
2299
2300
2301 Test-related configuration settings
2302 -----------------------------------
2303
2304 Many options can be set at configure time to determine what tests are enabled
2305 and how they are run. The following subsections described these various
2306 settings.
2307
2308
2309 Enabling different test categories
2310 ++++++++++++++++++++++++++++++++++
2311
2312 To turn on a set a given set of tests by test category, set::
2313
2314 -D <Project>_TEST_CATEGORIES="<CATEGORY0>;<CATEGORY1>;..."
2315
2316 Valid categories include ``BASIC``, ``CONTINUOUS``, ``NIGHTLY``, ``HEAVY`` and
2317 ``PERFORMANCE``. ``BASIC`` tests get built and run for pre-push testing, CI
2318 testing, and nightly testing. ``CONTINUOUS`` tests are for post-push testing
2319 and nightly testing. ``NIGHTLY`` tests are for nightly testing only.
2320 ``HEAVY`` tests are for more expensive tests that require larger number of MPI
2321 processes and longer run times. These test categories are nested
2322 (e.g. ``HEAVY`` contains all ``NIGHTLY``, ``NIGHTLY`` contains all
2323 ``CONTINUOUS`` and ``CONTINUOUS`` contains all ``BASIC`` tests). However,
2324 ``PERFORMANCE`` tests are special category used only for performance testing
2325 and don't nest with the other categories.
2326
2327
2328 Disabling specific tests
2329 ++++++++++++++++++++++++
2330
2331 Any TriBITS-added ctest test (i.e. listed in ``ctest -N``) can be disabled at
2332 configure time by setting::
2333
2334 -D <fullTestName>_DISABLE=ON
2335
2336 where ``<fullTestName>`` must exactly match the test listed out by ``ctest
2337 -N``. This will result in the printing of a line for the excluded test when
2338 `Trace test addition or exclusion`_ is enabled and the test will not be added
2339 with ``add_test()`` and therefore CTest (and CDash) will never see the
2340 disabled test.
2341
2342 Another approach to disable a test is the set the ctest property ``DISABLED``
2343 and print and a message at configure time by setting::
2344
2345 -D <fullTestName>_SET_DISABLED_AND_MSG="<messageWhyDisabled>"
2346
2347 In this case, the test will still be added with ``add_test()`` and seen by
2348 CTest, but CTest will not run the test locally but will mark it as "Not Run"
2349 (and post to CDash as "Not Run" tests with test details "Not Run (Disabled)"
2350 in processes where tests get posted to CDash). Also, ``<messageWhyDisabled>``
2351 will get printed to STDOUT when CMake is run to configure the project and
2352 ``-D<Project>_TRACE_ADD_TEST=ON`` is set.
2353
2354 Also, note that if a test is currently disabled using the ``DISABLED`` option
2355 in the CMakeLists.txt file, then that ``DISABLE`` property can be removed by
2356 configuring with::
2357
2358 -D <fullTestName>_SET_DISABLED_AND_MSG=FALSE
2359
2360 (or any value that CMake evaluates to FALSE like "FALSE", "false", "NO", "no",
2361 "", etc.).
2362
2363 Also note that other specific defined tests can also be excluded using the
2364 ``ctest -E`` argument.
2365
2366
2367 Disabling specific test executable builds
2368 +++++++++++++++++++++++++++++++++++++++++
2369
2370 Any TriBITS-added executable (i.e. listed in ``make help``) can be disabled
2371 from being built by setting::
2372
2373 -D <exeTargetName>_EXE_DISABLE=ON
2374
2375 where ``<exeTargetName>`` is the name of the target in the build system.
2376
2377 Note that one should also disable any ctest tests that might use this
2378 executable as well with ``-D<fullTestName>_DISABLE=ON`` (see above). This
2379 will result in the printing of a line for the executable target being disabled
2380 at configure time to CMake STDOUT.
2381
2382
2383 Disabling just the ctest tests but not the test executables
2384 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2385
2386 To allow the building of the tests and examples in a package (enabled either
2387 through setting `<Project>_ENABLE_TESTS`_ ``= ON`` or
2388 `<TRIBITS_PACKAGE>_ENABLE_TESTS`_ ``= ON``) but not actually define the ctest
2389 tests that will get run, configure with::
2390
2391 -D <TRIBITS_PACKAGE>_SKIP_CTEST_ADD_TEST=TRUE \
2392
2393 (This has the effect of skipping calling the ``add_test()`` command in the
2394 CMake code for the package ``<TRIBITS_PACKAGE>``.)
2395
2396 To avoid defining ctest tests for all of the enabled packages, configure
2397 with::
2398
2399 -D <Project>_SKIP_CTEST_ADD_TEST=TRUE \
2400
2401 (The default for ``<TRIBITS_PACKAGE>_SKIP_CTEST_ADD_TEST`` for each TriBITS
2402 package ``<TRIBITS_PACKAGE>`` is set to the project-wide option
2403 ``<Project>_SKIP_CTEST_ADD_TEST``.)
2404
2405 One can also use these options to "white-list" and "black-list" the set of
2406 package tests that one will run. For example, to enable the building of all
2407 test and example targets but only actually defining ctest tests for two
2408 specific packages (i.e. "white-listing"), one would configure with::
2409
2410 -D <Project>_ENABLE_ALL_PACKAGES=ON \
2411 -D <Project>_ENABLE_TESTS=ON \
2412 -D <Project>_SKIP_CTEST_ADD_TEST=TRUE \
2413 -D <TRIBITS_PACKAGE_1>_SKIP_CTEST_ADD_TEST=FALSE \
2414 -D <TRIBITS_PACKAGE_2>_SKIP_CTEST_ADD_TEST=FALSE \
2415
2416 Alternatively, to enable the building of all test and example targets and
2417 allowing the ctest tests to be defined for all packages except for a couple of
2418 specific packages (i.e. "black-listing"), one would configure with::
2419
2420 -D <Project>_ENABLE_ALL_PACKAGES=ON \
2421 -D <Project>_ENABLE_TESTS=ON \
2422 -D <TRIBITS_PACKAGE_1>_SKIP_CTEST_ADD_TEST=TRUE \
2423 -D <TRIBITS_PACKAGE_2>_SKIP_CTEST_ADD_TEST=TRUE \
2424
2425 Using different values for ``<Project>_SKIP_CTEST_ADD_TEST`` and
2426 ``<TRIBITS_PACKAGE>_SKIP_CTEST_ADD_TEST`` in this way allows for building all
2427 of the test and example targets for the enabled packages but not defining
2428 ctest tests for any set of packages desired. This allows setting up testing
2429 scenarios where one wants to test the building of all test-related targets but
2430 not actually run the tests with ctest for a subset of all of the enabled
2431 packages. (This can be useful in cases where the tests are very expensive and
2432 one can't afford to run all of them given the testing budget, or when running
2433 tests on a given platform is very flaky, or when some packages have fragile or
2434 poor quality tests that don't port to new platforms very well.)
2435
2436 NOTE: These options avoid having to pass specific sets of labels when running
2437 ``ctest`` itself (such as when defining ``ctest -S <script>.cmake`` scripts)
2438 and instead the decisions as to the exact set of ctest tests to define is made
2439 at configure time. Therefore, all of the decisions about what test targets
2440 should be build and which tests should be run can be made at configure time.
2441
2442
2443 Set specific tests to run in serial
2444 +++++++++++++++++++++++++++++++++++
2445
2446 In order to cause a specific test to run by itself on the machine and not at
2447 the same time as other tests (such as when running multiple tests at the same
2448 time with something like ``ctest -j16``), set at configure time::
2449
2450 -D <fullTestName>_SET_RUN_SERIAL=ON
2451
2452 This will set the CTest test property ``RUN_SERIAL`` for the test
2453 ``<fullTestName>``.
2454
2455 This can help to avoid longer runtimes and timeouts when some individual tests
2456 don't run as quickly when run beside other tests running at the same time on
2457 the same machine. These longer runtimes can often occur when running tests
2458 with CUDA code on GPUs and with OpenMP code on some platforms with some OpenMP
2459 options.
2460
2461 Also, if individual tests have ``RUN_SERIAL`` set by default internally, they
2462 can have the ``RUN_SERIAL`` property removed by setting::
2463
2464 -D <fullTestName>_SET_RUN_SERIAL=OFF
2465
2466
2467 Trace test addition or exclusion
2468 ++++++++++++++++++++++++++++++++
2469
2470 To see what tests get added and see those that don't get added for various
2471 reasons, configure with::
2472
2473 -D <Project>_TRACE_ADD_TEST=ON
2474
2475 That will print one line per test and will show if the test got added or not.
2476 If the test is added, it shows some of the key test properties. If the test
2477 did not get added, then this line will show why the test was not added
2478 (i.e. due to criteria related to the test's ``COMM``, ``NUM_MPI_PROCS``,
2479 ``CATEGORIES``, ``HOST``, ``XHOST``, ``HOSTTYPE``, or ``XHOSTTYPE``
2480 arguments).
2481
2482
2483 Enable advanced test start and end times and timing blocks
2484 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2485
2486 For tests added using ``tribits_add_advanced_test()``, one can see start and
2487 end times for the tests and the timing for each ``TEST_<IDX>`` block in the
2488 detailed test output by configuring with::
2489
2490 -D<Project>_SHOW_TEST_START_END_DATE_TIME=ON
2491
2492 The implementation of this feature currently uses ``execute_process(date)``
2493 and therefore will only work on many (but perhaps not all) Linux/Unix/Mac
2494 systems and not native Windows systems.
2495
2496
2497 Setting test timeouts at configure time
2498 +++++++++++++++++++++++++++++++++++++++
2499
2500 .. _DART_TESTING_TIMEOUT:
2501
2502 A maximum default time limit (timeout) for all the tests can be set at
2503 configure time using the cache variable::
2504
2505 -D DART_TESTING_TIMEOUT=<maxSeconds>
2506
2507 where ``<maxSeconds>`` is the number of wall-clock seconds. The default for
2508 most projects is 1500 seconds (see the default value set in the CMake cache).
2509 This value gets scaled by `<Project>_SCALE_TEST_TIMEOUT`_ and then set as the
2510 field ``TimeOut`` in the CMake-generated file ``DartConfiguration.tcl``. The
2511 value ``TimeOut`` from this file is what is directly read by the ``ctest``
2512 executable. Timeouts for tests are important. For example, when an MPI
2513 program has a defect, it can easily hang (forever) until it is manually
2514 killed. If killed by a timeout, CTest will kill the test process and all of
2515 its child processes correctly.
2516
2517 NOTES:
2518
2519 * If ``DART_TESTING_TIMEOUT`` is not explicitly set by the user, then the
2520 projects gives it a default value (typically 1500 seconds but see the value
2521 in the CMakeCache.txt file).
2522
2523 * If ``DART_TESTING_TIMEOUT`` is explicitly set to empty
2524 (i.e. ``-DDART_TESTING_TIMEOUT=``), then by default tests have no timeout
2525 and can run forever until manually killed.
2526
2527 * Individual tests may have their timeout limit set on a test-by-test basis
2528 internally in the project's ``CMakeLists.txt`` files (see the ``TIMEOUT``
2529 argument for ``tribits_add_test()`` and ``tribits_add_advanced_test()``).
2530 When this is the case, the global timeout set with ``DART_TESTING_TIMEOUT``
2531 has no impact on these individually set test timeouts.
2532
2533 * Be careful not set the global test timeout too low since if a machine
2534 becomes loaded tests can take longer to run and may result in timeouts that
2535 would not otherwise occur.
2536
2537 * The value of ``DART_TESTING_TIMEOUT`` and the timeouts for individual tests
2538 can be scaled up or down using the cache variable
2539 `<Project>_SCALE_TEST_TIMEOUT`_.
2540
2541 * To set or override the default global test timeout limit at runtime, see
2542 `Overriding test timeouts`_.
2543
2544
2545 Scaling test timeouts at configure time
2546 +++++++++++++++++++++++++++++++++++++++
2547
2548 .. _<Project>_SCALE_TEST_TIMEOUT:
2549
2550 The global default test timeout `DART_TESTING_TIMEOUT`_ as well as all of the
2551 timeouts for the individual tests that have their own timeout set (through the
2552 ``TIMEOUT`` argument for each individual test) can be scaled by a constant
2553 factor ``<testTimeoutScaleFactor>`` by configuring with::
2554
2555 -D <Project>_SCALE_TEST_TIMEOUT=<testTimeoutScaleFactor>
2556
2557 Here, ``<testTimeoutScaleFactor>`` can be an integral number like ``5`` or can
2558 be fractional number like ``1.5``.
2559
2560 This feature is generally used to compensate for slower machines or overloaded
2561 test machines and therefore only scaling factors greater than 1 are to be
2562 used. The primary use case for this feature is to add large scale factors
2563 (e.g. ``40`` to ``100``) to compensate for running tests using valgrind (see
2564 `Running memory checking`_) but this can also be used for debug-mode builds
2565 that create tests which run more slowly than for full release-mode optimized
2566 builds.
2567
2568 NOTES:
2569
2570 * If ``<Project>_SCALE_TEST_TIMEOUT`` is not set, the the default value is set
2571 to ``1.0`` (i.e. no scaling of test timeouts).
2572
2573 * When scaling the timeouts, the timeout is first truncated to integral
2574 seconds so an original timeout like ``200.5`` will be truncated to ``200``
2575 before it gets scaled.
2576
2577 * Only the first fractional digit of ``<Project>_SCALE_TEST_TIMEOUT`` is used
2578 so ``1.57`` is truncated to ``1.5``, for example, before scaling the test
2579 timeouts.
2580
2581 * The value of the variable `DART_TESTING_TIMEOUT`_ is not changed in the
2582 ``CMakeCache.txt`` file. Only the value of ``TimeOut`` written into the
2583 ``DartConfiguration.tcl`` file (which is directly read by ``ctest``) will be
2584 scaled. (This ensures that running configure over and over again will not
2585 increase ``DART_TESTING_TIMEOUT`` or ``TimeOut`` with each new configure.)
2586
2587
2588 Spreading out and limiting tests running on GPUs
2589 ++++++++++++++++++++++++++++++++++++++++++++++++
2590
2591 For CUDA builds (i.e. ``TPL_ENABLE_CUDA=ON``) with tests that run on a single
2592 node which has multiple GPUs, there are settings that can help ``ctest``
2593 spread out the testing load over all of the GPUs and limit the number of
2594 kernels that can run at the same time on a single GPU.
2595
2596 To instruct ``ctest`` to spread out the load on multiple GPUs, one can set the
2597 following configure-time options::
2598
2599 -D TPL_ENABLE_CUDA=ON \
2600 -D <Project>_AUTOGENERATE_TEST_RESOURCE_FILE=ON \
2601 -D <Project>_CUDA_NUM_GPUS=<num-gpus> \
2602 -D <Project>_CUDA_SLOTS_PER_GPU=<slots-per-gpu> \
2603
2604 This will cause a file ``ctest_resources.json`` to get generated in the base
2605 build directory that CTest will use to spread out the work across the
2606 ``<num-gpus>`` GPUs with a maximum of ``<slots-per-gpu>`` processes running
2607 kernels on any one GPU. (This uses the `CTest Resource Allocation System`_
2608 first added in CMake 3.16 and made more usable in CMake 3.18.)
2609
2610 For example, when running on one node on a system with 4 GPUs per node
2611 (allowing 5 kernels to run at a time on a single GPU) one would configure
2612 with::
2613
2614 -D TPL_ENABLE_CUDA=ON \
2615 -D <Project>_AUTOGENERATE_TEST_RESOURCE_FILE=ON \
2616 -D <Project>_CUDA_NUM_GPUS=4 \
2617 -D <Project>_CUDA_SLOTS_PER_GPU=5 \
2618
2619 This allows, for example, up to 5 tests using 4-rank MPI jobs, or 10 tests
2620 using 2-rank MPI jobs, or 20 tests using 1-rank MPI jobs, to run at the same
2621 time (or any combination of tests that add up to 20 or less total MPI
2622 processes to run a the same time). But a single 21-rank or above MPI test job
2623 would not be allowed to run and would be listed as "Not Run" because it would
2624 have required more than ``<slots-per-gpu> = 5`` MPI processes running kernels
2625 at one time on a single GPU. (Therefore, one must set ``<slots-per-gpu>``
2626 large enough to allow all of the defined tests to run or one should avoid
2627 defining tests that require too many slots for available GPUs.)
2628
2629 The CTest implementation uses a breath-first approach to spread out the work
2630 across all the available GPUs before adding more work for each GPU. For
2631 example, when running two 2-rank MPI tests at the same time (e.g. using
2632 ``ctest -j4``) in the above example, CTest will instruct these tests at
2633 runtime to spread out across all 4 GPUs and therefore run the CUDA kernels for
2634 just one MPI process on each GPU. But when running four 2-rank MPI tests at
2635 the same time (e.g. using ``ctest -j8``), then each of the 4 GPUs would get
2636 the work of two MPI processes (i.e. running two kernels at a time on each of
2637 the 4 GPUs).
2638
2639 One can also manually create a `CTest Resource Specification File`_ and point
2640 to it by setting::
2641
2642 -D TPL_ENABLE_CUDA=ON \
2643 -D CTEST_RESOURCE_SPEC_FILE=<file-path> \
2644
2645 In all cases, ctest will not spread out and limit running on the GPUs unless
2646 ``TPL_ENABLE_CUDA=ON`` is set which causes TriBITS to add the
2647 `RESOURCE_GROUPS`_ test property to each test.
2648
2649 NOTES:
2650
2651 * This setup assumes that a single MPI process will run just one kernel on its
2652 assigned GPU and therefore take up one GPU "slot". So a 2-rank MPI test
2653 will take up 2 total GPU "slots" (either on the same or two different GPUs,
2654 as determined by CTest).
2655
2656 * The underlying test executables/scripts themselves must be set up to read in
2657 the `CTest Resource Allocation Environment Variables`_ set specifically by
2658 ``ctest`` on the fly for each test and then must run on the specific GPUs
2659 specified in those environment variables. (If the project is using a Kokkos
2660 back-end implementation for running CUDA code on the GPU then this will work
2661 automatically since Kokkos is set up to automatically look for these
2662 CTest-set environment variables. Without this CTest and TriBITS
2663 implementation, when running 2-rank MPI tests on a node with 4 GPUs, Kokkos
2664 would just utilize the first two GPUs and leave the other two GPUs idle.
2665 One when running 1-rank MPI tests, Kokkos would only utilize the first GPU
2666 and leave the last three GPUs idle.)
2667
2668 * The option ``<Project>_AUTOGENERATE_TEST_RESOURCE_FILE=ON`` sets the
2669 built-in CMake variable ``CTEST_RESOURCE_SPEC_FILE`` to point to the
2670 generated file ``ctest_resources.json`` in the build directory.
2671
2672 * One can avoid setting the CMake cache variables
2673 ``<Project>_AUTOGENERATE_TEST_RESOURCE_FILE`` or
2674 ``CTEST_RESOURCE_SPEC_FILE`` at configure time and can instead directly pass
2675 the path to the `CTest Resource Specification File`_ directly into ``ctest``
2676 using the command-line option ``--resource-spec-file`` or the
2677 ``ctest_test()`` function argument ``RESOURCE_SPEC_FILE`` (when using a
2678 ``ctest -S`` script driver). (This allows using CMake 3.16+ since support
2679 for the ``CTEST_RESOURCE_SPEC_FILE`` cache variable was not added until
2680 CMake 3.18.)
2681
2682 * **WARNING:** This currently only works for a single node, not multiple
2683 nodes. (CTest needs to be extended to work correctly for multiple nodes
2684 where each node has multiple GPUs. Alternatively, TriBITS could be extended
2685 to make this work for multiple nodes but will require considerable work and
2686 will need to closely interact with the MPI launcher to control what nodes
2687 are run on for each MPI job/test.)
2688
2689 * **WARNING:** This feature is still evolving in CMake/CTest and TriBITS and
2690 therefore the input options and behavior of this may change in the future.
2691
2692
2693 Enabling support for coverage testing
2694 -------------------------------------
2695
2696 To turn on support for coverage testing set::
2697
2698 -D <Project>_ENABLE_COVERAGE_TESTING=ON
2699
2700 This will set compile and link options -fprofile-arcs -ftest-coverage for GCC.
2701 Use 'make dashboard' (see below) to submit coverage results to CDash
2702
2703
2704 Viewing configure options and documentation
2705 -------------------------------------------
2706
2707 a) Viewing available configure-time options with documentation:
2708
2709 ::
2710
2711 $ cd $BUILD_DIR
2712 $ rm -rf CMakeCache.txt CMakeFiles/
2713 $ cmake -LAH -D <Project>_ENABLE_ALL_PACKAGES=ON \
2714 $SOURCE_BASE
2715
2716 You can also just look at the text file CMakeCache.txt after configure which
2717 gets created in the build directory and has all of the cache variables and
2718 documentation.
2719
2720 b) Viewing available configure-time options without documentation:
2721
2722 ::
2723
2724 $ cd $BUILD_DIR
2725 $ rm -rf CMakeCache.txt CMakeFiles/
2726 $ cmake -LA <SAME_AS_ABOVE> $SOURCE_BASE
2727
2728 c) Viewing current values of cache variables:
2729
2730 ::
2731
2732 $ cmake -LA $SOURCE_BASE
2733
2734 or just examine and grep the file CMakeCache.txt.
2735
2736
2737 Enabling extra repositories with add-on packages:
2738 -------------------------------------------------
2739
2740 .. _<Project>_EXTRA_REPOSITORIES:
2741
2742 To configure <Project> with an post extra set of packages in extra TriBITS
2743 repositories, configure with::
2744
2745 -D<Project>_EXTRA_REPOSITORIES="<REPO0>,<REPO1>,..."
2746
2747 Here, ``<REPOi>`` is the name of an extra repository that typically has been
2748 cloned under the main <Project> source directory as::
2749
2750 <Project>/<REPOi>/
2751
2752 For example, to add the packages from SomeExtraRepo one would configure as::
2753
2754 $ cd $SOURCE_BASE_DIR
2755 $ git clone some_url.com/some/dir/SomeExtraRepo
2756 $ cd $BUILD_DIR
2757 $ ./do-configure -D<Project>_EXTRA_REPOSITORIES=SomeExtraRepo \
2758 [Other Options]
2759
2760 After that, all of the extra packages defined in ``SomeExtraRepo`` will appear
2761 in the list of official <Project> packages (after all of the native packages)
2762 and one is free to enable any of the defined add-on packages just like any
2763 other native <Project> package.
2764
2765 NOTE: If ``<Project>_EXTRAREPOS_FILE`` and
2766 ``<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE`` are specified, then the list of
2767 extra repositories in ``<Project>_EXTRA_REPOSITORIES`` must be a subset and in
2768 the same order as the list extra repos read in from the file specified by
2769 `<Project>_EXTRAREPOS_FILE`_. (Also see the variable
2770 `<Project>_PRE_REPOSITORIES`_ as well.)
2771
2772
2773 Enabling extra repositories through a file
2774 ------------------------------------------
2775
2776 .. _<Project>_EXTRAREPOS_FILE:
2777
2778 .. _<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE:
2779
2780 In order to provide the list of extra TriBITS repositories containing add-on
2781 packages from a file, configure with::
2782
2783 -D<Project>_EXTRAREPOS_FILE:FILEPATH=<EXTRAREPOSFILE> \
2784 -D<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE=Continuous
2785
2786 Specifying extra repositories through an extra repos file allows greater
2787 flexibility in the specification of extra repos. This is not needed for a
2788 basic configure of the project but is useful in generating version information
2789 using `<Project>_GENERATE_VERSION_DATE_FILES`_ and
2790 `<Project>_GENERATE_REPO_VERSION_FILE`_ as well as in automated testing using
2791 the ctest -S scripts with the ``tribits_ctest_driver()`` function and the
2792 ``checkin-test.py`` tool.
2793
2794 The valid values of ``<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE`` include
2795 ``Continuous``, ``Nightly``, and ``Experimental``. Only repositories listed
2796 in the file ``<EXTRAREPOSFILE>`` that match this type will be included. Note
2797 that ``Nightly`` matches ``Continuous`` and ``Experimental`` matches
2798 ``Nightly`` and ``Continuous`` and therefore includes all repos by default.
2799
2800 If ``<Project>_IGNORE_MISSING_EXTRA_REPOSITORIES`` is set to ``TRUE``, then
2801 any extra repositories selected who's directory is missing will be ignored.
2802 This is useful when the list of extra repos that a given developer develops or
2803 tests is variable and one just wants TriBITS to pick up the list of existing
2804 repos automatically.
2805
2806 If the file ``<projectDir>/cmake/ExtraRepositoriesList.cmake`` exists, then it
2807 is used as the default value for ``<Project>_EXTRAREPOS_FILE``. However, the
2808 default value for ``<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE`` is empty so
2809 no extra repositories are defined by default unless
2810 ``<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE`` is specifically set to one of
2811 the allowed values.
2812
2813 .. _<Project>_PRE_REPOSITORIES:
2814
2815 NOTE: The set of extra repositories listed in the file
2816 ``<Project>_EXTRAREPOS_FILE`` can be filtered down by setting the variables
2817 ``<Project>_PRE_REPOSITORIES`` if PRE extra repos are listed and/or
2818 ``<Project>_EXTRA_REPOSITORIES`` if POST extra repos are listed.
2819
2820
2821 Selecting a different source location for a package
2822 ---------------------------------------------------
2823
2824 The source location for any package can be changed by configuring with::
2825
2826 -D<TRIBITS_PACKAGE>_SOURCE_DIR_OVERRIDE:STRING=<path>
2827
2828 Here, ``<path>`` can be a relative path or an absolute path, but in both cases
2829 must be under the project source directory (otherwise, an error will occur).
2830 The relative path will then become the relative path for the package under the
2831 binary tree as well.
2832
2833 This can be used, for example, to use a different repository for the
2834 implementation of a package that is otherwise snapshotted into the base
2835 project source repository (e.g. Kokkos in Trilinos).
2836
2837
2838 Reconfiguring completely from scratch
2839 -------------------------------------
2840
2841 To reconfigure from scratch, one needs to delete the the ``CMakeCache.txt``
2842 and base-level ``CMakeFiles/`` directory, for example, as::
2843
2844 $ rm -rf CMakeCache.txt CMakeFiles/
2845 $ ./do-configure [options]
2846
2847 Removing the ``CMakeCache.txt`` file is often needed when removing variables
2848 from the configure line since they are already in the cache. Removing the
2849 ``CMakeFiles/`` directories is needed if there are changes in some CMake
2850 modules or the CMake version itself. However, usually removing just the
2851 top-level ``CMakeCache.txt`` and ``CMakeFiles/`` directory is enough to
2852 guarantee a clean reconfigure from a dirty build directory.
2853
2854 If one really wants a clean slate, then try::
2855
2856 $ rm -rf `ls | grep -v do-configure`
2857 $ ./do-configure [options]
2858
2859
2860 Viewing configure errors
2861 -------------------------
2862
2863 To view various configure errors, read the file::
2864
2865 $BUILD_BASE_DIR/CMakeFiles/CMakeError.log
2866
2867 This file contains detailed output from try-compile commands, Fortran/C name
2868 mangling determination, and other CMake-specific information.
2869
2870
2871 Adding configure timers
2872 -----------------------
2873
2874 To add timers to various configure steps, configure with::
2875
2876 -D <Project>_ENABLE_CONFIGURE_TIMING=ON
2877
2878 This will do bulk timing for the major configure steps which is independent
2879 of the number of packages in the project.
2880
2881 To additionally add timing for the configure of individual packages, configure
2882 with::
2883
2884 -D <Project>_ENABLE_CONFIGURE_TIMING=ON \
2885 -D <Project>_ENABLE_PACKAGE_CONFIGURE_TIMING=ON
2886
2887 If you are configuring a large number of packages (perhaps by including a lot
2888 of add-on packages in extra repos) then you might not want to enable
2889 package-by-package timing since it can add some significant overhead to the
2890 configure times.
2891
2892 If you just want to time individual packages instead, you can enable that
2893 with::
2894
2895 -D <Project>_ENABLE_CONFIGURE_TIMING=ON \
2896 -D <TRIBITS_PACKAGE_0>_PACKAGE_CONFIGURE_TIMING=ON \
2897 -D <TRIBITS_PACKAGE_1>_PACKAGE_CONFIGURE_TIMING=ON \
2898 ...
2899
2900 NOTES:
2901
2902 * This requires that you are running on a Linux/Unix system that has the
2903 standard shell command ``date``. CMake does not have built-in timing
2904 functions so this system command needs to be used instead. This will report
2905 timings to 0.001 seconds but note that the overall configure time will go up
2906 due to the increased overhead of calling ``date`` as a process shell
2907 command.
2908
2909 * '''WARNING:''' Because this feature has to call the ``data`` using CMake's
2910 ``execute_process()`` command, it can be expensive. Therefore, this should
2911 really only be turned on for large projects (where the extra overhead is
2912 small) or for smaller projects for extra informational purposes.
2913
2914
2915 Generating export files
2916 -----------------------
2917
2918 The project <Project> can generate export files for external CMake projects.
2919 These export files provide the lists of libraries, include directories, compilers
2920 and compiler options, etc.
2921
2922 To configure to generate CMake export files for the project, configure with::
2923
2924 -D <Project>_ENABLE_INSTALL_CMAKE_CONFIG_FILES=ON
2925
2926 This will generate the file ``<Project>Config.cmake`` for the project and the
2927 files ``<Package>Config.cmake`` for each enabled package in the build tree.
2928 In addition, this will install versions of these files into the install tree.
2929
2930 The list of export files generated can be reduced by specifying the exact list
2931 of packages the files are requested for with::
2932
2933 -D <Project>_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_PACKAGES="<pkg0>;<pkg1>"
2934
2935 To only install the package ``<Package>Config.cmake`` files and **not** the
2936 project-level ``<Project>Config.cmake`` file, configure with::
2937
2938 -D <Project>_ENABLE_INSTALL_CMAKE_CONFIG_FILES=ON \
2939 -D <Project>_SKIP_INSTALL_PROJECT_CMAKE_CONFIG_FILES=ON \
2940
2941 NOTES:
2942
2943 * Only enabled packages will have their export files generated.
2944
2945 * One would only want to limit the export files generated for very large
2946 projects where the cost my be high for doing so.
2947
2948 * One would want to skip the installation of the project-level
2949 ``<Project>Config.cmake`` file in cases where the TriBITS project's packages
2950 may be built in smaller subsets of packages in different individual CMake
2951 project builds where there is no clear completion to the installation of the
2952 packages for a given TriBITS project containing a larger collection of
2953 packages.
2954
2955
2956 Generating a project repo version file
2957 --------------------------------------
2958
2959 .. _<Project>_GENERATE_REPO_VERSION_FILE:
2960
2961 When working with local git repos for the project sources, one can generate a
2962 ``<Project>RepoVersion.txt`` file which lists all of the repos and their
2963 current versions using::
2964
2965 -D <Project>_GENERATE_REPO_VERSION_FILE=ON
2966
2967 This will cause a ``<Project>RepoVersion.txt`` file to get created in the
2968 binary directory, get installed in the install directory, and get included in
2969 the source distribution tarball.
2970
2971 NOTE: If the base ``.git/`` directory is missing, then no
2972 ``<Project>RepoVersion.txt`` file will get generated and a ``NOTE`` message is
2973 printed to cmake STDOUT.
2974
2975
2976 Show parent(s) commit info in the repo version output
2977 -----------------------------------------------------
2978
2979 .. _<Project>_SHOW_GIT_COMMIT_PARENTS:
2980
2981 When working with local git repos for the project sources, one can include
2982 the repo's head commit parent(s) info in the repo version output using::
2983
2984 -D <Project>_SHOW_GIT_COMMIT_PARENTS=ON
2985
2986 For each parent commit, this will include their SHA1, author name, date, email
2987 and its 80 character summary message in the repo version output string.
2988
2989
2990 Generating git version date files
2991 ---------------------------------
2992
2993 .. _<Project>_GENERATE_VERSION_DATE_FILES:
2994
2995 When working with local git repos for the project sources, one can generate
2996 the files ``VersionDate.cmake`` and ``<Project>_version_date.h`` in the build
2997 directory by setting::
2998
2999 -D <Project>_GENERATE_VERSION_DATE_FILES=ON
3000
3001 These files are generated in the build directory and the file
3002 ``<Project>_version_date.h`` is installed in the installation directory. (In
3003 addition, these files are also generated for each extra repository that are
3004 also version-controlled repos, see `<Project>_EXTRAREPOS_FILE`_.)
3005
3006 These files contain ``<PROJECT_NAME_UC>_VERSION_DATE`` which is a 10-digit
3007 date-time version integer. This integer is created by first using git to
3008 extract the commit date for ``HEAD`` using the command::
3009
3010 env TZ=GMT git log --format="%cd" --date=iso-local -1 HEAD
3011
3012 which returns the date and time for the commit date of ``HEAD`` in the form::
3013
3014 "YYYY-MM-DD hh:mm:ss +0000"
3015
3016 This git commit date is then is used to create a 10-digit date/time integer of
3017 the form::
3018
3019 YYYYMMDDhh
3020
3021 This 10-digit integer is set to a CMake variable
3022 ``<PROJECT_NAME_UC>_VERSION_DATE`` in the generated ``VersionDate.cmake`` file
3023 and a C/C++ preprocessor macro ``<PROJECT_NAME_UC>_VERSION_DATE`` in the
3024 generated ``<Project>_version_date.h`` header file.
3025
3026 This 10-digit date/time integer ``YYYYMMDDhh`` will fit in a signed 32-bit
3027 integer with a maximum value of ``2^32 / 2 - 1`` = ``2147483647``. Therefore,
3028 the maximum date that can be handled is the year 2147 with the max date/time
3029 of ``2147 12 31 23`` = ``2147123123``.
3030
3031 The file ``<Project>_version_date.h`` is meant to be included by downstream
3032 codes to determine the version of ``<Project>`` being used and allows
3033 ``<PROJECT_NAME_UC>_VERSION_DATE`` to be used in C/C++ ``ifdefs`` like::
3034
3035 #if defined(<PROJECT_NAME_UC>_VERSION_DATE) && <PROJECT_NAME_UC>_VERSION_DATE >= 2019032704
3036 /* The version is newer than 2019-03-27 04:00:00 UTC */
3037 ...
3038 #else
3039 /* The version is older than 2019-03-27 04:00:00 UTC */
3040 ...
3041 #endif
3042
3043 This allows downstream codes to know the fine-grained version of <Project> at
3044 configure and build time to adjust for the addition of new features,
3045 deprecation of code, or breaks in backward compatibility (which occur in
3046 specific commits with unique commit dates).
3047
3048 NOTE: If the branch is not hard-reset then the first-parent commits on that
3049 branch will have monotonically increasing git commit dates (adjusted for UTC).
3050 This assumption is required for the correct usage of the
3051 ``<PROJECT_NAME_UC>_VERSION_DATE`` macro as demonstrated above.
3052
3053 NOTE: If the base ``.git/`` directory is missing or the version of git is not
3054 2.10.0 or greater (needed for the ``--date=iso-local`` argument), then the
3055 ``<Project>_version_date.h`` file will still get generated but will have an
3056 undefined macro ``<PROJECT_NAME_UC>_VERSION_DATE`` and a ``NOTE`` message will
3057 be printed to cmake STDOUT.
3058
3059
3060 CMake configure-time development mode and debug checking
3061 --------------------------------------------------------
3062
3063 To turn off CMake configure-time development-mode checking, set::
3064
3065 -D <Project>_ENABLE_DEVELOPMENT_MODE=OFF
3066
3067 This turns off a number of CMake configure-time checks for the <Project>
3068 TriBITS/CMake files including checking the package dependencies and other
3069 usage of TriBITS. These checks can be expensive and may also not be
3070 appropriate for a tarball release of the software. However, this also turns
3071 off strong compiler warnings so this is not recommended by default (see
3072 `<TRIBITS_PACKAGE>_DISABLE_STRONG_WARNINGS`_). For a release of <Project>
3073 this option is set OFF by default.
3074
3075 One of the CMake configure-time debug-mode checks performed as part of
3076 ``<Project>_ENABLE_DEVELOPMENT_MODE=ON`` is to assert the existence of TriBITS
3077 package directories. In development mode, the failure to find a package
3078 directory is usually a programming error (i.e. a miss-spelled package
3079 directory name). But in a tarball release of the project, package directories
3080 may be purposefully missing (see `Creating a tarball of the source tree`_) and
3081 must be ignored.
3082
3083 When building from a reduced source tarball created from the
3084 development sources, set::
3085
3086 -D <Project>_ASSERT_DEFINED_DEPENDENCIES=OFF
3087
3088 or to ``IGNORE``. (valid values include ``FATAL_ERROR``, ``SEND_ERROR``,
3089 ``WARNING``, ``NOTICE``, ``IGNORE`` and ``OFF``)
3090
3091 Setting this ``OFF`` will cause the TriBITS CMake configure to simply ignore
3092 any undefined packages and turn off all dependencies on these missing
3093 packages.
3094
3095 Another type of checking is for optional inserted/external packages
3096 (e.g. packages who's source can optionally be included and is flagged with
3097 ``tribits_allow_missing_external_packages()``). Any of these package
3098 directories that are missing result in the packages being silently ignored by
3099 default. However, notes on what missing packages are being ignored can
3100 printed by configuring with::
3101
3102 -D <Project>_WARN_ABOUT_MISSING_EXTERNAL_PACKAGES=TRUE
3103
3104 These warnings starting with 'NOTE' (not starting with 'WARNING' that would
3105 otherwise trigger warnings in CDash) about missing inserted/external packages
3106 will print regardless of the setting for
3107 ``<Project>_ASSERT_DEFINED_DEPENDENCIES``.
3108
3109 Finally, ``<Project>_ENABLE_DEVELOPMENT_MODE=ON`` results in a number of
3110 checks for invalid usage of TriBITS in the project's ``CMakeLists.txt`` files
3111 and will, by default, abort configure with a fatal error on the first failed
3112 check. This is appropriate for development mode when a project is clean of all
3113 such invalid usage patterns but there are times when it makes sense to report
3114 these check failures in different ways (such as when upgrading TriBITS in a
3115 project that has some invalid usage patterns that just happen work but may be
3116 disallowed in future versions of TriBITS). To change how these invalid usage
3117 checks are handled, set::
3118
3119 -D <Project>_ASSERT_CORRECT_TRIBITS_USAGE=<check-mode>
3120
3121 where ``<check-mode>`` can be ``FATAL_ERROR``, ``SEND_ERROR``, ``WARNING``,
3122 ``IGNORE`` or ``OFF`` (where ``IGNORE`` or ``OFF`` avoids any error reporting
3123 or warnings).
3124
3125 For ``<Project>_ENABLE_DEVELOPMENT_MODE=OFF``, the default for
3126 ``<Project>_ASSERT_CORRECT_TRIBITS_USAGE`` is set to ``IGNORE``.
3127
3128
3129 Building (Makefile generator)
3130 =============================
3131
3132 This section described building using the default CMake Makefile generator.
3133 Building with the Ninja is described in section `Building (Ninja generator)`_.
3134 But every other CMake generator is also supported such as Visual Studio on
3135 Windows, XCode on Macs, and Eclipse project files but using those build
3136 systems are not documented here (consult standard CMake and concrete build
3137 tool documentation).
3138
3139
3140 Building all targets
3141 --------------------
3142
3143 To build all targets use::
3144
3145 $ make [-jN]
3146
3147 where ``N`` is the number of processes to use (i.e. 2, 4, 16, etc.) .
3148
3149
3150 Discovering what targets are available to build
3151 -----------------------------------------------
3152
3153 CMake generates Makefiles with a 'help' target! To see the targets at the
3154 current directory level type::
3155
3156 $ make help
3157
3158 NOTE: In general, the ``help`` target only prints targets in the current
3159 directory, not targets in subdirectories. These targets can include object
3160 files and all, anything that CMake defines a target for in the current
3161 directory. However, running ``make help`` it from the base build directory
3162 will print all major targets in the project (i.e. libraries, executables,
3163 etc.) but not minor targets like object files. Any of the printed targets can
3164 be used as a target for ``make <some-target>``. This is super useful for just
3165 building a single object file, for example.
3166
3167
3168 Building all of the targets for a package
3169 -----------------------------------------
3170
3171 To build only the targets for a given TriBITS package, one can use::
3172
3173 $ make <TRIBITS_PACKAGE>_all
3174
3175 or::
3176
3177 $ cd packages/<TRIBITS_PACKAGE>
3178 $ make
3179
3180 This will build only the targets for TriBITS package ``<TRIBITS_PACKAGE>`` and
3181 its required upstream targets.
3182
3183
3184 Building all of the libraries for a package
3185 -------------------------------------------
3186
3187 To build only the libraries for given TriBITS package, use::
3188
3189 $ make <TRIBITS_PACKAGE>_libs
3190
3191
3192 Building all of the libraries for all enabled packages
3193 ------------------------------------------------------
3194
3195 To build only the libraries for all enabled TriBITS packages, use::
3196
3197 $ make libs
3198
3199 NOTE: This target depends on the ``<PACKAGE>_libs`` targets for all of the
3200 enabled ``<Project>`` packages. You can also use the target name
3201 ``'<Project>_libs``.
3202
3203
3204 Building a single object file
3205 -----------------------------
3206
3207 To build just a single object file (i.e. to debug a compile problem), first,
3208 look for the target name for the object file build based on the source file,
3209 for example for the source file ``SomeSourceFile.cpp``, use::
3210
3211 $ make help | grep SomeSourceFile
3212
3213 The above will return a target name like::
3214
3215 ... SomeSourceFile.o
3216
3217 To find the name of the actual object file, do::
3218
3219 $ find . -name "*SomeSourceFile*.o"
3220
3221 that will return something like::
3222
3223 ./CMakeFiles/<source-dir-path>.dir/SomeSourceFile.cpp.o
3224
3225 (but this file location and name depends on the source directory structure,
3226 the version of CMake, and other factors). Use the returned name (exactly) for
3227 the object file returned in the above find operation to remove the object file
3228 first, for example, as::
3229
3230 $ rm ./CMakeFiles/<source-dir-path>.dir/SomeSourceFile.cpp.o
3231
3232 and then build it again, for example, with::
3233
3234 $ make SomeSourceFile.o
3235
3236 Again, the names of the target and the object file name an location depend on
3237 the CMake version, the structure of your source directories and other factors
3238 but the general process of using ``make help | grep <some-file-base-name>`` to
3239 find the target name and then doing a find ``find . -name
3240 "*<some-file-base-name>*"`` to find the actual object file path always works.
3241
3242 For this process to work correctly, you must be in the subdirectory where the
3243 ``tribits_add_library()`` or ``tribits_add_executable()`` command is called
3244 from its ``CMakeLists.txt`` file, otherwise the object file targets will not be
3245 listed by ``make help``.
3246
3247 NOTE: CMake does not seem to not check on dependencies when explicitly
3248 building object files as shown above so you need to always delete the object
3249 file first to make sure that it gets rebuilt correctly.
3250
3251
3252 Building with verbose output without reconfiguring
3253 --------------------------------------------------
3254
3255 One can get CMake to generate verbose make output at build time by just
3256 setting the Makefile variable ``VERBOSE=1``, for example, as::
3257
3258 $ make VERBOSE=1 [<SOME_TARGET>]
3259
3260 Any number of compile or linking problem can be quickly debugged by seeing the
3261 raw compile and link lines. See `Building a single object file`_ for more
3262 details.
3263
3264 NOTE: The libraries listed on the link line are often in the form
3265 ``-L<lib-dir> -l<lib1> -l<lib2>`` even if one passed in full library paths for
3266 TPLs through ``TPL_<TPLNAME>_LIBRARIES`` (see `Enabling support for an
3267 optional Third-Party Library (TPL)`_). That is because CMake tries to keep
3268 the link lines as short as possible and therefore it often does this
3269 translation automatically (whether you want it to or not).
3270
3271
3272 Relink a target without considering dependencies
3273 ------------------------------------------------
3274
3275 CMake provides a way to rebuild a target without considering its dependencies
3276 using::
3277
3278 $ make <SOME_TARGET>/fast
3279
3280
3281 Building (Ninja generator)
3282 ==========================
3283
3284 When using the Ninja back-end (see `Enabling support for Ninja`_), one can
3285 build with simply::
3286
3287 ninja -j<N>
3288
3289 or use any options and workflows that the raw ``ninja`` executable supports
3290 (see ``ninja --help``). In general, the ``ninja`` command can only be run
3291 from the base project binary directory and running it from the subdirectory
3292 will not work without having to use the ``-C <dir>`` option pointing to the
3293 base dir and one will need to pass in specific target names or the entire
3294 project targets will get built with the default ``all`` target.
3295
3296 But if the TriBITS-created Ninja makefiles are also generated (see
3297 `<Project>_WRITE_NINJA_MAKEFILES`_), then ``make`` can be run from any
3298 subdirectory to build targets in that subdirectory. Because of this and other
3299 advantages of these makefiles, the majority of the instructions below will be
3300 for running with these makefiles, not the raw ``ninja`` command. These
3301 makefiles define many of the standard targets that are provided by the default
3302 CMake-generated makefiles like ``all``, ``clean``, ``install``, and
3303 ``package_source`` (run ``make help`` to see all of the targets).
3304
3305
3306 Building in parallel with Ninja
3307 -------------------------------
3308
3309 By default, running the raw ``ninja`` command::
3310
3311 ninja
3312
3313 will use **all** of the free cores on the node to build targets in parallel on
3314 the machine! This will not overload the machine but it will not leave any
3315 unused cores either (see Ninja documentation).
3316
3317 To run the raw ``ninja`` command to build with a specific number of build
3318 processes (regardless of machine load), e.g. ``16`` build processes, use::
3319
3320 ninja -j16
3321
3322 When using the TriBITS-generated Ninja makefiles, running with::
3323
3324 make
3325
3326 will also use all of the free cores, and **not** just one process like with
3327 the default CMake-generated makefiles.
3328
3329 But with the TriBITS-generated Ninja makefiles, to build with a specific
3330 number of build processes (regardless of machine load), e.g. ``16`` build
3331 processes, one can **not** use ``-j<N>`` but instead must use the ``NP=<N>``
3332 argument with::
3333
3334 make NP=16
3335
3336 which will call ``ninja -j16`` internally.
3337
3338 That reason that ``-j16`` cannot be used with these TriBITS-generated Ninja
3339 Makefiles is that the ``make`` program does not inform the executed
3340 ``Makefile`` the value of this option and therefore this can't be passed on to
3341 the underlying ``ninja`` command. Therefore the ``make`` option ``-j<N>`` is
3342 essentially ignored. Therefore, running ``make -j16`` will result in calling
3343 raw ``ninja`` which will use all of the free cores on the machine. Arguably
3344 that is better than using only one core and will not overload the machine but
3345 still this is behavior the user must be aware.
3346
3347
3348 Building in a subdirectory with Ninja
3349 -------------------------------------
3350
3351 To build from a binary subdirectory in the build tree with the
3352 TriBITS-generated Ninja makefiles, just ``cd`` into that directory and build
3353 with::
3354
3355 cd <some-subdir>/
3356 make NP=16
3357
3358 and this will only build targets that are defined in that subdirectory. (See
3359 the raw ``ninja`` command that gets called in this case which is echoed at the
3360 top.)
3361
3362
3363 Building verbose without reconfiguring with Ninja
3364 -------------------------------------------------
3365
3366 To build targets and see the full build lines for each with the Ninja
3367 makefiles, build with::
3368
3369 make NP=10 VERBOSE=1 <target_name>
3370
3371 But note that ``ninja`` will automatically provide the full build command for
3372 a build target when that target fails so the ``VERBOSE=1`` option is not
3373 needed in the case were a build target is failing but is useful in other cases
3374 none the less.
3375
3376
3377 Discovering what targets are available to build with Ninja
3378 ----------------------------------------------------------
3379
3380 To determine the target names for library, executable (or any other general
3381 target except for object files) that can be built in any binary directory with
3382 the TriBITS-generated Ninja Makefiles, use::
3383
3384 make help
3385
3386 which will return::
3387
3388 This Makefile supports the following standard targets:
3389
3390 all (default)
3391 clean
3392 help
3393 install
3394 test
3395 package
3396 package_source
3397 edit_cache
3398 rebuild_cache
3399
3400 and the following project targets:
3401
3402 <target0>
3403 <target1>
3404 ...
3405
3406 Run 'make help-objects' to list object files.
3407
3408 To determine the target names for building any object files that can be run in
3409 any directory with the TriBITS-generated Ninja Makefiles, use::
3410
3411 make help-objects
3412
3413 which will return::
3414
3415 This Makefile supports the following object files:
3416
3417 <object-target-0>
3418 <object-target-1>
3419 ...
3420
3421 NOTE: The raw ``ninja`` command does not provide a compact way to list all of
3422 the targets that can be built in any given directory.
3423
3424
3425 Building specific targets with Ninja
3426 ------------------------------------
3427
3428 To build with any specific target, use::
3429
3430 make NP=16 <target>
3431
3432 See `Discovering what targets are available to build with Ninja`_ for how to get
3433 a list of targets.
3434
3435
3436 Building single object files with Ninja
3437 ---------------------------------------
3438
3439 To build any object file, use::
3440
3441 make NP=16 <object-target>
3442
3443 See `Discovering what targets are available to build with Ninja`_ for how to get
3444 a list of the object file targets.
3445
3446 Note that unlike the native CMake-generated Makefiles, when an object target
3447 like this gets built, Ninja will build all of the upstream targets as well.
3448 For example, if you change an upstream header file and just want to see the
3449 impact of building a single ``*.o`` file, this target will build **all** of
3450 the targets for the library where the object fill will gets used. But this is
3451 not generally what one wants to do to iteratively develop the compilation of a
3452 single object file.
3453
3454 To avoid that behavior and instead just build a single ``*.o`` file, first one
3455 must instead use::
3456
3457 make VERBOSE=1 <object-target>
3458
3459 to print the command-line for building the one object file, and then ``cd`` to
3460 the base project binary directory and manually run that command to build only
3461 that object file. (This can be considered a regression w.r.t. the native
3462 CMake-generated Makefiles.)
3463
3464 NOTE: The raw ``ninja`` command does not provide a compact way to list all of
3465 the object files that can be built and does not make it easy to build a single
3466 object file.
3467
3468
3469 Cleaning build targets with Ninja
3470 ---------------------------------
3471
3472 With the TriBITS-generated Ninja Makefiles, when one runs::
3473
3474 make clean
3475
3476 in a subdirectory to clean out the targets in that subdirectory, the
3477 underlying ``ninja`` command will actually delete not only the targets in that
3478 subdirectory but instead will clean **all** the targets upstream from the
3479 targets in the current subdirectory as well! This is **not** the behavior of
3480 the default CMake-generated Makefiles where only the generated files in that
3481 subdirectory will be removed and files for upstream dependencies.
3482
3483 Therefore, if one then wants to clean only the object files, libraries, and
3484 executables in a subdirectory, one should just manually delete them with::
3485
3486 cd <some-subdir>/
3487 find . -name "*.o" -exec rm {} \;
3488 find . -name "lib*.a" -exec rm {} \;
3489 find . -name "lib*.so*" -exec rm {} \;
3490 find . -name "*.exe" -exec rm {} \;
3491
3492 then one can rebuild just the targets in that subdirectory with::
3493
3494 make NP=10
3495
3496
3497 Testing with CTest
3498 ==================
3499
3500 This section assumes one is using the CMake Makefile generator described
3501 above. Also, the ``ctest`` does not consider make dependencies when running
3502 so the software must be completely built before running ``ctest`` as described
3503 here.
3504
3505
3506 Running all tests
3507 -----------------
3508
3509 To run all of the defined tests (i.e. created using ``tribits_add_test()`` or
3510 ``tribits_add_advanced_test()``) use::
3511
3512 $ ctest -j<N>
3513
3514 (where ``<N>`` is an integer for the number of processes to try to run tests
3515 in parallel). A summary of what tests are run and their pass/fail status will
3516 be printed to the screen. Detailed output about each of the tests is archived
3517 in the generate file::
3518
3519 Testing/Temporary/LastTest.log
3520
3521 where CTest creates the ``Testing`` directory in the local directory where you
3522 run it from.
3523
3524 NOTE: The ``-j<N>`` argument allows CTest to use more processes to run tests.
3525 This will intelligently load balance the defined tests with multiple processes
3526 (i.e. MPI tests) and will try not exceed the number of processes ``<N>``.
3527 However, if tests are defined that use more that ``<N>`` processes, then CTest
3528 will still run the test but will not run any other tests while the limit of
3529 ``<N>`` processes is exceeded. To exclude tests that require more than
3530 ``<N>`` processes, set the cache variable ``MPI_EXEC_MAX_NUMPROCS`` (see
3531 `Configuring with MPI support`_).
3532
3533
3534 Only running tests for a single package
3535 ---------------------------------------
3536
3537 Tests for just a single TriBITS package can be run with::
3538
3539 $ ctest -j4 -L <TRIBITS_PACKAGE>
3540
3541 or::
3542
3543 $ cd packages/<TRIBITS_PACKAGE>
3544 $ ctest -j4
3545
3546 This will run tests for packages and subpackages inside of the parent package
3547 ``<TRIBITS_PACKAGE>``.
3548
3549 NOTE: CTest has a number of ways to filter what tests get run. You can use
3550 the test name using ``-E``, you can exclude tests using ``-I``, and there are
3551 other approaches as well. See ``ctest --help`` and on-line documentation, and
3552 experiment for more details.
3553
3554
3555 Running a single test with full output to the console
3556 -----------------------------------------------------
3557
3558 To run just a single test and send detailed output directly to the console,
3559 one can run::
3560
3561 $ ctest -R ^<FULL_TEST_NAME>$ -VV
3562
3563 However, when running just a single test, it is usually better to just run the
3564 test command manually to allow passing in more options. To see what the
3565 actual test command is, use::
3566
3567 $ ctest -R ^<FULL_TEST_NAME>$ -VV -N
3568
3569 This will only print out the test command that ``ctest`` runs and show the
3570 working directory. To run the test exactly as ``ctest`` would, cd into the
3571 shown working directory and run the shown command.
3572
3573
3574 Overriding test timeouts
3575 -------------------------
3576
3577 The configured global test timeout described in ``Setting test timeouts at
3578 configure time`` can be overridden on the CTest command-line as::
3579
3580 $ ctest --timeout <maxSeconds>
3581
3582 This will override the configured cache variable `DART_TESTING_TIMEOUT`_
3583 (actually, the scaled value set as ``TimeOut`` in the file
3584 ``DartConfiguration.tcl``). However, this will **not** override the test
3585 time-outs set on individual tests on a test-by-test basis!
3586
3587 **WARNING:** Do not try to use ``--timeout=<maxSeconds>`` or CTest will just
3588 ignore the argument!
3589
3590
3591 Running memory checking
3592 -----------------------
3593
3594 To configure for running memory testing with ``valgrind``, use::
3595
3596 -D MEMORYCHECK_COMMAND=<abs-path-to-valgrind>/valgrind \
3597 -D MEMORYCHECK_SUPPRESSIONS_FILE=<abs-path-to-supp-file0> \
3598 -D MEMORYCHECK_COMMAND_OPTIONS="-q --trace-children=yes --tool=memcheck \
3599 --leak-check=yes --workaround-gcc296-bugs=yes \
3600 --num-callers=50 --suppressions=<abs-path-to-supp-file1> \
3601 ... --suppressions=<abs-path-to-supp-fileN>"
3602
3603 Above, you have to set the absolute path to the valgrind executable to run
3604 using ``MEMORYCHECK_COMMAND`` as CMake will not find this for you by default.
3605 To use a single valgrind suppression file, just set
3606 ``MEMORYCHECK_SUPPRESSIONS_FILE`` to the path of that suppression file as
3607 shown above. To add other suppression files, they have to be added as other
3608 general valgrind arguments in ``MEMORYCHECK_COMMAND_OPTIONS`` as shown.
3609
3610 After configuring with the above options, to run the memory tests for all
3611 enabled tests, from the **base** project build directory, do::
3612
3613 $ ctest -T memcheck
3614
3615 This will run valgrind on **every** test command that is run by ctest.
3616
3617 To run valgrind on the tests for a single package, from the **base** project
3618 directory, do::
3619
3620 $ ctest -T memcheck -L <TRIBITS_PACKAGE>
3621
3622 To run valgrind on a specific test, from the **base** project directory, do::
3623
3624 $ ctest -T memcheck -R ^<FULL_TEST_NAME>$
3625
3626 Detailed output from valgrind is printed in the file::
3627
3628 Testing/Temporary/LastDynamicAnalysis_<DATE_TIME>.log
3629
3630 NOTE: If you try to run memory tests from any subdirectories, it will not
3631 work. You have to run them from the ***base** project build directory as
3632 shown above. A nice way to view valgrind results is to submit to CDash using
3633 the ``dashboard`` target (see `Dashboard submissions`_).
3634
3635 NOTE: You have to use the valgrind option ``--trace-children=yes`` to trace
3636 through child processes. This is needed if you have tests that are given as
3637 CMake -P scripts (such as advanced tests) or tests driven in bash, Perl,
3638 Python, or other languages.
3639
3640
3641 Installing
3642 ==========
3643
3644 After a build and test of the software is complete, the software can be
3645 installed. Actually, to get ready for the install, the install directory must
3646 be specified at configure time by setting the variable
3647 ``CMAKE_INSTALL_PREFIX`` in addition to other variables that affect the
3648 installation (see the following sections). The other commands described below
3649 can all be run after the build and testing is complete.
3650
3651 For the most typical case where the software is build and installed on the
3652 same machine in the same location where it will be used, one just needs to
3653 configure with::
3654
3655 $ cmake -DCMAKE_INSTALL_PREFIX=<install-base-dir> [other options] \
3656 ${SOURCE_DIR}
3657 $ make -j<N> install
3658
3659 For more details, see the following subsections:
3660
3661 * `Setting the install prefix`_
3662 * `Setting install RPATH`_
3663 * `Avoiding installing libraries and headers`_
3664 * `Installing the software`_
3665 * `Using the installed software in downstream CMake projects`_
3666 * `Using packages from the build tree in downstream CMake projects`_
3667
3668
3669 Setting the install prefix
3670 --------------------------
3671
3672 In order to set up for the install, the install prefix should be set up at
3673 configure time by setting, for example::
3674
3675 -D CMAKE_INSTALL_PREFIX=$HOME/install/<Project>/mpi/opt
3676
3677 The default location for the installation of libraries, headers, and
3678 executables is given by the variables (with defaults)::
3679
3680 -D <Project>_INSTALL_INCLUDE_DIR="include" \
3681 -D <Project>_INSTALL_LIB_DIR="lib" \
3682 -D <Project>_INSTALL_RUNTIME_DIR="bin" \
3683 -D <Project>_INSTALL_EXAMPLE_DIR="example"
3684
3685 If these paths are relative (i.e. don't start with "/" and use type
3686 ``STRING``) then they are relative to ``${CMAKE_INSTALL_PREFIX}``. Otherwise
3687 the paths can be absolute (use type ``PATH``) and don't have to be under
3688 ``${CMAKE_INSTALL_PREFIX}``. For example, to install each part in any
3689 arbitrary location use::
3690
3691 -D <Project>_INSTALL_INCLUDE_DIR="/usr/<Project>_include" \
3692 -D <Project>_INSTALL_LIB_DIR="/usr/<Project>_lib" \
3693 -D <Project>_INSTALL_RUNTIME_DIR="/usr/<Project>_bin" \
3694 -D <Project>_INSTALL_EXAMPLE_DIR="/usr/share/<Project>/examples"
3695
3696 NOTE: The defaults for the above include paths will be set by the standard
3697 CMake module ``GNUInstallDirs`` if ``<Project>_USE_GNUINSTALLDIRS=TRUE`` is
3698 set. Some projects have this set by default (see the ``CMakeCache.txt`` after
3699 configuring to see default being used by this project).
3700
3701 WARNING: To overwrite default relative paths, you must use the data type
3702 ``STRING`` for the cache variables. If you don't, then CMake will use the
3703 current binary directory for the base path. Otherwise, if you want to specify
3704 absolute paths, use the data type ``PATH`` as shown above.
3705
3706
3707 Setting install ownership and permissions
3708 -----------------------------------------
3709
3710 By default, when installing with the ``install`` (or
3711 ``install_package_by_package``) target, any files and directories created are
3712 given the default permissions for the user that runs the install command (just
3713 as if they typed ``mkdir <some-dir>`` or ``touch <some-file>``). On most
3714 Unix/Linux systems, one can use ``umask`` to set default permissions and one
3715 can set the default group and the group sticky bit to control what groups owns
3716 the newly created files and directories. However, some computer systems do
3717 not support the group sticky bit and there are cases where one wants or needs
3718 to provide different group ownership and write permissions.
3719
3720 To control what group owns the install-created files and directories related
3721 to ``CMAKE_INSTALL_PREFIX`` and define the permissions on those, one can set
3722 one or more of the following options::
3723
3724 -D <Project>_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR=<install-base-dir> \
3725 -D <Project>_MAKE_INSTALL_GROUP=[<owning-group>] \
3726 -D <Project>_MAKE_INSTALL_GROUP_READABLE=[TRUE|FALSE] \
3727 -D <Project>_MAKE_INSTALL_GROUP_WRITABLE=[TRUE|FALSE] \
3728 -D <Project>_MAKE_INSTALL_WORLD_READABLE=[TRUE|FALSE] \
3729
3730 (where ``<Project>_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR`` must be a
3731 base directory of ``CMAKE_INSTALL_PREFIX``). This has the impact of both
3732 setting the built-in CMake variable
3733 ``CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`` with the correct permissions
3734 according to these and also triggers the automatic running of the recursive
3735 ``chgrp`` and ``chmod`` commands starting from the directory
3736 ``<install-base-dir>`` on down, after all of the other project files have been
3737 installed. The directory set by
3738 ``<Project>_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR`` and those below it
3739 may be created by the ``install`` command by CMake (as it may not exist before
3740 the install). If ``<Project>_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR``
3741 is not given, then it is set internally to the same directory as
3742 ``CMAKE_INSTALL_PREFIX``.
3743
3744 For an example, to configure for an install based on a dated base directory
3745 where a non-default group should own the installation and have group
3746 read/write permissions, and "others" only have read access, one would
3747 configure with::
3748
3749 -D CMAKE_INSTALL_PREFIX=$HOME/2020-04-25/my-proj \
3750 -D <Project>_SET_GROUP_AND_PERMISSIONS_ON_INSTALL_BASE_DIR=$HOME/2020-04-25 \
3751 -D <Project>_MAKE_INSTALL_GROUP=some-other-group \
3752 -D <Project>_MAKE_INSTALL_GROUP_WRITABLE=TRUE \
3753 -D <Project>_MAKE_INSTALL_WORLD_READABLE=TRUE \
3754
3755 Using these settings, after all of the files and directories have been
3756 installed using the ``install`` or ``install_package_by_package`` build
3757 targets, the following commands are automatically run at the very end::
3758
3759 chgrp some-other-group $HOME/2020-04-25
3760 chmod g+rwX,o+rX $HOME/2020-04-25
3761 chgrp some-other-group -R $HOME/2020-04-25/my-proj
3762 chmod g+rwX,o+rX -R $HOME/2020-04-25/my-proj
3763
3764 That allows the owning group ``some-other-group`` to later modify or delete
3765 the installation and allows all users to use the installation.
3766
3767 NOTES:
3768
3769 * Setting ``<Project>_MAKE_INSTALL_GROUP_WRITABLE=TRUE`` implies
3770 ``<Project>_MAKE_INSTALL_GROUP_READABLE=TRUE``.
3771
3772 * Non-recursive ``chgrp`` and ``chmod`` commands are run on the directories
3773 above ``CMAKE_INSTALL_PREFIX``. Recursive ``chgrp`` and ``chmod`` commands
3774 are only run on the base ``CMAKE_INSTALL_PREFIX`` directory itself. (This
3775 avoids touching any files or directories not directly involved in this
3776 install.)
3777
3778
3779 Setting install RPATH
3780 ---------------------
3781
3782 Setting RPATH for installed shared libraries and executables
3783 (i.e. ``BUILD_SHARED_LIBS=ON``) can be a little tricky. Some discussion of
3784 how raw CMake handles RPATH and installations can be found at:
3785
3786 .. _CMake RPATH handling reference:
3787
3788 https://cmake.org/Wiki/CMake_RPATH_handling
3789
3790 The TriBITS/CMake build system being used for this <Project> CMake project
3791 defines the following default behavior for installed RPATH (which is not the
3792 same as the raw CMake default behavior):
3793
3794 * ``CMAKE_INSTALL_RPATH`` for all libraries and executables built and installed
3795 by this CMake project is set to ``${<Project>_INSTALL_LIB_DIR}``. (This
3796 default is controlled by the variable `<Project>_SET_INSTALL_RPATH`_.)
3797
3798 * The path for all shared external libraries (i.e. TPLs) is set to the
3799 location of the external libraries passed in (or automatically discovered)
3800 at configure time. (This is controlled by the built-in CMake cache variable
3801 ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` which is set to ``TRUE`` by default
3802 for most TriBITS projects but is empty "" for raw CMake.)
3803
3804 The above default behavior allows the installed executables and libraries to
3805 be run without needing to set ``LD_LIBRARY_PATH`` or any other system
3806 environment variables. However, this setting does not allow the installed
3807 libraries and executables to be easily moved or relocated. There are several
3808 built-in CMake variables that control how RPATH is handled related to
3809 installations. The built-in CMake variables that control RPATH handling
3810 include ``CMAKE_INSTALL_RPATH``, ``CMAKE_SKIP_BUILD_RPATH``,
3811 ``CMAKE_SKIP_INSTALL_RPATH``, ``CMAKE_SKIP_RPATH``,
3812 ``CMAKE_BUILD_WITH_INSTALL_RPATH``, ``CMAKE_INSTALL_RPATH_USE_LINK_PATH``.
3813 The TriBITS/CMake build system for <Project> respects all of these raw CMake
3814 variables and their documented effect on the build and install.
3815
3816 In addition, this TriBITS/CMake project defines the cache variable:
3817
3818 .. _<Project>_SET_INSTALL_RPATH:
3819
3820 **<Project>_SET_INSTALL_RPATH**: If ``TRUE``, then the global CMake variable
3821 ``CMAKE_INSTALL_RPATH`` is set to ``<Project>_INSTALL_LIB_DIR``. If
3822 ``CMAKE_INSTALL_RPATH`` is set by the user, then that is used instead. This
3823 avoids having to manually set ``CMAKE_INSTALL_RPATH`` to the correct default
3824 install directory.
3825
3826 Rather than re-documenting all of the native CMake RPATH variables mentioned
3827 above, instead, we describe how these variables should be set for different
3828 installation and distribution scenarios:
3829
3830 0. `Use default CMake behavior`_
3831 1. `Libraries and executables are built, installed and used on same machine`_ (TriBITS default)
3832 2. `Targets will move after installation`_
3833 3. `Targets and TPLs will move after installation`_
3834 4. `Explicitly set RPATH for the final target system`_
3835 5. `Define all shared library paths at runtime using environment variables`_
3836
3837 These scenarios in detail are:
3838
3839 .. _Use default CMake behavior:
3840
3841 0. *Use default CMake behavior:* If one just wants the default raw CMake
3842 behavior with respect to RPATH, then configure with::
3843
3844 -D<Project>_SET_INSTALL_RPATH=FALSE \
3845 -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=FALSE \
3846
3847 This will not put any directories into RPATH for the installed libraries or
3848 executables. This is the same behavior as setting
3849 ``CMAKE_SKIP_INSTALL_RPATH=TRUE`` (see `Define all shared library paths at
3850 runtime using environment variables`_).
3851
3852 .. _Libraries and executables are built, installed and used on same machine:
3853
3854 1. *Libraries and executables are built, installed and used on same machine
3855 (TriBITS default):* One needs no options for this behavior but to make this
3856 explicit then configure with::
3857
3858 -D<Project>_SET_INSTALL_RPATH=TRUE \
3859 -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \
3860
3861 As described above, this allows libraries and executables to be used right
3862 away once installed without needing to set any environment variables.
3863
3864 Note that this also allows the installed libraries and executables to be
3865 moved to the same location on an different but identical machine as well.
3866
3867 .. _Targets will move after installation:
3868
3869 2. *Targets will move after installation:* In this scenario, the final
3870 location of built libraries and executables will be different on the same
3871 machine or an otherwise identical machine. In this case, we assume that
3872 all of the external library references and directories would be the same.
3873 In this case, one would generally configure with::
3874
3875 -D<Project>_SET_INSTALL_RPATH=FALSE \
3876 -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \
3877
3878 Then, to run any executables using these shared libraries, one must update
3879 LD_LIBRARY_PATH as::
3880
3881 $ export LD_LIBRARY_PATH=<final-install-dir>/lib:$LD_LIBRARY_PATH
3882
3883 Or, if the final directory location is known, then one can directly
3884 ``CMAKE_INSTALL_RPATH`` at configure time to match the final target system
3885 and then one does not need to mess with ``LD_LIBRARY_PATH`` or any other
3886 env variables (see `Explicitly set RPATH for the final target system`_).
3887
3888 .. _Targets and TPLs will move after installation:
3889
3890 3. *Targets and TPLs will move after installation*: In this scenario, the
3891 final location of the installed libraries and executables will not be the
3892 same as the initial install location and the external library (i.e. TPL)
3893 locations may not be the same on the final target machine. This can be
3894 handled in one of two ways. First, if one knows the final target machine
3895 structure, then one can directly set ``CMAKE_INSTALL_RPATH`` to the
3896 locations on the final target machine (see `Explicitly set RPATH for the
3897 final target system`_). Second, if one does not know the final machine
3898 directory structure (or the same distribution needs to support several
3899 different systems with different directory structures), then one can set
3900 ``CMAKE_SKIP_INSTALL_RPATH=TRUE`` and then require setting the paths in the
3901 env (see `Define all shared library paths at runtime using environment
3902 variables`_).
3903
3904 .. _Explicitly set RPATH for the final target system:
3905
3906 4. *Explicitly set RPATH for the final target system:* If one knows the
3907 directory structure of the final target machine where the installed
3908 libraries and executables will be used, then one can set those paths at
3909 configure time with::
3910
3911 -D<Project>_SET_INSTALL_RPATH=FALSE \
3912 -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=FALSE \
3913 -DCMAKE_INSTALL_RPATH="<path0>;<path1>;..." \
3914
3915 In this case ``CMAKE_INSTALL_RPATH`` is explicitly set. (The value of
3916 ``<Project>_SET_INSTALL_RPATH`` has no effect but setting it to ``FALSE``
3917 may help to avoid confusion.)
3918
3919 Once the install directories are moved to the final location, the
3920 executables can be run without any need to set environment variables.
3921
3922 Note that TriBITS also accepts the directory separator "``:``" for::
3923
3924 -DCMAKE_INSTALL_RPATH="<path0>:<path1>:..." \
3925
3926 and replaces it internally with "``;``" which raw CMake requires. (This
3927 makes it more robust to pass around inside of CMake code since "``;``"
3928 means array boundary with CMake.). However, since ":" is not a valid
3929 character for a path for any Unix system, this is a safe substitution (and
3930 ``CMAKE_INSTALL_RPATH`` is not used on Windows systems that allow "``:``"
3931 in a directory path).
3932
3933 Also note that Linux supports RPATHs with the special value ``$ORIGIN`` to
3934 allow for relative paths and for relocatable installations. (Mac OSX has
3935 similar variables like ``@executable_path``.) With this, one can define
3936 ``CMAKE_INSTALL_RPATH`` using something like ``$ORIGIN/../lib``. See the
3937 above `CMake RPATH handling reference`_ for more details.
3938
3939 .. _Define all shared library paths at runtime using environment variables:
3940
3941 5. *Define all shared library paths at runtime using environment variables:*
3942 If one wants complete freedom to define the paths for the shared libraries
3943 at runtime with ``LD_LIBRARY_PATH`` on Linux (and similar variables on
3944 other platforms), then one can completely strip RPATH out of the installed
3945 libraries and executables by configuring with::
3946
3947 -DCMAKE_SKIP_INSTALL_RPATH=TRUE \
3948
3949 This will result in all paths being stripped out of RPATH regardless of the
3950 values of ``<Project>_SET_INSTALL_RPATH`` or
3951 ``CMAKE_INSTALL_RPATH_USE_LINK_PATH``. (This is the same default behavior
3952 as raw CMake, see `Use default CMake behavior`_).
3953
3954 Then the runtime environment must be set up to find the correct shared
3955 libraries in the correct order at runtime (e.g. by setting
3956 ``LD_LIBRARY_PATH``) . But this approach provides the most flexibility
3957 about where executables and libraries are installed and run from.
3958
3959 Also note that, while not necessary, in order to avoid confusion, it is
3960 likely desired to configure with::
3961
3962 -D<Project>_SET_INSTALL_RPATH=FALSE \
3963 -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=FALSE \
3964 -DCMAKE_SKIP_INSTALL_RPATH=TRUE \
3965
3966 This will produce the least confusing CMake configure output.
3967
3968 One additional issue about RPATH handling on Mac OSX systems needs to be
3969 mentioned. That is, in order for this default RPATH approach to work on OSX
3970 systems, all of the upstream shared libraries must have
3971 ``@rpath/lib<libname>.dylib`` embedded into them (as shown by ``otool -L
3972 <lib_or_exec>``). For libraries built and installed with CMake, the parent
3973 CMake project must be configured with::
3974
3975 -DBUILD_SHARED_LIBS=ON \
3976 -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \
3977 -DCMAKE_MACOSX_RPATH=TRUE \
3978
3979 For other build systems, see their documentation for shared library support on
3980 OSX. To see the proper way to handle RPATH on OSX, just inspect the build and
3981 install commands that CMake generates (e.g. using ``make VERBOSE=1 <target>``)
3982 for shared libraries and then make sure that these other build systems use
3983 equivalent commands. If that is done properly for the chain of all upstream
3984 shared libraries then the behaviors of this <Project> CMake project described
3985 above should hold on OSX systems as well.
3986
3987
3988 Avoiding installing libraries and headers
3989 -----------------------------------------
3990
3991 By default, any libraries and header files defined by in the TriBITS project
3992 <Project> will get installed into the installation directories specified by
3993 ``CMAKE_INSTALL_PREFIX``, ``<Project>_INSTALL_INCLUDE_DIR`` and
3994 ``<Project>_INSTALL_LIB_DIR``. However, if the primary desire is to install
3995 executables only, then the user can set::
3996
3997 -D <Project>_INSTALL_LIBRARIES_AND_HEADERS=OFF
3998
3999 which, if in addition static libraries are being built
4000 (i.e. ``BUILD_SHARED_LIBS=OFF``), this this option will result in no libraries
4001 or headers being installed into the ``<install>/include/`` and
4002 ``<install>/lib/`` directories, respectively. However, if shared libraries
4003 are being built (i.e. ``BUILD_SHARED_LIBS=ON``), they the libraries will be
4004 installed in ``<install>/lib/`` along with the executables because the
4005 executables can't run without the shared libraries being installed.
4006
4007
4008 Installing the software
4009 -----------------------
4010
4011 To install the software, type::
4012
4013 $ make install
4014
4015 Note that by default CMake actually puts in the build dependencies for
4016 installed targets so in some cases you can just type ``make -j<N> install``
4017 and it will also build the software before installing (but this can be
4018 disabled by setting ``-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON``). It is
4019 advised to always build and test the software first before installing with::
4020
4021 $ make -j<N> && ctest -j<N> && make -j<N> install
4022
4023 This will ensure that everything is built correctly and all tests pass before
4024 installing.
4025
4026 If there are build failures in any packages and one wants to still install the
4027 packages that do build correctly, then configure with::
4028
4029 -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON
4030
4031 and run the custom install target::
4032
4033 $ make install_package_by_package
4034
4035 This will ensure that every package that builds correctly will get installed.
4036 (The default 'install' target aborts on the first file install failure.)
4037
4038
4039 Using the installed software in downstream CMake projects
4040 ---------------------------------------------------------
4041
4042 As described in `Generating export files`_, when ``-D
4043 <Project>_ENABLE_INSTALL_CMAKE_CONFIG_FILES=ON`` is set at configure time, a
4044 ``<Project>Config.cmake`` file and a different ``<Package>Config.cmake`` file
4045 for each enabled package is installed into the install tree under ``-D
4046 CMAKE_INSTALL_PREFIX=<upstreamInstallDir>``. A downstream CMake project can
4047 then pull in CMake targets for the installed libraries using
4048 ``find_package()`` in the downstream project's ``CMakeLists.txt`` file. All
4049 of the built and installed libraries can be pulled in and built against at the
4050 project level by configuring the downstream CMake project with::
4051
4052 -D CMAKE_PREFIX_PATH=<upstreamInstallDir>
4053
4054 and having the downstream project's ``CMakeLists.txt`` file call, for
4055 example::
4056
4057 find_package(<Project> REQUIRED)
4058 ...
4059 target_link_libraries( <downstream-target>
4060 PRIVATE <Project>::all_libs )
4061
4062 This will put the needed include directories and other imported compiler
4063 options on the downstream compile lines as specified through the IMPORTED
4064 library targets and will put the needed libraries on the link line.
4065
4066 To pull in libraries from only a subset of the installed packages ``<pkg0>
4067 <pkg1> ...``, use, for example::
4068
4069 find_package(<Project> REQUIRED COMPONENTS <pkg0> <pkg1> ...)
4070 ...
4071 target_link_libraries( <downstream-target>
4072 PRIVATE <Project>::all_selected_libs )
4073
4074 The target ``<Project>::all_selected_libs`` only contains the library targets
4075 for the selected packages (through their ``<Package>::all_libs`` targets) for
4076 the packages requested in the ``COMPONENTS <pkg0> <pkg1> ...`` argument.
4077 (NOTE, the target ``<Project>::all_libs`` is unaffected by the ``COMPONENTS``
4078 argument and always links to all of the enabled package's libraries.)
4079
4080 Downstream projects can also pull in and use installed libraries by finding
4081 individual packages by calling ``find_package(<Package> REQUIRED)`` for each
4082 package ``<Package>`` and then linking against the defined IMPORTED CMake
4083 target ``<Package>::all_libs`` such as::
4084
4085 find_package(<Package1> REQUIRED)
4086 find_package(<Package2> REQUIRED)
4087 ...
4088 target_link_libraries( <downstream-target>
4089 PUBLIC <Package1>::all_libs
4090 PRIVATE <Package2>::all_libs
4091 )
4092
4093 Finding and using libraries for packages at the package-level provides better
4094 fine-grained control over internal linking and provides greater flexibility in
4095 case these packages are not all installed in the same upstream CMake project
4096 in the future.
4097
4098 To see an example of all of these use cases being demonstrated, see
4099 `TribitsExampleApp`_ and the `TriBITS TribitsExampleApp Tests`_.
4100
4101
4102 Using packages from the build tree in downstream CMake projects
4103 ------------------------------------------------------------------
4104
4105 Note that libraries from enabled and built packages can also be used from the
4106 ``<Project>`` build tree without needing to install. Being able to build
4107 against pre-built packages in the build tree can be very useful such as when
4108 the project is part of a CMake super-build where one does not want to install
4109 the intermediate packages.
4110
4111 Let ``<upstreamBuildDir>`` be the build directory for ``<Project>`` that has
4112 already been configured and built (but not necessarily installed). A
4113 downstream CMake project can pull in and link against any of the enabled
4114 libraries in the upstream ``<Project>`` configuring the downstream CMake
4115 project with::
4116
4117 -D CMAKE_PREFIX_PATH=<upstreamBuildDir>/cmake_packages
4118
4119 and then finding the individual packages and linking to them in the downstream
4120 CMake project's ``CMakeLists.txt`` file as usual using, for example::
4121
4122 find_package(<Package1> REQUIRED)
4123 find_package(<Package2> REQUIRED)
4124 ...
4125 target_link_libraries( <downstream-target>
4126 PUBLIC <Package1>::all_libs
4127 PRIVATE <Package2>::all_libs
4128 )
4129
4130 Note that in this case, ``target_link_libraries()`` ensures that the include
4131 directories and other imported compiler options from the source tree and the
4132 build tree are automatically injected into the build targets associated with
4133 the ``<downstream-target>`` object compile lines and link lines.
4134
4135 Also note that package config files for all of the enabled external
4136 packages/TPLs will also be written into the build tree under
4137 ``<upstreamBuildDir>/external_packages``. These contain modern CMake targets
4138 that are pulled in by the downstream ``<Package>Config.cmake`` files under
4139 ``<upstreamBuildDir>/external_packages``. These external package/TPL config
4140 files are placed in a separate directory to avoid being found by accident.
4141
4142
4143 Installation Testing
4144 ====================
4145
4146 The CMake project <Project> has built-in support for testing an installation
4147 of itself using its own tests and examples. The way it works is to configure,
4148 build, and install just the libraries and header files using::
4149
4150 $ mkdir BUILD_LIBS
4151 $ cd BUILD_LIBS/
4152
4153 $ cmake \
4154 -DCMAKE_INSTALL_PREFIX=<install-dir> \
4155 -D<Project>_ENABLE_ALL_PACKAGES=ON \
4156 -D<Project>_ENABLE_TESTS=OFF \
4157 [other options] \
4158 <projectDir>
4159
4160 $ make -j16 install # or ninja -j16
4161
4162 and then create a different build directory to configure and build just the
4163 tests and examples (not the libraries) against the pre-installed libraries and
4164 header files using::
4165
4166 $ mkdir BUILD_TESTS
4167 $ cd BUILD_TESTS/
4168
4169 $ cmake \
4170 -D<Project>_ENABLE_ALL_PACKAGES=ON \
4171 -D<Project>_ENABLE_TESTS=ON \
4172 -D<Project>_ENABLE_INSTALLATION_TESTING=ON \
4173 -D<Project>_INSTALLATION_DIR=<install-dir> \
4174 [other options] \
4175 <projectDir>
4176
4177 $ make -j16 # or ninja -j16
4178
4179 $ ctest -j16
4180
4181 If that second project builds and all the tests pass, then the project was
4182 installed correctly. This uses the project's own tests and examples to test
4183 the installation of the project. The library source and header files are
4184 unused in the second project build. In fact, you can delete them and ensure
4185 that they are not used in the build and testing of the tests and examples!
4186
4187 This can also be used for testing backward compatibility of the project (or
4188 perhaps for a subset of packages). In this case, build and install the
4189 libraries and header files for a newer version of the project and then
4190 configure, build, and run the tests and examples for an older version of the
4191 project sources pointing to the installed header files and libraries from the
4192 newer version.
4193
4194
4195 Packaging
4196 =========
4197
4198 Packaged source and binary distributions can also be created using CMake and
4199 CPack.
4200
4201
4202 Creating a tarball of the source tree
4203 -------------------------------------
4204
4205 To create a source tarball of the project, first configure with the list of
4206 desired packages (see `Selecting the list of packages to enable`_) and pass in
4207 ::
4208
4209 -D <Project>_ENABLE_CPACK_PACKAGING=ON
4210
4211 To actually generate the distribution files, use::
4212
4213 $ make package_source
4214
4215 The above command will tar up *everything* in the source tree except for files
4216 explicitly excluded in the CMakeLists.txt files and packages that are not
4217 enabled so make sure that you start with a totally clean source tree before
4218 you do this. You can clean the source tree first to remove all ignored files
4219 using::
4220
4221 $ git clean -fd -x
4222
4223 You can include generated files in the tarball, such as Doxygen output files,
4224 by creating them first, then running ``make package_source`` and they will be
4225 included in the distribution (unless there is an internal exclude set).
4226
4227 Disabled subpackages can be included or excluded from the tarball by setting
4228 ``<Project>_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION`` (the TriBITS
4229 project has its own default, check ``CMakeCache.txt`` to see what the default
4230 is). If ``<Project>_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION=ON`` and
4231 but one wants to include some subpackages that are otherwise excluded, just
4232 enable them or their outer package so they will be included in the source
4233 tarball. To get a printout of set regular expressions that will be used to
4234 match files to exclude, set::
4235
4236 -D <Project>_DUMP_CPACK_SOURCE_IGNORE_FILES=ON
4237
4238 Extra directories or files can be excluded from the reduced source tarball by
4239 adding the configure argument::
4240
4241 "-DCPACK_SOURCE_IGNORE_FILES=<extra-exclude-regex-0>;<extra-exclude-regex-1>;..."
4242
4243 NOTE: The entries in ``CPACK_SOURCE_IGNORE_FILES`` are regexes and **not**
4244 file globs, so be careful when specifying these or more files and directories
4245 will be excluded from the reduced source tarball that intended/desired.
4246
4247 While a set of default CPack source generator types is defined for this
4248 project (see the ``CMakeCache.txt`` file), it can be overridden using, for
4249 example::
4250
4251 -D <Project>_CPACK_SOURCE_GENERATOR="TGZ;TBZ2"
4252
4253 (See CMake documentation to find out the types of CPack source generators
4254 supported on your system.)
4255
4256 NOTE: When configuring from an untarred source tree that has missing packages,
4257 one must configure with::
4258
4259 -D <Project>_ASSERT_DEFINED_DEPENDENCIES=OFF
4260
4261 Otherwise, TriBITS will error out complaining about missing packages. (Note
4262 that ``<Project>_ASSERT_DEFINED_DEPENDENCIES`` will default to ```OFF``` in
4263 release mode, i.e. ``<Project>_ENABLE_DEVELOPMENT_MODE==OFF``.)
4264
4265
4266 Dashboard submissions
4267 =====================
4268
4269 All TriBITS projects have built-in support for submitting configure, build,
4270 and test results to CDash using the custom ``dashboard`` target. This uses
4271 the `tribits_ctest_driver()`_ function internally set up to work correctly
4272 from an existing binary directory with a valid initial configure. The few of
4273 the advantages of using the custom TriBITS-enabled ``dashboard`` target over
4274 just using the standard ``ctest -D Experimental`` command are:
4275
4276 * The configure, build, and test results are broken down nicely
4277 package-by-package on CDash.
4278
4279 * Additional notes files will be uploaded to the build on CDash.
4280
4281 For more details, see `tribits_ctest_driver()`_.
4282
4283 To use the ``dashboard`` target, first, configure as normal but add cache vars
4284 for the build and test parallel levels with::
4285
4286 -DCTEST_BUILD_FLAGS=-j4 -DCTEST_PARALLEL_LEVEL=4
4287
4288 (or with some other values ``-j<N>``). Then, invoke the (re)configure, build,
4289 test and submit with::
4290
4291 $ make dashboard
4292
4293 This invokes a ``ctest -S`` script that calls the `tribits_ctest_driver()`_
4294 function to do an experimental build for all of the enabled packages for which
4295 you have enabled tests. (The packages that are implicitly enabled due to
4296 package dependencies are not directly processed and no rows on CDash will be
4297 show up for those packages.)
4298
4299 **NOTE:** This target generates a lot of output, so it is typically better to
4300 pipe this to a file with::
4301
4302 $ make dashboard &> make.dashboard.out
4303
4304 and then watch that file in another terminal with::
4305
4306 $ tail -f make.dashboard.out
4307
4308 **NOTE:** To pass multiple arguments for ``CTEST_BUILD_FLAGS`` (like adding
4309 ``-k 99999999`` to tell ninja to continue even if there are build errors),
4310 one must quote the entire argument string as::
4311
4312 "-DCTEST_BUILD_FLAGS=-j4 -k 99999999"
4313
4314
4315 Setting options to change behavior of 'dashboard' target
4316 --------------------------------------------------------
4317
4318 There are a number of options that you can set in the cache and/or in the
4319 environment to control what this script does. Several options must be set in
4320 the cache in the CMake configure of the project such as the CDash sites where
4321 results are submitted to with the vars ``CTEST_DROP_METHOD``,
4322 ``CTEST_DROP_SITE``, ``CTEST_DROP_LOCATION``,
4323 ``TRIBITS_2ND_CTEST_DROP_LOCATION``, and ``TRIBITS_2ND_CTEST_DROP_SITE``.
4324 Other options that control the behavior of the ``dashboard`` target must be
4325 set in the env when calling ``make dashboard``. For the full set of options
4326 that control the ``dashboard`` target, see `tribits_ctest_driver()`_. To see
4327 the full list of options, and their default values, one can run with::
4328
4329 $ env CTEST_DEPENDENCY_HANDLING_UNIT_TESTING=TRUE \
4330 make dashboard
4331
4332 This will print the options with their default values and then do a sort of
4333 mock running of the CTest driver script and point out what it will do with the
4334 given setup.
4335
4336 Any of the vars that are forwarded to the ``ctest -S`` invocation will be
4337 shown in the STDOUT of the ``make dashboard`` invocation on the line::
4338
4339 Running: env [vars passed through env] <path>/ctest ... -S ...
4340
4341 Any variables passed through the ``env`` command listed there in ``[vars
4342 passed through env ]`` can only be changed by setting cache variables in the
4343 CMake project and can't be overridden in the env when invoking the
4344 ``dashboard`` target. For example, the variable ``CTEST_DO_SUBMIT`` is
4345 forwarded to the ``ctest -S`` invocation and can't be overridden with::
4346
4347 $ env CTEST_DO_SUBMIT=OFF make dashboard
4348
4349 Instead, to change this value, one must reconfigure and then run as::
4350
4351 $ cmake CTEST_DO_SUBMIT=OFF .
4352 $ make dashboard
4353
4354 But any variable that is not listed in ``[vars passed through env ]`` in the
4355 printed out ``ctest -S`` command that are read in by `tribits_ctest_driver()`_
4356 can be set in the env by calling::
4357
4358 $ env [other vars read by tribits_ctest_driver()] make dashboard
4359
4360 To know that these vars are picked up, grep the STDOUT from ``make dashboard``
4361 for lines containing::
4362
4363 -- ENV_<var_name>=
4364
4365 That way, you will know the var was pick up and read correctly.
4366
4367
4368 Common options and use cases for the 'dashboard' target
4369 -------------------------------------------------------
4370
4371 What follows are suggestions on how to use the ``dashboard`` target for
4372 different use cases.
4373
4374 One option that is useful to set is the build name on CDash at configure time
4375 with::
4376
4377 -DCTEST_BUILD_NAME=MyBuild
4378
4379 After ``make dashboard`` finishes running, look for the build 'MyBuild' (or
4380 whatever build name you used above) in the <Project> CDash dashboard (the
4381 CDash URL is printed at the end of STDOUT). It is useful to set
4382 ``CTEST_BUILD_NAME`` to some unique name to make it easier to find your
4383 results on the CDash dashboard. If one does not set ``CTEST_BUILD_NAME``,
4384 then the name of the binary directory is used instead by default (which may
4385 not be very descriptive if it called something like ``BUILD``).
4386
4387 If there is already a valid configure and build and one does not want to
4388 reconfigure and rebuild or submit configure and build results then one can run
4389 with::
4390
4391 $ env CTEST_DO_CONFIGURE=OFF CTEST_DO_BUILD=OFF \
4392 make dashboard
4393
4394 This will only run the enabled pre-built tests and submit test results to
4395 CDash. (But is usually good to reconfigure and rebuild and submit those
4396 results to CDash as well in order to define more context for the test
4397 results.)
4398
4399 The configure, builds, and submits are either done package-by-package or
4400 all-at-once as controlled by the variable ``<Project>_CTEST_DO_ALL_AT_ONCE``.
4401 This can be set in the CMake cache when configuring the project using::
4402
4403 -D<Project>_CTEST_DO_ALL_AT_ONCE=TRUE
4404
4405 Using the ``dashboard`` target, one can also run coverage and memory testing
4406 and submit to CDash as described below. But to take full advantage of the
4407 all-at-once mode and to have results displayed on CDash broken down
4408 package-by-package, one must be submitting to a newer CDash version 3.0+.
4409
4410 For submitting line coverage results, configure with::
4411
4412 -D<Project>_ENABLE_COVERAGE_TESTING=ON
4413
4414 and the environment variable ``CTEST_DO_COVERAGE_TESTING=TRUE`` is
4415 automatically set by the target ``dashboard`` so you don't have to set this
4416 yourself. Then, when you run the ``dashboard`` target, it will automatically
4417 submit coverage results to CDash as well.
4418
4419 Doing memory checking running the enabled tests with Valgrind requires that
4420 you set ``CTEST_DO_MEMORY_TESTING=TRUE`` with the ``env`` command when running
4421 the ``dashboard`` target as::
4422
4423 $ env CTEST_DO_MEMORY_TESTING=TRUE make dashboard
4424
4425 but also note that you may also need to set the valgrind command and options
4426 with::
4427
4428 $ env CTEST_DO_MEMORY_TESTING=TRUE \
4429 CTEST_MEMORYCHECK_COMMAND=<abs-path-to-valgrind> \
4430 CTEST_MEMORYCHECK_COMMAND_OPTIONS="-q --trace-children=yes --tool=memcheck \
4431 --leak-check=yes --workaround-gcc296-bugs=yes \
4432 --num-callers=50 --suppressions=<abs-path-to-supp-file1> \
4433 ... --suppressions=<abs-path-to-supp-fileN>" \
4434 make dashboard
4435
4436 The CMake cache variable ``<Project>_DASHBOARD_CTEST_ARGS`` can be set on the
4437 cmake configure line in order to pass additional arguments to ``ctest -S``
4438 when invoking the package-by-package CTest driver. For example::
4439
4440 -D<Project>_DASHBOARD_CTEST_ARGS="-VV" \
4441
4442 will set very verbose output with CTest that includes the STDOUT for every
4443 test run. (The default args are ``-V`` which shows which tests are run but
4444 not the test STDOUT.)
4445
4446
4447 Changing the CDash sites for the 'dashboard' target
4448 ---------------------------------------------------
4449
4450 As described above in `Setting options to change behavior of 'dashboard'
4451 target`_, one can change the location where configure, build, and test results
4452 are submitted to one more two CDash sites. For well-structured TriBITS CMake
4453 projects defining a flexible ``CTestConfig.cmake`` file, the location of the
4454 main CDash site can be changed by configuring with::
4455
4456 -DCTEST_DROP_SITE="some-site.com" \
4457 -DCTEST_DROP_LOCATION="/cdash/submit.php?project=<Project>" \
4458
4459 .. _TRIBITS_2ND_CTEST_DROP_SITE:
4460 .. _TRIBITS_2ND_CTEST_DROP_LOCATION:
4461
4462 Also note that one can submit results to a second CDash site by configuring
4463 with::
4464
4465 -DTRIBITS_2ND_CTEST_DROP_SITE="<second-site>" \
4466 -DTRIBITS_2ND_CTEST_DROP_LOCATION="<second-location>" \
4467
4468 If left the same as ``CTEST_DROP_SITE`` or ``CTEST_DROP_LOCATION``, then
4469 ``TRIBITS_2ND_CTEST_DROP_SITE`` and ``TRIBITS_2ND_CTEST_DROP_LOCATION``,
4470 respectively, can be left empty "" and the defaults will be used. For
4471 example, to submit to an experimental CDash site on the same machine, one
4472 would configure with::
4473
4474 -DTRIBITS_2ND_CTEST_DROP_LOCATION="/testing/cdash/submit.php?project=<Project>"
4475
4476 and ``CTEST_DROP_SITE`` would be used for ``TRIBITS_2ND_CTEST_DROP_SITE``
4477 since ``TRIBITS_2ND_CTEST_DROP_SITE`` is empty. This is a common use case
4478 when upgrading to a new CDash installation or testing new features for CDash
4479 before impacting the existing CDash site. (However, the user must set at
4480 least one of these variables to non-empty in order to trigger the second
4481 submit.)
4482
4483 **NOTE:** If the project is already set up to submit to a second CDash site
4484 and one wants to turn that off, one can configure with::
4485
4486 -DTRIBITS_2ND_CTEST_DROP_SITE=OFF \
4487 -DTRIBITS_2ND_CTEST_DROP_LOCATION=OFF \
4488
4489
4490 Configuring from scratch needed if 'dashboard' target aborts early
4491 ------------------------------------------------------------------
4492
4493 Finally, note that in package-by-package mode
4494 (i.e. ``<Project>_CTEST_DO_ALL_AT_ONCE=FALSE``) that if one kills the ``make
4495 dashboard`` target before it completes, then one must reconfigure from scratch
4496 in order to get the build directory back into the same state before the
4497 command was run. This is because the ``dashboard`` target in
4498 package-by-package mode must first reconfigure the project with no enabled
4499 packages before it does the package-by-package configure/build/test/submit
4500 which enables each package one at a time. After the package-by-package
4501 configure/build/test/submit cycles are complete, then the project is
4502 reconfigured with the original set of package enables and returned to the
4503 original configure state. Even with the all-at-once mode, if one kills the
4504 ``make dashboard`` command before the reconfigure completes, one may be left
4505 with an invalid configuration of the project. In these cases, one may need to
4506 configure from scratch to get back to the original state before calling ``make
4507 dashboard``.
4508
4509 .. _TribitsExampleApp: https://github.com/TriBITSPub/TriBITS/tree/master/tribits/examples/TribitsExampleApp
4510
4511 .. _TriBITS TribitsExampleApp Tests: https://github.com/TriBITSPub/TriBITS/blob/master/test/core/ExamplesUnitTests/TribitsExampleApp_Tests.cmake
4512
4513 .. _xSDK Community Package Policies: https://doi.org/10.6084/m9.figshare.4495136
4514
4515 .. _FindPython3.cmake: https://cmake.org/cmake/help/latest/module/FindPython3.html
4516
4517
4518 .. LocalWords: templated instantiation Makefiles CMake