WIP: Add documentation for <Project>_ASSERT_CORRECT_TRIBITS_USAGE and…

… set default for dev mode (#200)

This also sets ${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT=ON if it is not
set.  This is what it should have always been from the beginning.  Hopefully
this will not break any existing TriBITS projects (but it is easy to fix by
just setting the default in the <projectDir>/ProjectName.cmake file).

tribits/core/package_arch/TribitsGlobalMacros.cmake

@@ -623,18 +623,26 @@ MACRO(TRIBITS_DEFINE_GLOBAL_OPTIONS_AND_DEFINE_EXTRA_REPOS)
     "Relative CPU speed of the computer used to scale performance tests (default 1.0)."
     )
 
+  IF ("${${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT}" STREQUAL "")
+    SET(${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT ON)
+  ENDIF()
   ADVANCED_SET( ${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE
     ${${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT}
     CACHE BOOL
-    "Determines if a variety of development mode checks are turned on by default or not." )
+    "Determines if a variety of development mode checks are turned on by default or not."
+    )
 
   ADVANCED_SET( ${PROJECT_NAME}_ASSERT_MISSING_PACKAGES
     ${${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE}
     CACHE BOOL
     "Determines if asserts are performed on missing packages or not." )
 
   IF ("${${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT}" STREQUAL "")
-    SET(${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT FATAL_ERROR)
+    IF (${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE)
+      SET(${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT FATAL_ERROR)
+    ELSE()
+      SET(${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT IGNORE)
+    ENDIF()
   ENDIF()
   ADVANCED_SET( ${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE
     "${${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT}"

tribits/doc/build_ref/TribitsBuildReferenceBody.rst

@@ -2422,28 +2422,29 @@ To turn off CMake configure-time development-mode checking, set::
   -D <Project>_ENABLE_DEVELOPMENT_MODE=OFF
 
 This turns off a number of CMake configure-time checks for the <Project>
-TriBITS/CMake files including checking the package dependencies.  These checks
-can be expensive and may also not be appropriate for a tarball release of the
-software.  However, this also turns off strong compiler warnings so this is
-not recommended by default (see `<TRIBITS_PACKAGE>_DISABLE_STRONG_WARNINGS`_).
-For a release of <Project> this option is set OFF by default.
+TriBITS/CMake files including checking the package dependencies and other
+usage of TriBITS.  These checks can be expensive and may also not be
+appropriate for a tarball release of the software.  However, this also turns
+off strong compiler warnings so this is not recommended by default (see
+`<TRIBITS_PACKAGE>_DISABLE_STRONG_WARNINGS`_).  For a release of <Project>
+this option is set OFF by default.
 
 One of the CMake configure-time debug-mode checks performed as part of
 ``<Project>_ENABLE_DEVELOPMENT_MODE=ON`` is to assert the existence of TriBITS
 package directories.  In development mode, the failure to find a package
 directory is usually a programming error (i.e. a miss-spelled package
 directory name).  But in a tarball release of the project, package directories
 may be purposefully missing (see `Creating a tarball of the source tree`_) and
-must be ignored.  When building from a reduced tarball created from the
+must be ignored.  When building from a reduced source tarball created from the
 development sources, set::
 
   -D <Project>_ASSERT_MISSING_PACKAGES=OFF
 
-Setting this off will cause the TriBITS CMake configure to simply ignore any
-missing packages and turn off all dependencies on these missing packages.
+Setting this ``OFF`` will cause the TriBITS CMake configure to simply ignore
+any missing packages and turn off all dependencies on these missing packages.
 
 Another type of checking is for optional inserted/external packages
-(e.g. packages who's source can optionally be included in and is flagged with
+(e.g. packages who's source can optionally be included and is flagged with
 ``TRIBITS_ALLOW_MISSING_EXTERNAL_PACKAGES()``).  Any of these package
 directories that are missing result in the packages being silently ignored by
 default.  However, notes on what missing packages are being ignored can
@@ -2455,6 +2456,24 @@ These warnings (starting with 'NOTE', not 'WARNING' that would otherwise
 trigger warnings in CDash) about missing inserted/external packages will print
 regardless of the setting for ``<Project>_ASSERT_MISSING_PACKAGES``.
 
+Finally, ``<Project>_ENABLE_DEVELOPMENT_MODE=ON`` results in a number of
+checks for invalid usage of TriBITS in the project's ``CMakeList.txt`` files
+and will abort configure with a fatal error on the first check failure. This
+is appropriate for development mode when a project is clean of all such
+invalid usage patterns but there are times when it makes sense to report these
+check failures in different ways (such as when upgrading TriBITS in a project
+that has some invalid usage patterns that just happen work but may be
+disallowed in future versions of TriBITS).  To change how these invalid usage
+checks are handled, set::
+
+  -D <Project>_ASSERT_CORRECT_TRIBITS_USAGE=<check-mode>
+
+where ``<check-mode>`` can be 'FATAL_ERROR', 'SEND_ERROR', 'WARNING', or
+'IGNORE'.
+
+For ``<Project>_ENABLE_DEVELOPMENT_MODE=OFF``, the default for
+``<Project>_ASSERT_CORRECT_TRIBITS_USAGE`` is actually set to ``IGNORE``.
+
 
 Building (Makefile generator)
 =============================

tribits/doc/developers_guide/TribitsDevelopersGuide.rst

@@ -8016,6 +8016,7 @@ be documented in `TribitsBuildReference`_.
 The global project-level TriBITS options for which defaults can be provided by
 a given TriBITS project are:
 
+* `${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE`_
 * `${PROJECT_NAME}_C_Standard`_
 * `${PROJECT_NAME}_CHECK_FOR_UNPARSED_ARGUMENTS`_
 * `${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE_APPEND`_
@@ -8055,6 +8056,26 @@ a given TriBITS project are:
 
 These options are described below.
 
+.. _${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE:
+
+**${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE**
+
+  The CMake cache variable ``${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE`` is
+  used to define how some invalid TriBITS usage checks are handled.  The valid
+  values include 'FATAL_ERROR', 'SEND_ERROR', 'WARNING', and 'IGNORE'.  The
+  default value is 'FATAL_ERROR' for a project when
+  ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=ON``, which is best for
+  development mode for a project that currently has no invalid usage patterns.
+  The default is 'IGNORE' when
+  ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=OFF``.  But a project with some
+  existing invalid usage patterns might want to set, for example, a default of
+  'WARNING' in order to allow for a smooth upgrade of TriBITS.  To do so,
+  set::
+
+    SET(${PROJECT_NAME}_ASSERT_CORRECT_TRIBITS_USAGE_DEFAULT WARNING)
+
+  in the project's base `<projectDir>/ProjectName.cmake`_ file.
+
 .. _${PROJECT_NAME}_C_Standard:
 
 **${PROJECT_NAME}_C_Standard**