cmake: fix sporadic WSDG build failure on Windows

The Windows builds (using msbuild) fail sporadically when building
documentation (target developer_guides). The problem is that the targets
"developer_guide_pdf_a4" and "developer_guide_html" both depend on
developer-guide.xml and msbuild does not notice that the file has
already been generated by the generate_developer-guide.xml target.

For a discussion of the problem, see
https://gitlab.kitware.com/cmake/cmake/issues/16767

To fix this, remove the "developer-guide.xml" dependency from
"developer_guide_xyz" (to prevent these targets from triggering building
"developer-guide.xml"). Instead, depend on a generated
"developer-guide.xml-stamp" file which is created by the
"generate_developer-guide.xml" target (but do *not* add it as output of
this target, otherwise we will have the original problem again).

This workaround is restricted to the MSVC generators because otherwise
it would trigger a CMP0058 policy warning when used with Ninja.

Change-Id: Idb3975cde35be2601b038a500d4886bbd3a684d7
Reviewed-on: https://code.wireshark.org/review/20812
Petri-Dish: Peter Wu <peter@lekensteyn.nl>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Graham Bloice <graham.bloice@trihedral.com>
Reviewed-by: Anders Broman <a.broman58@gmail.com>

2 files changed, 46 insertions, 6 deletions

diff --git a/cmake/modules/FindASCIIDOC.cmake b/cmake/modules/FindASCIIDOC.cmake
index b6e66caf79..31fbb71fd3 100644
--- a/cmake/modules/FindASCIIDOC.cmake
+++ b/cmake/modules/FindASCIIDOC.cmake
@@ -85,6 +85,17 @@ MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files _src_files _built_deps )
 
     TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource} _a2x_asciidocsource )
 
+    if(CMAKE_GENERATOR MATCHES "Visual Studio")
+      # Workaround to prevent parallel msbuild builds from failing, see function
+      # get_docbook_xml_depends in FindXSLTPROC.cmake for details. This command
+      # updates the stamp file when the XML file is updated.
+      set(_stamp_file "${CMAKE_CURRENT_BINARY_DIR}/${_output_xml}-stamp")
+      set_property(SOURCE "${_stamp_file}" PROPERTY GENERATED)
+      set(_command_touch_stamp COMMAND "${CMAKE_COMMAND}" -E touch "${_stamp_file}")
+    else()
+      set(_command_touch_stamp "")
+    endif()
+
     add_custom_command(
         OUTPUT
             ${_output_xml}
@@ -101,6 +112,7 @@ MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files _src_files _built_deps )
             --fop
             ${A2X_HTML_OPTS}
             ${_a2x_asciidocsource}
+        ${_command_touch_stamp}
         DEPENDS
             ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource}
             ${_conf_deps}
diff --git a/cmake/modules/FindXSLTPROC.cmake b/cmake/modules/FindXSLTPROC.cmake
index 5c42028a24..4bfd560eeb 100644
--- a/cmake/modules/FindXSLTPROC.cmake
+++ b/cmake/modules/FindXSLTPROC.cmake
@@ -68,6 +68,34 @@ else()
     set ( _xsltproc_path "${CMAKE_CURRENT_SOURCE_DIR}:${CMAKE_CURRENT_BINARY_DIR}:${CMAKE_CURRENT_BINARY_DIR}/wsluarm_src")
 endif()
 
+# Workaround for parallel build issue with msbuild.
+# https://gitlab.kitware.com/cmake/cmake/issues/16767
+if(CMAKE_GENERATOR MATCHES "Visual Studio")
+  # msbuild (as used by the Visual Studio generators) must not depend on the XML
+  # file (otherwise the XML file will be generated multiple times, possibly in
+  # parallel, breaking the build). Workaround: add one dependency to generate
+  # the XML file when outdated, depend on the -stamp file to ensure that the
+  # target is rebuilt when the XML file is regenerated.
+  function(get_docbook_xml_depends varname _dbk_source)
+    set(${varname}
+      "generate_${_dbk_source}"
+      "${CMAKE_CURRENT_BINARY_DIR}/${_dbk_source}-stamp"
+      PARENT_SCOPE
+    )
+  endfunction()
+else()
+  # Unix Makefiles, Ninja, etc: first dependency enforces that the XML file is
+  # rebuilt when outdated, the second dependency ensures that the target is
+  # rebuilt when the XML file has changed.
+  function(get_docbook_xml_depends varname _dbk_source)
+    set(${varname}
+      "generate_${_dbk_source}"
+      "${_dbk_source}"
+      PARENT_SCOPE
+    )
+  endfunction()
+endif()
+
 # Translate XML to HTML
 #XML2HTML(
 #        wsug or wsdg
@@ -91,6 +119,7 @@ MACRO(XML2HTML _target_dep _dir_pfx _mode _dbk_source _gfx_sources)
 
     SET(_out_dir ${CMAKE_CURRENT_BINARY_DIR}/${_basedir})
     SET(_output ${_basedir}/index.html)
+    get_docbook_xml_depends(_dbk_xml_deps "${_dbk_source}")
 
     FOREACH(_tmpgfx ${${_gfx_sources}})
         set(_gfx_deps ${CMAKE_CURRENT_SOURCE_DIR}/${_tmpgfx})
@@ -126,8 +155,7 @@ MACRO(XML2HTML _target_dep _dir_pfx _mode _dbk_source _gfx_sources)
             ${_STYLESHEET}
             ${_dbk_source}
         DEPENDS
-            generate_${_dbk_source}
-            ${_dbk_source}
+            ${_dbk_xml_deps}
             ${_dbk_dep}
             ${_gfx_deps}
     )
@@ -153,6 +181,7 @@ MACRO(XML2PDF _target_dep _output _dbk_source _stylesheet _paper)
     # We depend on the docbook target to avoid parallel builds.
     SET(_dbk_dep ${_target_dep}_docbook)
     file(RELATIVE_PATH _img_relative_path ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR})
+    get_docbook_xml_depends(_dbk_xml_deps "${_dbk_source}")
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output}
@@ -173,8 +202,7 @@ MACRO(XML2PDF _target_dep _output _dbk_source _stylesheet _paper)
             ${_output}.fo
             ${_output}
         DEPENDS
-            generate_${_dbk_source}
-            ${_dbk_source}
+            ${_dbk_xml_deps}
             ${_dbk_dep}
             ${_stylesheet}
     )
@@ -193,6 +221,7 @@ MACRO(XML2HHP _target_dep _guide _dbk_source)
     set( _output_hhp ${_source_base_name}.hhp )
     set( _output_toc_hhc ${_source_base_name}-toc.hhc )
     set( _docbook_plain_title ${_source_base_name}-plain-title.xml )
+    get_docbook_xml_depends(_dbk_xml_deps "${_dbk_source}")
 
     SET(_gfxdir ${_guide}_graphics)
     SET(_basedir ${_guide}_chm)
@@ -220,8 +249,7 @@ MACRO(XML2HHP _target_dep _guide _dbk_source)
             --nonet custom_layer_chm.xsl
             ${_docbook_plain_title}
         DEPENDS
-            generate_${_dbk_source}
-            ${_dbk_source}
+            ${_dbk_xml_deps}
             ${_dbk_dep}
             # AsciiDoc uses UTF-8 by default, which is unsupported by HTML
             # Help. We may want to render an ISO-8859-1 version, or get rid