X-Git-Url: http://git.linex4red.de/pub/lufa.git/blobdiff_plain/393fc71d8e82f4be67fac7f7f33538b92555b4f9..72fc4a204de72bfc3b2d62162d2c8ff59dd5803f:/LUFA/DoxygenPages/BuildSystem.txt diff --git a/LUFA/DoxygenPages/BuildSystem.txt b/LUFA/DoxygenPages/BuildSystem.txt index 0d7d6be74..3ee524ba3 100644 --- a/LUFA/DoxygenPages/BuildSystem.txt +++ b/LUFA/DoxygenPages/BuildSystem.txt @@ -12,16 +12,20 @@ * application makefile. The system is written in GNU Make, and each module is independant of * one-another. * - * To use a LUFA build system module, simply add an include to your project makefile: + * 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. All user projects + * should at a minimum include \ref Page_BuildModule_CORE for base functionality: * \code - * include $(LUFA_PATH)/Build/lufa.core.in + * include $(LUFA_PATH)/Build/lufa_core.mk * \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. + * Once included in your project makefile, the associated build module targets will be added to your + * project's build makefile targets 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. + * \see \ref Sec_AppMakefileParams 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 @@ -46,15 +50,15 @@ * * 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. + * suitable for programming into a target device, using the GCC compiler. * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.build.in + * include $(LUFA_PATH)/Build/lufa_build.mk * \endcode * * \section SSec_BuildModule_BUILD_Requirements Requirements - * This module requires the the architecture appropriate binaries of the GCC compiler are available in your + * 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. * @@ -70,6 +74,10 @@ * Display a size-sorted list of symbols from the compiled application, in decimal bytes. * * + * 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. * @@ -89,6 +97,14 @@ * clean * Remove all intermediatary files and binary output files. * + * + * mostlyclean + * Remove all intermediatary files but preserve any binary output files. + * + * + * <filename>.s + * Create an assembly listing of a given input C/C++ source file. + * * * * \section SSec_BuildModule_BUILD_MandatoryParams Mandatory Parameters @@ -140,6 +156,14 @@ * Version of the C++ standard to apply when compiling C++ source files (see GCC manual). * * + * DEBUG_FORMAT + * Format of the debug information to embed in the generated object files (see GCC manual). + * + * + * DEBUG_LEVEL + * Level of the debugging information to embed in the generated object files (see GCC manual). + * + * * F_CPU * Speed of the processor CPU clock, in Hz. * @@ -157,20 +181,31 @@ * * * CC_FLAGS - * Common flags to pass to the compiler, assembler and linker, after the automatically generated flags. + * Common flags to pass to the C/C++ compiler and assembler, after the automatically generated flags. * * * LD_FLAGS * Flags to pass to the linker, after the automatically generated flags. * * + * LINKER_RELAXATIONS + * Enables or disables linker relaxations when linking the application binary. This can reduce the total size + * of the application by replacing full \c CALL instructions with smaller \c RCALL instructions where possible. + * \note On some unpatched versions of binutils, this can cause link failures in some circumstances. If you + * receive a link error relocation truncated to fit: R_AVR_13_PCREL, disable this setting. + * + * * 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. + * \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_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_BUILD_ProvidedVariables Module Provided Variables * * * @@ -193,7 +228,7 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.core.in + * include $(LUFA_PATH)/Build/lufa_core.mk * \endcode * * \section SSec_BuildModule_CORE_Requirements Requirements @@ -249,7 +284,7 @@ * *
* - * \section SSec_BuildModule_CORE_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_CORE_ProvidedVariables Module Provided Variables * * * @@ -273,7 +308,7 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.atprogram.in + * include $(LUFA_PATH)/Build/lufa_atprogram.mk * \endcode * * \section SSec_BuildModule_ATPROGRAM_Requirements Requirements @@ -324,7 +359,7 @@ * *
* - * \section SSec_BuildModule_ATPROGRAM_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_ATPROGRAM_ProvidedVariables Module Provided Variables * * * @@ -348,13 +383,13 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.avrdude.in + * include $(LUFA_PATH)/Build/lufa_avrdude.mk * \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 + * Windows (http://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 @@ -365,7 +400,7 @@ * * * - * + * * * *
Program the device FLASH memory with the application's executable data.
avrdudeavrdude-eeProgram the device EEPROM memory with the application's EEPROM data.
@@ -391,16 +426,16 @@ * Name of the programmer or debugger tool to communicate with (e.g. jtagicemkii). * * - * ATPROGRAM_PORT + * AVRDUDE_PORT * Name of the communication port to use when when programming with the connected tool (e.g. COM2, /dev/ttyUSB0 or usb). * * - * ATPROGRAM_FLAGS + * AVRDUDE_FLAGS * Additional flags to pass to avrdude when programming, applied after the automatically generated flags. * * * - * \section SSec_BuildModule_AVRDUDE_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_AVRDUDE_ProvidedVariables Module Provided Variables * * * @@ -424,7 +459,7 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.cppcheck.in + * include $(LUFA_PATH)/Build/lufa_cppcheck.mk * \endcode * * \section SSec_BuildModule_CPPCHECK_Requirements Requirements @@ -492,7 +527,7 @@ * *
* - * \section SSec_BuildModule_CPPCHECK_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_CPPCHECK_ProvidedVariables Module Provided Variables * * * @@ -518,7 +553,7 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.dfu.in + * include $(LUFA_PATH)/Build/lufa_dfu.mk * \endcode * * \section SSec_BuildModule_DFU_Requirements Requirements @@ -569,7 +604,7 @@ * *
* - * \section SSec_BuildModule_DFU_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_DFU_ProvidedVariables Module Provided Variables * * * @@ -594,14 +629,14 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.doxygen.in + * include $(LUFA_PATH)/Build/lufa_doxygen.mk * \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. + * (http://www.doxygen.org/) 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 * @@ -610,6 +645,14 @@ * * * + * + * + * + * + * + * + * + * *
doxygenGenerate project documentation.
doxygen_createCreate a new Doxygen configuration file using the latest template.
doxygen_upgradeUpgrade an existing Doxygen configuration file to the latest template
* * \section SSec_BuildModule_DOXYGEN_MandatoryParams Mandatory Parameters @@ -638,7 +681,7 @@ * * * - * \section SSec_BuildModule_DOXYGEN_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_DOXYGEN_ProvidedVariables Module Provided Variables * * * @@ -664,7 +707,7 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.hid.in + * include $(LUFA_PATH)/Build/lufa_hid.mk * \endcode * * \section SSec_BuildModule_HID_Requirements Requirements @@ -681,8 +724,20 @@ * * * - * - * + * + * + * + * + * + * + * + * + * + * * *
Program the device FLASH memory with the application's executable data using hid_bootloader_cli.
hid-teensyProgram the device EEPROM memory with the application's executable data using teensy_loader_cli.hid-eeProgram 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.
teensyProgram the device FLASH memory with the application's executable data using teensy_loader_cli.
teensy-eeProgram 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.
* @@ -707,7 +762,7 @@ * * * - * \section SSec_BuildModule_HID_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_HID_ProvidedVariables Module Provided Variables * * * @@ -733,7 +788,7 @@ * * To use this module in your application makefile, add the following code: * \code - * include $(LUFA_PATH)/Build/lufa.sources.in + * include $(LUFA_PATH)/Build/lufa_sources.mk * \endcode * * \section SSec_BuildModule_SOURCES_Requirements Requirements @@ -768,7 +823,7 @@ * *
* - * \section SSec_BuildModule_SOURCES_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_SOURCES_ProvidedVariables Module Provided Variables * * *