LUFA/Build/lufa_doxygen.mk

   1 #
   2 #             LUFA Library
   3 #     Copyright (C) Dean Camera, 2016.
   4 #
   5 #  dean [at] fourwalledcubicle [dot] com
   6 #           www.lufa-lib.org
   7 #
   8
   9 LUFA_BUILD_MODULES         += DOXYGEN
  10 LUFA_BUILD_TARGETS         += doxygen doxygen_upgrade doxygen_create
  11 LUFA_BUILD_MANDATORY_VARS  += LUFA_PATH
  12 LUFA_BUILD_OPTIONAL_VARS   += DOXYGEN_CONF DOXYGEN_FAIL_ON_WARNING DOXYGEN_OVERRIDE_PARAMS
  13 LUFA_BUILD_PROVIDED_VARS   +=
  14 LUFA_BUILD_PROVIDED_MACROS +=
  15
  16 # -----------------------------------------------------------------------------
  17 #                 LUFA Doxygen Buildsystem Makefile Module.
  18 # -----------------------------------------------------------------------------
  19 # DESCRIPTION:
  20 #   Provides a set of targets to automatically build Doxygen documentation for
  21 #   a project (see www.doxygen.org).
  22 # -----------------------------------------------------------------------------
  23 # TARGETS:
  24 #
  25 #    doxygen                   - Build Doxygen Documentation
  26 #    doxygen_create            - Create a new Doxygen configuration file using
  27 #                                the latest template
  28 #    doxygen_upgrade           - Upgrade an existing Doxygen configuration file
  29 #                                to the latest template
  30 #
  31 # MANDATORY PARAMETERS:
  32 #
  33 #    LUFA_PATH                 - Path to the LUFA library core
  34 #
  35 # OPTIONAL PARAMETERS:
  36 #
  37 #    DOXYGEN_CONF              - Doxygen configuration filename
  38 #    DOXYGEN_FAIL_ON_WARNING   - Set to Y to fail the build on Doxygen warnings,
  39 #                                N to continue even if warnings occur
  40 #    DOXYGEN_OVERRIDE_PARAMS   - Parameters to override in the doxygen
  41 #                                configuration file
  42 # PROVIDED VARIABLES:
  43 #
  44 #    (None)
  45 #
  46 # PROVIDED MACROS:
  47 #
  48 #    (None)
  49 #
  50 # -----------------------------------------------------------------------------
  51
  52 SHELL = /bin/sh
  53
  54 ERROR_IF_UNSET   ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
  55 ERROR_IF_EMPTY   ?= $(if $(strip $($(strip $(1)))), , $(error Makefile $(strip $(1)) option cannot be blank))
  56 ERROR_IF_NONBOOL ?= $(if $(filter Y N, $($(strip $(1)))), , $(error Makefile $(strip $(1)) option must be Y or N))
  57
  58 # Default values of optionally user-supplied variables
  59 DOXYGEN_CONF            ?= doxyfile
  60 DOXYGEN_FAIL_ON_WARNING ?= Y
  61 DOXYGEN_OVERRIDE_PARAMS ?= QUIET=YES HTML_EXTRA_STYLESHEET=$(patsubst %/,%,$(LUFA_PATH))/DoxygenPages/Style/Style.css
  62
  63 # Sanity check user supplied values
  64 $(foreach MANDATORY_VAR, $(LUFA_BUILD_MANDATORY_VARS), $(call ERROR_IF_UNSET, $(MANDATORY_VAR)))
  65 $(call ERROR_IF_EMPTY, DOXYGEN_CONF)
  66 $(call ERROR_IF_EMPTY, LUFA_PATH)
  67 $(call ERROR_IF_NONBOOL, DOXYGEN_FAIL_ON_WARNING)
  68
  69 # Output Messages
  70 MSG_DOXYGEN_CMD         := ' [DOXYGEN] :'
  71
  72 # Determine Doxygen invocation command
  73 BASE_DOXYGEN_CMD := ( cat $(DOXYGEN_CONF) $(DOXYGEN_OVERRIDE_PARAMS:%=; echo "%") ) | doxygen -
  74 ifeq ($(DOXYGEN_FAIL_ON_WARNING), Y)
  75    DOXYGEN_CMD := if ( $(BASE_DOXYGEN_CMD) 2>&1 | grep -v -e "[Ww]arning:\|recompile doxygen" ;); then exit 1; fi;
  76 else
  77    DOXYGEN_CMD := $(BASE_DOXYGEN_CMD)
  78 endif
  79
  80 # Error if the specified Doxygen configuration file does not exist
  81 $(DOXYGEN_CONF):
  82         $(error Doxygen configuration file $@ does not exist)
  83
  84 # Builds the project documentation using the specified configuration file and the DOXYGEN tool
  85 doxygen: $(DOXYGEN_CONF) $(MAKEFILE_LIST)
  86         @echo $(MSG_DOXYGEN_CMD) Configuration file \"$(DOXYGEN_CONF)\" with parameters \"$(DOXYGEN_OVERRIDE_PARAMS)\"
  87         $(DOXYGEN_CMD)
  88
  89 # Upgrades an existing Doxygen configuration file to the latest Doxygen template, preserving settings
  90 doxygen_upgrade: $(DOXYGEN_CONF) $(MAKEFILE_LIST)
  91         @echo $(MSG_DOXYGEN_CMD) Upgrading configuration file \"$(DOXYGEN_CONF)\" with latest template
  92         doxygen -u $(DOXYGEN_CONF) > /dev/null
  93
  94 # Creates a new Doxygen configuration file with the set file name
  95 doxygen_create: $(MAKEFILE_LIST)
  96         @echo $(MSG_DOXYGEN_CMD) Creating new configuration file \"$(DOXYGEN_CONF)\" with latest template
  97         doxygen -g $(DOXYGEN_CONF) > /dev/null
  98
  99 # Phony build targets for this module
 100 .PHONY: doxygen doxygen_upgrade doxygen_create