--- /dev/null
+*.lss
+*.bin
+*.elf
+*.hex
+*.eep
+*.map
+*.o
+*.d
+*.sym
--- /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
+===================================
+
+
+Module: ATPROGRAM
+-----------------
+
+The ATPROGRAM module provides build targets for use with the official
+`ATPROGRAM` back-end utility distributed with the free
+[Atmel Studio](http://www.atmel.com) software released by Atmel.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/atprogram.mk
+
+## Prerequisites:
+
+This module requires the `atprogram.exe` utility to be available in your
+system's `PATH` variable. The `atprogram.exe` utility is distributed in Atmel
+Studio (usually) inside the application install folder's `atbackend`
+subdirectory.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>atprogram</td>
+ <td>Program the device FLASH memory with the application's executable data.</td>
+ </tr>
+ <tr>
+ <td>atprogram-ee</td>
+ <td>Program the device EEPROM memory with the application's EEPROM data.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>MCU</td>
+ <td>Name of the Atmel processor model (e.g. `at90usb1287`).</td>
+ </tr>
+ <tr>
+ <td>TARGET</td>
+ <td>Name of the application output file prefix (e.g. `TestApplication`).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>ATPROGRAM_PROGRAMMER</td>
+ <td>Name of the Atmel programmer or debugger tool to communicate with (e.g. `jtagice3`). Default is `atmelice`.</td>
+ </tr>
+ <tr>
+ <td>ATPROGRAM_INTERFACE</td>
+ <td>Name of the programming interface to use when programming the target (e.g. `spi`). Default is `jtag`.</td>
+ </tr>
+ <tr>
+ <td>ATPROGRAM_PORT</td>
+ <td>Name of the communication port to use when when programming with a serially connected tool (e.g. `COM2`). Default is `usb`.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS ATPROGRAM Programmer Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to re-program a device using the Atmel atprogram
-# utility in AVR Studio 5.x and Atmel Studio 6.0 onwards.
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# atprogram - Program target FLASH with application using
-# atprogram
-# atprogram-ee - Program target EEPROM with application data
-# using atprogram
-#
-# MANDATORY PARAMETERS:
-#
-# MCU - Microcontroller device model name
-# TARGET - Application name
-#
-# OPTIONAL PARAMETERS:
-#
-# ATPROGRAM_PROGRAMMER - Name of programming hardware to use
-# ATPROGRAM_INTERFACE - Name of programming interface to use
-# ATPROGRAM_PORT - Name of communication port to use
-#
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: AVRDUDE
+-----------------
+
+The AVRDUDE module provides build targets for use with the official
+open source `AVRDUDE` programmer utility, for the reprogramming of Atmel devices
+using a wide variety of official and non-official programming devices and
+bootloaders.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/avrdude.mk
+
+## Prerequisites:
+
+This module requires the `avrdude` utility to be available in your
+system's `PATH` variable. The `avrdude` utility is distributed on the project's
+[official site](https://savannah.nongnu.org/projects/avrdude) but is also
+made available in many *nix operating system's package managers.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>avrdude</td>
+ <td>Program the device FLASH memory with the application's executable data.</td>
+ </tr>
+ <tr>
+ <td>avrdude-ee</td>
+ <td>Program the device EEPROM memory with the application's EEPROM data.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>MCU</td>
+ <td>Name of the Atmel processor model (e.g. `at90usb1287`).</td>
+ </tr>
+ <tr>
+ <td>TARGET</td>
+ <td>Name of the application output file prefix (e.g. `TestApplication`).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>AVRDUDE_PROGRAMMER</td>
+ <td>Name of the programmer/debugger tool or bootloader to communicate with (e.g. `jtagicemkii`). Default is `jtagicemkii`.</td>
+ </tr>
+ <tr>
+ <td>AVRDUDE_PORT</td>
+ <td>Name of the communication port to use when when programming with a serially connected tool (e.g. `COM2`). Default is `usb`.</td>
+ </tr>
+ <tr>
+ <td>AVRDUDE_FLAGS</td>
+ <td>Additional flags to pass to `avrdude` when invoking the tool. Default is empty (no additional flags).</td>
+ </tr>
+ <tr>
+ <td>AVRDUDE_MEMORY</td>
+ <td>Memory space to program when executing the `avrdude` target (e.g. 'application` for an XMEGA device). Default is `flash`.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS AVRDUDE Programmer Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to re-program a device using the open source
-# avr-dude utility.
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# avrdude - Program target FLASH with application using
-# avrdude
-# avrdude-ee - Program target EEPROM with application data
-# using avrdude
-#
-# MANDATORY PARAMETERS:
-#
-# MCU - Microcontroller device model name
-# TARGET - Application name
-#
-# OPTIONAL PARAMETERS:
-#
-# AVRDUDE_PROGRAMMER - Name of programming hardware to use
-# AVRDUDE_PORT - Name of communication port to use
-# AVRDUDE_FLAGS - Flags to pass to avr-dude
-# AVRDUDE_MEMORY - Memory space to program application into (e.g.
-# "application" for an XMEGA DFU device)
-#
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: CORE
+------------
+
+The CORE module provides the core DMBS infrastructure used by other DMBS
+modules, and must always be imported. Additionally, this module provides the
+help system for DMBS.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/core.mk
+
+## Prerequisites:
+
+None.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>help</td>
+ <td>Show help for the current project, including a list of all available targets, variables and macros from the imported modules.</td>
+ </tr>
+ <tr>
+ <td>list_targets</td>
+ <td>Show a list of all build targets from the imported modules.</td>
+ </tr>
+ <tr>
+ <td>list_modules</td>
+ <td>Show a list of all imported modules.</td>
+ </tr>
+ <tr>
+ <td>list_mandatory</td>
+ <td>Show a list of all mandatory variables from the imported modules.</td>
+ </tr>
+ <tr>
+ <td>list_optional</td>
+ <td>Show a list of all optional variables from the imported modules.</td>
+ </tr>
+ <tr>
+ <td>list_provided</td>
+ <td>Show a list of all variables provided by the imported modules.</td>
+ </tr>
+ <tr>
+ <td>list_macros</td>
+ <td>Show a list of all macros provided by the imported modules.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module has no mandatory variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module has no optional variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>DMBS_VERSION</td>
+ <td>Current version of this DMBS release.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS += DMBS_VERSION
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS Core Build System Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of core build targets for the DMBS build system
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# help - Build system help
-# list_targets - List all build targets
-# list_modules - List all build modules
-# list_mandatory - List all mandatory make variables required by
-# the included build modules of the application
-# list_optional - List all optional make variables required by
-# the included build modules of the application
-# list_provided - List all provided make variables from the
-# included build modules of the application
-# list_macros - List all provided make macros from the
-# included build modules of the application
-#
-# MANDATORY PARAMETERS:
-#
-# (None)
-#
-# OPTIONAL PARAMETERS:
-#
-# (None)
-#
-# PROVIDED VARIABLES:
-#
-# DMBS_VERSION
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
-
# Current DMBS release version
DMBS_VERSION = 0.4
-
# 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))
-
# Build sorted and filtered lists of the included build module data
SORTED_DMBS_BUILD_MODULES = $(sort $(DMBS_BUILD_MODULES))
SORTED_DMBS_BUILD_TARGETS = $(sort $(DMBS_BUILD_TARGETS))
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: CPPCHECK
+-----------------
+
+The CPPCHECK module provides build targets to perform static analysis of the
+user application, using the open source `cppcheck` tool.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/cppcheck.mk
+
+## Prerequisites:
+
+This module requires the `cppcheck` utility to be available in your system's
+`PATH` variable. The `cppcheck` utility is distributed on the project's
+[official site](http://cppcheck.sourceforge.net/) but is also
+made available in many *nix operating system's package managers.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>cppcheck</td>
+ <td>Scan the project with CPPCHECK, and show all discovered issues.</td>
+ </tr>
+ <tr>
+ <td>cppcheck-config</td>
+ <td>Check the project with CPPCHECK, to find missing header paths.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>SRC</td>
+ <td>List of all project source files to scan.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>CPPCHECK_INCLUDES</td>
+ <td>Extra include paths to search, for any missing header files. Default is empty (no additional paths).</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_EXCLUDES</td>
+ <td>List of source files, file paths or path fragments to exclude from the scan. Default is empty (no exclusions).</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_MSG_TEMPLATE</td>
+ <td>Template for error and warning message output. Default is `{file}:{line}: {severity} ({id}): {message}`.</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_ENABLE</td>
+ <td>List of CPPCHECK checks to enable. Default is `all`.</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_SUPPRESS</td>
+ <td>List of CPPCHECK checks to ignore. Default is `variableScope missingInclude`.</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_FAIL_ON_WARNING</td>
+ <td>Boolean, if `Y` the build will fail if CPPCHECK discovers any errors or warnings. If `N`, fail only on errors. Default is `Y`.</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_QUIET</td>
+ <td>Boolean, if `Y` CPPCHECK will suppress all output except for discovered errors or warnings. If `N`, scan progress will be emitted. Default is `Y`.</td>
+ </tr>
+ <tr>
+ <td>CPPCHECK_FLAGS_</td>
+ <td>Additional flags to pass to CPPCHECK when scans are started. Default is empty (no additional flags).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS CPPCheck Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to scan a project with the free "cppcheck" static
-# analysis tool, to check for code errors at runtime
-# (see http://cppcheck.sourceforge.net).
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# cppcheck - Scan the project with CPPCheck
-# cppcheck-config - Use CPPCheck to look for missing include files
-#
-# MANDATORY PARAMETERS:
-#
-# SRC - List of source files to statically analyze
-#
-# OPTIONAL PARAMETERS:
-#
-# CPPCHECK_INCLUDES - Extra include paths to search for missing
-# header files
-# CPPCHECK_EXCLUDES - Source file paths to exclude checking (can be
-# a path fragment if desired)
-# CPPCHECK_MSG_TEMPLATE - Template for cppcheck error and warning output
-# CPPCHECK_ENABLE - General cppcheck category checks to enable
-# CPPCHECK_SUPPRESS - Specific cppcheck warnings to disable by ID
-# CPPCHECK_FAIL_ON_WARNING - Set to Y to fail the build on cppcheck
-# warnings, N to continue even if warnings occur
-# CPPCHECK_QUIET - Enable cppcheck verbose or quiet output mode
-# CPPCHECK_FLAGS - Additional flags to pass to cppcheck
-#
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: DFU
+-----------------
+
+The DFU module provides build targets to program a USB connected target running
+a DFU class bootloader, via the official Atmel FLIP utility running via the
+command line, or the open source `DFU-Programmer` tool.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/dfu.mk
+
+## Prerequisites:
+
+This module requires the `batchisp` utility to be available in your system's
+`PATH` variable. The `batchisp` utility is distributed as part of Atmel's FLIP
+software which can be downloaded from the [official site](http://www.atmel.com).
+
+This module requires the `dfu-programmer` utility to be available in your
+system's `PATH` variable. The `dfu-programmer` utility is distributed from the
+[official project site](https://dfu-programmer.github.io/).
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>flip</td>
+ <td>Program the application into the device's flash memory, using Atmel FLIP.</td>
+ </tr>
+ <tr>
+ <td>flip-ee</td>
+ <td>Program the application's EEPROM data into the device's EEPROM memory, using Atmel FLIP.</td>
+ </tr>
+ <tr>
+ <td>dfu</td>
+ <td>Program the application into the device's flash memory, using `dfu-programmer`.</td>
+ </tr>
+ <tr>
+ <td>dfu-ee</td>
+ <td>Program the application's EEPROM data into the device's EEPROM memory, using `dfu-programmer`.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>MCU</td>
+ <td>Name of the Atmel processor model (e.g. `at90usb1287`).</td>
+ </tr>
+ <tr>
+ <td>TARGET</td>
+ <td>Name of the application output file prefix (e.g. `TestApplication`).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module has no optional variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS DFU Bootloader Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to re-program a device currently running a DFU
-# class bootloader with a project's FLASH and EEPROM files.
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# flip - Program FLASH into target via Atmel FLIP
-# flip-ee - Program EEPROM into target via Atmel FLIP
-# dfu - Program FLASH into target via dfu-programmer
-# dfu-ee - Program EEPROM into target via dfu-programmer
-#
-# MANDATORY PARAMETERS:
-#
-# MCU - Microcontroller device model name
-# TARGET - Application name
-#
-# OPTIONAL PARAMETERS:
-#
-# (None)
-#
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: DOXYGEN
+-----------------
+
+The DOXYGEN module provides build targets to automatically generate API
+documentation for a project, using the open-source Doxygen tool.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/doxygen.mk
+
+## Prerequisites:
+
+This module requires the `doxygen` utility to be available in your system's
+`PATH` variable. The `doxygen` utility is distributed on the project's
+[official site](http://doxygen.org/) but is also
+made available in many *nix operating system's package managers.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>doxygen</td>
+ <td>Generate project documentation, via Doxygen.</td>
+ </tr>
+ <tr>
+ <td>doxygen-create</td>
+ <td>Create a new project Doxygen template, which can then be customized.</td>
+ </tr>
+ <tr>
+ <td>doxygen-upgrade</td>
+ <td>Upgrade an existing project Doxygen template to the latest Doxygen version.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module has no mandatory variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>DOXYGEN_CONF</td>
+ <td>Name of the Doxygen project configuration file that should be used when generating documentation, or creating/upgrading the configuration file.</td>
+ </tr>
+ <tr>
+ <td>DOXYGEN_FAIL_ON_WARNING</td>
+ <td>Boolean, if `Y` the build will fail if Doxygen encounters any errors or warnings. If `N`, fail only on errors. Default is `Y`.</td>
+ </tr>
+ <tr>
+ <td>DOXYGEN_OVERRIDE_PARAMS</td>
+ <td>List of `NAME=VALUE` parameters which should override the values specified in the project configuration file, when building documentation.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
#
DMBS_BUILD_MODULES += DOXYGEN
-DMBS_BUILD_TARGETS += doxygen doxygen_upgrade doxygen_create
+DMBS_BUILD_TARGETS += doxygen doxygen-upgrade doxygen-create
DMBS_BUILD_MANDATORY_VARS +=
DMBS_BUILD_OPTIONAL_VARS += DOXYGEN_CONF DOXYGEN_FAIL_ON_WARNING DOXYGEN_OVERRIDE_PARAMS
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS Doxygen Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to automatically build Doxygen documentation for
-# a project (see www.doxygen.org).
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# doxygen - Build Doxygen Documentation
-# doxygen_create - Create a new Doxygen configuration file using
-# the latest template
-# doxygen_upgrade - Upgrade an existing Doxygen configuration file
-# to the latest template
-#
-# MANDATORY PARAMETERS:
-#
-# (None)
-#
-# OPTIONAL PARAMETERS:
-#
-# DOXYGEN_CONF - Doxygen configuration filename
-# DOXYGEN_FAIL_ON_WARNING - Set to Y to fail the build on Doxygen warnings,
-# N to continue even if warnings occur
-# DOXYGEN_OVERRIDE_PARAMS - Parameters to override in the doxygen
-# configuration file
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
$(DOXYGEN_CMD)
# Upgrades an existing Doxygen configuration file to the latest Doxygen template, preserving settings
-doxygen_upgrade: $(DOXYGEN_CONF) $(MAKEFILE_LIST)
+doxygen-upgrade: $(DOXYGEN_CONF) $(MAKEFILE_LIST)
@echo $(MSG_DOXYGEN_CMD) Upgrading configuration file \"$(DOXYGEN_CONF)\" with latest template
doxygen -u $(DOXYGEN_CONF) > /dev/null
# Creates a new Doxygen configuration file with the set file name
-doxygen_create: $(MAKEFILE_LIST)
+doxygen-create: $(MAKEFILE_LIST)
@echo $(MSG_DOXYGEN_CMD) Creating new configuration file \"$(DOXYGEN_CONF)\" with latest template
doxygen -g $(DOXYGEN_CONF) > /dev/null
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: GCC
+-----------------
+
+The GCC module provides build targets to compile a user application, using a
+variant of GCC for a specific target architecture (such as `avr-gcc`).
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/gcc.mk
+
+## Prerequisites:
+
+This module requires the GCC compiler to be installed and available in the
+system's `PATH` variable for the desired target architecture.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>size</td>
+ <td>Show the compiled binary size for the various memory segments.</td>
+ </tr>
+ <tr>
+ <td>symbol-sizes</td>
+ <td>Show the size of each symbol in the compiled binary (useful to find large functions to optimize further).</td>
+ </tr>
+ <tr>
+ <td>all</td>
+ <td>Build application and generate all binary (BIN, ELF, HEX) and auxiliary (LSS, MAP, SYM, etc.) output files.</td>
+ </tr>
+ <tr>
+ <td>lib</td>
+ <td>Generate a static `.a` library from the application code, containing the flash region's data.</td>
+ </tr>
+ <tr>
+ <td>elf</td>
+ <td>Generate an ELF debug file from the application code, containing all region's data.</td>
+ </tr>
+ <tr>
+ <td>bin</td>
+ <td>Generate a flat BIN binary file from the application code, containing the flash region's data.</td>
+ </tr>
+ <tr>
+ <td>hex</td>
+ <td>Generate a pair of Intel HEX files from the application code, containing the flash region's data (HEX) and EEPROM data (EEP).</td>
+ </tr>
+ <tr>
+ <td>lss</td>
+ <td>Generate a LSS listing file showing the disassembly of the compiled application.</td>
+ </tr>
+ <tr>
+ <td>clean</td>
+ <td>Remove all generated project intermediary and binary output files.</td>
+ </tr>
+ <tr>
+ <td>mostlyclean</td>
+ <td>Remove all generated project intermediary output files, but preserve the binary output files.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>MCU</td>
+ <td>Name of the Atmel processor model (e.g. `at90usb1287`).</td>
+ </tr>
+ <tr>
+ <td>TARGET</td>
+ <td>Name of the application output file prefix (e.g. `TestApplication`).</td>
+ </tr>
+ <tr>
+ <td>ARCH</td>
+ <td>Target device architecture (e.g. `AVR8`).</td>
+ </tr>
+ <tr>
+ <td>SRC</td>
+ <td>List of all project source files (C, C++, ASM).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>OPTIMIZATION</td>
+ <td>Optimization level to use when compiling C and C++ source files. Default is `s` (optimize for smallest size).</td>
+ </tr>
+ <tr>
+ <td>C_STANDARD</td>
+ <td>C language standard used when compiling C language source files. Default is `gnu99` (C99 standard with GNU extensions)./td>
+ </tr>
+ <tr>
+ <td>CPP_STANDARD</td>
+ <td>C++ language standard used when compiling C++ language source files. Default is `gnu++98` (C++98 standard with GNU extensions)./td>
+ </tr>
+ <tr>
+ <td>F_CPU</td>
+ <td>Processor core clock frequency, in Hz. This is used by some architectures for functions such as software spin-loop delays. Default is blank (no value defined).</td>
+ </tr>
+ <tr>
+ <td>C_FLAGS</td>
+ <td>Common GCC flags passed to the compiler for C language (C) input files. Default is blank (no additional flags).</td>
+ </tr>
+ <tr>
+ <td>CPP_FLAGS</td>
+ <td>Common GCC flags passed to the compiler for C++ language (CPP) input files. Default is blank (no additional flags).</td>
+ </tr>
+ <tr>
+ <td>ASM_FLAGS</td>
+ <td>Common GCC flags passed to the assembler for assembly language (S) input files. Default is blank (no additional flags).</td>
+ </tr>
+ <tr>
+ <td>CC_FLAGS</td>
+ <td>Common GCC flags passed to the compiler for all source file types. Default is blank (no additional flags).</td>
+ </tr>
+ <tr>
+ <td>LD_FLAGS</td>
+ <td>Extra flags to pass to the GNU linker when linking the compiled object files into the resulting binary. Default is blank (no additional flags).</td>
+ </tr>
+ <tr>
+ <td>LINKER_RELAXATIONS</td>
+ <td>Boolean, if `Y` linker relaxations will be enabled to slightly reduce the resulting binary's size. Default is `Y`.</td>
+ </tr>
+ <tr>
+ <td>OBJDIR</td>
+ <td>Directory to store the intermediate object files, as they are generated from the source files. Default is `obj`.</td>
+ </tr>
+ <tr>
+ <td>OBJECT_FILES</td>
+ <td>List of additional `.o` object files to link into the final binary. Default is blank (no additional objects).</td>
+ </tr>
+ <tr>
+ <td>DEBUG_FORMAT</td>
+ <td>Debug ELF file format to generate. Default is `dwarf-2`.</td>
+ </tr>
+ <tr>
+ <td>DEBUG_LEVEL</td>
+ <td>Level of the debugging information to generate in the compiled object files. Debug is 2 (medium level debugging information).</td>
+ </tr>
+ <tr>
+ <td>COMPILER_PATH</td>
+ <td>Path to the compiler to use, in case a specific compiler should be substituted for the one in the system's `PATH` variable. Default is blank (use `PATH` provided compiler).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS GCC Compiler Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to build a C, C++ and/or Assembly application
-# via the AVR-GCC compiler.
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# size - List built application size
-# symbol-sizes - Print application symbols from the binary ELF
-# file as a list sorted by size in bytes
-# all - Build application and list size
-# lib - Build and archive source files into a library
-# elf - Build application ELF debug object file
-# bin - Build application BIN binary object file
-# hex - Build application HEX object file
-# lss - Build application LSS assembly listing file
-# clean - Remove all project intermediary and binary
-# output files
-# mostlyclean - Remove intermediary output files, but
-# preserve binaries
-# <filename>.s - Compile C/C++ source file into an assembly file
-# for manual code inspection
-#
-# MANDATORY PARAMETERS:
-#
-# TARGET - Application name
-# ARCH - Device architecture name
-# MCU - Microcontroller device model name
-# SRC - List of input source files (*.c, *.cpp, *.S)
-#
-# OPTIONAL PARAMETERS:
-#
-# OPTIMIZATION - Optimization level
-# C_STANDARD - C Language Standard to use
-# CPP_STANDARD - C++ Language Standard to use
-# F_CPU - Speed of the CPU, in Hz
-# C_FLAGS - Flags to pass to the C compiler only
-# CPP_FLAGS - Flags to pass to the C++ compiler only
-# ASM_FLAGS - Flags to pass to the assembler only
-# CC_FLAGS - Common flags to pass to the C/C++ compiler and
-# assembler
-# LD_FLAGS - Flags to pass to the linker
-# LINKER_RELAXATIONS - Enable or disable linker relaxations to
-# decrease binary size (note: can cause link
-# failures on systems with an unpatched binutils)
-# OBJDIR - Directory for the output object and dependency
-# files; if equal to ".", the output files will
-# be generated in the same folder as the sources
-# OBJECT_FILES - Extra object files to link in to the binaries
-# DEBUG_FORMAT - Format of the debugging information to
-# generate in the compiled object files
-# DEBUG_LEVEL - Level the debugging information to generate in
-# the compiled object files
-# COMPILER_PATH - Location of the GCC toolchain to use
-#
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
ERROR_IF_UNSET ?= $(if $(filter undefined, $(origin $(strip $(1)))), $(error Makefile $(strip $(1)) value not set))
--- /dev/null
+DMBS - Dean's Makefile Build System
+===================================
+
+
+Module: HID
+-----------------
+
+The HID module provides build targets to program a target running a PJRC Teensy
+or LUFA compatible HID class bootloader.
+
+## Importing This Module into a Makefile:
+
+To use this module in your application makefile, add the following code to your
+makefile:
+
+ include $(DMBS_PATH)/hid.mk
+
+## Prerequisites:
+
+This module requires the `teensy_loader_cli` utility to be available in your
+system's `PATH` variable. The `teensy_loader_cli` utility is distributed in
+a modified form (from PJRC) in the LUFA project's
+[official site](http://www.lufa-lib.org/), but is also
+made available in its original form directly from the
+[PJRC website](https://www.pjrc.com/teensy/loader_cli.html). Note that the
+original tool works with Teensy boards only, and not LUFA HID bootloader
+devices.
+
+This module requires the `hid_bootloader_cli` utility to be available in your
+system's `PATH` variable. The `hid_bootloader_cli` Python script utility is
+distributed in LUFA project's [official site](http://www.lufa-lib.org/).
+
+This module requires the AVR-GCC compiler to be installed and available in the
+system's `PATH` variable.
+
+## Build Targets:
+
+The following targets are supported by this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>hid</td>
+ <td>Program a LUFA HID class bootloader device, using the `hid_bootloader_cli.py` Python script.</td>
+ </tr>
+ <tr>
+ <td>hid-ee</td>
+ <td>Program a LUFA HID class bootloader device's EEPROM, using the `hid_bootloader_cli.py` Python script and a shim application which is programmed into the target's flash.</td>
+ </tr>
+ <tr>
+ <td>teensy</td>
+ <td>Program a LUFA HID class bootloader device or Teensy board, using the `teensy_loader_cli` tool.</td>
+ </tr>
+ <tr>
+ <td>teensy-ee</td>
+ <td>Program a LUFA HID class bootloader device's EEPROM, using the `teensy_loader_cli` tool and a shim application which is programmed into the target's flash.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Mandatory Variables:
+
+The following variables must be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile to be able to use this module:
+
+<table>
+ <tbody>
+ <tr>
+ <td>MCU</td>
+ <td>Name of the Atmel processor model (e.g. `at90usb1287`).</td>
+ </tr>
+ <tr>
+ <td>TARGET</td>
+ <td>Name of the application output file prefix (e.g. `TestApplication`).</td>
+ </tr>
+ </tbody>
+</table>
+
+## Optional Variables:
+
+The following variables may be defined (with a `NAME = VALUE` syntax, one
+variable per line) in the user makefile. If not specified, a default value will
+be assumed.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module has no optional variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Variables:
+
+The following variables may be referenced in a user makefile (via `$(NAME)`
+syntax) if desired, as they are provided by this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no variables.</td>
+ </tr>
+ </tbody>
+</table>
+
+## Provided Macros:
+
+The following macros may be referenced in a user makefile (via
+`$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
+this module.
+
+<table>
+ <tbody>
+ <tr>
+ <td>N/A</td>
+ <td>This module provides no macros.</td>
+ </tr>
+ </tbody>
+</table>
DMBS_BUILD_PROVIDED_VARS +=
DMBS_BUILD_PROVIDED_MACROS +=
-# -----------------------------------------------------------------------------
-# DMBS HID Bootloader Buildsystem Makefile Module.
-# -----------------------------------------------------------------------------
-# DESCRIPTION:
-# Provides a set of targets to re-program a device currently running a HID
-# class bootloader with a project's FLASH files.
-# -----------------------------------------------------------------------------
-# TARGETS:
-#
-# hid - Program FLASH into target via
-# hid_bootloader_cli
-# hid-ee - Program EEPROM into target via a temporary
-# AVR application and hid_bootloader_cli
-# teensy - Program FLASH into target via
-# teensy_loader_cli
-# teensy-ee - Program EEPROM into target via a temporary
-# AVR application and teensy_loader_cli
-#
-# MANDATORY PARAMETERS:
-#
-# MCU - Microcontroller device model name
-# TARGET - Application name
-#
-# OPTIONAL PARAMETERS:
-#
-# (None)
-#
-# PROVIDED VARIABLES:
-#
-# (None)
-#
-# PROVIDED MACROS:
-#
-# (None)
-#
-# -----------------------------------------------------------------------------
-
SHELL = /bin/sh
DMBS_MODULE_PATH := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
always required, you can pick and choose what other modules you wish to add to
your user project.
-DMBS is also used in the LUFA Project which provides a
-[detailed documentation](http://www.fourwalledcubicle.com/files/LUFA/Doc/151115/html/_page__build_system.html)
-of DMBS.
+[See here for the documentation on the individual modules provided by DMBS.](DMBS/Modules.md)
Here's an example user makefile:
projects / pub / USBasp.git / commitdiff