From cadd86ac4993fa9fcd69827c083803e159f499b1 Mon Sep 17 00:00:00 2001
From: Simon Tatham <anakin@pobox.com>
Date: Sat, 22 Jan 2022 14:42:03 +0000
Subject: [PATCH] doc/CMakeLists.txt: reorganise custom targets.

Jacob reported that on Debian buster, the command sequence

  cmake $srcdir
  cmake --build .
  cmake --build . --target doc

would fail at the third step, with the make error "No rule to make
target 'doc/cmake_version.but', needed by 'doc/html/index.html'".

That seems odd, because the file ${VERSION_BUT} _was_ declared as a
dependency of the rule that builds doc/html/*.html, and _cmake_ knew
what rule built it (namely the custom target 'cmake_version_but'). I
suspect this is a bug in cmake 3.13, because the same command sequence
works fine with cmake 3.20.

However, it's possible to work around, by means of adding the cmake
_target name_ to the dependencies for any rule that uses that file,
instead of relying on it to map the output _file_ name to that target.

While I'm at it, I've transformed the rules that build copy.but and
licence.but in the same way, turning those too into custom targets
instead of custom commands (I've found that the former are more
generally reliable across a range of cmake versions), and including
the target names themselves as dependencies.
---
 doc/CMakeLists.txt | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index cc90fcdc..709df3de 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -22,6 +22,9 @@ if(HALIBUT AND PERL_EXECUTABLE)
   # If this is a source archive in which a fixed version.but was
   # provided, use that. Otherwise, infer one from the git checkout (if
   # possible).
+
+  set(manual_dependencies) # extra target names to depend on
+
   if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/version.but)
     set(VERSION_BUT ${CMAKE_CURRENT_SOURCE_DIR}/version.but)
   else()
@@ -43,16 +46,20 @@ if(HALIBUT AND PERL_EXECUTABLE)
         ${INTERMEDIATE_VERSION_BUT} ${VERSION_BUT}
       DEPENDS check_git_commit_for_doc ${INTERMEDIATE_VERSION_BUT}
       COMMENT "Updating cmake_version.but")
+    set(manual_dependencies ${manual_dependencies} cmake_version_but)
   endif()
 
-  add_custom_command(OUTPUT copy.but
+  add_custom_target(copy_but
+    BYPRODUCTS copy.but
     COMMAND ${PERL_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl
       --copyrightdoc -o copy.but
     DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl ${CMAKE_CURRENT_SOURCE_DIR}/../LICENCE)
-  add_custom_command(OUTPUT licence.but
+  add_custom_target(licence_but
+    BYPRODUCTS licence.but
     COMMAND ${PERL_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl
       --licencedoc -o licence.but
     DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl ${CMAKE_CURRENT_SOURCE_DIR}/../LICENCE)
+  set(manual_dependencies ${manual_dependencies} copy_but licence_but)
 
   set(manual_sources
     ${CMAKE_CURRENT_BINARY_DIR}/copy.but
@@ -83,7 +90,7 @@ if(HALIBUT AND PERL_EXECUTABLE)
   add_custom_command(OUTPUT ${html_dir}/index.html
     COMMAND ${HALIBUT} --html ${manual_sources}
     WORKING_DIRECTORY ${html_dir}
-    DEPENDS ${manual_sources})
+    DEPENDS ${manual_sources} ${manual_dependencies})
   list(APPEND doc_outputs ${html_dir}/index.html)
 
   # Windows help.
@@ -92,14 +99,14 @@ if(HALIBUT AND PERL_EXECUTABLE)
   add_custom_command(OUTPUT putty.chm
     COMMAND ${HALIBUT} --chm chmextra.but ${manual_sources}
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-    DEPENDS ${manual_sources})
+    DEPENDS ${manual_sources} ${manual_dependencies})
   list(APPEND doc_outputs putty.chm)
 
   # Plain text.
   add_custom_command(OUTPUT puttydoc.txt
     COMMAND ${HALIBUT} --text ${manual_sources}
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-    DEPENDS ${manual_sources})
+    DEPENDS ${manual_sources} ${manual_dependencies})
   list(APPEND doc_outputs puttydoc.txt)
 endif()