+++ /dev/null
-DMBS - Dean's Makefile Build System
-===================================
-
-
-Modules Overview
----------------
-
-The following modules are currently included:
-
- - [ATPROGRAM](atprogram.md) - Device Programming
- - [AVRDUDE](avrdude.md) - Device Programming
- - [CORE](core.md) - DMBS Core Functionality
- - [CPPCHECK](cppcheck.md) - Static Code Analysis
- - [DFU](dfu.md) - Device Programming
- - [DOXYGEN](doxygen.md) - Automated Source Code Documentation
- - [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
-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.
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Modules Overview
+----------------
+
+The following modules are currently included:
+
+ - [ATPROGRAM](atprogram.md) - Device Programming
+ - [AVRDUDE](avrdude.md) - Device Programming
+ - [CORE](core.md) - DMBS Core Functionality
+ - [CPPCHECK](cppcheck.md) - Static Code Analysis
+ - [DFU](dfu.md) - Device Programming
+ - [DOXYGEN](doxygen.md) - Automated Source Code Documentation
+ - [GCC](gcc.md) - Compiling/Assembling/Linking with GCC
+ - [HID](hid.md) - Device Programming
+
+## 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 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)
--- /dev/null
+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
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
-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))
+# 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
# Default values of optionally user-supplied variables
ATPROGRAM_PROGRAMMER ?= atmelice
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
-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))
+# 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
# Default values of optionally user-supplied variables
AVRDUDE_PROGRAMMER ?= jtagicemkii
<tbody>
<tr>
<td>DMBS_VERSION</td>
- <td>Current version of this DMBS release.</td>
+ <td>Current version of this DMBS release, as a ISO 8601 integer (such as `160403` for `2016-04-03`).</td>
</tr>
</tbody>
</table>
<table>
<tbody>
<tr>
- <td>N/A</td>
- <td>This module provides no macros.</td>
+ <td>DMBS_CHECK_VERSION</td>
+ <td>Macro to check the current DMBS version against the first argument and abort if the required version is newer than the current version.</td>
+ </tr>
+ <tr>
+ <td>ERROR_IF_UNSET</td>
+ <td>Macro to check the given makefile variable name passed as the first argument, and abort if it has not been set by any makefile module.</td>
+ </tr>
+ <tr>
+ <td>ERROR_IF_EMPTY</td>
+ <td>Macro to check the given makefile variable name passed as the first argument, and abort if it has an empty value.</td>
+ </tr>
+ <tr>
+ <td>ERROR_IF_NONBOOL</td>
+ <td>Macro to check the given makefile variable name passed as the first argument, and abort if it has a value other than `Y` or `N`.</td>
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_MANDATORY_VARS +=
DMBS_BUILD_OPTIONAL_VARS +=
DMBS_BUILD_PROVIDED_VARS += DMBS_VERSION
-DMBS_BUILD_PROVIDED_MACROS +=
+DMBS_BUILD_PROVIDED_MACROS += DMBS_CHECK_VERSION ERROR_IF_UNSET ERROR_IF_EMPTY ERROR_IF_NONBOOL
SHELL = /bin/sh
# Current DMBS release version
-DMBS_VERSION = 0.4
+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))
# 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))
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
-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))
+# 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
# Default values of optionally user-supplied variables
CPPCHECK_INCLUDES ?=
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
-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))
+# 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
# Sanity-check values of mandatory user-supplied variables
$(foreach MANDATORY_VAR, $(DMBS_BUILD_MANDATORY_VARS), $(call ERROR_IF_UNSET, $(MANDATORY_VAR)))
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
-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))
+# 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
# Default values of optionally user-supplied variables
DOXYGEN_CONF ?= doxyfile
@echo $(MSG_DOXYGEN_CMD) Creating new configuration file \"$(DOXYGEN_CONF)\" with latest template
doxygen -g $(DOXYGEN_CONF) > /dev/null
-# Phony build targets for this module
-.PHONY: $(DMBS_BUILD_TARGETS)
+
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
-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))
+# 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
# Default values of optionally user-supplied variables
COMPILER_PATH ?=
</tr>
</tbody>
</table>
+
+## Module Changelog:
+
+The changes to this module since its initial release are listed below, as of the
+DMBS version where the change was made.
+
+### 20160403
+Initial release.
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-SHELL = /bin/sh
-
+# Conditionally import the CORE module of DMBS if it is not already imported
DMBS_MODULE_PATH := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
-
-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))
+ifeq ($(findstring CORE, $(DMBS_BUILD_MODULES)),)
+ include $(DMBS_MODULE_PATH)/core.mk
+endif
# Sanity-check values of mandatory user-supplied variables
$(foreach MANDATORY_VAR, $(DMBS_BUILD_MANDATORY_VARS), $(call ERROR_IF_UNSET, $(MANDATORY_VAR)))
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:
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
----------------
# Default target
all:
-# Include LUFA-specific DMBS extension modules
-DMBS_LUFA_PATH ?= $(LUFA_PATH)/Build/LUFA
-include $(DMBS_LUFA_PATH)/lufa-sources.mk
-include $(DMBS_LUFA_PATH)/lufa-gcc.mk
-
-# Include common DMBS build system modules
-DMBS_PATH ?= $(LUFA_PATH)/Build/DMBS/DMBS
+# Include DMBS build script makefiles
+DMBS_PATH ?= ../DMBS
include $(DMBS_PATH)/core.mk
+include $(DMBS_PATH)/gcc.mk
include $(DMBS_PATH)/cppcheck.mk
include $(DMBS_PATH)/doxygen.mk
include $(DMBS_PATH)/dfu.mk
-include $(DMBS_PATH)/gcc.mk
include $(DMBS_PATH)/hid.mk
include $(DMBS_PATH)/avrdude.mk
include $(DMBS_PATH)/atprogram.mk
projects / pub / USBasp.git / commitdiff