1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
## Copyright (c) 2009, 2011 Openismus GmbH <http://www.openismus.com/>
##
## This file is part of mm-common.
##
## mm-common is free software: you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published
## by the Free Software Foundation, either version 2 of the License,
## or (at your option) any later version.
##
## mm-common is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with mm-common. If not, see <http://www.gnu.org/licenses/>.
## Parameters: book_name
## Overrides: pubdocbase, htmlrefpub, book_title, htmlref_patterns,
## doc_outdir, doc_config, doc_postprocess, doc_install,
## tagfile_to_devhelp2, doxytagfile, devhelpfile
## Files: doc_input
## Output: dist_noinst_DATA, DISTCLEANFILES, MAINTAINERCLEANFILES
# The name of the sub-directory where the generated documentation
# will be placed.
doc_outdir ?= reference
# The name of the Doxygen configuration file.
doc_config ?= $(doc_outdir)/Doxyfile
# The base URL where the online documentation for C++ binding modules
# is located, including the trailing slash.
pubdocbase ?= http://library.gnome.org/devel/
# The URL of the module's online HTML reference documentation, which
# may or may not end in a trailing slash.
htmlrefpub ?= $(pubdocbase)$(PACKAGE_TARNAME)/unstable/
# The title of the generated Devhelp book.
book_title ?= $(PACKAGE_NAME) Reference Manual
# A list of wildcard patterns matching the files from the HTML directory
# generated by Doxygen which should be distributed and installed.
htmlref_patterns ?= $(addprefix $(doc_outdir)/html/*.,css gif html png js)
# Locations of utilities shipped with glibmm. Made overridable
# in case the installed utilities cannot be used for some reason.
doc_postprocess ?= $(PERL) -- "$(MMDOCTOOLDIR)/doc-postprocess.pl"
doc_install ?= $(PERL) -- "$(MMDOCTOOLDIR)/doc-install.pl"
tagfile_to_devhelp2 ?= "$(MMDOCTOOLDIR)/tagfile-to-devhelp2.xsl"
# Names of the main output files.
doxytagfile ?= $(doc_outdir)/$(book_name).tag
devhelpfile ?= $(doc_outdir)/$(book_name).devhelp2
# Function: $(call vpath_listall,PATTERN ...)
# Get all filenames which match a PATTERN from the list. Look for files
# relative to either the current directory or $(srcdir). Strip $(srcdir)/
# again before returning and remove any duplicates.
vpath_srclist = $(patsubst $(srcdir)/%,%,$(wildcard $(addprefix $(srcdir)/,$(1))))
vpath_listall = $(sort $(wildcard $(1)) $(if $(srcdir:.=),$(vpath_srclist)))
# Installation directories.
libdocdir = $(datarootdir)/doc/$(book_name)
referencedir = $(libdocdir)/reference
htmlrefdir = $(referencedir)/html
devhelpdir = $(datadir)/devhelp/books/$(book_name)
# Optionally, the documentation utilities may be included in source tarballs
# so that mm-common is only required when building in maintainer mode.
if DIST_DOCTOOLS
doctools_dist_files = $(addprefix $(MMDOCTOOLDIR)/,doc-postprocess.pl doc-install.pl tagfile-to-devhelp2.xsl doxygen-extra.css)
else
doctools_dist_files =
endif
if ENABLE_DOCUMENTATION
doc_inst_targets = install-htmlref install-devhelp
doc_inst_files = $(doxytagfile)
doc_dist_files = $(devhelpfile) $(call vpath_listall,$(htmlref_patterns))
else
doc_inst_targets =
doc_inst_files =
doc_dist_files =
endif
dist_reference_DATA = $(strip $(doc_inst_files))
dist_noinst_DATA = $(strip $(doctools_dist_files) $(doc_dist_files))
DISTCLEANFILES = $(doc_outdir)/doxygen.log
MAINTAINERCLEANFILES = $(doxytagfile) $(devhelpfile) $(doc_outdir)/html/*
# The generic bit of the doc-install.pl command line.
doc_install_cmd = $(doc_install) --verbose --mode=0644
# Transform $(datarootdir) into a URI to match MM_ARG_WITH_TAGFILE_DOC().
datarootdir_esc = $(subst $(subst ,, ),%20,$(subst \,/,$(datarootdir)))
docdir_base_uri = file:///$(patsubst /%,%,$(datarootdir_esc:/=))/doc
# The command and options used to install the files from the HTML reference
# documentation. The $(subst) magic translates external tag references from
# absolute to relative paths if the destination is on the local file system
# and installed under the same prefix as the package being built.
htmlref_relinst = $(subst @$(docdir_base_uri)/,@../../../,$(DOCINSTALL_FLAGS))
htmlref_install = $(doc_install_cmd) $(htmlref_relinst)
# The command and options used to install the Devhelp file.
devhelp_install = $(doc_install_cmd) --book-base='$(htmlrefdir:/=)'
# Helper variables to replicate each pattern with a $(srcdir)/ prefix.
# Also add quoting to prevent the shell from expanding the patterns.
htmlref_patterns_dup = $(foreach item,$(htmlref_patterns),'$(item)' '$(srcdir)/$(item)')
htmlref_patterns_quote = $(patsubst %,'%',$(htmlref_patterns))
htmlref_patterns_vpath = $(if $(srcdir:.=),$(htmlref_patterns_dup),$(htmlref_patterns_quote))
# Expand to a list of -name 'PATTERN' arguments for use with 'find'.
htmlref_find_patterns = $(patsubst %,-name '%' -o,$(notdir $(htmlref_patterns))) -false
# The parameters to the Doxygen-to-Devhelp XSLT script
dh_xsl_params = --stringparam book_title '$(book_title)' \
--stringparam book_name '$(book_name)' \
--stringparam book_base html
# Generated configuration files which, when updated, should cause the
# reference documentation to be rebuilt.
doc_config_deps = $(CONFIG_HEADER) $(srcdir)/$(doc_config).in $(srcdir)/Makefile.in
# Regenerate the documentation automatically only in maintainer mode.
# Depend on the generated configuration header files to trigger a rebuild
# if a configuration value changed. The configuration header files only
# have their timestamp modified when the content actually changed, which
# is not the case for any other files generated by configure.
if MAINTAINER_MODE
doc_dependencies = $(doc_config_deps) $(doc_input)
else
doc_dependencies =
endif
# Export this variable for use in the Doxygen configuration file.
export MMDOCTOOLDIR
# Explicitly depend on the files to be distributed or installed.
all-local: $(doc_inst_files) $(doc_dist_files)
# Hook up custom rules for translating references to external documentation
# to the actual location at install time.
install-data-local: $(doc_inst_targets)
# Hook up corresponding custom uninstall rules.
uninstall-local: $(addprefix un,$(doc_inst_targets))
# Install the HTML reference documentation files with just one invocation
# of doc-install.pl to speed up the build process. Make use of the --glob
# option, which tells it to perform filename globbing itself, like 'find'.
# This helps to avoid excessively long command lines, as some platforms
# have rather restrictive limits.
install-htmlref: $(doc_outdir)/html/index.html
@$(NORMAL_INSTALL)
$(MKDIR_P) '$(DESTDIR)$(htmlrefdir)'
$(htmlref_install) -t '$(DESTDIR)$(htmlrefdir)' --glob -- $(htmlref_patterns_vpath)
# Delete files from the html installation directory. Avoid recursive
# directory removal, and apply the same wildcard pattern as was used to
# select files for installation.
uninstall-htmlref:
@$(NORMAL_UNINSTALL)
(cd '$(DESTDIR)$(htmlrefdir)' 2>/dev/null || exit 0; \
find . -type f '(' $(htmlref_find_patterns) ')' -exec rm -f '{}' '+')
-test ! -r '$(DESTDIR)$(htmlrefdir)' || rmdir '$(DESTDIR)$(htmlrefdir)'
# Install the Devhelp file, translating the base path on the fly.
install-devhelp: $(devhelpfile)
@$(NORMAL_INSTALL)
$(MKDIR_P) '$(DESTDIR)$(devhelpdir)'
$(devhelp_install) -t '$(DESTDIR)$(devhelpdir)' -- $^
# Remove the installed Devhelp file and directory.
uninstall-devhelp:
@$(NORMAL_UNINSTALL)
rm -f '$(DESTDIR)$(devhelpdir)/$(notdir $(devhelpfile))'
-test ! -r '$(DESTDIR)$(devhelpdir)' || rmdir '$(DESTDIR)$(devhelpdir)'
# Regenerate the Doxygen configuration file automatically. In the
# top-level build directory Automake already takes care of this.
ifneq ($(subdir),.)
$(doc_config): $(srcdir)/$(doc_config).in $(top_builddir)/config.status
$(AM_V_GEN)cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@
endif
# Make sure that the documentation will always have been generated before
# executing commands of a rule that depends on files in $(doc_outdir)/html/.
$(doc_outdir)/html/%: | $(doxytagfile)
# Run Doxygen to build the reference documentation. The generated tag file
# also functions as time stamp target for the documentation as a whole.
$(doxytagfile): $(doc_dependencies) | $(doc_config)
-$(AM_V_at)rm -f $@
-$(AM_V_at)rm -fr $(doc_outdir)/html
$(AM_V_GEN)(echo '@INCLUDE =' $(doc_config) && echo 'INPUT =' $(doc_input)) | "$(DOXYGEN)" -
$(AM_V_at)$(doc_postprocess) '$(doc_outdir)/html/*.html'
# Run XSL transformation to generate a Devhelp book from a Doxygen tag file.
%.devhelp2: %.tag
$(AM_V_GEN)$(XSLTPROC) $(dh_xsl_params) -o $@ $(tagfile_to_devhelp2) $<
.PHONY: install-htmlref uninstall-htmlref install-devhelp uninstall-devhelp
# Instruct GNU make to delete the targets of a rule after it failed, in
# order to avoid the complication of handling that situation manually.
.DELETE_ON_ERROR:
|
