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