Update documentation and release notes for change in ETI default to ON (

trilinos/Trilinos#8130)

See the updated documentation and notes for details.

tribits/ReleaseNotes.txt

@@ -2,15 +2,25 @@
 Release Notes for TriBITS
 ----------------------------------------
 
+2020/11/12:
+
+*) MAJOR: The default for `<Project>_ENABLE_EXPLICIT_INSTANTIATION` (ETI) was
+ changed from `OFF` to `ON`.  This was turned on in practice for almost all
+ users of Trilinos so while this change technically breaks backward
+ compatibility of TriBITS, in practice, this will likely not impact any
+ important customers.  (And new customers of Trilinos and related TriBITS
+ projects will enjoy the benefits of ETI by default.  See
+ trilinos/Trilinos#8130.)
+
 2020/10/08:
 
 *) MAJOR: Tests defined with `TRIBITS_ADD_TEST()` and
  `TRIBITS_ADD_ADVANCED_TEST()` with `NUM_MPI_PROCS > 1` will now not be added
  for non-MPI TPL_ENABLE_MPI=OFF configurations.  Before, the test would get
  added and basically ignore the value of `NUM_MPI_PROCS`.  This change
  together with the change to move to using `add_test(NAME <name> COMMAND
- <command>)` mostly restores backward compatbility for projects using TriBITS.
- For more details, see trilinos/Trilinos#8110.
+ <command>)` mostly restores backward compatibility for projects using
+ TriBITS.  For more details, see trilinos/Trilinos#8110.
 
 2020/09/28:
 

tribits/doc/build_ref/TribitsBuildReferenceBody.rst

@@ -991,30 +991,30 @@ NOTE: These options are ignored when using Makefiles or other CMake
 generators.  They only work for the Ninja generator.
 
 
-Enabling explicit template instantiation for C++
-------------------------------------------------
+Disabling explicit template instantiation for C++
+-------------------------------------------------
 
-To enable explicit template instantiation for C++ code for packages that
-support it, configure with::
+By default, support for optional explicit template instantiation (ETI) for C++
+code is enabled.  To disable support for optional ETI, configure with::
 
-  -D <Project>_ENABLE_EXPLICIT_INSTANTIATION=ON
+  -D <Project>_ENABLE_EXPLICIT_INSTANTIATION=OFF
 
 When ``OFF``, all packages that have templated C++ code will use implicit
-template instantiation.
-
-Explicit template instantiation can be enabled (``ON``) or disabled (``OFF``)
-for individual packages with::
+template instantiation (unless they have hard-coded usage of ETI).
 
+ETI can be enabled (``ON``) or disabled (``OFF``) for individual packages
+with::
 
   -D <TRIBITS_PACKAGE>_ENABLE_EXPLICIT_INSTANTIATION=[ON|OFF]
 
 The default value for ``<TRIBITS_PACKAGE>_ENABLE_EXPLICIT_INSTANTIATION`` is
 set by ``<Project>_ENABLE_EXPLICIT_INSTANTIATION``.
 
-For packages that support it, explicit template instantation can massively
-reduce the compile times for the C++ code involved.  To see what packages
-support explicit instantation just search the CMakeCache.txt file for
-variables with ``ENABLE_EXPLICIT_INSTANTIATION`` in the name.
+For packages that support it, explicit template instantiation can massively
+reduce the compile times for the C++ code involved and can even avoid compiler
+crashes in some cases.  To see what packages support explicit template
+instantiation, just search the CMakeCache.txt file for variables with
+``ENABLE_EXPLICIT_INSTANTIATION`` in the name.
 
 
 Disabling the Fortran compiler and all Fortran code
@@ -3916,3 +3916,5 @@ original configure state.  Even with the all-at-once mode, if one kills the
 with an invalid configuration of the project.  In these cases, one may need to
 configure from scratch to get back to the original state before calling ``make
 dashboard``.
+
+..  LocalWords:  templated instantiation Makefiles CMake