## Copyright (c) 2009, 2011 Openismus GmbH ## ## 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 . ## Parameters: book_name ## Overrides: doc_outdir, doc_config, book_title, htmlref_patterns, ## 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 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 js png) # 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_build_files = $(doxytagfile) $(devhelpfile) doc_inst_targets = install-htmlref install-devhelp doc_inst_files = $(doxytagfile) doc_dist_files = $(devhelpfile) $(call vpath_listall,$(htmlref_patterns)) else doc_build_files = 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 # Depend on files that we know shall be built. # $(call vpath_listall,$(htmlref_patterns)) is not used as a prerequisite. # It would expand to files that exist when the make command is issued, # which is not necessarily the set of files that shall be built. all-local: $(doc_build_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: