diff --git a/DMBS/Modules.md b/DMBS/ModulesOverview.md similarity index 50% rename from DMBS/Modules.md rename to DMBS/ModulesOverview.md index 65caf8a..1fd9cc1 100644 --- a/DMBS/Modules.md +++ b/DMBS/ModulesOverview.md @@ -3,7 +3,7 @@ DMBS - Dean's Makefile Build System Modules Overview ---------------- +---------------- The following modules are currently included: @@ -16,11 +16,23 @@ The following modules are currently included: - [GCC](gcc.md) - Compiling/Assembling/Linking with GCC - [HID](hid.md) - Device Programming -To use a module, you will need to add the following boilerplate to your +## Importing modules into your project makefile + +To use a module, it is recommended to add the following boilerplate to your makefile: # Include DMBS build script makefiles DMBS_PATH ?= ../DMBS -Which is then used to indicate the location of your DMBS installation, relative -to the current directory. +Which can then used to indicate the location of your DMBS installation, relative +to the current directory, when importing modules. For example: + + DMBS_PATH ?= ../DMBS + include $(DMBS_PATH)/core.mk + include $(DMBS_PATH)/gcc.mk + +Imports the `CORE` and `GCC` modules from DMBS using a single path relative to +your project's makefile. + +If you wish to write your own DMBS module(s), +[see the documentation here for more details.](WritingYourOwnModules.md) diff --git a/DMBS/WritingYourOwnModules.md b/DMBS/WritingYourOwnModules.md new file mode 100644 index 0000000..3ecbb33 --- /dev/null +++ b/DMBS/WritingYourOwnModules.md @@ -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 diff --git a/DMBS/core.mk b/DMBS/core.mk index 0e1399c..7fdb7f2 100644 --- a/DMBS/core.mk +++ b/DMBS/core.mk @@ -16,15 +16,15 @@ DMBS_BUILD_PROVIDED_MACROS += DMBS_CHECK_VERSION ERROR_IF_UNSET ERROR_IF_EMPTY E SHELL = /bin/sh # Current DMBS release version -DMBS_VERSION = 20160403 +DMBS_VERSION := 20160403 # Macro to check the DMBS version, aborts if the given DMBS version is below the current version DMBS_CHECK_VERSION ?= $(if $(filter-out 0, $(shell test $(DMBS_VERSION) -lt $(1); echo $$?)), , $(error DMBS version $(1) or newer required, current version is $(DMBS_VERSION))) # Macros to use in other modules to check various conditions -ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set)) -ERROR_IF_EMPTY ?= $(if $(strip $($(strip $(1)))), , $(error Makefile $(strip $(1)) option cannot be blank)) -ERROR_IF_NONBOOL ?= $(if $(filter Y N, $($(strip $(1)))), , $(error Makefile $(strip $(1)) option must be Y or N)) +ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set)) +ERROR_IF_EMPTY ?= $(if $(strip $($(strip $(1)))), , $(error Makefile $(strip $(1)) option cannot be blank)) +ERROR_IF_NONBOOL ?= $(if $(filter Y N, $($(strip $(1)))), , $(error Makefile $(strip $(1)) option must be Y or N)) # Converts a given input to a printable output using "(None)" if no items are in the list CONVERT_TO_PRINTABLE = $(if $(strip $(1)), $(1), (None)) diff --git a/Readme.md b/Readme.md index 05125ce..f4f7a5f 100644 --- a/Readme.md +++ b/Readme.md @@ -35,7 +35,8 @@ are included via a GNU Make `include` directive. While the DMBS `core` module is always required, you can pick and choose what other modules you wish to add to your user project. -[See here for the documentation on the individual modules provided by DMBS.](DMBS/Modules.md) +[See here for the documentation on the individual modules provided by DMBS.](DMBS/ModulesOverview.md) +If you're interested in writing your own DMBS module(s), [see here.](DMBS/WritingYourOwnModules.md) Here's an example user makefile: @@ -72,6 +73,21 @@ As modules are added, you can get a list of available targets by simply typing as well as mandatory and optional variables and exposed variables and macros. +Distribution +---------------- + +You can embed DMBS in your project any way you like - some options are: +1. A git submodule +2. A source tarball +3. A manually copied extracted archive + +The intention of DMBS is that users can just import it from whatever source +they like. If your project needs to extend the existing modules in an unusual +manner, or if you want to provide your own modules, you can include them in +your project repository (or submit a patch to DMBS if your module is generic +enough to warrant wide use). + + License ----------------