CMake: Try to fix generated docbook dependencies.

Add custom {developer,user}_guide_docbook targets for docbook output. Make
sure the HTML, PDF, and CHM outputs depend on their associated docbook
target and not on the output .xml file. This keeps us from running a2x
instances in parallel.

Change-Id: I73b0db50ae92f62eb08ae284d498cdf2d697ac00
Reviewed-on: https://code.wireshark.org/review/9920
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Gerald Combs <gerald@wireshark.org>

4 files changed, 173 insertions, 134 deletions

diff --git a/cmake/modules/FindASCIIDOC.cmake b/cmake/modules/FindASCIIDOC.cmake
index 73d29f16e6..a0d89ae62d 100644
--- a/cmake/modules/FindASCIIDOC.cmake
+++ b/cmake/modules/FindASCIIDOC.cmake
@@ -63,22 +63,26 @@ MARK_AS_ADVANCED(RUNA2X)
 
 TO_A2X_COMPATIBLE_PATH( ${CMAKE_CURRENT_BINARY_DIR} _a2x_current_binary_dir )
 
-MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files )
+MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files _src_files _built_deps )
     GET_FILENAME_COMPONENT( _source_base_name ${_asciidocsource} NAME_WE )
     set( A2X_HTML_OPTS --stylesheet=ws.css )
     set( _output_xml ${_source_base_name}.xml )
     set( _output_dbk ${_source_base_name}.dbk )
 
-    foreach(_conf_file ${_conf_files})
+    foreach(_conf_file ${${_conf_files}})
         TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} _a2x_conf_file )
         set( _conf_opts_list ${_conf_opts_list} --conf-file=${_a2x_conf_file})
     endforeach()
     string( REPLACE ";" " " _conf_opts "${_conf_opts_list}")
 
-    foreach(_conf_file ${_conf_files})
+    foreach(_conf_file ${${_conf_files}})
         set( _conf_deps ${_conf_deps} ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file})
     endforeach()
 
+    foreach(_src_file ${${_src_files}})
+        set( _src_deps ${_src_deps} ${CMAKE_CURRENT_SOURCE_DIR}/${_src_file})
+    endforeach()
+
     TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource} _a2x_asciidocsource )
 
     ADD_CUSTOM_COMMAND(
@@ -100,6 +104,8 @@ MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files )
         DEPENDS
             ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource}
             ${_conf_deps}
+            ${_src_deps}
+            ${${_built_deps}}
     )
 ENDMACRO()
 
diff --git a/cmake/modules/FindXMLLINT.cmake b/cmake/modules/FindXMLLINT.cmake
index ccc93f38bb..aee58c80ff 100644
--- a/cmake/modules/FindXMLLINT.cmake
+++ b/cmake/modules/FindXMLLINT.cmake
@@ -47,6 +47,7 @@ else()
 endif()
 
 # Validate XML
+# XXX Unused?
 MACRO(VALIDATE_XML _validated _sources)
     # FIXME: How do I extract the first element of a variable containing a
     # list of values? Isn't there a "cleaner" solution?
diff --git a/cmake/modules/FindXSLTPROC.cmake b/cmake/modules/FindXSLTPROC.cmake
index 2a2993ae1e..e7565eb9bc 100644
--- a/cmake/modules/FindXSLTPROC.cmake
+++ b/cmake/modules/FindXSLTPROC.cmake
@@ -72,71 +72,68 @@ endif()
 #        WSUG_FILES
 #        WSUG_GRAPHICS
 #)
-MACRO(XML2HTML _guide _mode _xmlsources _gfxsources)
-    SET(_validated ${_guide}.validated)
+MACRO(XML2HTML _target_dep _dir_pfx _mode _dbk_source _gfx_sources)
+    # We depend on the docbook target to avoid parallel builds.
+    SET(_dbk_dep ${_target_dep}_docbook)
+    #SET(_validated ${_dir_pfx}.validated)
 
     IF(${_mode} STREQUAL "chunked")
-        SET(_basedir ${_guide}_html_chunked)
+        SET(_basedir ${_dir_pfx}_html_chunked)
         SET(_STYLESHEET "http://docbook.sourceforge.net/release/xsl/current/xhtml5/chunk.xsl")
         SET(_modeparams --stringparam html.ext .html --noout)
     ELSE() # single-page
-        SET(_basedir ${_guide}_html)
+        SET(_basedir ${_dir_pfx}_html)
         SET(_STYLESHEET "http://docbook.sourceforge.net/release/xsl/current/xhtml5/docbook.xsl")
         SET(_modeparams --output ${_basedir}/index.html)
     ENDIF()
 
