build/doc-reference.am

   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.
  27 doc_outdir ?= reference
  28
  29 # The name of the Doxygen configuration file.
  30 doc_config ?= $(doc_outdir)/Doxyfile
  31
  32 # The title of the generated Devhelp book.
  33 book_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.
  37 htmlref_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.
  41 doc_postprocess     ?= $(PERL) -- "$(MMDOCTOOLDIR)/doc-postprocess.pl"
  42 doc_install         ?= $(PERL) -- "$(MMDOCTOOLDIR)/doc-install.pl"
  43 tagfile_to_devhelp2 ?= "$(MMDOCTOOLDIR)/tagfile-to-devhelp2.xsl"
  44
  45 # Names of the main output files.
  46 doxytagfile ?= $(doc_outdir)/$(book_name).tag
  47 devhelpfile ?= $(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.
  53 vpath_srclist = $(patsubst $(srcdir)/%,%,$(wildcard $(addprefix $(srcdir)/,$(1))))
  54 vpath_listall = $(sort $(wildcard $(1)) $(if $(srcdir:.=),$(vpath_srclist)))
  55
  56 # Installation directories.
  57 libdocdir    = $(datarootdir)/doc/$(book_name)
  58 referencedir = $(libdocdir)/reference
  59 htmlrefdir   = $(referencedir)/html
  60 devhelpdir   = $(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.
  64 if DIST_DOCTOOLS
  65 doctools_dist_files = $(addprefix $(MMDOCTOOLDIR)/,doc-postprocess.pl doc-install.pl tagfile-to-devhelp2.xsl doxygen-extra.css)
  66 else
  67 doctools_dist_files =
  68 endif
  69
  70 if ENABLE_DOCUMENTATION
  71 doc_build_files  = $(doxytagfile) $(devhelpfile)
  72 doc_inst_targets = install-htmlref install-devhelp
  73 doc_inst_files   = $(doxytagfile)
  74 doc_dist_files   = $(devhelpfile) $(call vpath_listall,$(htmlref_patterns))
  75 else
  76 doc_build_files  =
  77 doc_inst_targets =
  78 doc_inst_files   =
  79 doc_dist_files   =
  80 endif
  81
  82 dist_reference_DATA = $(strip $(doc_inst_files))
  83 dist_noinst_DATA    = $(strip $(doctools_dist_files) $(doc_dist_files))
  84
  85 DISTCLEANFILES       = $(doc_outdir)/doxygen.log
  86 MAINTAINERCLEANFILES = $(doxytagfile) $(devhelpfile) $(doc_outdir)/html/*
  87
  88 # The generic bit of the doc-install.pl command line.
  89 doc_install_cmd = $(doc_install) --verbose --mode=0644
  90
  91 # Transform $(datarootdir) into a URI to match MM_ARG_WITH_TAGFILE_DOC().
  92 datarootdir_esc = $(subst $(subst ,, ),%20,$(subst \,/,$(datarootdir)))
  93 docdir_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.
  99 htmlref_relinst = $(subst @$(docdir_base_uri)/,@../../../,$(DOCINSTALL_FLAGS))
 100 htmlref_install = $(doc_install_cmd) $(htmlref_relinst)
 101
 102 # The command and options used to install the Devhelp file.
 103 devhelp_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.
 107 htmlref_patterns_dup   = $(foreach item,$(htmlref_patterns),'$(item)' '$(srcdir)/$(item)')
 108 htmlref_patterns_quote = $(patsubst %,'%',$(htmlref_patterns))
 109 htmlref_patterns_vpath = $(if $(srcdir:.=),$(htmlref_patterns_dup),$(htmlref_patterns_quote))
 110
 111 # Expand to a list of -name 'PATTERN' arguments for use with 'find'.
 112 htmlref_find_patterns = $(patsubst %,-name '%' -o,$(notdir $(htmlref_patterns))) -false
 113
 114 # The parameters to the Doxygen-to-Devhelp XSLT script
 115 dh_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.
 121 doc_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.
 128 if MAINTAINER_MODE
 129 doc_dependencies = $(doc_config_deps) $(doc_input)
 130 else
 131 doc_dependencies =
 132 endif
 133
 134 # Export this variable for use in the Doxygen configuration file.
 135 export 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.
 141 all-local: $(doc_build_files)
 142
 143 # Hook up custom rules for translating references to external documentation
 144 # to the actual location at install time.
 145 install-data-local: $(doc_inst_targets)
 146
 147 # Hook up corresponding custom uninstall rules.
 148 uninstall-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.
 155 install-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.
 163 uninstall-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.
 170 install-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.
 176 uninstall-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: