| 1 |
# |
| 2 |
# api documentation |
| 3 |
# |
| 4 |
find_package(Doxygen) |
| 5 |
|
| 6 |
# always check doc target |
| 7 |
add_custom_target(doc ALL) |
| 8 |
|
| 9 |
if(DOXYGEN_EXECUTABLE) |
| 10 |
option(DBUS_ENABLE_DOXYGEN_DOCS "build DOXYGEN documentation (requires Doxygen)" ON) |
| 11 |
add_auto_option(ENABLE_QT_HELP "build qt help documentation (requires qhelpgenerator(-qt5)); set INSTALL_QCH_DIR for custom qch installation path" AUTO) |
| 12 |
endif() |
| 13 |
|
| 14 |
if(DBUS_ENABLE_DOXYGEN_DOCS) |
| 15 |
set(top_srcdir ${PROJECT_SOURCE_DIR}) |
| 16 |
set(top_builddir ${PROJECT_BINARY_DIR}) |
| 17 |
if(WIN32) |
| 18 |
set(DBUS_GENERATE_MAN NO) |
| 19 |
else() |
| 20 |
set(DBUS_GENERATE_MAN YES) |
| 21 |
endif() |
| 22 |
if(NOT DEFINED INSTALL_QCH_DIR) |
| 23 |
set(INSTALL_QCH_DIR ${CMAKE_INSTALL_DATADIR}/doc/dbus) |
| 24 |
endif() |
| 25 |
find_program(QHELPGENERATOR_EXECUTABLE NAMES qhelpgenerator qhelpgenerator-qt5) |
| 26 |
check_auto_option(ENABLE_QT_HELP "Qt help" QHELPGENERATOR_EXECUTABLE "qhelpgenerator") |
| 27 |
if(ENABLE_QT_HELP AND QHELPGENERATOR_EXECUTABLE) |
| 28 |
message(STATUS "${QHELPGENERATOR_EXECUTABLE} found") |
| 29 |
set(DOXYGEN_GENERATE_QHP YES) |
| 30 |
set(DOXYGEN_QHG_LOCATION ${QHELPGENERATOR_EXECUTABLE}) |
| 31 |
set(DOXYGEN_QCH_FILE ${CMAKE_CURRENT_BINARY_DIR}/api/qch/dbus-${VERSION}.qch) |
| 32 |
set(DBUS_ENABLE_QTHELP_DOCS ON PARENT_SCOPE) |
| 33 |
install(FILES ${DOXYGEN_QCH_FILE} DESTINATION ${INSTALL_QCH_DIR}) |
| 34 |
else() |
| 35 |
set(DOXYGEN_GENERATE_QHP NO) |
| 36 |
set(DBUS_ENABLE_QTHELP_DOCS OFF PARENT_SCOPE) |
| 37 |
endif() |
| 38 |
configure_file(../Doxyfile.in ${PROJECT_BINARY_DIR}/Doxyfile ) |
| 39 |
file(GLOB dbus_files "${PROJECT_SOURCE_DIR}/dbus/*.[ch]*") |
| 40 |
add_custom_command( |
| 41 |
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen.stamp |
| 42 |
DEPENDS ${PROJECT_SOURCE_DIR}/Doxyfile.in ${PROJECT_BINARY_DIR}/Doxyfile ${dbus_files} |
| 43 |
COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/api/html |
| 44 |
COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/api/man |
| 45 |
COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/api/xml |
| 46 |
COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/Doxyfile |
| 47 |
COMMAND ${CMAKE_COMMAND} -E touch ${CMAKE_CURRENT_BINARY_DIR}/doxygen.stamp |
| 48 |
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} |
| 49 |
COMMENT "Generating API documentation with Doxygen" |
| 50 |
) |
| 51 |
add_custom_target(apidoc |
| 52 |
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxygen.stamp |
| 53 |
) |
| 54 |
add_dependencies(doc apidoc) |
| 55 |
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/api/html/ DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/dbus/api/html) |
| 56 |
endif() |
| 57 |
|
| 58 |
find_program(XSLTPROC_EXECUTABLE xsltproc) |
| 59 |
if(XSLTPROC_EXECUTABLE) |
| 60 |
message(STATUS "${XSLTPROC_EXECUTABLE} found") |
| 61 |
set(DBUS_HAVE_XSLTPROC 1) |
| 62 |
endif() |
| 63 |
|
| 64 |
if(DBUS_HAVE_XSLTPROC AND DBUS_ENABLE_DOXYGEN_DOCS) |
| 65 |
add_custom_command( |
| 66 |
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/dbus.devhelp2 |
| 67 |
COMMAND ${XSLTPROC_EXECUTABLE} |
| 68 |
-o ${CMAKE_CURRENT_BINARY_DIR}/dbus.devhelp2 |
| 69 |
${CMAKE_CURRENT_SOURCE_DIR}/doxygen_to_devhelp.xsl |
| 70 |
${CMAKE_CURRENT_BINARY_DIR}/api/xml/index.xml |
| 71 |
DEPENDS |
| 72 |
${CMAKE_CURRENT_SOURCE_DIR}/doxygen_to_devhelp.xsl |
| 73 |
${CMAKE_CURRENT_BINARY_DIR}/doxygen.stamp |
| 74 |
) |
| 75 |
add_custom_target(devhelp2 |
| 76 |
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/dbus.devhelp2 |
| 77 |
) |
| 78 |
add_dependencies(doc devhelp2) |
| 79 |
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/dbus.devhelp2 DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/dbus) |
| 80 |
endif() |
| 81 |
|
| 82 |
# |
| 83 |
# docbook based documentation |
| 84 |
# |
| 85 |
find_package(DocBookXSL) |
| 86 |
|
| 87 |
if(DOCBOOKXSL_DIR AND XSLTPROC_EXECUTABLE) |
| 88 |
option(DBUS_ENABLE_XML_DOCS "build XML documentation" ON) |
| 89 |
set(DBUS_XML_DOCS_ENABLED 1) |
| 90 |
message(STATUS "xsltproc docbook generator found") |
| 91 |
add_custom_target(xmldoc) |
| 92 |
add_dependencies(doc xmldoc) |
| 93 |
endif() |
| 94 |
|
| 95 |
if(DBUS_ENABLE_XML_DOCS) |
| 96 |
|
| 97 |
# |
| 98 |
# generate output file from docbook xml source template or file |
| 99 |
# |
| 100 |
# @param _target base name for the generated file |
| 101 |
# @param TEMPLATE <file> docbook xml template file to generated the output from |
| 102 |
# (with '@var@' variable substitution) |
| 103 |
# @param SOURCE <file> alternative docbook xml file to generated the output from |
| 104 |
# (without variable substitution) |
| 105 |
# @param MAN_CATEGORY <cat> category for creating man pages (also used for html output) |
| 106 |
# @param FORMATS <formats> list with output formats to generate ('html' and/or 'man') |
| 107 |
# |
| 108 |
macro(add_docbook _target) |
| 109 |
set(options) |
| 110 |
set(oneValueArgs SOURCE TEMPLATE MAN_CATEGORY) |
| 111 |
set(multiValueArgs FORMATS) |
| 112 |
cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) |
| 113 |
|
| 114 |
foreach(_format ${ARGS_FORMATS}) |
| 115 |
if(ARGS_TEMPLATE) |
| 116 |
set(_xmlfile "${CMAKE_CURRENT_BINARY_DIR}/${_target}-${_format}.xml") |
| 117 |
get_filename_component(_infile ${ARGS_TEMPLATE} ABSOLUTE) |
| 118 |
configure_file(${_infile} ${_xmlfile}) |
| 119 |
else() |
| 120 |
get_filename_component(_infile ${ARGS_SOURCE} ABSOLUTE) |
| 121 |
set(_xmlfile ${_infile}) |
| 122 |
endif() |
| 123 |
if(${_format} STREQUAL "man") |
| 124 |
set(_outname "${_target}.${ARGS_MAN_CATEGORY}") |
| 125 |
set(STYLESHEET "${DOCBOOKXSL_DIR}/manpages/docbook.xsl") |
| 126 |
set(INSTALL_DIR ${CMAKE_INSTALL_DATADIR}/man/man${ARGS_MAN_CATEGORY}) |
| 127 |
else() |
| 128 |
if (NOT ARGS_MAN_CATEGORY) |
| 129 |
set(_outname "${_target}.html") |
| 130 |
else() |
| 131 |
set(_outname "${_target}.${ARGS_MAN_CATEGORY}.html") |
| 132 |
endif() |
| 133 |
set(STYLESHEET "${DOCBOOKXSL_DIR}/html/docbook.xsl") |
| 134 |
set(INSTALL_DIR ${CMAKE_INSTALL_DATADIR}/doc/dbus) |
| 135 |
endif() |
| 136 |
set(_outfile ${CMAKE_CURRENT_BINARY_DIR}/${_outname}) |
| 137 |
add_custom_command( |
| 138 |
OUTPUT ${_outfile} |
| 139 |
COMMAND ${XSLTPROC_EXECUTABLE} --output ${_outfile} --nonet --xinclude --param passivetex.extensions '1' --param generate.consistent.ids '1' ${STYLESHEET} ${_xmlfile} |
| 140 |
DEPENDS ${XSLTPROC_EXECUTABLE} ${_xmlfile} |
| 141 |
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} |
| 142 |
) |
| 143 |
add_custom_target(xmldoc-${_outname} DEPENDS ${_outfile}) |
| 144 |
add_dependencies(xmldoc xmldoc-${_outname}) |
| 145 |
install(FILES ${_outfile} DESTINATION ${INSTALL_DIR}) |
| 146 |
endforeach() |
| 147 |
endmacro() |
| 148 |
|
| 149 |
### copy tests to builddir so that generated tests and static tests |
| 150 |
### are all in one place. |
| 151 |
### todo how to add more filetypes |
| 152 |
macro(COPYDIR _src _type) |
| 153 |
foreach(FILE_TYPE ${_type}) |
| 154 |
foreach(DIR ${_src}) |
| 155 |
file(GLOB FILES "${DIR}/${FILE_TYPE}" ) |
| 156 |
file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/${DIR}) |
| 157 |
foreach(FILE ${FILES}) |
| 158 |
get_filename_component(FILENAME ${FILE} NAME) |
| 159 |
set(TARGET ${PROJECT_BINARY_DIR}/${DIR}/${FILENAME}) |
| 160 |
configure_file(${FILE} ${TARGET} COPYONLY) |
| 161 |
if(CONFIG_VERBOSE) |
| 162 |
message("FROM: ${FILE}\nTO: ${TARGET}\n") |
| 163 |
endif() |
| 164 |
endforeach() |
| 165 |
endforeach() |
| 166 |
endforeach() |
| 167 |
endmacro() |
| 168 |
|
| 169 |
# copy source files from doc directory into associated binary directory |
| 170 |
# which is required to run generated xml docs from build directory |
| 171 |
COPYDIR(doc *.png) |
| 172 |
COPYDIR(doc *.svg) |
| 173 |
|
| 174 |
# setup variables used in docbook templates |
| 175 |
set(EXPANDED_SYSCONFDIR ${CMAKE_INSTALL_FULL_SYSCONFDIR}) |
| 176 |
set(EXPANDED_DATADIR ${CMAKE_INSTALL_FULL_DATADIR}) |
| 177 |
|
| 178 |
set(formats html) |
| 179 |
if(UNIX) |
| 180 |
list(APPEND formats man) |
| 181 |
endif() |
| 182 |
# generate docbook output |
| 183 |
add_docbook(dbus-cleanup-sockets TEMPLATE dbus-cleanup-sockets.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 184 |
add_docbook(dbus-daemon TEMPLATE dbus-daemon.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 185 |
add_docbook(dbus-launch TEMPLATE dbus-launch.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 186 |
add_docbook(dbus-monitor TEMPLATE dbus-monitor.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 187 |
add_docbook(dbus-run-session TEMPLATE dbus-run-session.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 188 |
add_docbook(dbus-send TEMPLATE dbus-send.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 189 |
add_docbook(dbus-test-tool TEMPLATE dbus-test-tool.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 190 |
add_docbook(dbus-uuidgen TEMPLATE dbus-uuidgen.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 191 |
add_docbook(dbus-update-activation-environment TEMPLATE dbus-update-activation-environment.1.xml.in MAN_CATEGORY 1 FORMATS ${formats}) |
| 192 |
add_docbook(dbus-faq SOURCE dbus-faq.xml FORMATS html) |
| 193 |
add_docbook(dbus-specification SOURCE dbus-specification.xml FORMATS html) |
| 194 |
add_docbook(dbus-test-plan SOURCE dbus-test-plan.xml FORMATS html) |
| 195 |
add_docbook(dbus-tutorial SOURCE dbus-tutorial.xml FORMATS html) |
| 196 |
|
| 197 |
# |
| 198 |
# handle html index file |
| 199 |
# |
| 200 |
if(DBUS_ENABLE_DOXYGEN_DOCS) |
| 201 |
set(DBUS_APIDOC_LINK "<a href=\"api/html/index.html\">libdbus API Documentation</a>") |
| 202 |
else() |
| 203 |
set(DBUS_APIDOC_LINK "") |
| 204 |
endif() |
| 205 |
configure_file(index.html.in ${CMAKE_CURRENT_BINARY_DIR}/index.html) |
| 206 |
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/index.html DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/dbus) |
| 207 |
|
| 208 |
# |
| 209 |
# misc files |
| 210 |
# |
| 211 |
set(DTD_DATA |
| 212 |
diagram.png |
| 213 |
diagram.svg |
| 214 |
) |
| 215 |
|
| 216 |
install(FILES ${DTD_DATA} DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/dbus) |
| 217 |
|
| 218 |
set(DOC_DATA |
| 219 |
system-activation.txt |
| 220 |
) |
| 221 |
|
| 222 |
install(FILES ${DOC_DATA} DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/dbus) |
| 223 |
|
| 224 |
set(DBUS_DTD_DIR "${CMAKE_INSTALL_DATADIR}/xml/dbus-1" CACHE STRING "Directory for installing DTD files") |
| 225 |
set(DBUS_XML_CATALOG_DIR "${DBUS_DTD_DIR}" CACHE STRING "Directory for installing XML catalog file") |
| 226 |
|
| 227 |
set(EXTRA_DIST |
| 228 |
busconfig.dtd |
| 229 |
introspect.dtd |
| 230 |
introspect.xsl |
| 231 |
) |
| 232 |
|
| 233 |
install(FILES ${EXTRA_DIST} DESTINATION ${DBUS_DTD_DIR}) |
| 234 |
|
| 235 |
configure_file( |
| 236 |
"${CMAKE_CURRENT_SOURCE_DIR}/catalog.xml.in" |
| 237 |
"${CMAKE_CURRENT_BINARY_DIR}/catalog.xml" |
| 238 |
@ONLY) |
| 239 |
|
| 240 |
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/catalog.xml" DESTINATION ${DBUS_XML_CATALOG_DIR}) |
| 241 |
|
| 242 |
endif() |