refactor git submodule support in cmake (#448)

In some places our CMake scripts were attempting to check out git submodules when required, if they have not already been checked out. The code that does this was cut and pasted, and was getting unwieldy.

To minimise the responsibilities of CMake, this PR

removes calls to git
introduces a function check_git_submodule that can be used to test if a git submodule is installed, and print a helpful message that informs the user how to check it out if needed.
introduces a function add_error_target that makes a target that prints a message then quits with an error. This can be used to generate a proxy target when a problem is detected during CMake setup. This means that an error is only generated when building a target with a missing dependency, instead of an error during CMake setup.
refactors the CMake setup for the docs and ubenches targets to use these new features.

CMakeLists.txt

@@ -291,9 +291,23 @@ if(NOT use_external_modcc)
     add_subdirectory(modcc)
 endif()
 
+#----------------------------------------------------------
+# set up for targets that require git submodules.
+#----------------------------------------------------------
+include(GitSubmodule) # required for check_git_submodule
+include(ErrorTarget)  # reguired for add_error_target
+check_git_submodule(rtdtheme "${PROJECT_SOURCE_DIR}/doc/rtd_theme")
+
 add_subdirectory(src)
 add_subdirectory(mechanisms) # after src path so that gpu_mechanism library is last on link line
 add_subdirectory(tests)
 add_subdirectory(example)
 add_subdirectory(lmorpho)
-add_subdirectory(doc)
+if (rtdtheme_avail)
+    add_subdirectory(doc)
+else()
+    add_error_target( docs
+        "Generating Sphinx documentation"
+        "The git submodule for read the docs is not available")
+endif()
+

cmake/ErrorTarget.cmake

+# Creates a target that prints an error message and returns 1 when built.
+#   name    : the name of the target
+#   comment : the COMMENT string for the real target, e.g. "Building the Sphinx documentation"
+#   message : the error message
+
+function(add_error_target name comment message)
+    add_custom_target(${name}
+        COMMAND echo "  Error: ${message}."
+        COMMAND exit 1
+        COMMENT "${comment}")
+endfunction()

cmake/GitSubmodule.cmake

+# Call to ensure that the git submodule in location `path` is loaded.
+# If the submodule is not loaded, an error message that describes
+# how to update the submodules is printed.
+# Sets the variable name_avail to `ON` if the submodule is available,
+# or `OFF` otherwise.
+
+function(check_git_submodule name path)
+    set(success_var "${name}_avail")
+    set(${success_var} ON PARENT_SCOPE)
+
+    if(NOT EXISTS "${path}/.git")
+        message(
+            "\nThe git submodule for ${name} is not available.\n"
+            "To check out all submodules use the following commands:\n"
+            "    git submodule init\n"
+            "    git submodule update\n"
+            "Or download submodules recursively when checking out:\n"
+            "    git clone --recursive https://github.com/eth-cscs/arbor.git\n"
+        )
+
+        # if the repository was not available, and git failed, set AVAIL to false
+        set(${success_var} OFF PARENT_SCOPE)
+    endif()
+endfunction()

doc/CMakeLists.txt

-# Set up rtd theme as an external project.
-set(rtdtheme_src_dir "${CMAKE_CURRENT_SOURCE_DIR}/rtd_theme")
-
-find_package(Git)
-if(NOT EXISTS "${rtdtheme_src_dir}/.git")
-    set(git_failed)
-
-    if(GIT_FOUND)
-        message(STATUS "Updating the ReadTheDocs theme submodule ${rtdtheme_src_dir}")
-        execute_process(
-            COMMAND "${GIT_EXECUTABLE}" submodule update --init "${rtdtheme_src_dir}"
-            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
-            ERROR_VARIABLE git_error
-            RESULT_VARIABLE git_result)
-        if(NOT git_result EQUAL 0)
-            set(git_failed "${git_error}")
-        endif()
-    else()
-        set(git_failed "git not found")
-    endif()
-
-    if(git_failed)
-        message(WARNING "Unable to update the ReadTheDocs theme submodule: ${git_failed}")
-    endif()
-
-endif()
-
 # a static path is required to avoid warning messages from sphinx-build
 file(MAKE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/static")
 
@@ -33,9 +6,8 @@ find_package(Sphinx)
 
 set(DOCS_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
 set(DOCS_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
-set(DOCS_TARGET_NAME docs)
 if (SPHINX_FOUND)
-    add_custom_target( ${DOCS_TARGET_NAME}
+    add_custom_target(docs
         COMMAND
             ${SPHINX_EXECUTABLE}
             -b html
@@ -46,16 +18,10 @@ if (SPHINX_FOUND)
         COMMENT
             "Generating Sphinx documentation")
 else()
-    add_custom_target( ${DOCS_TARGET_NAME}
-        COMMAND
-            echo "Error: Sphinx must be installed to build documentation."
-        COMMAND
-            exit 1  # return error code to let CMake know that the build proccess should fail
-        COMMENT
-            "Generating Sphinx documentation")
+    add_error_target(docs
+        "Generating Sphinx documentation"
+        "Sphinx must be installed to build documentation")
 endif()
 
 # remove generated documentation when make clean is run
 set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${DOCS_BUILD_DIR}")
-
-unset(git_failed)

tests/CMakeLists.txt

@@ -14,7 +14,15 @@ add_subdirectory(global_communication)
 add_subdirectory(performance)
 
 # Microbenchmarks.
-add_subdirectory(ubench)
+# Attempt to update git submodule if required.
+check_git_submodule(google_bench "${CMAKE_CURRENT_SOURCE_DIR}/ubench/google-benchmark")
+if (google_bench_avail)
+    add_subdirectory(ubench)
+else()
+    add_error_target(ubenches
+        "Building micro benchmarks"
+        "The git submodule for google benchmark is not available")
+endif()
 
 # regression / delta tests
 # Employing the full simulator. validated using deltas on output data

tests/ubench/CMakeLists.txt

@@ -24,30 +24,6 @@ set(gbench_cmake_args
     "-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}"
     "-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}")
 
-
-# Attempt to update git submodule if required.
-find_package(Git)
-if(NOT EXISTS "${gbench_src_dir}/.git")
-    set(git_failed)
-    if(GIT_FOUND)
-        message(STATUS "Updating the google-benchmark submodule ${gbench_src_dir}")
-        execute_process(
-            COMMAND "${GIT_EXECUTABLE}" submodule update --init "${gbench_src_dir}"
-            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
-            ERROR_VARIABLE git_error
-            RESULT_VARIABLE git_result)
-        if(NOT git_result EQUAL 0)
-            set(git_failed "${git_error}")
-        endif()
-    else()
-        set(git_failed "git not found")
-    endif()
-
-    if(git_failed)
-        message(WARNING "Unable to update the google-benchmark submodule: ${git_failed}")
-    endif()
-endif()
-
 ExternalProject_Add(gbench
     # Add dummy DOWNLOAD_COMMAND to stop ExternalProject_Add terminating CMake if the
     # git submodule had not been udpated.
@@ -85,4 +61,3 @@ if(ARB_WITH_CUDA)
 endif()
 
 add_custom_target(ubenches DEPENDS ${bench_exe_list})
-