Improve tests/examples: generate deps for output files (#1962)

This still runs all the tests in the configure phase, since the tests
report back what output file (png/svg/none) will be generated.. :/

This could be improved by having this table in CMakeLists directly, or
by having a callback into the tests that only reports back that
information.  The latter would still execute all the tests (via a Lua
process).

Adds an explicit check-examples target.

tests/examples/CMakeLists.txt

@@ -16,8 +16,9 @@ endif()
 
 cmake_minimum_required(VERSION 3.0.0)
 
-# Get and update the LUA_PATH so the scripts can be executed without Awesome.
+# Get and update the LUA_PATH so the scripts can be executed without awesome.
-execute_process(COMMAND lua -e print\(package.path\) OUTPUT_VARIABLE "LUA_PATH_")
+execute_process(COMMAND lua -e "p = package.path:gsub(';', '\\\\;'); io.stdout:write(p)"
+    OUTPUT_VARIABLE "LUA_PATH_")
 
 # Make sure the system can be called from the test directory
 if(NOT SOURCE_DIR AND ${CMAKE_CURRENT_SOURCE_DIR} MATCHES "/tests/examples")
@@ -45,28 +46,22 @@ else()
 endif()
 
 # Add the main awesome lua libraries.
-set(LUA_PATH2_ "\
+set(LUA_PATH_ "\
-${TOP_SOURCE_DIR}/lib/?.lua;\
+${TOP_SOURCE_DIR}/lib/?.lua\\;\
-${TOP_SOURCE_DIR}/lib/?/init.lua;\
+${TOP_SOURCE_DIR}/lib/?/init.lua\\;\
-${TOP_SOURCE_DIR}/lib/?;\
+${TOP_SOURCE_DIR}/lib/?\\;\
-${TOP_SOURCE_DIR}/themes/?.lua;\
+${TOP_SOURCE_DIR}/themes/?.lua\\;\
-${TOP_SOURCE_DIR}/themes/?;"
+${TOP_SOURCE_DIR}/themes/?\\;\
-)
+${LUA_PATH_}")
 
 # Add the C API shims.
-set(LUA_PATH3_ "\
+set(LUA_PATH_ "\
-${TOP_SOURCE_DIR}/tests/examples/shims/?.lua;\
+${TOP_SOURCE_DIR}/tests/examples/shims/?.lua\\;\
-${TOP_SOURCE_DIR}/tests/examples/shims/?/init.lua;\
+${TOP_SOURCE_DIR}/tests/examples/shims/?/init.lua\\;\
-${TOP_SOURCE_DIR}/tests/examples/shims/?;"
+${TOP_SOURCE_DIR}/tests/examples/shims/?\\;\
-)
+${LUA_PATH_}")
 
-# Done in 3 variables to avoid CMake from implicitly converting into a list.
+set(LUA_COV_RUNNER env -u LUA_PATH_5_1 -u LUA_PATH_5_2 -u LUA_PATH_5_3 "LUA_PATH=${LUA_PATH_}" ${LUA_COV_RUNNER})
-set(ENV{LUA_PATH} "${LUA_PATH3_}${LUA_PATH2_}${LUA_PATH_}")
-
-# Unset environment variables that would get in the way of evaluating LUA_PATH.
-unset(ENV{LUA_PATH_5_1})
-unset(ENV{LUA_PATH_5_2})
-unset(ENV{LUA_PATH_5_3})
 
 # The documentation images directory.
 set(IMAGE_DIR "${CMAKE_BINARY_DIR}/doc/images")
@@ -194,6 +189,9 @@ function(run_test test_path namespace escaped_content)
     # Execute the script, leave the image extension decision to the test.
     # SVG is preferred, but PNG is better suited for some tests, like bitmap
     # patterns.
+    file(RELATIVE_PATH rel_test_path "${TOP_SOURCE_DIR}" "${test_path}")
+    message(STATUS "Running ${rel_test_path}…")
+
     execute_process(
         COMMAND ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH}
         RESULT_VARIABLE TEST_RESULT
@@ -221,15 +219,19 @@ function(run_test test_path namespace escaped_content)
 
     # If the image has been created, then add it.
     if(EXISTS "${IMAGE_PATH}.svg")
+        set(OUTPUT_IMAGE_PATH "${IMAGE_PATH}.svg")
         escape_string(
             "![Usage example](../images/AUTOGEN${namespace}_${TEST_FILE_NAME}.svg)\n"
             "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT ""
         )
     elseif(EXISTS "${IMAGE_PATH}.png")
+        set(OUTPUT_IMAGE_PATH "${IMAGE_PATH}.png")
         escape_string(
             "![Usage example](../images/AUTOGEN${namespace}_${TEST_FILE_NAME}.png)\n"
             "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT ""
         )
+    else()
+        set(OUTPUT_IMAGE_PATH "")
     endif()
 
     # If there is an output, assume it is relevant and add it to the
@@ -256,25 +258,39 @@ function(run_test test_path namespace escaped_content)
             " ${DOC_BLOCK_PREFIX}"
             "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT ""
         )
