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

157 lines
5.9 KiB
CMake
Raw Normal View History

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
cmake_minimum_required(VERSION 3.12)
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).
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")
endif()
add_custom_command(OUTPUT 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)
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
add_custom_command(OUTPUT 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)
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
${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()
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()
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})
Add the man pages to the 'make install' target. doc/CMakeLists.txt now sets a variable indicating that we either have, or can build, each individual man page. And when we call our installed_program() function to mark a program as official enough to put in 'make install', that function also installs the man page similarly if it exists, and warns if not. For the convenience of people building-and-installing from the .tar.gz we ship, I've arranged that they can still get the man pages installed without needing Halibut: the previous commit ensured that the prebuilt man pages are still in the tarball, and this one arranges that if we don't have Halibut but we do have prebuilt man pages, then we can 'build' them by copying from the prebuilt versions.
2021-05-03 15:25:21 +00:00
elseif(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${title}.${section})
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})
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