-    SET(_outdir ${CMAKE_CURRENT_BINARY_DIR}/${_basedir})
+    SET(_out_dir ${CMAKE_CURRENT_BINARY_DIR}/${_basedir})
     SET(_output ${_basedir}/index.html)
 
-#    FOREACH(_tmpgfx ${${_gfxsources}})
-#        set(_gfx ${_tmpgfx})
-#        BREAK()
-#    ENDFOREACH()
+    FOREACH(_tmpgfx ${${_gfx_sources}})
+        set(_gfx_deps ${CMAKE_CURRENT_SOURCE_DIR}/${_tmpgfx})
+    ENDFOREACH()
+
 #    GET_FILENAME_COMPONENT(_GFXDIR ${_gfx} ABSOLUTE)
 #    GET_FILENAME_COMPONENT(_GFXDIR ${_GFXDIR} PATH)
 #    GET_FILENAME_COMPONENT(_OUTDIR ${_output} PATH)
 #    SET(_OUTDIR ${CMAKE_CURRENT_BINARY_DIR}/${_OUTDIR})
 
-    FOREACH(_tmpsource ${${_xmlsources}})
-        set(_source ${_tmpsource})
-        BREAK()
-    ENDFOREACH()
-
-    SET(_gfxdir ${_guide}_graphics)
+    SET(_gfx_dir ${_dir_pfx}_graphics)
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output}
         COMMAND ${CMAKE_COMMAND}
-            -E make_directory ${_outdir}
+            -E make_directory ${_out_dir}
         COMMAND ${CMAKE_COMMAND}
-           -E make_directory ${_outdir}/${_gfxdir}/toolbar
+           -E make_directory ${_out_dir}/${_gfx_dir}/toolbar
         COMMAND ${CMAKE_COMMAND}
-           -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${_gfxdir} ${_outdir}/${_gfxdir}
+           -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${_gfx_dir} ${_out_dir}/${_gfx_dir}
         COMMAND ${CMAKE_COMMAND}
-           -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/common_graphics ${_outdir}/${_gfxdir}
+           -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/common_graphics ${_out_dir}/${_gfx_dir}
         COMMAND ${CMAKE_COMMAND}
-           -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${_gfxdir}/toolbar ${_outdir}/${_gfxdir}/toolbar
+           -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${_gfx_dir}/toolbar ${_out_dir}/${_gfx_dir}/toolbar
         COMMAND ${CMAKE_COMMAND}
-            -E copy ${CMAKE_CURRENT_SOURCE_DIR}/ws.css ${_outdir}
+            -E copy ${CMAKE_CURRENT_SOURCE_DIR}/ws.css ${_out_dir}
         COMMAND ${XSLTPROC_EXECUTABLE}
             --path "${_xsltproc_path}"
             --stringparam base.dir ${_basedir}/
             ${_common_xsltproc_args}
-            --stringparam admon.graphics.path ${_gfxdir}/
+            --stringparam admon.graphics.path ${_gfx_dir}/
             ${_modeparams}
             ${_STYLESHEET}
-            ${_source}
+            ${_dbk_source}
         DEPENDS
-            ${_validated}
-            ${${_xmlsources}}
-            ${${_gfxsources}}
+            ${_dbk_dep}
+            #${_validated}
+            ${_gfx_deps}
     )
     IF(NOT WIN32)
         ADD_CUSTOM_COMMAND(
             OUTPUT
                 ${_output}
             COMMAND chmod
-                -R og+rX ${_outdir}
+                -R og+rX ${_out_dir}
             APPEND
         )
     ENDIF()
@@ -149,15 +146,13 @@ ENDMACRO(XML2HTML)
 #       custom_layer_pdf.xsl
 #       A4 or letter
 #)
-MACRO(XML2PDF _output _sources _stylesheet _paper)
-    FOREACH(_tmpsource ${${_sources}})
-        set(_source ${_tmpsource})
-        BREAK()
-    ENDFOREACH()
-
+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)
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output}
+            ${_output}.fo
         COMMAND ${XSLTPROC_EXECUTABLE}
             --path "${_xsltproc_path}"
             --stringparam paper.type ${_paper}
@@ -169,12 +164,12 @@ MACRO(XML2PDF _output _sources _stylesheet _paper)
             --nonet
             --output ${_output}.fo
             ${_stylesheet}
-            ${_source}
+            ${_dbk_source}
         COMMAND ${FOP_EXECUTABLE}
             ${_output}.fo
             ${_output}
         DEPENDS
-            ${${_sources}}
+            ${_dbk_dep}
             ${_stylesheet}
     )
 ENDMACRO(XML2PDF)
