[CMake] FIND_PATH_VERIFY macro

[Vincent Scheib]

Here's a handy usability improvement we recently implemented. It may
be possible to fold this type of functionality back into FIND_PATH.

The use case is this:
- CMake is called
- FIND_PATH is used to determine the location of a package
- FIND_PATH set's a variable, and places it into the cache
- The package moves for some reason.
- CMake is called (again)
- FIND_PATH doesn't re-search, because the cache contains a valid
directory value for the variable.
- user doesn't notice the error until build.

Here's the new use case:
- CMake is called
- FIND_PATH_VERIFY is called, the variable isn't set, so it stays unset.
- FIND_PATH is used to determine the location of a package
- FIND_PATH set's a variable, and places it into the cache
- The package moves for some reason.
- CMake is called (again)
- FIND_PATH_VERIFY is called, the variable is checked, and found to be
invalid. The variable is cleared to "NOTFOUND"
- FIND_PATH is used to determine the location of a package.
(re-searching, because the variable had been cleared)
- user doesn't even notice the move happened, doesn't care, the build works.



Here's some example FindFOO.cmake code:
################################################################################
FIND_PATH_VERIFY(FOO_INCLUDE_DIR foo.txt)

FIND_PATH(FOO_INCLUDE_DIR foo.txt)



Here's the macro implementation:
################################################################################
# This macro checks that a FIND_PATH variable is valid, and will work.
#
# An optional file can be specified, which is used to check that the directory
# not only exists, but contains that file.
#
# If the path is not found, the path variable is set to NOTFOUND
#
# Usage: FIND_PATH_VERIFY <directory variable> [file to find]
#
#        Typically, just before a command such as:
#
#        FIND_PATH(<directory variable> <file to find>)
#
################################################################################
MACRO(FIND_PATH_VERIFY directory_variable ...)

    IF(${ARGC} EQUAL 1)     # Only directory provided, test that it exists

           IF(NOT EXISTS ${${directory_variable}})
               MESSAGE("EE_FIND_PATH_VERIFY Failed to find \n"
${directory_variable} "\n\nClearing variable")
               SET(${directory_variable}
${directory_variable}-NOTFOUND CACHE PATH "" FORCE)
           ENDIF(NOT EXISTS ${${directory_variable}})

    ELSE(${ARGC} EQUAL 1)   # test that directory/file exists

           IF(NOT EXISTS ${${directory_variable}}/${ARGV1})
               MESSAGE("EE_FIND_PATH_VERIFY Failed to find \n"
${directory_variable}/${ARGV1} "\n\nClearing variable")
               SET(${directory_variable}
${directory_variable}-NOTFOUND CACHE PATH "" FORCE)
           ENDIF(NOT EXISTS ${${directory_variable}}/${ARGV1})

    ENDIF(${ARGC} EQUAL 1)

ENDMACRO(FIND_PATH_VERIFY directory_variable ...)