nhyatt/putty-source
1
0
Fork 0
mirror of https://git.tartarus.org/simon/putty.git synced 2025-01-10 01:48:00 +00:00
Code Issues Projects Releases Wiki Activity
ebe2453446
putty-source/doc/CMakeLists.txt

191 lines
7.5 KiB
CMake
Raw Normal View History

Compatibility with older versions of cmake. After this change, the cmake setup now works even on Debian stretch (oldoldstable), which runs cmake 3.7. In order to support a version that early I had to: - write a fallback implementation of 'add_compile_definitions' for older cmakes, which is easy, because add_compile_definitions(FOO) is basically just add_compile_options(-DFOO) - stop using list(TRANSFORM) and string(JOIN), of which I had one case each, and they were easily replaced with simple foreach loops - stop putting OBJECT libraries in the target_link_libraries command for executable targets, in favour of adding $<TARGET_OBJECTS:foo> to the main sources list for the same target. That matches what I do with library targets, so it's probably more sensible anyway. I tried going back by another Debian release and getting this cmake setup to work on jessie, but that runs CMake 3.0.1, and in _that_ version of cmake the target_sources command is missing, and I didn't find any alternative way to add extra sources to a target after having first declared it. Reorganising to cope with _that_ omission would be too much upheaval without a very good reason.
2021-10-29 17:08:18 +00:00
cmake_minimum_required(VERSION 3.7)
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
project(putty-documentation LANGUAGES)
# This build script can be run standalone, or included as a
# subdirectory of the main PuTTY cmake build system. If the latter, a
# couple of things change: it has to set variables telling the rest of
# the build system what manpages are available to be installed, and it
# will change whether the 'make doc' target is included in 'make all'.
include(FindGit)
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.)
2021-05-02 14:34:57 +00:00
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).
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.
2022-01-22 14:42:03 +00:00
set(manual_dependencies) # extra target names to depend on
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.)
2021-05-02 14:34:57 +00:00
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}
-DOUTPUT_FILE=${INTERMEDIATE_VERSION_BUT}
-DOUTPUT_TYPE=halibut
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
-P ${CMAKE_CURRENT_SOURCE_DIR}/../cmake/gitcommit.cmake
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake/gitcommit.cmake
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/..
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.)
2021-05-02 14:34:57 +00:00
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")
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.
2022-01-22 14:42:03 +00:00
set(manual_dependencies ${manual_dependencies} cmake_version_but)
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.)
2021-05-02 14:34:57 +00:00
endif()
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.
2022-01-22 14:42:03 +00:00
add_custom_target(copy_but
BYPRODUCTS copy.but
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
COMMAND ${PERL_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl
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.)
2021-05-02 14:34:57 +00:00
--copyrightdoc -o copy.but
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl ${CMAKE_CURRENT_SOURCE_DIR}/../LICENCE)
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.
2022-01-22 14:42:03 +00:00
add_custom_target(licence_but
BYPRODUCTS licence.but
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
COMMAND ${PERL_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl
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.)
2021-05-02 14:34:57 +00:00
--licencedoc -o licence.but
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../licence.pl ${CMAKE_CURRENT_SOURCE_DIR}/../LICENCE)
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.
2022-01-22 14:42:03 +00:00
set(manual_dependencies ${manual_dependencies} copy_but licence_but)
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.)
2021-05-02 14:34:57 +00:00
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
New feature: k-i authentication helper plugins. In recent months I've had two requests from different people to build support into PuTTY for automatically handling complicated third-party auth protocols layered on top of keyboard-interactive - the kind of thing where you're asked to enter some auth response, and you have to refer to some external source like a web server to find out what the right response _is_, which is a pain to do by hand, so you'd prefer it to be automated in the SSH client. That seems like a reasonable thing for an end user to want, but I didn't think it was a good idea to build support for specific protocols of that kind directly into PuTTY, where there would no doubt be an ever-lengthening list, and maintenance needed on all of them. So instead, in collaboration with one of my correspondents, I've designed and implemented a protocol to be spoken between PuTTY and a plugin running as a subprocess. The plugin can opt to handle the keyboard-interactive authentication loop on behalf of the user, in which case PuTTY passes on all the INFO_REQUEST packets to it, and lets it make up responses. It can also ask questions of the user if necessary. The protocol spec is provided in a documentation appendix. The entire configuration for the end user consists of providing a full command line to use as the subprocess. In the contrib directory I've provided an example plugin written in Python. It gives a set of fixed responses suitable for getting through Uppity's made-up k-i system, because that was a reasonable thing I already had lying around to test against. But it also provides example code that someone else could pick up and insert their own live response-provider into the middle of, assuming they were happy with it being in Python.
2022-09-01 18:38:46 +00:00
${CMAKE_CURRENT_SOURCE_DIR}/authplugin.but
Add a docs appendix about privacy considerations. During the 0.81 release process, I found out that the Windows Store now requires applications to provide a privacy policy, so I had to write one in order to get 0.81 into the Store. This initially seemed like makework (especially having to do it in a hurry as a prerequisite to get a really important security fix distributed!). But after I started writing it, I found there was actually quite a lot to say. It's easy to think "PuTTY doesn't phone home to the developers, that's all, we're done". But of course it _does_ store information on your machine (host key cache, saved sessions, etc). And it does send information to servers on the network (only the ones you ask it to, but even so). And it's not 100% obvious in every case what is and isn't stored, and what a privacy- conscious individual might be revealing about themself by doing this or that thing. So I think the web page I hastily put up at the time of the 0.81 release deserves to be promoted into part of the documentation. Here's a (very lightly) copy-edited version in the form of a docs appendix. (Once this is committed and built, I expect I'll turn the privacy web page into a mirror of this docs appendix, in the same way as the website FAQ and feedback pages.)
2024-09-27 09:14:41 +00:00
${CMAKE_CURRENT_SOURCE_DIR}/privacy.but
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.)
2021-05-02 14:34:57 +00:00
${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}
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.
2022-01-22 14:42:03 +00:00
DEPENDS ${manual_sources} ${manual_dependencies})
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.)
2021-05-02 14:34:57 +00:00
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}
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.
2022-01-22 14:42:03 +00:00
DEPENDS ${manual_sources} ${manual_dependencies})
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.)
2021-05-02 14:34:57 +00:00
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}
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.
2022-01-22 14:42:03 +00:00
DEPENDS ${manual_sources} ${manual_dependencies})
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.)
2021-05-02 14:34:57 +00:00
list(APPEND doc_outputs puttydoc.txt)
Docs: add a 'pdf' cmake target. We still don't build or ship a PDF PuTTY manual by default, but we may as well conveniently expose Halibut's ability to do so. (I don't guarantee the resulting PDF is particularly pretty -- some of our overlong code lines do go off the right margin currently.)
2022-10-29 14:30:26 +00:00
# PDF. (We don't ship this; so it's only built on explicit request.)
add_custom_command(OUTPUT putty.pdf
COMMAND ${HALIBUT} --pdf ${manual_sources}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${manual_sources} ${manual_dependencies})
add_custom_target(pdf DEPENDS putty.pdf)
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.)
2021-05-02 14:34:57 +00:00
endif()
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
macro(register_manpage title section)
list(APPEND manpage_outputs ${title}.${section})
if(NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
# Only set this variable if there _is_ a parent scope.
set(HAVE_MANPAGE_${title}_${section} ON PARENT_SCOPE)
endif()
endmacro()
Fix cyclic dependency in docs build. If Halibut is not available to build the docs, but on the other hand pre-built man pages already exist (e.g. because you unpacked a source zip file with them already provided), then docs/CMakeLists.txt creates a set of build rules that copy the pre-built man pages from the source directory to the build directory. However, if the source and build directories are the _same_, this creates a set of cyclic dependencies, i.e. files which depend directly on themselves. Some build tools (in particular 'ninja') will report this as an error. In that situation, the simple fix is to leave off the build rules completely: if the man pages are already where the build will want them to end up, there need not be any build rule to do anything about them.
2022-09-01 18:33:44 +00:00
if(NOT HALIBUT)
# If we don't have Halibut available to rebuild the man pages from
# source, we must check whether the build and source directories
# correspond, so as to suppress the build rules that copy them from
# the source dir to the build dir. (Otherwise, someone unpacking
# putty-src.zip and building on a system without Halibut will find
# that there's a circular dependency in the makefile, which at least
# Ninja complains about.)
get_filename_component(DOCBUILDDIR ${CMAKE_CURRENT_BINARY_DIR} REALPATH)
get_filename_component(DOCSRCDIR ${CMAKE_CURRENT_SOURCE_DIR} REALPATH)
endif()
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.)
2021-05-02 14:34:57 +00:00
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)
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
register_manpage(${title} ${section})
Fix installing man pages from our tarballs. As of the cyclic-dependency fix in b01173c6b7, building from our tarball using the instructions in its README (using the source tree as build tree), in the absence of Halibut, would lead to the pre-built man pages not being installed. (Also, a load of "Could not build man page" complaints at cmake generation time, which is how I actually noticed.)
2022-10-19 18:44:14 +00:00
elseif(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${title}.${section})
# Our tarballs include prebuilt man pages in the source tree, so
# they can be installed from there even if Halibut isn't available.
if(NOT (DOCBUILDDIR STREQUAL DOCSRCDIR))
# Iff the build tree isn't the source tree, they'll need copying
# to the build tree first.
add_custom_command(OUTPUT ${title}.${section}
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${CMAKE_CURRENT_SOURCE_DIR}/${title}.${section} ${title}.${section}
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${title}.${section})
endif()
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
register_manpage(${title} ${section})
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.)
2021-05-02 14:34:57 +00:00
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)
Allow standalone cmake in the doc subdirectory. It's silly to require all the time-consuming cmake configuration for the source code, if all you want to do is to build the documentation. My own website update script will like this optimisation, and so will Buildscr. In order to make doc/CMakeLists.txt work standalone, I had to add a 'project' header (citing no languages, so that cmake won't even bother looking for a C compiler); include FindGit, which cmake/setup.cmake now won't be doing for it; change all references to CMAKE_SOURCE_DIR to CMAKE_CURRENT_SOURCE_DIR/.. (since now the former will be defined differently in a nested or standalone doc build); and spot whether we're nested or not in order to conditionalise things designed to interoperate with the parent CMakeLists.
2021-05-08 09:11:56 +00:00
add_custom_target(manpages ALL DEPENDS ${manpage_outputs})
add_custom_target(doc DEPENDS ${doc_outputs} manpages)
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
# If we're doing a cmake from just the doc subdir, we expect the
# user to want to make all the documentation, including HTML and so
# forth. (What else would be the point?)
#
# But if we're included from the main makefile, then by default we
# only make the man pages (which are necessary for 'make install'),
# and we leave everything else to a separate 'make doc' target which
# the user can invoke if they need to.
add_custom_target(doc-default ALL DEPENDS doc)
endif()
Reference in New Issue Copy Permalink