@@ -184,7 +179,9 @@ ENDMACRO(XML2PDF)
 #       wsug or wsdg
 #       user-guide.xml or developer-guide.xml
 #)
-MACRO(XML2HHP _guide _docbooksource)
+MACRO(XML2HHP _target_dep _guide _docbooksource)
+    # We depend on the docbook target to avoid parallel builds.
+    SET(_dbk_dep ${_target_dep}_docbook)
     GET_FILENAME_COMPONENT( _source_base_name ${_docbooksource} NAME_WE )
     set( _output_chm ${_source_base_name}.chm )
     set( _output_hhp ${_source_base_name}.hhp )
@@ -196,6 +193,7 @@ MACRO(XML2HHP _guide _docbooksource)
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output_hhp}
+            ${_output_toc_hhc}
         COMMAND ${CMAKE_COMMAND} -E make_directory ${_basedir}
         COMMAND ${CMAKE_COMMAND} -E make_directory ${_basedir}/${_gfxdir}
         COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${_gfxdir} ${_basedir}/${_gfxdir}
@@ -216,9 +214,10 @@ MACRO(XML2HHP _guide _docbooksource)
             --nonet custom_layer_chm.xsl
             ${_docbook_plain_title}
         DEPENDS
+            ${_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
             # of HTML Help.
-            ${_docbooksource}
+            custom_layer_chm.xsl
     )
 ENDMACRO(XML2HHP)
diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt
index ead8d2d0c8..a728daaf51 100644
--- a/docbook/CMakeLists.txt
+++ b/docbook/CMakeLists.txt
@@ -74,7 +74,6 @@ set(WSUG_FILES
 	wsug_src/WSUG_chapter_use.asciidoc
 	wsug_src/WSUG_chapter_work.asciidoc
 	wsug_src/WSUG_preface.asciidoc
-	ws.css
 )
 
 set(WSUG_GRAPHICS
@@ -215,7 +214,6 @@ set(WSDG_FILES
 	wsdg_src/WSDG_chapter_works.asciidoc
 	wsdg_src/WSDG_preface.asciidoc
 	wsluarm.asciidoc
-	ws.css
 )
 
 set(WSDG_GRAPHICS
@@ -229,15 +227,11 @@ set(WSDG_GRAPHICS
 	${COMMON_GRAPHICS}
 )
 
-# user-guide.xml must be first in the list
 set(WSUG_SOURCE
-	user-guide.xml
 	${WSUG_FILES}
 	${WSUG_GRAPHICS}
 )
 
-set( ASCIIDOC_CONF_FILES asciidoc.conf asciidoctor-asciidoc.conf )
-
 add_custom_command(
 	OUTPUT ws.css
 	COMMAND ${CMAKE_COMMAND} -E copy_if_different
@@ -245,12 +239,9 @@ add_custom_command(
 		${CMAKE_CURRENT_BINARY_DIR}/ws.css
 )
 
-ASCIIDOC2DOCBOOK( developer-guide.asciidoc "${ASCIIDOC_CONF_FILES}" )
-ASCIIDOC2DOCBOOK( user-guide.asciidoc "${ASCIIDOC_CONF_FILES}" )
+set( WSUG_BUILT_DEPS ws.css )
 
-# developer-guide.xml must be first in the list
 set(WSDG_SOURCE
-	developer-guide.xml
 	${WSDG_FILES}
 	${WSDG_GRAPHICS}
 )
@@ -285,14 +276,72 @@ set(WSLUA_MODULES
 	${CMAKE_SOURCE_DIR}/epan/wslua/wslua_struct.c
 )
 
-add_custom_target(user_guides)
+# Empty file to trigger wsluarm generation.
+ADD_CUSTOM_COMMAND(
+	OUTPUT
+		wsluarm
+	COMMAND ${CMAKE_COMMAND} -E make_directory wsluarm_src
+	COMMAND ${PERL_EXECUTABLE}
+		${CMAKE_CURRENT_SOURCE_DIR}/make-wsluarm.pl
+		${WSLUA_MODULES}
+	COMMAND ${CMAKE_COMMAND} -E touch
+		wsluarm
+	DEPENDS
+		${CMAKE_CURRENT_SOURCE_DIR}/make-wsluarm.pl
+		${WSLUA_MODULES}
+)
+
+set( WSDG_BUILT_DEPS ws.css wsluarm )
+
+# Generate the DocBook sources of user and developer guides
+
+set( ASCIIDOC_CONF_FILES asciidoc.conf asciidoctor-asciidoc.conf )
+
+ASCIIDOC2DOCBOOK(user-guide.asciidoc ASCIIDOC_CONF_FILES WSUG_SOURCE WSUG_BUILT_DEPS)
+add_custom_target(user_guide_docbook DEPENDS user-guide.xml)
+set_target_properties(user_guide_docbook PROPERTIES FOLDER "Docbook")
+ASCIIDOC2DOCBOOK(developer-guide.asciidoc ASCIIDOC_WSLUARM_CONF_FILES WSDG_SOURCE WSDG_BUILT_DEPS)
+add_custom_target(developer_guide_docbook DEPENDS developer-guide.xml)
+set_target_properties(developer_guide_docbook PROPERTIES FOLDER "Docbook")
+
+# Top-level guide targets.
+add_custom_target(user_guides DEPENDS user_guide_docbook)
+set_target_properties(user_guides PROPERTIES FOLDER "Docbook")
+add_custom_target(developer_guides DEPENDS developer_guide_docbook)
+set_target_properties(developer_guides PROPERTIES FOLDER "Docbook")
+add_custom_target(all_guides ALL DEPENDS user_guides developer_guides )
+set_target_properties(all_guides PROPERTIES FOLDER "Docbook")
+
+# User's Guide chain.
 if(ENABLE_HTML_GUIDES)
-	set(WSUG_HTML_OUTPUT wsug_html_chunked/index.html wsug_html/index.html)
+	# a2x always generates valid XML, *right*?
+	#VALIDATE_XML(
+	#	wsug.validated
+	#	user-guide.xml
+	#)
+
+	XML2HTML(
+		user_guide
+		wsug
+		single-page
+		user-guide.xml
+		WSUG_GRAPHICS
+	)
+
+	XML2HTML(
+		user_guide
+		wsug
+		chunked
+		user-guide.xml
+		WSUG_GRAPHICS
+	)
 	add_custom_target(
 		user_guide_html
 		DEPENDS
-			${WSUG_HTML_OUTPUT}
+			wsug_html/index.html
+			wsug_html_chunked/index.html
 	)
+	set_target_properties(user_guide_html PROPERTIES FOLDER "Docbook")
 	add_dependencies(user_guides user_guide_html)
 endif()
 
@@ -304,124 +353,123 @@ if(ENABLE_PDF_GUIDES)
 	# - Generate PDFs using AsciiDoc.
 
 	XML2PDF(
+		user_guide
 		user-guide-a4.pdf
-		WSUG_SOURCE
+		user-guide.xml
 		custom_layer_pdf.xsl
 		A4
 	)
-	add_custom_target(user_guide_pdf_a4 DEPENDS user-guide-a4.pdf)
-	add_dependencies(user_guides user_guide_pdf_a4)
 
 	XML2PDF(
+		user_guide
 		user-guide-us.pdf
-		WSUG_SOURCE
+		user-guide.xml
 		custom_layer_pdf.xsl
 		letter
 	)
-	add_custom_target(user_guide_pdf_us DEPENDS user-guide-us.pdf)
-	add_dependencies(user_guides user_guide_pdf_us)
+	add_custom_target(
+		user_guide_pdf_a4
+		DEPENDS
+			user-guide-a4.pdf
+	)
+	set_target_properties(user_guide_pdf_a4 PROPERTIES FOLDER "Docbook")
+	add_custom_target(
+		user_guide_pdf_us
+		DEPENDS
+			user-guide-us.pdf
+	)
+	set_target_properties(user_guide_pdf_us PROPERTIES FOLDER "Docbook")
+	add_dependencies(user_guides user_guide_pdf_a4 user_guide_pdf_us)
 endif()
 
 if(ENABLE_CHM_GUIDES)
-	set(WSUG_CHM_OUTPUT user-guide.chm)
-	XML2HHP(wsug user-guide.xml)
+	XML2HHP(user_guide wsug user-guide.xml)
 	HHP2CHM(user-guide.hhp)
 	add_custom_target(
 		user_guide_chm
 		DEPENDS
-			${WSUG_CHM_OUTPUT}
+			user-guide.chm
 	)
+	set_target_properties(user_guide_chm PROPERTIES FOLDER "Docbook")
 	add_dependencies(user_guides user_guide_chm)
 endif()
 
-VALIDATE_XML(
-	wsug.validated
-	WSUG_SOURCE
-)
-
-XML2HTML(
-	wsug
-	single-page
-	WSUG_SOURCE
-	WSUG_GRAPHICS
-)
-
-XML2HTML(
-	wsug
-	chunked
-	WSUG_SOURCE
-	WSUG_GRAPHICS
-)
-
-add_custom_target(developer_guides)
+# Developer's Guide chain.
 if(ENABLE_HTML_GUIDES)
-	set(WSDG_HTML_OUTPUT wsdg_html_chunked/index.html wsdg_html/index.html)
+	# a2x always generates valid XML, *right*?
+	#VALIDATE_XML(
+	#	wsdg.validated
+	#	developer-guide.xml
+	#)
+
+	XML2HTML(
+		developer_guide
+		wsdg
+		single-page
+		developer-guide.xml
+		WSDG_GRAPHICS
+	)
+
+	XML2HTML(
+		developer_guide
+		wsdg
+		chunked
+		developer-guide.xml
+		WSDG_GRAPHICS
+	)
 	add_custom_target(
 		developer_guide_html
 		DEPENDS
-			wsluarm
-			${WSDG_HTML_OUTPUT}
+			wsdg_html/index.html
+			wsdg_html_chunked/index.html
 	)
+	set_target_properties(developer_guide_html PROPERTIES FOLDER "Docbook")
 	add_dependencies(developer_guides developer_guide_html)
 endif()
 
 if(ENABLE_PDF_GUIDES)
 	XML2PDF(
+		developer_guide
 		developer-guide-a4.pdf
-		WSDG_SOURCE
+		developer-guide.xml
 		custom_layer_pdf.xsl
 		A4
 	)
-	add_custom_target(developer_guide_pdf_a4 DEPENDS developer-guide-a4.pdf)
-	add_dependencies(developer_guides developer_guide_pdf_a4)
 
 	XML2PDF(
+		developer_guide
 		developer-guide-us.pdf
-		WSDG_SOURCE
+		developer-guide.xml
 		custom_layer_pdf.xsl
 		letter
 	)
-	add_custom_target(developer_guide_pdf_us DEPENDS developer-guide-us.pdf)
-	add_dependencies(developer_guides developer_guide_pdf_us)
+	add_custom_target(
+		developer_guide_pdf_a4
+		DEPENDS
+			developer-guide-a4.pdf
+	)
+	set_target_properties(developer_guide_pdf_a4 PROPERTIES FOLDER "Docbook")
+	add_custom_target(
+		developer_guide_pdf_us
+		DEPENDS
+			developer-guide-us.pdf
+	)
+	set_target_properties(developer_guide_pdf_us PROPERTIES FOLDER "Docbook")
+	add_dependencies(developer_guides developer_guide_pdf_a4 developer_guide_pdf_us)
 endif()
 
 if(ENABLE_CHM_GUIDES)
-	set(WSDG_CHM_OUTPUT developer-guide.chm)
-	XML2HHP(wsdg developer-guide.xml)
+	XML2HHP(developer_guide	wsdg developer-guide.xml)
 	HHP2CHM(developer-guide.hhp)
 	add_custom_target(
 		developer_guide_chm
 		DEPENDS
-			wsluarm
-			${WSDG_CHM_OUTPUT}
+			developer-guide.chm
 	)
+	set_target_properties(developer_guide_chm PROPERTIES FOLDER "Docbook")
 	add_dependencies(developer_guides developer_guide_chm)
 endif()
 
-VALIDATE_XML(
-	wsdg.validated
-	WSDG_SOURCE
-)
-
-XML2HTML(
-	wsdg
-	single-page
-	WSDG_SOURCE
-	WSDG_GRAPHICS
-)
-
-XML2HTML(
-	wsdg
-	chunked
-	WSDG_SOURCE
-	WSDG_GRAPHICS
-)
-
-if(ENABLE_HTML_GUIDES OR ENABLE_PDF_GUIDES OR ENABLE_CHM_GUIDES)
-	add_custom_target( all_guides ALL )
-	add_dependencies ( all_guides user_guides developer_guides )
-endif()
-
 # release_notes: release-notes.html release-notes.txt release-notes-a4.pdf release-notes-us.pdf
 
 add_custom_target( release_notes_html DEPENDS ws.css release-notes.html )
@@ -471,18 +519,3 @@ ASCIIDOC2TXT(
 #	"${ASCIIDOC_CONF_FILES}"
 #	letter
 #)
-
-# wsluarm
-ADD_CUSTOM_COMMAND(
-	OUTPUT
-		wsluarm
-	COMMAND ${CMAKE_COMMAND} -E make_directory wsluarm_src
-	COMMAND ${PERL_EXECUTABLE}
-		${CMAKE_CURRENT_SOURCE_DIR}/make-wsluarm.pl
-		${WSLUA_MODULES}
-	COMMAND ${CMAKE_COMMAND} -E touch
-		 wsluarm
-	DEPENDS
-		${CMAKE_CURRENT_SOURCE_DIR}/make-wsluarm.pl
-		${WSLUA_MODULES}
-)