1
0
mirror of https://git.tartarus.org/simon/putty.git synced 2025-03-28 09:17:07 -05:00

Integrate the 'doc' subdir into the CMake system.

The standalone separate doc/Makefile is gone, replaced by a
CMakeLists.txt that makes 'doc' function as a subdirectory of the main
CMake build system. This auto-detects Halibut, and if it's present,
uses it to build the man pages and the various forms of the main
manual, including the Windows CHM help file in particular.

One awkward thing I had to do was to move just one config directive in
blurb.but into its own file: the one that cites a relative path to the
stylesheet file to put into the CHM. CMake builds often like to be
out-of-tree, so there's no longer a fixed relative path between the
build directory and chm.css. And Halibut has no concept of an include
path to search for files cited by other files, so I can't fix that
with an -I option on the Halibut command line. So I moved that single
config directive into its own file, and had CMake write out a custom
version of that file in the build directory citing the right path.

(Perhaps in the longer term I should fix that omission in Halibut;
out-of-tree friendliness seems like a useful feature. But even if I
do, I still need this build to work now.)
This commit is contained in:
Simon Tatham 2021-05-02 15:34:57 +01:00
parent f60853ec66
commit 31f496b59c
8 changed files with 166 additions and 112 deletions

View File

@ -55,7 +55,7 @@ ifneq "$(SNAPSHOT)" "" set Puttytextver PuTTY development snapshot $(Date).$(vcs
ifneq "$(SNAPSHOT)" "" set Textver Development snapshot $(Date).$(vcsid)
ifeq "$(RELEASE)$(PRERELEASE)$(SNAPSHOT)" "" set Puttytextver PuTTY custom build $(Date).$(vcsid)
ifeq "$(RELEASE)$(PRERELEASE)$(SNAPSHOT)" "" set Textver Custom build $(Date).$(vcsid)
set Docmakever VERSION="$(Puttytextver)"
in putty/doc do echo "\\versionid $(Puttytextver)" > version.but
# Set up the version string for use in the SSH connection greeting.
#
@ -122,9 +122,13 @@ in putty do echo '$#define BINARY_VERSION $(Winvercommas)' >> version.h
# the source archive will still get a useful value.
in putty do sed -i '/set(DEFAULT_COMMIT/s/unavailable/$(vcsfullid)/' cmake/gitcommit.cmake
in . do mkdir docbuild
in docbuild do cmake ../putty
in docbuild do make -j$(nproc) VERBOSE=1 doc
in putty/doc do cp ../../docbuild/doc/*.1 .
in putty do ./mksrcarc.sh
in putty do ./mkunxarc.sh '$(Uxarcsuffix)' $(Docmakever)
in putty/doc do make $(Docmakever) putty.chm -j$(nproc)
in putty do ./mkunxarc.sh '$(Uxarcsuffix)'
delegate -
# Run the test suite, under self-delegation so that we don't leave any
@ -194,10 +198,10 @@ ifneq "$(cross_winsigncode)" "" in putty/windows do $(cross_winsigncode) -N -i h
in putty do for hash in md5 sha1 sha256 sha512; do for dir_plat in "build32 w32" "build64 w64" "abuild32 wa32" "abuild64 wa64"; do set -- $$dir_plat; (cd windows/$$1 && $${hash}sum *.exe | sed 's!\( \+\)!\1'$$2'/!;s!$$! (installer version)!') >> $${hash}sums.installer; done; done
# Build a WiX MSI installer, for each build flavour.
in putty/windows with wixonlinux do candle -arch x86 -dRealPlatform=x86 -dDllOk=yes -dBuilddir=build32/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installer32.msi -spdb
in putty/windows with wixonlinux do candle -arch x64 -dRealPlatform=x64 -dDllOk=yes -dBuilddir=build64/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installer64.msi -spdb
in putty/windows with wixonlinux do candle -arch x64 -dRealPlatform=Arm -dDllOk=no -dBuilddir=abuild32/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installera32.msi -spdb
in putty/windows with wixonlinux do candle -arch x64 -dRealPlatform=Arm64 -dDllOk=no -dBuilddir=abuild64/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installera64.msi -spdb
in putty/windows with wixonlinux do candle -arch x86 -dRealPlatform=x86 -dDllOk=yes -dBuilddir=build32/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" -dHelpFilePath="../../docbuild/doc/putty.chm" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installer32.msi -spdb
in putty/windows with wixonlinux do candle -arch x64 -dRealPlatform=x64 -dDllOk=yes -dBuilddir=build64/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" -dHelpFilePath="../../docbuild/doc/putty.chm" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installer64.msi -spdb
in putty/windows with wixonlinux do candle -arch x64 -dRealPlatform=Arm -dDllOk=no -dBuilddir=abuild32/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" -dHelpFilePath="../../docbuild/doc/putty.chm" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installera32.msi -spdb
in putty/windows with wixonlinux do candle -arch x64 -dRealPlatform=Arm64 -dDllOk=no -dBuilddir=abuild64/ -dWinver="$(Winver)" -dPuttytextver="$(Puttytextver)" -dHelpFilePath="../../docbuild/doc/putty.chm" installer.wxs && light -ext WixUIExtension -ext WixUtilExtension -sval installer.wixobj -o installera64.msi -spdb
# Change the width field for our dialog background image so that it
# doesn't stretch across the whole dialog. (WiX's default one does; we
@ -219,13 +223,13 @@ ifneq "$(cross_winsigncode)" "" in putty/windows do $(cross_winsigncode) -i http
# Build the standalone binaries, in both 32- and 64-bit flavours.
# These differ from the previous set in that they embed the help file.
in putty/windows/build32 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../doc/putty.chm)
in putty/windows/build32 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../../docbuild/doc/putty.chm)
in putty/windows/build32 with cmake_at_least_3.20 do make -j$(nproc) VERBOSE=1
in putty/windows/build64 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../doc/putty.chm)
in putty/windows/build64 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../../docbuild/doc/putty.chm)
in putty/windows/build64 with cmake_at_least_3.20 do make -j$(nproc) VERBOSE=1
in putty/windows/abuild32 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../doc/putty.chm)
in putty/windows/abuild32 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../../docbuild/doc/putty.chm)
in putty/windows/abuild32 with cmake_at_least_3.20 do make -j$(nproc) VERBOSE=1
in putty/windows/abuild64 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../doc/putty.chm)
in putty/windows/abuild64 with cmake_at_least_3.20 do cmake . -DPUTTY_EMBEDDED_CHM_FILE=$$(realpath ../../../docbuild/doc/putty.chm)
in putty/windows/abuild64 with cmake_at_least_3.20 do make -j$(nproc) VERBOSE=1
# Build the 'old' binaries, which should still run on all 32-bit
@ -253,14 +257,12 @@ in putty/windows do mkdir deliver
in putty/windows do for subdir in build32 abuild32 build64 abuild64 buildold; do mkdir deliver/$$subdir; done
in putty/windows do while read x; do mv $$x deliver/$$x; mv $$x.map deliver/$$x.map; done < to-sign.txt
in putty/doc do make mostlyclean
in putty/doc do make $(Docmakever) -j$(nproc)
in putty/windows/deliver/buildold do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../doc/putty.chm
in putty/windows/deliver/build32 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../doc/putty.chm
in putty/windows/deliver/build64 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../doc/putty.chm
in putty/windows/deliver/abuild32 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../doc/putty.chm
in putty/windows/deliver/abuild64 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../doc/putty.chm
in putty/doc do zip puttydoc.zip *.html
in putty/windows/deliver/buildold do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../../docbuild/doc/putty.chm
in putty/windows/deliver/build32 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../../docbuild/doc/putty.chm
in putty/windows/deliver/build64 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../../docbuild/doc/putty.chm
in putty/windows/deliver/abuild32 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../../docbuild/doc/putty.chm
in putty/windows/deliver/abuild64 do zip -k -j putty.zip `ls *.exe | grep -v puttytel` ../../../docbuild/doc/putty.chm
in docbuild/doc/html do zip puttydoc.zip *.html
# Deliver the actual PuTTY release directory into a subdir `putty'.
deliver putty/windows/deliver/buildold/*.exe putty/w32old/$@
@ -277,10 +279,10 @@ deliver putty/windows/deliver/abuild32/*.exe putty/wa32/$@
deliver putty/windows/deliver/abuild32/putty.zip putty/wa32/$@
deliver putty/windows/deliver/abuild64/*.exe putty/wa64/$@
deliver putty/windows/deliver/abuild64/putty.zip putty/wa64/$@
deliver putty/doc/puttydoc.zip putty/$@
deliver putty/doc/putty.chm putty/$@
deliver putty/doc/puttydoc.txt putty/$@
deliver putty/doc/*.html putty/htmldoc/$@
deliver docbuild/doc/html/puttydoc.zip putty/$@
deliver docbuild/doc/putty.chm putty/$@
deliver docbuild/doc/puttydoc.txt putty/$@
deliver docbuild/doc/html/*.html putty/htmldoc/$@
deliver putty/putty-src.zip putty/$@
deliver putty/*.tar.gz putty/$@

View File

@ -3,6 +3,8 @@ project(putty LANGUAGES C)
include(cmake/setup.cmake)
add_subdirectory(doc)
add_compile_definitions(HAVE_CMAKE_H)
add_library(utils STATIC

View File

@ -47,6 +47,16 @@ if(OUTPUT_TYPE STREQUAL header)
const char commitid[] = \"${commit}\";
")
elseif(OUTPUT_TYPE STREQUAL halibut)
if(commit STREQUAL "unavailable")
file(WRITE "${OUTPUT_FILE}" "\
\\versionid no version information available
")
else()
file(WRITE "${OUTPUT_FILE}" "\
\\versionid built from git commit ${commit}
")
endif()
else()
message(FATAL_ERROR "Set OUTPUT_TYPE when running this script")
endif()

123
doc/CMakeLists.txt Normal file
View File

@ -0,0 +1,123 @@
include(FindPerl)
find_program(HALIBUT halibut)
set(doc_outputs)
set(manpage_outputs)
if(HALIBUT AND PERL_EXECUTABLE)
# Build the main manual, which requires not only Halibut, but also
# Perl to run licence.pl to generate the copyright and licence
# sections from the master data outside this directory.
# 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).
if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/version.but)
set(VERSION_BUT ${CMAKE_CURRENT_SOURCE_DIR}/version.but)
else()
set(VERSION_BUT ${CMAKE_CURRENT_BINARY_DIR}/cmake_version.but)
set(INTERMEDIATE_VERSION_BUT ${VERSION_BUT}.tmp)
add_custom_target(check_git_commit_for_doc
BYPRODUCTS ${INTERMEDIATE_VERSION_BUT}
COMMAND ${CMAKE_COMMAND}
-DGIT_EXECUTABLE=${GIT_EXECUTABLE}
-DTOPLEVEL_SOURCE_DIR=${CMAKE_SOURCE_DIR}
-DOUTPUT_FILE=${INTERMEDIATE_VERSION_BUT}
-DOUTPUT_TYPE=halibut
-P ${CMAKE_SOURCE_DIR}/cmake/gitcommit.cmake
DEPENDS ${CMAKE_SOURCE_DIR}/cmake/gitcommit.cmake
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
COMMENT "Checking current git commit")
add_custom_target(cmake_version_but
BYPRODUCTS ${VERSION_BUT}
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${INTERMEDIATE_VERSION_BUT} ${VERSION_BUT}
DEPENDS check_git_commit_for_doc ${INTERMEDIATE_VERSION_BUT}
COMMENT "Updating cmake_version.but")
endif()
add_custom_command(OUTPUT copy.but
COMMAND ${PERL_EXECUTABLE} ${CMAKE_SOURCE_DIR}/licence.pl
--copyrightdoc -o copy.but
DEPENDS ${CMAKE_SOURCE_DIR}/licence.pl ${CMAKE_SOURCE_DIR}/LICENCE)
add_custom_command(OUTPUT licence.but
COMMAND ${PERL_EXECUTABLE} ${CMAKE_SOURCE_DIR}/licence.pl
--licencedoc -o licence.but
DEPENDS ${CMAKE_SOURCE_DIR}/licence.pl ${CMAKE_SOURCE_DIR}/LICENCE)
set(manual_sources
${CMAKE_CURRENT_BINARY_DIR}/copy.but
${CMAKE_CURRENT_SOURCE_DIR}/blurb.but
${CMAKE_CURRENT_SOURCE_DIR}/intro.but
${CMAKE_CURRENT_SOURCE_DIR}/gs.but
${CMAKE_CURRENT_SOURCE_DIR}/using.but
${CMAKE_CURRENT_SOURCE_DIR}/config.but
${CMAKE_CURRENT_SOURCE_DIR}/pscp.but
${CMAKE_CURRENT_SOURCE_DIR}/psftp.but
${CMAKE_CURRENT_SOURCE_DIR}/plink.but
${CMAKE_CURRENT_SOURCE_DIR}/pubkey.but
${CMAKE_CURRENT_SOURCE_DIR}/pageant.but
${CMAKE_CURRENT_SOURCE_DIR}/errors.but
${CMAKE_CURRENT_SOURCE_DIR}/faq.but
${CMAKE_CURRENT_SOURCE_DIR}/feedback.but
${CMAKE_CURRENT_SOURCE_DIR}/pubkeyfmt.but
${CMAKE_CURRENT_BINARY_DIR}/licence.but
${CMAKE_CURRENT_SOURCE_DIR}/udp.but
${CMAKE_CURRENT_SOURCE_DIR}/pgpkeys.but
${CMAKE_CURRENT_SOURCE_DIR}/sshnames.but
${CMAKE_CURRENT_SOURCE_DIR}/index.but
${VERSION_BUT})
# The HTML manual goes in a subdirectory, for convenience.
set(html_dir ${CMAKE_CURRENT_BINARY_DIR}/html)
file(MAKE_DIRECTORY ${html_dir})
add_custom_command(OUTPUT ${html_dir}/index.html
COMMAND ${HALIBUT} --html ${manual_sources}
WORKING_DIRECTORY ${html_dir}
DEPENDS ${manual_sources})
list(APPEND doc_outputs ${html_dir}/index.html)
# Windows help.
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/chmextra.but
"\\cfg{chm-extra-file}{${CMAKE_CURRENT_SOURCE_DIR}/chm.css}{chm.css}\n")
add_custom_command(OUTPUT putty.chm
COMMAND ${HALIBUT} --chm chmextra.but ${manual_sources}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${manual_sources})
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})
list(APPEND doc_outputs puttydoc.txt)
endif()
macro(manpage title section)
if(HALIBUT)
add_custom_command(OUTPUT ${title}.${section}
COMMAND ${HALIBUT} --man=${title}.${section}
${CMAKE_CURRENT_SOURCE_DIR}/mancfg.but
${CMAKE_CURRENT_SOURCE_DIR}/man-${title}.but
DEPENDS
mancfg.but man-${title}.but)
list(APPEND manpage_outputs ${title}.${section})
endif()
endmacro()
manpage(putty 1)
manpage(puttygen 1)
manpage(plink 1)
manpage(pscp 1)
manpage(psftp 1)
manpage(puttytel 1)
manpage(pterm 1)
manpage(pageant 1)
manpage(psocks 1)
manpage(psusan 1)
add_custom_target(manpages ALL
DEPENDS ${manpage_outputs})
add_custom_target(doc
DEPENDS ${doc_outputs} manpages)

View File

@ -1,85 +0,0 @@
all: man index.html
# Decide on the versionid policy.
#
# If the user has passed in $(VERSION) on the command line (`make
# VERSION="Release 0.56"'), we use that as an explicit version string.
# Otherwise, we use `svnversion' to examine the checked-out
# documentation source, and if that returns a single revision number
# then we invent a version string reflecting just that number. Failing
# _that_, we resort to versionids.but which gives 'version
# unavailable'.
#
# So here, we define VERSION using svnversion if it isn't already
# defined ...
ifndef VERSION
SVNVERSION=$(shell test -d .svn && svnversion .)
BADCHARS=$(findstring :,$(SVNVERSION))$(findstring S,$(SVNVERSION))
ifeq ($(BADCHARS),)
ifneq ($(SVNVERSION),)
ifneq ($(SVNVERSION),exported)
VERSION=Built from revision $(patsubst M,,$(SVNVERSION))
endif
endif
endif
endif
# ... and now, we condition our build behaviour on whether or not
# VERSION _is_ defined.
ifdef VERSION
VERSIONIDS=vstr
vstr.but: FORCE
printf '\\versionid $(VERSION)\n' > vstr.but
FORCE:;
else
VERSIONIDS=vids
endif
CHAPTERS := $(SITE) copy blurb intro gs using config pscp psftp plink
CHAPTERS += pubkey pageant errors faq feedback pubkeyfmt licence udp
CHAPTERS += pgpkeys sshnames
CHAPTERS += index $(VERSIONIDS)
INPUTS = $(patsubst %,%.but,$(CHAPTERS))
# This is temporary. Hack it locally or something.
HALIBUT = halibut
index.html: $(INPUTS)
$(HALIBUT) --text --html --chm $(INPUTS)
# During formal builds it's useful to be able to build this one alone.
putty.chm: $(INPUTS)
$(HALIBUT) --chm $(INPUTS)
# We don't ship this any more.
putty.hlp: $(INPUTS)
$(HALIBUT) --winhelp $(INPUTS)
putty.info: $(INPUTS)
$(HALIBUT) --info $(INPUTS)
licence.but: ../licence.pl ../LICENCE
perl $< --licencedoc -o $@
copy.but: ../licence.pl ../LICENCE
perl $< --copyrightdoc -o $@
MKMAN = $(HALIBUT) --man=$@ mancfg.but $<
MANPAGES = putty.1 puttygen.1 plink.1 pscp.1 psftp.1 puttytel.1 pterm.1 \
pageant.1 psocks.1 psusan.1
man: $(MANPAGES)
putty.1: man-putty.but mancfg.but; $(MKMAN)
puttygen.1: man-puttygen.but mancfg.but; $(MKMAN)
plink.1: man-plink.but mancfg.but; $(MKMAN)
pscp.1: man-pscp.but mancfg.but; $(MKMAN)
psftp.1: man-psftp.but mancfg.but; $(MKMAN)
puttytel.1: man-puttytel.but mancfg.but; $(MKMAN)
pterm.1: man-pterm.but mancfg.but; $(MKMAN)
pageant.1: man-pageant.but mancfg.but; $(MKMAN)
psocks.1: man-psocks.but mancfg.but; $(MKMAN)
psusan.1: man-psusan.but mancfg.but; $(MKMAN)
mostlyclean:
rm -f *.html *.txt *.hlp *.cnt *.1 *.info vstr.but *.hh[pck]
clean: mostlyclean
rm -f *.chm

View File

@ -17,7 +17,6 @@ page</a>.</p>}
\cfg{chm-contents-filename}{index.html}
\cfg{chm-template-filename}{%k.html}
\cfg{chm-head-end}{<link rel="stylesheet" type="text/css" href="chm.css">}
\cfg{chm-extra-file}{chm.css}
\cfg{xhtml-contents-filename}{index.html}
\cfg{text-filename}{puttydoc.txt}

6
doc/chmextra.but Normal file
View File

@ -0,0 +1,6 @@
\# If you want to do a Halibut build of the CHM file by hand, without
\# the help of the CMake edifice, then include this file which will
\# refer to chm.css. The CMake edifice builds its own with a different
\# pathname in it, for the sake of out-of-tree builds.
\cfg{chm-extra-file}{chm.css}

View File

@ -7,9 +7,6 @@
# - the options to put on the 'make' command line for the docs
arcsuffix="$1"
docver="$2"
(cd doc && make -s ${docver:+"$docver"})
relver=`cat LATEST.VER`
arcname="putty$arcsuffix"