Debian Codegraph @

buildsystems/cmake/GtkDocConfig.cmake

raw
1 # CMake macros to use the GtkDoc documentation system
2 #
3 # See the GTK-Doc manual (help/manual/C/index.docbook) for an example of how to
4 # use this.
5
6 # Output variables:
7 #
8 # GTKDOC_FOUND ... set to 1
9 #
10 # GTKDOC_SCAN_EXE ... the location of the gtkdoc-scan executable
11 # GTKDOC_SCANGOBJ_EXE ... the location of the gtkdoc-scangobj executable
12 # GTKDOC_MKDB_EXE ... the location of the gtkdoc-mkdb executable
13 # GTKDOC_MKHTML_EXE ... the location of the gtkdoc-mkhtml executable
14 # GTKDOC_FIXXREF_EXE ... the location of the gtkdoc-fixxref executable
15
16
17 #=============================================================================
18 # Copyright 2009 Rich Wareham
19 # Copyright 2015 Lautsprecher Teufel GmbH
20 #
21 # This program is free software; you can redistribute it and/or modify
22 # it under the terms of the GNU General Public License as published by
23 # the Free Software Foundation; either version 2 of the License, or
24 # (at your option) any later version.
25 #
26 # This program is distributed in the hope that it will be useful,
27 # but WITHOUT ANY WARRANTY; without even the implied warranty of
28 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
29 # GNU General Public License for more details.
30 #
31 # You should have received a copy of the GNU General Public License
32 # along with this program. If not, see <http://www.gnu.org/licenses/>.
33 #=============================================================================
34
35 include(CMakeParseArguments)
36
37 set(GTKDOC_FOUND 1)
38
39 find_program(GTKDOC_SCAN_EXE gtkdoc-scan)
40 find_program(GTKDOC_SCANGOBJ_EXE gtkdoc-scangobj)
41 find_program(GTKDOC_MKDB_EXE gtkdoc-mkdb)
42 find_program(GTKDOC_MKHTML_EXE gtkdoc-mkhtml)
43 find_program(GTKDOC_FIXXREF_EXE gtkdoc-fixxref)
44
45 get_filename_component(_this_dir ${CMAKE_CURRENT_LIST_FILE} PATH)
46 find_file(GTKDOC_SCANGOBJ_WRAPPER GtkDocScanGObjWrapper.cmake PATH ${_this_dir})
47
48 # ::
49 #
50 # gtk_doc_add_module(doc_prefix
51 # SOURCE <sourcedir> [...]
52 # XML xmlfile
53 # [LIBRARIES depend1...]
54 # [FIXXREFOPTS fixxrefoption1...]
55 # [IGNOREHEADERS header1...]
56 # [CONTENT_FILES example1...]
57 # [SCANOPTS scanoption1...]
58 # [SCANOBJOPTS scanobjoption1...]
59 # [MKDBOPTS mkdboption1...]
60 # [HTMLOPTS htmloption1...])
61 #
62 # Add a module with documentation to be processed with GTK-Doc.
63 #
64 # <sourcedir> must be the *full* path to the source directory.
65 #
66 # If omitted, xmlfile defaults to the auto generated ${doc_prefix}/${doc_prefix}-docs.xml.
67 #
68 # The `gtkdoc-scangobj` program is used to get introspection information for
69 # the module. You should pass the target(s) to be scanned as LIRARIES. This
70 # will try to set the correct compiler and link flags for the introspection
71 # build to use, and the correct LD_LIBRARY_PATH for it to run, and the correct
72 # dependencies for the doc target.
73 #
74 # You *can* also set the compile and link flags manually, using the 'CFLAGS'
75 # and 'LDFLAGS' options. The 'LDPATH' option controls the LD_LIBRARY_PATH. You
76 # can also manually add additional targets as dependencies of the
77 # documentation build with the DEPENDS option.
78 #
79 # The 'CONTENT_FILES' option is here to copy the files extending the documentation
80 # such as exemples and custom xml files.
81 #
82 # The 'SCANOPTS' option is here to pass arguments to 'gtkdoc-scan'
83 # The 'SCANOBJOPTS' option is here to pass arguments to 'gtkdoc-scangobj'
84 # The 'MKDBOPTS' option is here to pass arguments to 'gtkdoc-mkdb'
85 # The 'HTMLOPTS' option is here to pass arguments to 'gtkdoc-mkhtml'
86 #
87 # This function a target named "doc-${doc_prefix}". You will need to manually
88 # add it to the ALL target if you want it to be built by default, you can do
89 # something like this:
90 #
91 # gtk_doc_add_module(doc-mymodule
92 # SOURCE ${CMAKE_SOURCE_DIR}/module ${CMAKE_BINARY_DIR}/module
93 # LIBRARIES mylibrary
94 # LIBRARY_DIRS ${GLIB_LIBRARY_DIRS} ${FOO_LIBRARY_DIRS}
95 # add_custom_target(all-documentation ALL)
96 # add_dependencies(all-documentation doc-mymodule)
97 #
98 function(gtk_doc_add_module _doc_prefix)
99 set(_one_value_args "XML")
100 set(_multi_value_args "FIXXREFOPTS" "IGNOREHEADERS" "LIBRARIES" "LIBRARY_DIRS" "SOURCE" "SUFFIXES"
101 "CFLAGS" "DEPENDS" "LDFLAGS" "LDPATH" "CONTENT_FILES" "SCANOPTS" "SCANOBJOPTS"
102 "MKDBOPTS" "HTMLOPTS")
103 cmake_parse_arguments("GTK_DOC" "" "${_one_value_args}" "${_multi_value_args}" ${ARGN})
104
105 if(NOT GTK_DOC_SOURCE)
106 message(FATAL_ERROR "No SOURCE specified for gtk_doc_add_module ${_doc_prefix}")
107 endif()
108
109 set(_xml_file ${GTK_DOC_XML})
110
111 set(_fixxrefopts ${GTK_DOC_FIXXREFOPTS})
112 set(_ignore_headers ${GTK_DOC_IGNOREHEADERS})
113 set(_libraries ${GTK_DOC_LIBRARIES})
114 set(_library_dirs ${GTK_DOC_LIBRARY_DIRS})
115 set(_suffixes ${GTK_DOC_SUFFIXES})
116
117 set(_content_files ${GTK_DOC_CONTENT_FILES})
118 set(_scanopts ${GTK_DOC_SCANOPTS})
119 set(_scanobjopts ${GTK_DOC_SCANOBJOPTS})
120 set(_mkdbopts ${GTK_DOC_MKDBOPTS})
121 set(_htmlopts ${GTK_DOC_HTMLOPTS})
122
123 set(_extra_cflags ${GTK_DOC_CFLAGS})
124 set(_depends ${GTK_DOC_DEPENDS})
125 set(_extra_ldflags ${GTK_DOC_LDFLAGS})
126 set(_extra_ldpath ${GTK_DOC_LDPATH})
127
128 if(_suffixes)
129 set(_doc_source_suffixes "")
130 foreach(_suffix ${_suffixes})
131 if(_doc_source_suffixes)
132 set(_doc_source_suffixes "${_doc_source_suffixes},${_suffix}")
133 else(_doc_source_suffixes)
134 set(_doc_source_suffixes "${_suffix}")
135 endif(_doc_source_suffixes)
136 endforeach(_suffix)
137 else(_suffixes)
138 set(_doc_source_suffixes "h")
139 endif(_suffixes)
140
141 # Parse the LIBRARIES option and collect compile and link flags for those
142 # targets.
143 foreach(target ${_libraries})
144 _gtk_doc_get_cflags_for_target(_target_cflags ${target})
145 _gtk_doc_get_ldflags_for_target(_target_ldflags ${target} "${_libraries}")
146 list(APPEND _extra_cflags ${_target_cflags})
147 list(APPEND _extra_ldflags ${_target_ldflags})
148 list(APPEND _extra_ldpath $<TARGET_FILE_DIR:${target}>)
149
150 list(APPEND _depends ${target})
151 endforeach()
152
153 # Link directories can't be specified per target, only for every target
154 # under a given directory.
155 get_property(all_library_directories DIRECTORY PROPERTY LINK_DIRECTORIES)
156 foreach(library_dir ${all_library_directories})
157 list(APPEND _extra_ldflags ${CMAKE_LIBRARY_PATH_FLAG}${library_dir})
158 list(APPEND _extra_ldpath ${library_dir})
159 endforeach()
160
161 list(REMOVE_DUPLICATES _extra_cflags)
162 list(SORT _extra_cflags)
163
164 list(REMOVE_DUPLICATES _extra_ldflags)
165 list(SORT _extra_ldflags)
166
167 list(REMOVE_DUPLICATES _extra_ldpath)
168 list(SORT _extra_ldpath)
169
170 # a directory to store output.
171 set(_output_dir "${CMAKE_CURRENT_BINARY_DIR}")
172 set(_output_dir_stamp "${_output_dir}/dir.stamp")
173
174 # set default sgml file if not specified
175 set(_default_xml_file "${_output_dir}/${_doc_prefix}-docs.xml")
176 get_filename_component(_default_xml_file ${_default_xml_file} ABSOLUTE)
177
178 # a directory to store html output.
179 set(_output_html_dir "${_output_dir}/html")
180 set(_output_html_dir_stamp "${_output_dir}/html_dir.stamp")
181
182 # The output files
183 set(_output_decl_list "${_output_dir}/${_doc_prefix}-decl-list.txt")
184 set(_output_decl "${_output_dir}/${_doc_prefix}-decl.txt")
185 set(_output_overrides "${_output_dir}/${_doc_prefix}-overrides.txt")
186 set(_output_sections "${_output_dir}/${_doc_prefix}-sections.txt")
187 set(_output_types "${_output_dir}/${_doc_prefix}.types")
188
189 set(_output_signals "${_output_dir}/${_doc_prefix}.signals")
190
191 set(_output_unused "${_output_dir}/${_doc_prefix}-unused.txt")
192 set(_output_undeclared "${_output_dir}/${_doc_prefix}-undeclared.txt")
193 set(_output_undocumented "${_output_dir}/${_doc_prefix}-undocumented.txt")
194
195 set(_output_xml_dir "${_output_dir}/xml")
196 set(_output_sgml_stamp "${_output_dir}/sgml.stamp")
197
198 set(_output_html_stamp "${_output_dir}/html.stamp")
199
200 # we depend on the content files being there before doing anything
201 if(_content_files)
202 list(APPEND _depends ${_content_files})
203 endif(_content_files)
204
205 # add a command to create output directory
206 add_custom_command(
207 OUTPUT "${_output_dir_stamp}" "${_output_dir}"
208 COMMAND ${CMAKE_COMMAND} -E make_directory "${_output_dir}"
209 COMMAND ${CMAKE_COMMAND} -E touch ${_output_dir_stamp}
210 VERBATIM)
211
212 set(_ignore_headers_opt "")
213 if(_ignore_headers)
214 set(_ignore_headers_opt "--ignore-headers=")
215 foreach(_header ${_ignore_headers})
216 set(_ignore_headers_opt "${_ignore_headers_opt}${_header} ")
217 endforeach(_header ${_ignore_headers})
218 endif(_ignore_headers)
219
220 foreach(source_dir ${GTK_DOC_SOURCE})
221 set(_source_dirs_opt ${_source_dirs_opt} --source-dir=${source_dir})
222 endforeach()
223
224 # add a command to scan the input
225 add_custom_command(
226 OUTPUT
227 "${_output_decl_list}"
228 "${_output_decl}"
229 "${_output_overrides}"
230 "${_output_sections}"
231 "${_output_types}"
232 DEPENDS
233 "${_output_dir_stamp}"
234 ${_depends}
235 COMMAND
236 ${GTKDOC_SCAN_EXE}
237 --module=${_doc_prefix}
238 ${_ignore_headers_opt}
239 ${_source_dirs_opt}
240 --rebuild-sections
241 --rebuild-types
242 ${_scanopts}
243 WORKING_DIRECTORY ${_output_dir}
244 VERBATIM)
245
246 # add a command to scan the input via gtkdoc-scangobj
247 # This is such a disgusting hack!
248 add_custom_command(
249 OUTPUT
250 ${_output_signals}
251 DEPENDS
252 ${_output_types}
253 COMMAND ${CMAKE_COMMAND}
254 -D "GTKDOC_SCANGOBJ_EXE:STRING=${GTKDOC_SCANGOBJ_EXE}"
255 -D "_scanobjopts:STRING=${_scanobjopts}"
256 -D "doc_prefix:STRING=${_doc_prefix}"
257 -D "output_types:STRING=${_output_types}"
258 -D "output_dir:STRING=${_output_dir}"
259 -D "EXTRA_CFLAGS:STRING=${_extra_cflags}"
260 -D "EXTRA_LDFLAGS:STRING=${_extra_ldflags}"
261 -D "EXTRA_LDPATH:STRING=${_extra_ldpath}"
262 -P ${GTKDOC_SCANGOBJ_WRAPPER}
263 WORKING_DIRECTORY "${_output_dir}"
264 VERBATIM)
265
266 set(_copy_xml_if_needed "")
267 if(_xml_file)
268 get_filename_component(_xml_file ${_xml_file} ABSOLUTE)
269 set(_copy_xml_if_needed
270 COMMAND ${CMAKE_COMMAND} -E copy "${_xml_file}" "${_default_xml_file}")
271 endif(_xml_file)
272
273 set(_remove_xml_if_needed "")
274 if(_xml_file)
275 set(_remove_xml_if_needed
276 COMMAND ${CMAKE_COMMAND} -E remove ${_default_xml_file})
277 endif(_xml_file)
278
279 set(_copy_content_files_if_needed "")
280 if(_content_files)
281 foreach(_content_file ${_content_files})
282 # We need to copy the content files to the build directory.
283 # We respect the folder tree if the file comes from the current
284 # source or binary directory but copy the file to the current binary
285 # directory if it comes from somewhere else.
286 get_filename_component(_content_file ${_content_file} ABSOLUTE)
287 string(REGEX MATCH "^${CMAKE_CURRENT_SOURCE_DIR}" _is_in_source ${_content_file})
288 string(REGEX MATCH "^${CMAKE_CURRENT_BINARY_DIR}" _is_in_binary ${_content_file})
289 if (_is_in_source OR _is_in_binary)
290 if(_is_in_source)
291 file(RELATIVE_PATH _content_file_relative ${CMAKE_CURRENT_SOURCE_DIR} ${_content_file})
292 else(_is_in_source)
293 file(RELATIVE_PATH _content_file_relative ${CMAKE_CURRENT_BINARY_DIR} ${_content_file})
294 endif(_is_in_source)
295 set(_content_file_destination
296 "${_output_dir}/${_content_file_relative}")
297 else(_is_in_source OR _is_in_binary)
298 get_filename_component(_content_file_name ${_content_file} NAME)
299 set(_content_file_destination
300 "${_output_dir}/${_content_file_name}")
301 endif(_is_in_source OR _is_in_binary)
302 get_filename_component(_content_file_destination ${_content_file_destination} ABSOLUTE)
303 if(NOT ${_content_file_destination} EQUAL ${_content_file})
304 set(_copy_content_files_if_needed
305 ${_copy_content_files_if_needed}
306 COMMAND ${CMAKE_COMMAND} -E copy "${_content_file}" "${_content_file_destination}")
307 endif(NOT ${_content_file_destination} EQUAL ${_content_file})
308 endforeach(_content_file)
309 endif(_content_files)
310
311 # add a command to make the database
312 add_custom_command(
313 OUTPUT
314 ${_output_sgml_stamp}
315 ${_default_xml_file}
316 DEPENDS
317 ${_output_types}
318 ${_output_signals}
319 ${_output_sections}
320 ${_output_overrides}
321 ${_depends}
322 ${_remove_xml_if_needed}
323 COMMAND ${CMAKE_COMMAND} -E remove_directory ${_output_xml_dir}
324 ${_copy_xml_if_needed}
325 ${_copy_content_files_if_needed}
326 COMMAND ${GTKDOC_MKDB_EXE}
327 --module=${_doc_prefix}
328 ${_source_dirs_opt}
329 --source-suffixes=${_doc_source_suffixes}
330 --output-format=xml
331 --main-sgml-file=${_default_xml_file}
332 ${_mkdbopts}
333 WORKING_DIRECTORY "${_output_dir}"
334 VERBATIM)
335
336 # add a command to create html directory
337 add_custom_command(
338 OUTPUT "${_output_html_dir_stamp}" "${_output_html_dir}"
339 COMMAND ${CMAKE_COMMAND} -E make_directory ${_output_html_dir}
340 COMMAND ${CMAKE_COMMAND} -E touch ${_output_html_dir_stamp}
341 VERBATIM)
342
343 # add a command to output HTML
344 add_custom_command(
345 OUTPUT
346 ${_output_html_stamp}
347 DEPENDS
348 ${_output_html_dir_stamp}
349 ${_output_sgml_stamp}
350 ${_xml_file}
351 ${_depends}
352 ${_copy_xml_if_needed}
353 # The binary dir needs adding to --path in order for mkhtml to pick up
354 # any version.xml file there might be in there
355 COMMAND
356 cd ${_output_html_dir} && ${GTKDOC_MKHTML_EXE}
357 ${_doc_prefix}
358 ${_default_xml_file}
359 ${_htmlopts}
360 COMMAND
361 cd ${_output_dir} && ${GTKDOC_FIXXREF_EXE}
362 --module=${_doc_prefix}
363 --module-dir=${_output_html_dir}
364 ${_fixxrefopts}
365 COMMENT
366 "Generating HTML documentation for ${_doc_prefix} module with gtkdoc-mkhtml"
367 VERBATIM)
368
369 add_custom_target(doc-${_doc_prefix}
370 DEPENDS "${_output_html_stamp}")
371 endfunction(gtk_doc_add_module)
372
373 # These two functions reimplement some of the core logic of CMake, in order
374 # to generate compiler and linker flags from the relevant target properties.
375 # It sucks that we have to do this, but CMake's own code for this doesn't seem
376 # to be reusable -- there's no way to say "tell me the flags that you would
377 # pass to a linker for this target".
378
379 function(_gtk_doc_get_cflags_for_target result_var target)
380 get_target_property(target_definitions ${target} COMPILE_DEFINITIONS)
381 if(target_definitions)
382 foreach(target_definition ${target_definitions})
383 # We need to prepend -D to the definition flag
384 list(APPEND cflags -D${target_definition})
385 endforeach()
386 endif()
387
388 get_target_property(target_options ${target} COMPILE_OPTIONS)
389 if(target_options)
390 list(APPEND cflags ${target_options})
391 endif()
392
393 get_target_property(target_include_dirs ${target} INCLUDE_DIRECTORIES)
394 foreach(target_include_dir ${target_include_dirs})
395 list(APPEND cflags -I${target_include_dir})
396 endforeach()
397
398 list(REMOVE_DUPLICATES cflags)
399 list(SORT cflags)
400
401 set(${result_var} ${cflags} PARENT_SCOPE)
402 endfunction()
403
404 function(_gtk_doc_get_ldflags_for_target result_var target all_targets)
405 get_target_property(target_link_flags ${target} LINK_FLAGS)
406 if(target_link_flags)
407 list(APPEND ldflags ${target_link_flags})
408 endif()
409
410 get_target_property(target_link_libraries ${target} LINK_LIBRARIES)
411 foreach(target_library ${target_link_libraries})
412 # The IN_LIST operator is new in CMake 3.3, so I've tried to avoid using it.
413 list(FIND all_targets ${target_library} target_library_is_explicit_dependency)
414 if(NOT ${target_library_is_explicit_dependency} EQUAL -1)
415 # This target is part of the current project. We will add it to
416 # LDFLAGS explicitly, so don't try to add it as well.
417 # In fact, we can't do that, as the containing directory
418 # probably won't be in the linker search path, and we can't find
419 # that out and add it ourselves.
420 else()
421 list(APPEND ldflags "${target_library}")
422 endif()
423 endforeach()
424
425 # Link in the actual target, as well.
426 list(APPEND ldflags $<TARGET_FILE:${target}>)
427
428 list(REMOVE_DUPLICATES ldflags)
429 list(SORT ldflags)
430
431 set(${result_var} ${ldflags} PARENT_SCOPE)
432 endfunction()