Debian Codegraph @

doc/CMakeLists.txt

raw
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()