/** \file
*
* This file contains special DoxyGen information for the generation of the main page and other special
* documentation pages. It is not a project source file.
*/
/** \page Page_BuildSystem The LUFA Build System
*
* \section Sec_BuildSystemOverview Overview of the LUFA Build System
* The LUFA build system is an attempt at making a set of re-usable, modular build make files which
* can be referenced in a LUFA powered project, to minimise the amount of code required in an
* application makefile. The system is written in GNU Make, and each module is independant of
* one-another.
*
* For details on the prerequisites needed for Linux and Windows machines to be able to use the LUFA
* build system, see \ref Sec_Prerequisites.
*
* To use a LUFA build system module, simply add an include to your project makefile:
* \code
* include $(LUFA_PATH)/Build/lufa.core.in
* \endcode
*
* And the associated build module targets will be added to your project's build makefile automatically.
* To call a build target, run make {TARGET_NAME} from the command line, substituting in
* the appropriate target name.
*
* \see \ref Sec_AppConfigParams for a copy of the sample LUFA project makefile.
*
* Each build module may have one or more mandatory parameters (GNU Make variables) which must
* be supplied in the project makefile for the module to work, and one or more optional parameters which
* may be defined and which will assume a sensible default if not.
*
* \section SSec_BuildSystemModules Available Modules
*
* The following modules are included in this LUFA release:
*
* \li \subpage Page_BuildModule_ATPROGRAM - Device Programming
* \li \subpage Page_BuildModule_AVRDUDE - Device Programming
* \li \subpage Page_BuildModule_BUILD - Compiling/Assembling/Linking
* \li \subpage Page_BuildModule_CORE - Core Build System Functions
* \li \subpage Page_BuildModule_CPPCHECK - Static Code Analysis
* \li \subpage Page_BuildModule_DFU - Device Programming
* \li \subpage Page_BuildModule_DOXYGEN - Automated Source Code Documentation
* \li \subpage Page_BuildModule_HID - Device Programming
* \li \subpage Page_BuildModule_SOURCES - LUFA Module Source Code Variables
*/
/** \page Page_BuildModule_BUILD The BUILD build module
*
* The BUILD LUFA build system module, providing targets for the compilation,
* assembling and linking of an application from source code into binary files
* suitable for programming into a target device.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.build.in
* \endcode
*
* \section SSec_BuildModule_BUILD_Requirements Requirements
* This module requires the the architecture appropriate binaries of the GCC compiler are available in your
* system's PATH variable. The GCC compiler and associated toolchain is distributed in Atmel AVR Studio
* 5.x and Atmel Studio 6.x installation directories, as well as in many third party distribution packages.
*
* \section SSec_BuildModule_BUILD_Targets Targets
*
*
*
* size |
* Display size of the compiled application FLASH and SRAM segments. |
*
*
* symbol-sizes |
* Display a size-sorted list of symbols from the compiled application, in decimal bytes. |
*
*
* check-source |
* Display a list of input SRC source files which cannot be found (if any). |
*
*
* lib |
* Build and archive all source files into a library A binary file. |
*
*
* all |
* Build and link the application into ELF debug and HEX binary files. |
*
*
* elf |
* Build and link the application into an ELF debug file. |
*
*
* hex |
* Build and link the application and produce HEX and EEP binary files. |
*
*
* lss |
* Build and link the application and produce a LSS source code/assembly code mixed listing file. |
*
*
* clean |
* Remove all intermediatary files and binary output files. |
*
*
* mostlyclean |
* Remove all intermediatary files but preserve any binary output files. |
*
*
*
* \section SSec_BuildModule_BUILD_MandatoryParams Mandatory Parameters
*
*
*
* TARGET |
* Name of the application output file prefix (e.g. TestApplication). |
*
*
* ARCH |
* Architecture of the target processor (see \ref Page_DeviceSupport). |
*
*
* MCU |
* Name of the Atmel processor model (e.g. at90usb1287). |
*
*
* SRC |
* List of relative or absolute paths to the application C (.c), C++ (.cpp) and Assembly (.S) source files. |
*
*
* F_USB |
* Speed in Hz of the input clock frequency to the target's USB controller. |
*
*
* LUFA_PATH |
* Path to the LUFA library core, either relative or absolute (e.g. ../LUFA-000000/LUFA/). |
*
*
*
* \section SSec_BuildModule_BUILD_OptionalParams Optional Parameters
*
*
*
* BOARD |
* LUFA board hardware drivers to use (see \ref Page_DeviceSupport). |
*
*
* OPTIMIZATION |
* Optimization level to use when compiling source files (see GCC manual). |
*
*
* C_STANDARD |
* Version of the C standard to apply when compiling C++ source files (see GCC manual). |
*
*
* CPP_STANDARD |
* Version of the C++ standard to apply when compiling C++ source files (see GCC manual). |
*
*
* F_CPU |
* Speed of the processor CPU clock, in Hz. |
*
*
* C_FLAGS |
* Flags to pass to the C compiler only, after the automatically generated flags. |
*
*
* CPP_FLAGS |
* Flags to pass to the C++ compiler only, after the automatically generated flags. |
*
*
* ASM_FLAGS |
* Flags to pass to the assembler only, after the automatically generated flags. |
*
*
* CC_FLAGS |
* Common flags to pass to the compiler, assembler and linker, after the automatically generated flags. |
*
*
* LD_FLAGS |
* Flags to pass to the linker, after the automatically generated flags. |
*
*
* OBJDIR |
* Directory to place the generated object and dependency files. If set to "." the same folder as the source file will be used.
* \note When this option is enabled, all source filenames must be unique. |
*
*
* OBJECT_FILES |
* List of additional object files that should be linked into the resulting binary. |
*
*
*
* \section SSec_BuildModule_BUILD_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_BUILD_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_CORE The CORE build module
*
* The core LUFA build system module, providing common build system help and information targets.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.core.in
* \endcode
*
* \section SSec_BuildModule_CORE_Requirements Requirements
* This module has no requirements outside a standard *nix shell like environment; the sh
* shell, GNU make and *nix CoreUtils (echo, printf, etc.).
*
* \section SSec_BuildModule_CORE_Targets Targets
*
*
*
* help |
* Display build system help and configuration information. |
*
*
* list_targets |
* List all available build targets from the build system. |
*
*
* list_modules |
* List all available build modules from the build system. |
*
*
* list_mandatory |
* List all mandatory parameters required by the included modules. |
*
*
* list_optional |
* List all optional parameters required by the included modules. |
*
*
* list_provided |
* List all variables provided by the included modules. |
*
*
* list_macros |
* List all macros provided by the included modules. |
*
*
*
* \section SSec_BuildModule_CORE_MandatoryParams Mandatory Parameters
*
*
*
* \section SSec_BuildModule_CORE_OptionalParams Optional Parameters
*
*
*
* \section SSec_BuildModule_CORE_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_CORE_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_ATPROGRAM The ATPROGRAM build module
*
* The ATPROGRAM programming utility LUFA build system module, providing targets to reprogram an
* Atmel processor FLASH and EEPROM memories with a project's compiled binary output files.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.atprogram.in
* \endcode
*
* \section SSec_BuildModule_ATPROGRAM_Requirements Requirements
* This module requires the atprogram.exe utility to be available in your system's PATH
* variable. The atprogram.exe utility is distributed in Atmel AVR Studio 5.x and Atmel Studio 6.x
* inside the application install folder's "\avrdbg" subdirectory.
*
* \section SSec_BuildModule_ATPROGRAM_Targets Targets
*
*
*
* atprogram |
* Program the device FLASH memory with the application's executable data. |
*
*
* atprogram-ee |
* Program the device EEPROM memory with the application's EEPROM data. |
*
*
*
* \section SSec_BuildModule_ATPROGRAM_MandatoryParams Mandatory Parameters
*
*
*
* MCU |
* Name of the Atmel processor model (e.g. at90usb1287). |
*
*
* TARGET |
* Name of the application output file prefix (e.g. TestApplication). |
*
*
*
* \section SSec_BuildModule_ATPROGRAM_OptionalParams Optional Parameters
*
*
*
* ATPROGRAM_PROGRAMMER |
* Name of the Atmel programmer or debugger tool to communicate with (e.g. jtagice3). |
*
*
* ATPROGRAM_INTERFACE |
* Name of the programming interface to use when programming the target (e.g. spi). |
*
*
* ATPROGRAM_PORT |
* Name of the communication port to use when when programming with a serially connected tool (e.g. COM2). |
*
*
*
* \section SSec_BuildModule_ATPROGRAM_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_ATPROGRAM_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_AVRDUDE The AVRDUDE build module
*
* The AVRDUDE programming utility LUFA build system module, providing targets to reprogram an
* Atmel processor FLASH and EEPROM memories with a project's compiled binary output files.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.avrdude.in
* \endcode
*
* \section SSec_BuildModule_AVRDUDE_Requirements Requirements
* This module requires the avrdude utility to be available in your system's PATH
* variable. The avrdude utility is distributed in the old WinAVR project releases for
* Windows (winavr.sourceforge.net) or can be installed on *nix systems via the project's
* source code (https://savannah.nongnu.org/projects/avrdude) or through the package manager.
*
* \section SSec_BuildModule_AVRDUDE_Targets Targets
*
*
*
* avrdude |
* Program the device FLASH memory with the application's executable data. |
*
*
* avrdude |
* Program the device EEPROM memory with the application's EEPROM data. |
*
*
*
* \section SSec_BuildModule_AVRDUDE_MandatoryParams Mandatory Parameters
*
*
*
* MCU |
* Name of the Atmel processor model (e.g. at90usb1287). |
*
*
* TARGET |
* Name of the application output file prefix (e.g. TestApplication). |
*
*
*
* \section SSec_BuildModule_AVRDUDE_OptionalParams Optional Parameters
*
*
*
* AVRDUDE_PROGRAMMER |
* Name of the programmer or debugger tool to communicate with (e.g. jtagicemkii). |
*
*
* ATPROGRAM_PORT |
* Name of the communication port to use when when programming with the connected tool (e.g. COM2, /dev/ttyUSB0 or usb). |
*
*
* ATPROGRAM_FLAGS |
* Additional flags to pass to avrdude when programming, applied after the automatically generated flags. |
*
*
*
* \section SSec_BuildModule_AVRDUDE_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_AVRDUDE_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_CPPCHECK The CPPCHECK build module
*
* The CPPCHECK programming utility LUFA build system module, providing targets to statically
* analyze C and C++ source code for errors and performance/style issues.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.cppcheck.in
* \endcode
*
* \section SSec_BuildModule_CPPCHECK_Requirements Requirements
* This module requires the cppcheck utility to be available in your system's PATH
* variable. The cppcheck utility is distributed through the project's home page
* (http://cppcheck.sourceforge.net) for Windows, and can be installed on *nix systems via
* the project's source code or through the package manager.
*
* \section SSec_BuildModule_CPPCHECK_Targets Targets
*
*
*
* cppcheck |
* Statically analyze the project source code for issues. |
*
*
* cppcheck-config |
* Check the cppcheck configuration - scan source code and warn about missing header files and other issues. |
*
*
*
* \section SSec_BuildModule_CPPCHECK_MandatoryParams Mandatory Parameters
*
*
*
* SRC |
* List of source files to statically analyze. |
*
*
*
* \section SSec_BuildModule_CPPCHECK_OptionalParams Optional Parameters
*
*
*
* CPPCHECK_INCLUDES |
* Path of extra directories to check when attemting to resolve C/C++ header file includes. |
*
*
* CPPCHECK_EXCLUDES |
* Paths or path fragments to exclude when analyzing. |
*
*
* CPPCHECK_MSG_TEMPLATE |
* Output message template to use when printing errors, warnings and information (see cppcheck documentation). |
*
*
* CPPCHECK_ENABLE |
* Analysis rule categories to enable (see cppcheck documentation). |
*
*
* CPPCHECK_SUPPRESS |
* Specific analysis rules to suppress (see cppcheck documentation). |
*
*
* CPPCHECK_FAIL_ON_WARNING |
* Set to Y to fail the analysis job with an error exit code if warnings are found, N to continue without failing. |
*
*
* CPPCHECK_QUIET |
* Set to Y to suppress all output except warnings and errors, N to show verbose output information. |
*
*
* CPPCHECK_FLAGS |
* Extra flags to pass to cppcheck, after the automatically generated flags. |
*
*
*
* \section SSec_BuildModule_CPPCHECK_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_CPPCHECK_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_DFU The DFU build module
*
* The DFU programming utility LUFA build system module, providing targets to reprogram an
* Atmel processor FLASH and EEPROM memories with a project's compiled binary output files.
* This module requires a DFU class bootloader to be running in the target, compatible with
* the DFU bootloader protocol as published by Atmel.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.dfu.in
* \endcode
*
* \section SSec_BuildModule_DFU_Requirements Requirements
* This module requires either the batchisp utility from Atmel's FLIP utility, or the open
* source dfu-programmer utility (http://dfu-programmer.sourceforge.net/) to be
* available in your system's PATH variable. On *nix systems the dfu-programmer utility
* can be installed via the project's source code or through the package manager.
*
* \section SSec_BuildModule_DFU_Targets Targets
*
*
*
* dfu |
* Program the device FLASH memory with the application's executable data using dfu-programmer. |
*
*
* dfu-ee |
* Program the device EEPROM memory with the application's EEPROM data using dfu-programmer. |
*
*
* flip |
* Program the device FLASH memory with the application's executable data using batchisp. |
*
*
* flip-ee |
* Program the device EEPROM memory with the application's EEPROM data using batchisp. |
*
*
*
* \section SSec_BuildModule_DFU_MandatoryParams Mandatory Parameters
*
*
*
* MCU |
* Name of the Atmel processor model (e.g. at90usb1287). |
*
*
* TARGET |
* Name of the application output file prefix (e.g. TestApplication). |
*
*
*
* \section SSec_BuildModule_DFU_OptionalParams Optional Parameters
*
*
*
* \section SSec_BuildModule_DFU_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_DFU_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_DOXYGEN The DOXYGEN build module
*
* The DOXYGEN code documentation utility LUFA build system module, providing targets to generate
* project HTML and other format documentation from a set of source files that include special
* Doxygen comments.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.doxygen.in
* \endcode
*
* \section SSec_BuildModule_DOXYGEN_Requirements Requirements
* This module requires the doxygen utility from the Doxygen website
* (http://www.stack.nl/~dimitri/doxygen/) to be available in your system's PATH
* variable. On *nix systems the doxygen utility can be installed via the project's source
* code or through the package manager.
*
* \section SSec_BuildModule_DOXYGEN_Targets Targets
*
*
*
* doxygen |
* Generate project documentation. |
*
*
*
* \section SSec_BuildModule_DOXYGEN_MandatoryParams Mandatory Parameters
*
*
*
* LUFA_PATH |
* Path to the LUFA library core, either relative or absolute (e.g. ../LUFA-000000/LUFA/). |
*
*
*
* \section SSec_BuildModule_DOXYGEN_OptionalParams Optional Parameters
*
*
*
* DOXYGEN_CONF |
* Name and path of the base Doxygen configuration file for the project. |
*
*
* DOXYGEN_FAIL_ON_WARNING |
* Set to Y to fail the generation with an error exit code if warnings are found other than unsupported configuration parameters, N to continue without failing. |
*
*
* DOXYGEN_OVERRIDE_PARAMS |
* Extra Doxygen configuration parameters to apply, overriding the corresponding config entry in the project's configuration file (e.g. QUIET=YES). |
*
*
*
* \section SSec_BuildModule_DOXYGEN_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_DOXYGEN_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_HID The HID build module
*
* The HID programming utility LUFA build system module, providing targets to reprogram an
* Atmel processor's FLASH memory with a project's compiled binary output file. This module
* requires a HID class bootloader to be running in the target, using a protocol compatible
* with the PJRC "HalfKay" protocol (http://www.pjrc.com/teensy/halfkay_protocol.html).
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.hid.in
* \endcode
*
* \section SSec_BuildModule_HID_Requirements Requirements
* This module requires either the hid_bootloader_cli utility from the included LUFA HID
* class bootloader API subdirectory, or the teensy_loader_cli utility from PJRC
* (http://www.pjrc.com/teensy/loader_cli.html) to be available in your system's PATH
* variable.
*
* \section SSec_BuildModule_HID_Targets Targets
*
*
*
* hid |
* Program the device FLASH memory with the application's executable data using hid_bootloader_cli. |
*
*
* hid-ee |
* Program the device EEPROM memory with the application's EEPROM data using hid_bootloader_cli and
* a temporary AVR application programmed into the target's FLASH.
* \note This will erase the currently loaded application in the target. |
*
*
* hid-teensy |
* Program the device FLASH memory with the application's executable data using teensy_loader_cli. |
*
*
* hid-teensy-ee |
* Program the device EEPROM memory with the application's EEPROM data using teensy_loader_cli and
* a temporary AVR application programmed into the target's FLASH.
* \note This will erase the currently loaded application in the target. |
*
*
*
* \section SSec_BuildModule_HID_MandatoryParams Mandatory Parameters
*
*
*
* MCU |
* Name of the Atmel processor model (e.g. at90usb1287). |
*
*
* TARGET |
* Name of the application output file prefix (e.g. TestApplication). |
*
*
*
* \section SSec_BuildModule_HID_OptionalParams Optional Parameters
*
*
*
* \section SSec_BuildModule_HID_ProvidedVariables Module Provided Variables
*
*
*
* \section SSec_BuildModule_HID_ProvidedMacros Module Provided Macros
*
*
*/
/** \page Page_BuildModule_SOURCES The SOURCES build module
*
* The SOURCES LUFA build system module, providing variables listing the various LUFA source files
* required to be build by a project for a given LUFA module. This module gives a way to reference
* LUFA source files symbollically, so that changes to the library structure do not break the library
* makefile.
*
* To use this module in your application makefile, add the following code:
* \code
* include $(LUFA_PATH)/Build/lufa.sources.in
* \endcode
*
* \section SSec_BuildModule_SOURCES_Requirements Requirements
* None.
*
* \section SSec_BuildModule_SOURCES_Targets Targets
*
*
*
* \section SSec_BuildModule_SOURCES_MandatoryParams Mandatory Parameters
*
*
*
* LUFA_PATH |
* Path to the LUFA library core, either relative or absolute (e.g. ../LUFA-000000/LUFA/). |
*
*
* ARCH |
* Architecture of the target processor (see \ref Page_DeviceSupport). |
*
*
*
* \section SSec_BuildModule_SOURCES_OptionalParams Optional Parameters
*
*
*
* \section SSec_BuildModule_SOURCES_ProvidedVariables Module Provided Variables
*
*
*
* LUFA_SRC_USB |
* List of LUFA USB driver source files. |
*
*
* LUFA_SRC_USBCLASS |
* List of LUFA USB Class driver source files. |
*
*
* LUFA_SRC_TEMPERATURE |
* List of LUFA temperature sensor driver source files. |
*
*
* LUFA_SRC_SERIAL |
* List of LUFA Serial U(S)ART driver source files. |
*
*
* LUFA_SRC_TWI |
* List of LUFA TWI driver source files. |
*
*
* LUFA_SRC_PLATFORM |
* List of LUFA architecture specific platform management source files. |
*
*
*
* \section SSec_BuildModule_SOURCES_ProvidedMacros Module Provided Macros
*
*
*/