frameworks/kdoctools/KF5DocToolsMacros.cmake

0001 # SPDX-FileCopyrightText: 2006-2009 Alexander Neundorf <neundorf@kde.org>
0002 # SPDX-FileCopyrightText: 2006, 2007 Laurent Montel <montel@kde.org>
0003 # SPDX-FileCopyrightText: 2007 Matthias Kretz <kretz@kde.org>
0004 #
0005 # SPDX-License-Identifier: BSD-3-Clause
0006 #
0007 #  KDOCTOOLS_CREATE_HANDBOOK( docbookfile [INSTALL_DESTINATION installdest] [SUBDIR subdir])
0008 #   Create the handbook from the docbookfile (using meinproc5)
0009 #   The resulting handbook will be installed to <installdest> when using
0010 #   INSTALL_DESTINATION <installdest>, or to <installdest>/<subdir> if
0011 #   SUBDIR <subdir> is specified.
0012 #
0013 #  KDOCTOOLS_CREATE_MANPAGE( docbookfile section [INSTALL_DESTINATION installdest])
0014 #   Create the manpage for the specified section from the docbookfile (using meinproc5)
0015 #   The resulting manpage will be installed to <installdest> when using
0016 #   INSTALL_DESTINATION <installdest>.
0017 #
0018 #  KDOCTOOLS_INSTALL(podir)
0019 #   Search for docbook files in <podir> and install them to the standard
0020 #   location.
0021 #   This is a convenience function which relies on all docbooks being kept in
0022 #   <podir>/<lang>/docs/<project>, where <lang> is the language the docbooks
0023 #   for <project> are written in.
0024 #
0025 #   Within this directory, files ending with .[0-9].docbook are installed using
0026 #   KDOCTOOLS_CREATE_MANPAGE, other .docbook files are installed using
0027 #   KDOCTOOLS_CREATE_HANDBOOK if index.docbook is available.
0028 #
0029 #   For example, given the following directory structure:
0030 #
0031 #    po/
0032 #      fr/
0033 #        docs/
0034 #          foo/
0035 #            kioslave5/
0036 #              fooslave/
0037 #                index.docbook
0038 #            footool.1.docbook
0039 #            footool.conf.5.docbook
0040 #            index.docbook
0041 #
0042 #   KDOCTOOLS_INSTALL(po) does the following:
0043 #   - Create man pages from footool.1.docbook and footool.conf.5.docbook,
0044 #     install them in ${KDE_INSTALL_MANDIR}/fr
0045 #   - Create handbooks from index.docbook files, install the one from the
0046 #     fooslave/ directory in ${KDE_INSTALL_DOCBUNDLEDIR}/fr/kioslave5/fooslave
0047 #     and the one from the docs/ directory in ${KDE_INSTALL_DOCBUNDLEDIR}/fr
0048 #
0049 #   If ${KDE_INSTALL_DOCBUNDLEDIR} is not set, share/doc/HTML is used instead.
0050 #   If ${KDE_INSTALL_MANDIR} is not set, share/man/<lang> is used instead.
0051 #
0052 #  KDOCTOOLS_MEINPROC_EXECUTABLE - the meinproc5 executable
0053 #
0054 #  KDOCTOOLS_SERIALIZE_TOOL - wrapper to serialize potentially resource-intensive commands during
0055 #                      parallel builds (set to 'icecc' when using icecream)
0056 #
0057 # The following variables are defined for the various tools required to
0058 # compile KDE software:
0059 #
0060 #  KDOCTOOLS_MEINPROC_EXECUTABLE - the meinproc5 executable
0061 #
0062
0063 set(KDOCTOOLS_SERIALIZE_TOOL "" CACHE STRING "Tool to serialize resource-intensive commands in parallel builds")
0064 set(KDOCTOOLS_MEINPROC_EXECUTABLE "KF5::meinproc5")
0065
0066 if(KDOCTOOLS_SERIALIZE_TOOL)
0067     # parallel build with many meinproc invocations can consume a huge amount of memory
0068     set(KDOCTOOLS_MEINPROC_EXECUTABLE ${KDOCTOOLS_SERIALIZE_TOOL} ${KDOCTOOLS_MEINPROC_EXECUTABLE})
0069 endif(KDOCTOOLS_SERIALIZE_TOOL)
0070
0071 function(_kdoctools_create_target_name out in)
0072     file(RELATIVE_PATH in "${CMAKE_BINARY_DIR}" "${in}")
0073     string(REGEX REPLACE "[^0-9a-zA-Z]+" "-" tmp "${in}")
0074     set(${out} ${tmp} PARENT_SCOPE)
0075 endfunction()
0076
0077 function (kdoctools_create_handbook docbook)
0078     # Parse arguments
0079     set(options)
0080     set(oneValueArgs INSTALL_DESTINATION SUBDIR)
0081     set(multiValueArgs)
0082     cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
0083
0084     if(NOT DEFINED ARGS_SUBDIR)
0085         message(FATAL_ERROR "SUBDIR needs to be defined when calling kdoctools_create_handbook")
0086     endif()
0087
0088     # Init vars
0089     get_filename_component(docbook ${docbook} ABSOLUTE)
0090     file(RELATIVE_PATH src_doc ${CMAKE_CURRENT_SOURCE_DIR} ${docbook})
0091     get_filename_component(src_dir ${src_doc} DIRECTORY)
0092     set(build_dir ${CMAKE_CURRENT_BINARY_DIR}/${src_dir})
0093     set(build_doc ${build_dir}/index.cache.bz2)
0094     set(build_html ${build_dir}/index.html)
0095
0096     # current directory is the docbook directory, but if this is empty, the
0097     # globs which finds the docbooks and the images will be empty too as
0098     # they will expand into "/*.docbook" and "/*.png"
0099     if (NOT src_dir)
0100         set(src_dir ".")
0101     endif ()
0102
0103     # Create some place to store our files
0104     file(MAKE_DIRECTORY ${build_dir})
0105
0106     #Bootstrap
0107     if (_kdoctoolsBootStrapping OR _kdoctoolsTestsRunning)
0108         set(_bootstrapOption "--srcdir=${KDocTools_BINARY_DIR}/src")
0109     elseif (CMAKE_CROSSCOMPILING AND CMAKE_SYSTEM_NAME STREQUAL "Windows")
0110         set(_bootstrapOption "--srcdir=${KDOCTOOLS_DATA_INSTALL_DIR}/kdoctools")
0111     else ()
0112         set(_bootstrapOption)
0113     endif ()
0114     set(_ssheet "${KDOCTOOLS_CUSTOMIZATION_DIR}/kde-chunk.xsl")
0115
0116     file(GLOB candidate_src_docs ${src_dir}/*.docbook)
0117
0118     set(src_docs)
0119     foreach (src_single_doc ${candidate_src_docs})
0120         # Exclude manpages
0121         get_filename_component(src_single_doc_name ${src_single_doc} NAME)
0122         if (NOT src_single_doc_name MATCHES "^man-.+\\.docbook$")
0123             list(APPEND src_docs ${src_single_doc})
0124         endif()
0125     endforeach()
0126
0127     add_custom_command(OUTPUT ${build_doc}
0128         COMMAND ${KDOCTOOLS_MEINPROC_EXECUTABLE} --check ${_bootstrapOption} --cache ${build_doc} ${src_doc}
0129         DEPENDS ${src_docs} ${_ssheet}
0130         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
0131     )
0132
0133     _kdoctools_create_target_name(_targ ${build_doc})
0134     add_custom_target(${_targ} ALL DEPENDS ${build_doc})
0135
0136     if(KDOCTOOLS_ENABLE_HTMLHANDBOOK)
0137         add_custom_command(OUTPUT ${build_html}
0138             COMMAND ${KDOCTOOLS_MEINPROC_EXECUTABLE} --check ${_bootstrapOption} -o ${build_html} ${src_doc}
0139             DEPENDS ${src_doc} ${_ssheet}
0140             WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
0141         )
0142
0143         _kdoctools_create_target_name(_targ_html ${build_html})
0144         add_custom_target(${_targ_html} ALL DEPENDS ${build_html})
0145     endif(KDOCTOOLS_ENABLE_HTMLHANDBOOK)
0146
0147     set(installDest "${ARGS_INSTALL_DESTINATION}")
0148     if(installDest)
0149         set(subdir "${ARGS_SUBDIR}")
0150         file(GLOB images ${src_dir}/*.png)
0151         install(FILES ${build_doc} ${src_docs} ${images} DESTINATION ${installDest}/${subdir})
0152         if(KDOCTOOLS_ENABLE_HTMLHANDBOOK)
0153             install(FILES ${build_html} DESTINATION ${installDest}/${subdir})
0154         endif(KDOCTOOLS_ENABLE_HTMLHANDBOOK)
0155     endif()
0156
0157 endfunction()
0158
0159
0160 function (kdoctools_create_manpage docbook section)
0161     # Parse arguments
0162     set(options)
0163     set(oneValueArgs INSTALL_DESTINATION)
0164     set(multiValueArgs)
0165     cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
0166
0167     # Init vars
0168     get_filename_component(docbook ${docbook} ABSOLUTE)
0169     file(RELATIVE_PATH src_doc ${CMAKE_CURRENT_SOURCE_DIR} ${docbook})
0170     get_filename_component(src_dir ${src_doc} DIRECTORY)
0171     set(build_dir ${CMAKE_CURRENT_BINARY_DIR}/${src_dir})
0172
0173     get_filename_component(name ${src_doc} NAME)
0174     string(REGEX REPLACE "^man-(.*)\\.${section}\\.docbook$" "\\1" name ${name})
0175     set(build_doc ${build_dir}/${name}.${section})
0176
0177     # Create some place to store our files
0178     file(MAKE_DIRECTORY ${build_dir})
0179
0180     #Bootstrap
0181     if (_kdoctoolsBootStrapping)
0182         set(_bootstrapOption "--srcdir=${KDocTools_BINARY_DIR}/src")
0183         set(_extraDependency "docbookl10nhelper")
0184     elseif (_kdoctoolsTestsRunning)
0185         set(_bootstrapOption "--srcdir=${KDocTools_BINARY_DIR}/src")
0186         set(_extraDependency)
0187     elseif (CMAKE_CROSSCOMPILING AND CMAKE_SYSTEM_NAME STREQUAL "Windows")
0188         set(_bootstrapOption "--srcdir=${KDOCTOOLS_DATA_INSTALL_DIR}/kdoctools")
0189         set(_extraDependency)
0190     else ()
0191         set(_bootstrapOption)
0192         set(_extraDependency)
0193     endif ()
0194     set(_ssheet "${KDOCTOOLS_CUSTOMIZATION_DIR}/kde-include-man.xsl")
0195
0196     add_custom_command(OUTPUT ${build_doc}
0197         COMMAND ${KDOCTOOLS_MEINPROC_EXECUTABLE} --stylesheet ${_ssheet} --check ${_bootstrapOption} ${CMAKE_CURRENT_SOURCE_DIR}/${src_doc}
0198         DEPENDS ${src_doc} ${_ssheet} ${_extraDependency}
0199         WORKING_DIRECTORY ${build_dir}
0200     )
0201
0202     _kdoctools_create_target_name(_targ ${build_doc})
0203     add_custom_target(${_targ} ALL DEPENDS "${build_doc}")
0204
0205     if(ARGS_INSTALL_DESTINATION)
0206         install(FILES ${build_doc} DESTINATION ${ARGS_INSTALL_DESTINATION}/man${section})
0207     endif()
0208 endfunction()
0209
0210
0211 function(kdoctools_install podir)
0212     file(GLOB lang_dirs "${podir}/*")
0213     if (NOT KDE_INSTALL_MANDIR)
0214         if (MAN_INSTALL_DIR) # TODO KF6: deprecated, remove
0215             set(KDE_INSTALL_MANDIR ${MAN_INSTALL_DIR})
0216         else()
0217             set(KDE_INSTALL_MANDIR share/man)
0218         endif()
0219     endif()
0220     if (NOT KDE_INSTALL_DOCBUNDLEDIR)
0221         if (HTML_INSTALL_DIR) # TODO KF6: deprecated, remove
0222             set(KDE_INSTALL_DOCBUNDLEDIR ${HTML_INSTALL_DIR})
0223         else()
0224             set(KDE_INSTALL_DOCBUNDLEDIR share/doc/HTML)
0225         endif()
0226     endif()
0227     foreach(lang_dir ${lang_dirs})
0228         get_filename_component(lang ${lang_dir} NAME)
0229
0230         file(GLOB_RECURSE docbooks RELATIVE "${lang_dir}" "${lang_dir}/docs/*.docbook")
0231         foreach(docbook ${docbooks})
0232             string(REGEX MATCH "\\.([0-9])\\.docbook" match ${docbook})
0233             if (match)
0234                 kdoctools_create_manpage("${lang_dir}/${docbook}" ${CMAKE_MATCH_1}
0235                     INSTALL_DESTINATION ${KDE_INSTALL_MANDIR}/${lang}
0236                 )
0237             else()
0238                 string(REGEX MATCH "^docs/(.*)/index.docbook" match ${docbook})
0239                 if (match)
0240                     kdoctools_create_handbook("${lang_dir}/${docbook}"
0241                         INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/${lang}
0242                         SUBDIR ${CMAKE_MATCH_1}
0243                     )
0244                 endif()
0245             endif()
0246         endforeach()
0247     endforeach()
0248 endfunction()