X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/9ab445518a01e9b10b5d3e1c99f45d81d874278b..94b43e2f9d544971a68e095c404ba6305db56155:/LUFA/DoxygenPages/BuildSystem.txt diff --git a/LUFA/DoxygenPages/BuildSystem.txt b/LUFA/DoxygenPages/BuildSystem.txt index 61087a5ce..e8f0e5bec 100644 --- a/LUFA/DoxygenPages/BuildSystem.txt +++ b/LUFA/DoxygenPages/BuildSystem.txt @@ -8,20 +8,24 @@ * * \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 + * can be referenced in a LUFA powered project, to minimize the amount of code required in an + * application makefile. The system is written in GNU Make, and each module is independent 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 @@ -38,22 +42,25 @@ * \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 + * + * If you have problems building using the LUFA build system, see \subpage Page_BuildTroubleshooting for resolution steps. */ - + /** \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. + * 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. * @@ -69,6 +76,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. * @@ -77,6 +88,10 @@ * Build and link the application into an ELF debug file. * * + * bin + * Build and link the application and produce a BIN binary file. + * + * * hex * Build and link the application and produce HEX and EEP binary files. * @@ -86,7 +101,15 @@ * * * clean - * Remove all intermediatary files and binary output files. + * Remove all intermediary files and binary output files. + * + * + * mostlyclean + * Remove all intermediary files but preserve any binary output files. + * + * + * <filename>.s + * Create an assembly listing of a given input C/C++ source file. * * * @@ -139,6 +162,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. * @@ -156,26 +187,37 @@ * * * 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 * * * * * - *
None
+ * * * \section SSec_BuildModule_BUILD_ProvidedMacros Module Provided Macros * @@ -192,7 +234,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 @@ -248,13 +290,13 @@ * * * - * \section SSec_BuildModule_CORE_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_CORE_ProvidedVariables Module Provided Variables * * * * * - *
None
+ * * * \section SSec_BuildModule_CORE_ProvidedMacros Module Provided Macros * @@ -272,7 +314,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 @@ -323,13 +365,13 @@ * * * - * \section SSec_BuildModule_ATPROGRAM_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_ATPROGRAM_ProvidedVariables Module Provided Variables * * * * * - *
None
+ * * * \section SSec_BuildModule_ATPROGRAM_ProvidedMacros Module Provided Macros * @@ -347,13 +389,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 @@ -364,7 +406,7 @@ * Program the device FLASH memory with the application's executable data. * * - * avrdude + * avrdude-ee * Program the device EEPROM memory with the application's EEPROM data. * * @@ -390,22 +432,22 @@ * 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 * * * * * - *
None
+ * * * \section SSec_BuildModule_AVRDUDE_ProvidedMacros Module Provided Macros * @@ -415,7 +457,7 @@ * * */ - + /** \page Page_BuildModule_CPPCHECK The CPPCHECK build module * * The CPPCHECK programming utility LUFA build system module, providing targets to statically @@ -423,7 +465,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 @@ -491,13 +533,13 @@ * * * - * \section SSec_BuildModule_CPPCHECK_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_CPPCHECK_ProvidedVariables Module Provided Variables * * * * * - *
None
+ * * * \section SSec_BuildModule_CPPCHECK_ProvidedMacros Module Provided Macros * @@ -507,16 +549,17 @@ * * */ - + /** \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. + * 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 + * include $(LUFA_PATH)/Build/lufa_dfu.mk * \endcode * * \section SSec_BuildModule_DFU_Requirements Requirements @@ -567,13 +610,13 @@ * * * - * \section SSec_BuildModule_DFU_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_DFU_ProvidedVariables Module Provided Variables * * * * * - *
None
+ * * * \section SSec_BuildModule_DFU_ProvidedMacros Module Provided Macros * @@ -583,7 +626,7 @@ * * */ - + /** \page Page_BuildModule_DOXYGEN The DOXYGEN build module * * The DOXYGEN code documentation utility LUFA build system module, providing targets to generate @@ -592,14 +635,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 * @@ -608,6 +651,14 @@ * doxygen * Generate project 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 + * * * * \section SSec_BuildModule_DOXYGEN_MandatoryParams Mandatory Parameters @@ -636,13 +687,13 @@ * * * - * \section SSec_BuildModule_DOXYGEN_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_DOXYGEN_ProvidedVariables Module Provided Variables * * * * * - *
None
+ * * * \section SSec_BuildModule_DOXYGEN_ProvidedMacros Module Provided Macros * @@ -652,7 +703,88 @@ * * */ - + + /** \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.mk + * \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 + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
hidProgram the device FLASH memory with the application's executable data using hid_bootloader_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.
+ * + * \section SSec_BuildModule_HID_MandatoryParams Mandatory Parameters + * + * + * + * + * + * + * + * + * + * + *
MCUName of the Atmel processor model (e.g. at90usb1287).
TARGETName of the application output file prefix (e.g. TestApplication).
+ * + * \section SSec_BuildModule_HID_OptionalParams Optional Parameters + * + * + * + * + * + *
None
+ * + * \section SSec_BuildModule_HID_ProvidedVariables Module Provided Variables + * + * + * + * + * + *
None
+ * + * \section SSec_BuildModule_HID_ProvidedMacros Module Provided Macros + * + * + * + * + * + *
None
+ */ + /** \page Page_BuildModule_SOURCES The SOURCES build module * * The SOURCES LUFA build system module, providing variables listing the various LUFA source files @@ -662,7 +794,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 @@ -697,7 +829,7 @@ * * * - * \section SSec_BuildModule_SOURCES_ProvideVariables Module Provided Variables + * \section SSec_BuildModule_SOURCES_ProvidedVariables Module Provided Variables * * * @@ -723,8 +855,8 @@ * * * - * - *
LUFA_SRC_PLATFORMList of LUFA architecture specific platform management source files.
+ * + * * * \section SSec_BuildModule_SOURCES_ProvidedMacros Module Provided Macros * @@ -734,3 +866,106 @@ * * */ + +/** \page Page_BuildTroubleshooting Troubleshooting Information + * + * LUFA uses a lot of advanced features of the AVR-GCC compiler, linker, and surrounding binaries. This can sometimes lead to problems compiling applications if one of these + * features is buggy in the version of the tools used in a build environment. Missing utilities and incorrectly set makefile configuration options can also result in different + * errors being produced when compilation or other operations are attempted. The table below lists a set of commonly encountered errors and their resolutions. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ProblemResolution
Error "relocation truncated to fit: R_AVR_13_PCREL against symbol {X}" shown when compiling.Try compiling with the setting LINKER_RELAXATIONS=N in your LUFA Build System 2.0 makefile, or remove the line -Wl,--relax + * from other makefiles. Alternatively, make sure you have the latest version of the Atmel Toolchain installed for your system.
Error "error: ld terminated with signal 11 [Segmentation fault]" shown when compiling.Try compiling with the setting DEBUG_LEVEL=2 in your LUFA Build System 2.0 makefile, or make sure you are using binutils version 2.22 or later.
Error "EMERGENCY ABORT: INFINITE RECURSION DETECTED" shown when compiling.Make sure you are using an up to date version of GNU Make when compiling. This error is a safety system added to the mid-level makefiles, to prevent an issue with + * GNU make or other variants of Make causing an infinitely recursive build.
Error "Unsupported architecture "{X}"" shown when compiling.Ensure your makefile's ARCH setting is set to one of the architecture names (case-sensitive) supported by the version of LUFA you are compiling against.
Error "Makefile {X} value not set" shown when compiling.The specified Makefile value was not configured in your project's makefile or on the command line, and the nominated setting is required by one or more LUFA + * build system modules. Define the value in your project makefile and try again.
Error "Makefile {X} option cannot be blank" shown when compiling.The specified Makefile value was configured in your project's makefile or on the command line, but was set to an empty value. For the nominated configuration + * option, an empty value is not allowed. Define the nominated setting to a correct non-blank value and try again.
Error "Makefile {X} option must be Y or N" shown when compiling.The specified Makefile value was configured in your project's makefile or on the command line, but was set to a value other than a Y (for "Yes") or "N" (for "No"). + * This configuration option is required to be one of the aformentioned boolean values, and other values are invalid. Set this option to either Y or N and try again.
Error "Unknown input source file formats: {X}" shown when compiling.The nominated source files, specified in your project's makefile in the SRC configuration option, has an extension that the LUFA build system does not + * recognise. The file extensions are case sensitive, and must be one of the supported formats (*.c, *.cpp or *.S).
Error "Cannot build with OBJDIR parameter set - one or more object file name is not unique" shown when compiling.When a project is built with a non-empty OBJDIR object directory name set, all input source files must have unique names, excluding extension and path. + * This means that input files that are named identically and differ only by their path or extension are invalid when this mode is used.
Error "Source file does not exist: {X}" shown when compiling.The nominated input source file, specified in the user project's SRC parameter, could not be found. Ensure the source file exists and the absolute or + * relative path given in the user project makefile is correct and try again.
Error "Doxygen configuration file {X} does not exist" shown when upgrading a Doxygen configuration file.The nominated Doxygen configuration file, specified in the user project's DOXYGEN_CONF parameter, could not be found. Ensure the configuration file exists + * and the absolute or relative path given in the user project makefile is correct and try again, or run the appropriate makefile target to generate a new configuration + * file.
Error "avr-gcc: error: unrecognized option '{X}'" shown when compiling.An unrecognised option was supplied to the compiler, usually in the C_FLAGS, CPP_FLAGS, ASM_FLAGS or CC_FLAGS configuration + * options. The nominated compiler switch may be invalid, or unsupported by the version of AVR-GCC on the host system. Remove the unrecognised flag if invalid, or + * upgrade to the latest AVR-GCC. If the option is a valid linker option, use the prefix "-Wl," to ensure it is passed to the linker correctly.
Error "makefile:{X}: {Y}.mk: No such file or directory" shown when make is invoked.The path to the nominated makefile module was incorrect. This usually indicates that the makefile LUFA_PATH option is not set to a valid relative or + * absolute path to the LUFA library core.
Error "fatal error: LUFAConfig.h: No such file or directory" shown when compiling.The USE_LUFA_CONFIG_HEADER compile time option was set in the user project makefile, but the user supplied LUFAConfig.h header could not be + * found. Ensure that the directory that contains this configuration file is correctly passed to the compiler via the -I switch in the makefile CC_FLAGS + * parameter.
Error "ld.exe: section .apitable_trampolines loaded at {X} overlaps section .text" shown when compiling a bootloader.The bootloader is compiling too large for the given FLASH_SIZE_KB and BOOT_SECTION_SIZE_KB parameters set in the bootloader makefile. This + * usually indicates that these values are incorrect for the specified device the bootloader is targeting. If these values are correct, a newer version of the + * compiler may need to be used to ensure that the bootloader is built within the section size constraints of the target device.
Error "unknown MCU '{X}' specified" shown when compiling.The specified micocontroller device model name set in the user application's makefile as the MCU parameter is incorrect, or unsupported by the + * version of the compiler being used. Make sure the model name is correct, or upgrade to the latest Atmel Toolchain to obtain newer device support.
Error "undefined reference to `{X}'" shown when compiling.This is usually caused by a missing source file in the user application's SRC configuration parameter. If the indicated symbol is one from the LUFA + * library, you may be missing a LUFA source makefile module (see \ref Page_BuildModule_SOURCES).
+ * + * For troubleshooting other errors you encounter, please see \ref Sec_ProjectHelp. + */