Utilities/Release: Pass pre-built docs tarball

Avoid requiring all build machines for the upstream packaging process to
have Python and Sphinx installed.  Instead create a way to build the
documentation once on the host machine and copy it to each build machine
as a tarball with content to include in the installation tree for
packaging.

Utilities/CMakeLists.txt

@@ -11,4 +11,25 @@
 #=============================================================================
 subdirs(Doxygen KWStyle)
 
+if(CMAKE_DOC_TARBALL)
+  # Undocumented option to extract and install pre-built documentation.
+  # This is intended for use during packaging of CMake itself.
+  if(CMAKE_DOC_TARBALL MATCHES "/([^/]+)\\.tar\\.gz$")
+    set(dir "${CMAKE_MATCH_1}")
+  else()
+    message(FATAL_ERROR "CMAKE_DOC_TARBALL must end in .tar.gz")
+  endif()
+  add_custom_command(
+    OUTPUT ${dir}.stamp
+    COMMAND cmake -E remove_directory ${dir}
+    COMMAND cmake -E tar xf ${CMAKE_DOC_TARBALL}
+    COMMAND cmake -E touch ${dir}.stamp
+    DEPENDS ${CMAKE_DOC_TARBALL}
+    )
+  add_custom_target(documentation ALL DEPENDS ${dir}.stamp)
+  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${dir}/
+          DESTINATION . USE_SOURCE_PERMISSIONS)
+else()
+  # Normal documentation build.
   add_subdirectory(Sphinx)
+endif()

Utilities/Release/create-cmake-release.cmake

@@ -28,7 +28,7 @@ function(write_batch_shell_script filename)
     math(EXPR y "160*(${i}%4)")
     file(APPEND ${filename}
     "
-\"${CMAKE_COMMAND}\" -DCMAKE_CREATE_VERSION=${CMAKE_CREATE_VERSION} -P \"${CMAKE_ROOT}/Utilities/Release/${f}\" < /dev/null >& \"${CMAKE_CURRENT_SOURCE_DIR}/logs/${f}-${CMAKE_CREATE_VERSION}.log\" &
+\"${CMAKE_COMMAND}\" -DCMAKE_CREATE_VERSION=${CMAKE_CREATE_VERSION} -DCMAKE_DOC_TARBALL=\"${CMAKE_DOC_TARBALL}\" -P \"${CMAKE_ROOT}/Utilities/Release/${f}\" < /dev/null >& \"${CMAKE_CURRENT_SOURCE_DIR}/logs/${f}-${CMAKE_CREATE_VERSION}.log\" &
 xterm -geometry 64x6+${x}+${y} -sb -sl 2000 -T ${f}-${CMAKE_CREATE_VERSION}.log -e tail -f \"${CMAKE_CURRENT_SOURCE_DIR}/logs/${f}-${CMAKE_CREATE_VERSION}.log\" &
 ")
     math(EXPR i "${i}+1")
@@ -36,7 +36,45 @@ xterm -geometry 64x6+${x}+${y} -sb -sl 2000 -T ${f}-${CMAKE_CREATE_VERSION}.log
   execute_process(COMMAND chmod a+x ${filename})
 endfunction()
 
+function(write_docs_shell_script filename)
+  find_program(SPHINX_EXECUTABLE
+    NAMES sphinx-build sphinx-build.py
+    DOC "Sphinx Documentation Builder (sphinx-doc.org)"
+    )
+  if(NOT SPHINX_EXECUTABLE)
+    message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
+  endif()
+
+  set(name cmake-${CMAKE_CREATE_VERSION}-docs)
+  file(WRITE "${filename}" "#!/usr/bin/env bash
+
+name=${name} &&
+inst=\"\$PWD/\$name\"
+(GIT_WORK_TREE=x git archive --prefix=\${name}-src/ ${CMAKE_CREATE_VERSION}) | tar x &&
+rm -rf \${name}-build &&
+mkdir \${name}-build &&
+cd \${name}-build &&
+\"${CMAKE_COMMAND}\" ../\${name}-src/Utilities/Sphinx \\
+  -DCMAKE_INSTALL_PREFIX=\"\$inst/\" \\
+  -DSPHINX_EXECUTABLE=\"${SPHINX_EXECUTABLE}\" \\
+  -DSPHINX_HTML=ON -DSPHINX_MAN=ON &&
+make install &&
+cd .. &&
+tar czf \${name}.tar.gz \${name} ||
+echo 'Failed to create \${name}.tar.gz'
+")
+  execute_process(COMMAND chmod a+x ${filename})
+  set(CMAKE_DOC_TARBALL "${name}.tar.gz" PARENT_SCOPE)
+endfunction()
+
+write_docs_shell_script("create-${CMAKE_CREATE_VERSION}-docs.sh")
 write_batch_shell_script("create-${CMAKE_CREATE_VERSION}-batch1.sh" ${RELEASE_SCRIPTS_BATCH_1})
+unset(CMAKE_DOC_TARBALL) # No pre-built docs in second batch.
 write_batch_shell_script("create-${CMAKE_CREATE_VERSION}-batch2.sh" ${RELEASE_SCRIPTS_BATCH_2})
 
-message("Run ./create-${CMAKE_CREATE_VERSION}-batch1.sh, then after all those builds complete, run ./create-${CMAKE_CREATE_VERSION}-batch2.sh")
+message("Run one at a time:
+ ./create-${CMAKE_CREATE_VERSION}-docs.sh   &&
+ ./create-${CMAKE_CREATE_VERSION}-batch1.sh &&
+ ./create-${CMAKE_CREATE_VERSION}-batch2.sh &&
+ echo done
+")

Utilities/Release/release_cmake.cmake

@@ -66,6 +66,17 @@ macro(remote_command comment command)
   endif()
 endmacro()
 
+if(CMAKE_DOC_TARBALL)
+  message("scp '${CMAKE_DOC_TARBALL}' '${HOST}:'")
+  execute_process(COMMAND
+    scp ${CMAKE_DOC_TARBALL} ${HOST}:
+    RESULT_VARIABLE result)
+  if(${result} GREATER 0)
+    message("error sending doc tarball with scp '${CMAKE_DOC_TARBALL}' '${HOST}:'")
+  endif()
+  get_filename_component(CMAKE_DOC_TARBALL_NAME "${CMAKE_DOC_TARBALL}" NAME)
+endif()
+
 # set this so configure file will work from script mode
 # create the script specific for the given host
 set(SCRIPT_FILE release_cmake-${SCRIPT_NAME}.sh)

Utilities/Release/release_cmake.sh.in

@@ -15,6 +15,13 @@ check_exit_value()
    fi
 }
 
+CMAKE_DOC_TARBALL=""
+if [ ! -z "@CMAKE_DOC_TARBALL_NAME@" ] ; then
+    CMAKE_DOC_TARBALL=@CMAKE_RELEASE_DIRECTORY@/@CMAKE_DOC_TARBALL_NAME@
+    mv "$HOME/@CMAKE_DOC_TARBALL_NAME@" "$CMAKE_DOC_TARBALL"
+    check_exit_value $? "mv doc tarball" || exit 1
+fi
+
 if [ ! -z "@CC@" ]; then
     export CC="@CC@"
     check_exit_value $? "set CC compiler env var" || exit 1
@@ -76,6 +83,11 @@ if [ ! -z "@USER_OVERRIDE@" ]; then
   echo "CMAKE_USER_MAKE_RULES_OVERRIDE:FILEPATH=@CMAKE_RELEASE_DIRECTORY@/@CMAKE_CREATE_VERSION@-build/user.txt" >> @CMAKE_RELEASE_DIRECTORY@/@CMAKE_CREATE_VERSION@-build/CMakeCache.txt
 fi
 
+# Point build at pre-built documentation tarball, if any.
+if [ ! -z "$CMAKE_DOC_TARBALL" ]; then
+  echo "CMAKE_DOC_TARBALL:FILEPATH=$CMAKE_DOC_TARBALL" >> @CMAKE_RELEASE_DIRECTORY@/@CMAKE_CREATE_VERSION@-build/CMakeCache.txt
+fi
+
 echo "Checkout the source for @CMAKE_CREATE_VERSION@"
 cd @CMAKE_RELEASE_DIRECTORY@
 if [ ! -z "@GIT_COMMAND@" ]; then