docs/mk/api.mk

   1 ##===- docs/mk/api.mk --------------------------------------*- Makefile -*-===##
   2 #
   3 #                     The LLVM Compiler Infrastructure
   4 #
   5 # This file is distributed under the University of Illinois Open Source
   6 # License. See LICENSE.TXT for details.
   7 #
   8 ##===----------------------------------------------------------------------===##
   9 #
  10 # Generated API documentation support module.
  11 #
  12 # The following variables must be defined before including this makefile:
  13 #
  14 #       API.Project  formal project name. eg. LLVM or Clang.
  15 #       API.project  filesystem project name. eg. llvm or clang.
  16 #       API.srcdir   top-most source dir used in doxygen .cfg file.
  17 #
  18 ##===----------------------------------------------------------------------===##
  19
  20 include $(LLVM_SRC_ROOT)/docs/mk/common.defs.mk
  21
  22 API.in/  = $(PROJ_SRC_DIR)/
  23 API.out/ = ./
  24
  25 API.html/    = $(API.out/)html/api/
  26 API.html.tar = $(API.out/)html-api.tar.gz
  27
  28 API.doxygen                     = $(DOXYGEN)
  29 API.doxygen.target              = $(API.html/)index.html
  30 API.doxygen.extradeps           = $(foreach x,html xml h,$(wildcard $(API.in/)*.$(x)))
  31 API.doxygen.cfg                 = $(API.out/)doxygen.cfg
  32 API.doxygen.cfg.srcdir          = $(API.srcdir)
  33 API.doxygen.cfg.objdir          = .
  34 API.doxygen.cfg.output_dir      = $(API.out/)
  35 API.doxygen.cfg.dot             = # blank and doxygen will search path for 'dot'
  36 API.doxygen.cfg.opts            = $(call SELECT,API.doxygen.cfg.opts,$(HOST_OS))
  37 API.doxygen.cfg.opts.__.Darwin  = DOT_FONTNAME=Monaco DOT_FONTSIZE=8
  38 API.doxygen.cfg.opts.__.Linux   = DOT_FONTNAME=FreeSans DOT_FONTSIZE=9
  39 API.doxygen.cfg.opts.__.default = # values from file
  40 API.doxygen.cfg.version         = $(call fn.SVN.LCREV,$(API.srcdir))
  41
  42 API.doxygen.css = $(API.html/)api.css \
  43                   $(API.html/)api.ie.css
  44
  45 ifdef VERBOSE
  46 API.doxygen.cfg.opts := QUIET=NO WARN_IF_DOC_ERROR=YES $(API.doxygen.cfg.opts)
  47 endif
  48
  49 API.files += $(API.html.tar)
  50 API.files += $(API.doxygen.cfg)
  51 API.files += $(API.doxygen.css)
  52 API.files += $(API.doxygen.target)
  53
  54 DOCS.mkdir.files += $(API.files)
  55
  56 ##===----------------------------------------------------------------------===##
  57
  58 INSTALL.out/        = $(PROJ_prefix)/share/
  59 INSTALL.doc/        = $(INSTALL.out/)doc/$(API.project)/
  60
  61 INSTALL.html/       = $(INSTALL.doc/)html/api/
  62 INSTALL.html.target = $(API.doxygen.target:$(API.html/)%=$(INSTALL.html/)%)
  63 INSTALL.html.tar    = $(INSTALL.doc/)$(notdir $(API.html.tar))
  64
  65 INSTALL.files += $(INSTALL.html.tar)
  66
  67 DOCS.mkdir.files += $(INSTALL.doc/)file-placebo
  68 DOCS.mkdir.files += $(INSTALL.files)
  69
  70 ##===----------------------------------------------------------------------===##
  71
  72 clean-local::
  73         -$(Verb) $(RM) -f $(API.files)
  74         -$(Verb) $(call fn.RMRF,$(API.html/))
  75
  76 ifeq ($(ENABLE_DOXYGEN),1)
  77 all:: docs docs-tar
  78 install-local:: install-docs
  79 uninstall-local:: uninstall-docs
  80 endif
  81
  82 ##===----------------------------------------------------------------------===##
  83
  84 .PHONY: docs-tar
  85 docs-tar: $(API.html.tar)
  86
  87 .PHONY: docs
  88 docs: $(API.doxygen.target)
  89
  90 $(API.html.tar): | $(dir $(API.html.tar))
  91 $(API.html.tar): $(API.doxygen.target)
  92         $(Echo) Creating $(API.Project) API documentation tarball
  93         $(Verb) (set -e; cd $(API.out/); \
  94           $(TAR) cf - --exclude='*.md5' --exclude='*.map' html/api) \
  95           $(call fn.PIPE.COMP,$@) > $@
  96
  97 $(API.doxygen.cfg): | $(dir $(API.doxygen.cfg))
  98 $(API.doxygen.cfg): $(notdir $(API.doxygen.cfg)).in
  99         $(Echo) Generating $(API.Project) doxygen config
 100         $(Verb) $(CAT) $< | $(SED) \
 101           -e 's,@srcdir@,$(API.doxygen.cfg.srcdir),g' \
 102           -e 's,@objdir@,$(API.doxygen.cfg.objdir),g' \
 103           -e 's,@output_dir@,$(API.doxygen.cfg.output_dir),g' \
 104           -e 's,@dot@,$(API.doxygen.cfg.dot),g' \
 105           -e 's,@version@,$(API.doxygen.cfg.version),g' \
 106           > $@
 107
 108 $(API.html/)api.css: | $(dir $(API.html/)api.css)
 109 $(API.html/)api.css: api.css
 110         $(Echo) Copying $(API.Project) doxygen stylesheet
 111         $(Verb) $(CP) $< $@
 112
 113 # IE misbehaves when browser-specific constructs are used.
 114 # This target strips them out to create an IE-specific css file.
 115 # The following is an example of setting background to an extension.
 116 # With IE instead of skipping an unrecognized extension it resets
 117 # the background:
 118 #
 119 #   background: -webkit-gradient(...)
 120 #
 121 # Note this simple approach assumes source has strippable single-lines.
 122 #
 123 $(API.html/)api.ie.css: | $(dir $(API.html/)api.ie.css)
 124 $(API.html/)api.ie.css: api.css
 125         $(Echo) Generating $(API.Project) doxygen stylesheet for IE
 126         $(Verb) $(CAT) $< | egrep -v -e '-(moz|webkit)' > $@
 127
 128 # Generate API docs.
 129 #
 130 # Define API.nodot=1 to not use 'dot' tool even if available.
 131 # In this mode doxygen has built-in support to generate only class-diagrams
 132 # and thus all other diagrams are skipped. Shaves 80% off generate time.
 133 #
 134 # We pipe (doxygen.cfg + overrides) to doxygen. This allows us to override
 135 # almost any setting in doxygen.cfg file without having to edit it.
 136 #
 137 ifneq (undefined,$(origin API.nodot))
 138 $(API.doxygen.target): API.doxygen.cfg.opts += HAVE_DOT=NO
 139 $(API.doxygen.target): API.doxygen.target.msg = " (FAST)"
 140 endif
 141 $(API.doxygen.target): | $(dir $(API.doxygen.target))
 142 $(API.doxygen.target): $(API.doxygen.cfg)
 143 $(API.doxygen.target): $(API.doxygen.css)
 144 $(API.doxygen.target): $(API.doxygen.extradeps)
 145         $(Echo) Generating $(API.Project) API documentation$(API.doxygen.target.msg)
 146         $(Verb) ($(CAT) $(API.doxygen.cfg)$(foreach n,$(API.doxygen.cfg.opts),; echo '$n')) | \
 147           $(API.doxygen) -
 148
 149 ##===----------------------------------------------------------------------===##
 150
 151 .PHONY: install-docs
 152 install-docs: $(INSTALL.html.tar)
 153 install-docs: $(INSTALL.html.target)
 154
 155 $(INSTALL.html.target): | $(INSTALL.doc/)
 156 $(INSTALL.html.target): $(API.html.tar)
 157         $(Echo) Installing $(API.Project) API documentation
 158         $(Verb) $(CAT) $(API.html.tar) $(call fn.PIPE.DECOMP,$(API.html.tar)) | \
 159           (set -e; cd $(INSTALL.doc/); $(TAR) xf -)
 160         @touch $@
 161
 162 $(INSTALL.html.tar): | $(dir $(INSTALL.html.tar))
 163 $(INSTALL.html.tar): $(API.html.tar)
 164         $(Echo) Installing $(API.Project) API documentation tarball
 165         $(Verb) $(DataInstall) $< $@
 166
 167 uninstall-docs:
 168         $(Echo) Uninstalling $(API.Project) API documentation
 169         -$(Verb) $(RM) -f $(INSTALL.files)
 170         -$(Verb) $(call fn.RMRF,$(INSTALL.html/))
 171
 172 ##===----------------------------------------------------------------------===##
 173
 174 DOCS.vars.mandatory += API.Project API.project API.srcdir
 175 DOCS.vars.print     += $(sort $(filter INSTALL.%/,$(.VARIABLES)))
 176
 177 HELP.sections += API.help
 178
 179 define API.help
 180   API Documentation Module. This module is srcdir/objdir build-friendly.
 181
 182   WARNING: The following directories are recursively deleted during cleanup
 183   procedures. Be sure not to mix files therein or bad things will happen.
 184
 185     $(API.html/)
 186     $(INSTALL.html/)
 187
 188   ------------------------------------------------------------------------------
 189   TARGET          NOTES
 190   ------------------------------------------------------------------------------
 191  *all             invokes target docs
 192  *install         invokes target install-docs
 193  *uninstall       invokes target uninstall-docs
 194   ------------------------------------------------------------------------------
 195   docs            generate API docs from sources using doxygen
 196   ------------------------------------------------------------------------------
 197   docs-tar        create docs tarball $(API.html.tar)
 198   clean           remove built files
 199   install-docs    install to $(INSTALL.doc/)
 200   uninstall-docs  remove installed files
 201   ------------------------------------------------------------------------------
 202   (targets marked with '*' require configure --enable-doxygen)
 203 endef
 204
 205 include $(LLVM_SRC_ROOT)/docs/mk/common.rules.mk