diff options
Diffstat (limited to 'docs/mk/api.mk')
| -rw-r--r-- | docs/mk/api.mk | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/docs/mk/api.mk b/docs/mk/api.mk new file mode 100644 index 0000000000..74cd2db456 --- /dev/null +++ b/docs/mk/api.mk @@ -0,0 +1,205 @@ +##===- docs/mk/api.mk --------------------------------------*- Makefile -*-===## +# +# The LLVM Compiler Infrastructure +# +# This file is distributed under the University of Illinois Open Source +# License. See LICENSE.TXT for details. +# +##===----------------------------------------------------------------------===## +# +# Generated API documentation support module. +# +# The following variables must be defined before including this makefile: +# +# API.Project formal project name. eg. LLVM or Clang. +# API.project filesystem project name. eg. llvm or clang. +# API.srcdir top-most source dir used in doxygen .cfg file. +# +##===----------------------------------------------------------------------===## + +include $(LLVM_SRC_ROOT)/docs/mk/common.defs.mk + +API.in/ = $(PROJ_SRC_DIR)/ +API.out/ = ./ + +API.html/ = $(API.out/)html/api/ +API.html.tar = $(API.out/)html-api.tar.gz + +API.doxygen = $(DOXYGEN) +API.doxygen.target = $(API.html/)index.html +API.doxygen.extradeps = $(foreach x,html xml h,$(wildcard $(API.in/)*.$(x))) +API.doxygen.cfg = $(API.out/)doxygen.cfg +API.doxygen.cfg.srcdir = $(API.srcdir) +API.doxygen.cfg.objdir = . +API.doxygen.cfg.output_dir = $(API.out/) +API.doxygen.cfg.dot = # blank and doxygen will search path for 'dot' +API.doxygen.cfg.opts = $(call SELECT,API.doxygen.cfg.opts,$(HOST_OS)) +API.doxygen.cfg.opts.__.Darwin = DOT_FONTNAME=Monaco DOT_FONTSIZE=8 +API.doxygen.cfg.opts.__.Linux = DOT_FONTNAME=FreeSans DOT_FONTSIZE=9 +API.doxygen.cfg.opts.__.default = # values from file +API.doxygen.cfg.version = $(call fn.SVN.LCREV,$(API.srcdir)) + +API.doxygen.css = $(API.html/)api.css \ + $(API.html/)api.ie.css + +ifdef VERBOSE +API.doxygen.cfg.opts := QUIET=NO WARN_IF_DOC_ERROR=YES $(API.doxygen.cfg.opts) +endif + +API.files += $(API.html.tar) +API.files += $(API.doxygen.cfg) +API.files += $(API.doxygen.css) +API.files += $(API.doxygen.target) + +DOCS.mkdir.files += $(API.files) + +##===----------------------------------------------------------------------===## + +INSTALL.out/ = $(PROJ_prefix)/share/ +INSTALL.doc/ = $(INSTALL.out/)doc/$(API.project)/ + +INSTALL.html/ = $(INSTALL.doc/)html/api/ +INSTALL.html.target = $(API.doxygen.target:$(API.html/)%=$(INSTALL.html/)%) +INSTALL.html.tar = $(INSTALL.doc/)$(notdir $(API.html.tar)) + +INSTALL.files += $(INSTALL.html.tar) + +DOCS.mkdir.files += $(INSTALL.doc/)file-placebo +DOCS.mkdir.files += $(INSTALL.files) + +##===----------------------------------------------------------------------===## + +clean-local:: + -$(Verb) $(RM) -f $(API.files) + -$(Verb) $(call fn.RMRF,$(API.html/)) + +ifeq ($(ENABLE_DOXYGEN),1) +all:: docs docs-tar +install-local:: install-docs +uninstall-local:: uninstall-docs +endif + +##===----------------------------------------------------------------------===## + +.PHONY: docs-tar +docs-tar: $(API.html.tar) + +.PHONY: docs +docs: $(API.doxygen.target) + +$(API.html.tar): | $(dir $(API.html.tar)) +$(API.html.tar): $(API.doxygen.target) + $(Echo) Creating $(API.Project) API documentation tarball + $(Verb) (set -e; cd $(API.out/); \ + $(TAR) cf - --exclude='*.md5' --exclude='*.map' html/api) \ + $(call fn.PIPE.COMP,$@) > $@ + +$(API.doxygen.cfg): | $(dir $(API.doxygen.cfg)) +$(API.doxygen.cfg): $(notdir $(API.doxygen.cfg)).in + $(Echo) Generating $(API.Project) doxygen config + $(Verb) $(CAT) $< | $(SED) \ + -e 's,@srcdir@,$(API.doxygen.cfg.srcdir),g' \ + -e 's,@objdir@,$(API.doxygen.cfg.objdir),g' \ + -e 's,@output_dir@,$(API.doxygen.cfg.output_dir),g' \ + -e 's,@dot@,$(API.doxygen.cfg.dot),g' \ + -e 's,@version@,$(API.doxygen.cfg.version),g' \ + > $@ + +$(API.html/)api.css: | $(dir $(API.html/)api.css) +$(API.html/)api.css: api.css + $(Echo) Copying $(API.Project) doxygen stylesheet + $(Verb) $(CP) $< $@ + +# IE misbehaves when browser-specific constructs are used. +# This target strips them out to create an IE-specific css file. +# The following is an example of setting background to an extension. +# With IE instead of skipping an unrecognized extension it resets +# the background: +# +# background: -webkit-gradient(...) +# +# Note this simple approach assumes source has strippable single-lines. +# +$(API.html/)api.ie.css: | $(dir $(API.html/)api.ie.css) +$(API.html/)api.ie.css: api.css + $(Echo) Generating $(API.Project) doxygen stylesheet for IE + $(Verb) $(CAT) $< | egrep -v -e '-(moz|webkit)' > $@ + +# Generate API docs. +# +# Define API.nodot=1 to not use 'dot' tool even if available. +# In this mode doxygen has built-in support to generate only class-diagrams +# and thus all other diagrams are skipped. Shaves 80% off generate time. +# +# We pipe (doxygen.cfg + overrides) to doxygen. This allows us to override +# almost any setting in doxygen.cfg file without having to edit it. +# +ifneq (undefined,$(origin API.nodot)) +$(API.doxygen.target): API.doxygen.cfg.opts += HAVE_DOT=NO +$(API.doxygen.target): API.doxygen.target.msg = " (FAST)" +endif +$(API.doxygen.target): | $(dir $(API.doxygen.target)) +$(API.doxygen.target): $(API.doxygen.cfg) +$(API.doxygen.target): $(API.doxygen.css) +$(API.doxygen.target): $(API.doxygen.extradeps) + $(Echo) Generating $(API.Project) API documentation$(API.doxygen.target.msg) + $(Verb) ($(CAT) $(API.doxygen.cfg)$(foreach n,$(API.doxygen.cfg.opts),; echo '$n')) | \ + $(API.doxygen) - + +##===----------------------------------------------------------------------===## + +.PHONY: install-docs +install-docs: $(INSTALL.html.tar) +install-docs: $(INSTALL.html.target) + +$(INSTALL.html.target): | $(INSTALL.doc/) +$(INSTALL.html.target): $(API.html.tar) + $(Echo) Installing $(API.Project) API documentation + $(Verb) $(CAT) $(API.html.tar) $(call fn.PIPE.DECOMP,$(API.html.tar)) | \ + (set -e; cd $(INSTALL.doc/); $(TAR) xf -) + @touch $@ + +$(INSTALL.html.tar): | $(dir $(INSTALL.html.tar)) +$(INSTALL.html.tar): $(API.html.tar) + $(Echo) Installing $(API.Project) API documentation tarball + $(Verb) $(DataInstall) $< $@ + +uninstall-docs: + $(Echo) Uninstalling $(API.Project) API documentation + -$(Verb) $(RM) -f $(INSTALL.files) + -$(Verb) $(call fn.RMRF,$(INSTALL.html/)) + +##===----------------------------------------------------------------------===## + +DOCS.vars.mandatory += API.Project API.project API.srcdir +DOCS.vars.print += $(sort $(filter INSTALL.%/,$(.VARIABLES))) + +HELP.sections += API.help + +define API.help + API Documentation Module. This module is srcdir/objdir build-friendly. + + WARNING: The following directories are recursively deleted during cleanup + procedures. Be sure not to mix files therein or bad things will happen. + + $(API.html/) + $(INSTALL.html/) + + ------------------------------------------------------------------------------ + TARGET NOTES + ------------------------------------------------------------------------------ + *all invokes target docs + *install invokes target install-docs + *uninstall invokes target uninstall-docs + ------------------------------------------------------------------------------ + docs generate API docs from sources using doxygen + ------------------------------------------------------------------------------ + docs-tar create docs tarball $(API.html.tar) + clean remove built files + install-docs install to $(INSTALL.doc/) + uninstall-docs remove installed files + ------------------------------------------------------------------------------ + (targets marked with '*' require configure --enable-doxygen) +endef + +include $(LLVM_SRC_ROOT)/docs/mk/common.rules.mk |