diff options
Diffstat (limited to 'lib/lufa/LUFA/Build/DMBS/DMBS/WritingYourOwnModules.md')
| -rw-r--r-- | lib/lufa/LUFA/Build/DMBS/DMBS/WritingYourOwnModules.md | 95 |
1 files changed, 0 insertions, 95 deletions
diff --git a/lib/lufa/LUFA/Build/DMBS/DMBS/WritingYourOwnModules.md b/lib/lufa/LUFA/Build/DMBS/DMBS/WritingYourOwnModules.md deleted file mode 100644 index 16df7a53bb..0000000000 --- a/lib/lufa/LUFA/Build/DMBS/DMBS/WritingYourOwnModules.md +++ /dev/null @@ -1,95 +0,0 @@ -DMBS - Dean's Makefile Build System -=================================== - - -Writing Your Own Modules ------------------------- - -A DMBS module consists of the several boilerplate sections, explained below. - -## The DMBS module hooks - -Your module needs to advertise to DMBS its name, its makefile targets, the -required and optional variables, and the variables and macros the module -provides for use elsewhere. This is achieved with the following section: - - DMBS_BUILD_MODULES += EXAMPLE - DMBS_BUILD_TARGETS += example-target another-target - DMBS_BUILD_MANDATORY_VARS += MANDATORY_NAME ALSO_MANDATORY - DMBS_BUILD_OPTIONAL_VARS += OPTIONAL_NAME ALSO_OPTIONAL - DMBS_BUILD_PROVIDED_VARS += MEANING_OF_LIFE - DMBS_BUILD_PROVIDED_MACROS += STRIP_WHITESPACE - -The example above declares that this module is called `EXAMPLE`, and exposes the -listed targets, variable requirements and provides variables and macros. - -Your module name and provided variable/macro names must be unique, however you -can (and should) re-use variable names where appropriate if they apply to -several modules (such as `ARCH` to specify the project's microcontroller -architecture). Re-using targets is not recommended, but can be used to extend -the dependencies of another module's targets. - -## Importing the CORE module - -Next, your module should always import the DMBS `CORE` module, via the -following: - - # Conditionally import the CORE module of DMBS if it is not already imported - DMBS_MODULE_PATH := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST)))) - ifeq ($(findstring CORE, $(DMBS_BUILD_MODULES)),) - include $(DMBS_MODULE_PATH)/core.mk - endif - -This ensures that the `make help` target is always available. In addition, the -`CORE` module exposes some [commonly used macros and variables](core.md) to -your module. - -## Setting optional variable's defaults - -If a variable is optional, you should provide a default value. Do this via the -`?=` operator of `make`, which sets a variable's value if it has not yet been -set: - - MY_OPTIONAL_VARIABLE ?= some_default_value - -## Sanity checking user input - -Sanity checks are what make DMBS useful. Where possible, validate user input and -convert generated errors to human-friendly messages. This can be achieved by -enforcing that all the declared module mandatory variables have been set by the -user: - - # Sanity-check values of mandatory user-supplied variables - $(foreach MANDATORY_VAR, $(DMBS_BUILD_MANDATORY_VARS), $(call ERROR_IF_UNSET, $(MANDATORY_VAR))) - -As well as complaining if they are set, but currently empty: - - $(call ERROR_IF_EMPTY, SOME_MANDATORY_VARIABLE) - $(call ERROR_IF_EMPTY, SOME_OPTIONAL_BUT_NON_EMPTY_VARIABLE) - -Or even if they are boolean (`Y` or `N`) variables that have an invalid value: - - $(call ERROR_IF_NONBOOL, SOME_BOOL_VARIABLE) - -## Adding targets - -The meat of a DMBS module is the targets, which are run when the user types -`make {target name}` from the command line. These can be as complex or simple -as you like. See the GNU make manual for information on writing make targets. - - example-target: - echo "Your DMBS module works!" - -## And finally, list the PHONYs - -Important in GNU Make is the concept of phony targets; this special directive -tells make that a given target should never be considered a valid file. Listing -phonies ensures that, for example, if your module had a target called `build`, -it would always run when the user types `make build` from the command line, even -if a file called `build` existed in the user project folder. - -You can list module-internal targets here, as well as mark all public targets -via the module header's `DMBS_BUILD_TARGETS` variable. - - # Phony build targets for this module - .PHONY: $(DMBS_BUILD_TARGETS) some-module-internal-target another-internal-target |