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