Additional error checking and reporting for common TriBITS project developer and user mistakes

[bartlettroscoe]

This story continues the adding of error checking started in #200.

Additional checks to add

• Check if any required files like <repoDir>/PackagesList.cmake, <repoDir>/TPLsList.cmake, <packageDir>/cmake/Dependencies.cmake, and <packageDir>/CMakeLists.txt exist and if they don't, abort the configure with MESSAGE(FATAL_ERROR ...).

• Check that the commands TRIBITS_PACKAGE(), TRIBITS_PACKAGE_DECL(), TRIBITS_PACKAGE_DEF(), TRIBITS_PROCESS_SUBPACKAGES(), TRIBITS_PACKAGE_POSTPROCESS() are only called in a package's base CMakeLists.txt file and not in any CMakeLists.txt files in any subdir of that. That is, we should not set CACHE vars for checks but instead use DUAL_SCOPE_SET() to set some of these vars and then check for them at the top-level CMakeListst.txt scope.

• Check that the commands TRIBITS_SUBPACKAGE(), and TRIBITS_SUBPACKAGE_POSTPROCESS() are only called in a subpackage's base CMakeLists.txt file and not in any CMakeLists.txt files in subdirs. That is, we should not set CACHE vars but instead use DUAL_SCOPE_SET() to set some of these vars and check for them being set in the TRIBITS_PROCESS_SUBPACKAGES() command.

• Check that SOURCES <src0> <src1> ... has at least one value for TRIBITS_ADD_LIBRARY() and TRIBITS_ADD_EXECUTABLE().

• Check that PROJECT(${PROJECT_NAME} NONE) is called before including TriBITS.cmake and before calling TRIBITS_PROJECT(). Also, check that compilers have NOT been enabled yet (i.e. calling PROJECT(${PROJECT_NAME}) missing NONE).

• Check for the correct number of arguments passed in various functions that are parsed with CMAKE_PARSE_ARGUMENTS(PREFIX ...). I.e. implement and use TRIBITS_ASSERT_NUM_ARGS(<prefix> <arg_name> <num_args>) everywhere we can use them. Many inputs take only 1 argument and we need to be consistently checking for that. Other arguments are required and require one or more values (e.g. SOURCES). That would go a long way to helping to catch these errors. NOTE: This could be implemented inside if a TRIBITS_CMAKE_PARSE_ARGUMENTS() macro that calls CMAKE_PARSE_ARGUMENTS() and then asserts the after the call that the on-value arguments have just one value.

• Check for non-empty SUBPACKAGES_DIRS_CLASSIFICATIONS_OPTREQS argument to TRIBITS_DEFINE_PACKAGE_DEPENDENCIES() in a subpackage's cmake/Dependencies.cmake file. (i.e. Only a parent TriBITS package can define subpackages.)

• Check that when calling TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() in a Dependencies.cmake file that it is not also trying to directly set the vars LIB_REQUIRED_DEP_PACKAGES ... TEST_OPTIONAL_DEP_TPLS either before or after calling TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() (some people are actually trying to do this in Trilinos!)

• Check for TriBITS project user trying to directly configure a TriBITS package as a CMake project for packages not designed for that. (I.e. check that when TRIBITS_PACKAGE_DECL() is called, it is called in a subdir and inside of TRIBITS_PROJECT() call. Several people have tried to do this over the years. But it may not be possible to add a check like that.)

The above are just a few of the types of mistakes that TriBITS developers and users have made in the past and TriBITS does not catch and report very well. Some more thought and exploration will yield other missing checks. But this story does not have to involve finding and resolving all such errors.

What makes this story non-trivial is that we must set up automated testing to check that TriBITS can catch and report these mistakes. To do that, one could set up new testing dummy TriBITS package(s) that can be configured to make all of these mistakes and then add automated tests in the TriBITS test suite to make sure that TriBITS code catches the mistakes and prints the right error messages.