-
         set(TEST_DOC_CONTENT "${TEST_DOC_CONTENT}${TEST_CODE}")
     endif()
 
+    if(NOT ${OUTPUT_IMAGE_PATH} STREQUAL "")
+        file(RELATIVE_PATH rel_template "${TOP_SOURCE_DIR}" "${template}")
+        file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_IMAGE_PATH}")
+        add_custom_command(
+            COMMAND ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH}
+            COMMENT "Generating ${rel_output} (via ${rel_test_path} (${rel_template}))"
+            DEPENDS ${template} ${test_path}
+            OUTPUT  ${OUTPUT_IMAGE_PATH}
+            VERBATIM)
+        set(EXAMPLE_DOC_GENERATED_FILES ${OUTPUT_IMAGE_PATH} ${EXAMPLE_DOC_GENERATED_FILES}
+            PARENT_SCOPE)
+    endif()
+
     # Export the outout to the parent scope.
     set(${escaped_content} "${TEST_DOC_CONTENT}" PARENT_SCOPE)
-
 endfunction()
 
-# Find and run all test files.
+# Find all test files, and run them (generating custom commands for updating them).
 file(GLOB_RECURSE test_files LIST_DIRECTORIES false
     "${TOP_SOURCE_DIR}/tests/examples/*.lua")
+
+# TODO: check for changed files (timestamp)?!
+if(NOT "${test_files}" STREQUAL "${EXAMPLE_DOC_SOURCE_FILES}")
+    set(EXAMPLE_DOC_SOURCE_FILES "${test_files}" CACHE INTERNAL "Source files used to generate doc files.")
+
+    # Find and run all test files.
     foreach(file ${test_files})
         if ((NOT "${file}" MATCHES ".*/shims/.*")
             AND (NOT "${file}" MATCHES ".*/template.lua"))
 
-        file(RELATIVE_PATH relative_file "${TOP_SOURCE_DIR}" "${file}")
-        message(STATUS "Running ${relative_file}...")
-
             # Get the file name without the extension.
             get_filename_component(TEST_FILE_NAME ${file} NAME_WE)
 
@@ -294,6 +310,16 @@ foreach(file ${test_files})
         endif()
     endforeach()
 
-message(STATUS "Example tests passed.")
+    set(EXAMPLE_DOC_GENERATED_FILES ${EXAMPLE_DOC_GENERATED_FILES}
+        CACHE INTERNAL "List of generated files for example docs.")
+endif()
+
+add_custom_target(generate-examples ALL
+    DEPENDS ${EXAMPLE_DOC_GENERATED_FILES})
+
+add_custom_target(check-examples
+    ${CMAKE_COMMAND} -D EXAMPLE_DOC_SOURCE_FILES= ${CMAKE_SOURCE_DIR}
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+list(APPEND CHECK_TARGETS check-examples)
 
 # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker