Dean Camera
9 years ago
parent
75b68126d0
commit
3126cbbf96
@ -0,0 +1,94 @@
|
||||
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
|
||||
Loading…
Reference in new issue