LUFA/Build/DMBS/DMBS/WritingYourOwnModules.md

   1 DMBS - Dean's Makefile Build System
   2 ===================================
   3
   4
   5 Writing Your Own Modules
   6 ------------------------
   7
   8 A DMBS module consists of the several boilerplate sections, explained below.
   9
  10 ## The DMBS module hooks
  11
  12 Your module needs to advertise to DMBS its name, its makefile targets, the
  13 required and optional variables, and the variables and macros the module
  14 provides for use elsewhere. This is achieved with the following section:
  15
  16     DMBS_BUILD_MODULES         += EXAMPLE
  17     DMBS_BUILD_TARGETS         += example-target another-target
  18     DMBS_BUILD_MANDATORY_VARS  += MANDATORY_NAME ALSO_MANDATORY
  19     DMBS_BUILD_OPTIONAL_VARS   += OPTIONAL_NAME ALSO_OPTIONAL
  20     DMBS_BUILD_PROVIDED_VARS   += MEANING_OF_LIFE
  21     DMBS_BUILD_PROVIDED_MACROS += STRIP_WHITESPACE
  22
  23 The example above declares that this module is called `EXAMPLE`, and exposes the
  24 listed targets, variable requirements and provides variables and macros.
  25
  26 Your module name and provided variable/macro names must be unique, however you
  27 can (and should) re-use variable names where appropriate if they apply to
  28 several modules (such as `ARCH` to specify the project's microcontroller
  29 architecture). Re-using targets is not recommended, but can be used to extend
  30 the dependencies of another module's targets.
  31
  32 ## Importing the CORE module
  33
  34 Next, your module should always import the DMBS `CORE` module, via the
  35 following:
  36
  37     # Conditionally import the CORE module of DMBS if it is not already imported
  38     DMBS_MODULE_PATH := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
  39     ifeq ($(findstring CORE, $(DMBS_BUILD_MODULES)),)
  40       include $(DMBS_MODULE_PATH)/core.mk
  41     endif
  42
  43 This ensures that the `make help` target is always available. In addition, the
  44 `CORE` module exposes some [commonly used macros and variables](core.md) to
  45 your module.
  46
  47 ## Setting optional variable's defaults
  48
  49 If a variable is optional, you should provide a default value. Do this via the
  50 `?=` operator of `make`, which sets a variable's value if it has not yet been
  51 set:
  52
  53     MY_OPTIONAL_VARIABLE ?= some_default_value
  54
  55 ## Sanity checking user input
  56
  57 Sanity checks are what make DMBS useful. Where possible, validate user input and
  58 convert generated errors to human-friendly messages. This can be achieved by
  59 enforcing that all the declared module mandatory variables have been set by the
  60 user:
  61
  62     # Sanity-check values of mandatory user-supplied variables
  63     $(foreach MANDATORY_VAR, $(DMBS_BUILD_MANDATORY_VARS), $(call ERROR_IF_UNSET, $(MANDATORY_VAR)))
  64
  65 As well as complaining if they are set, but currently empty:
  66
  67     $(call ERROR_IF_EMPTY, SOME_MANDATORY_VARIABLE)
  68     $(call ERROR_IF_EMPTY, SOME_OPTIONAL_BUT_NON_EMPTY_VARIABLE)
  69
  70 Or even if they are boolean (`Y` or `N`) variables that have an invalid value:
  71
  72     $(call ERROR_IF_NONBOOL, SOME_BOOL_VARIABLE)
  73
  74 ## Adding targets
  75
  76 The meat of a DMBS module is the targets, which are run when the user types
  77 `make {target name}` from the command line. These can be as complex or simple
  78 as you like. See the GNU make manual for information on writing make targets.
  79
  80     example-target:
  81         echo "Your DMBS module works!"
  82
  83 ## And finally, list the PHONYs
  84
  85 Important in GNU Make is the concept of phony targets; this special directive
  86 tells make that a given target should never be considered a valid file. Listing
  87 phonies ensures that, for example, if your module had a target called `build`,
  88 it would always run when the user types `make build` from the command line, even
  89 if a file called `build` existed in the user project folder.
  90
  91 You can list module-internal targets here, as well as mark all public targets
  92 via the module header's `DMBS_BUILD_TARGETS` variable.
  93
  94     # Phony build targets for this module
  95     .PHONY: $(DMBS_BUILD_TARGETS) some-module-internal-target another-internal-target