From 2b43a6d7df6221b979f08326c02eb1cfdd077c49 Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Sun, 28 Oct 2012 13:53:55 +0000 Subject: [PATCH] Add troubleshooting page to the build system section of the documentation. --- LUFA/Build/lufa_build.mk | 14 +-- LUFA/DoxygenPages/BuildSystem.txt | 161 ++++++++++++++++++++++++++---- 2 files changed, 148 insertions(+), 27 deletions(-) diff --git a/LUFA/Build/lufa_build.mk b/LUFA/Build/lufa_build.mk index ce76b60dfb..486c863f57 100644 --- a/LUFA/Build/lufa_build.mk +++ b/LUFA/Build/lufa_build.mk @@ -10,8 +10,8 @@ LUFA_BUILD_MODULES += BUILD LUFA_BUILD_TARGETS += size symbol-sizes all lib elf hex lss clean mostlyclean LUFA_BUILD_MANDATORY_VARS += TARGET ARCH MCU SRC F_USB LUFA_PATH LUFA_BUILD_OPTIONAL_VARS += BOARD OPTIMIZATION C_STANDARD CPP_STANDARD F_CPU C_FLAGS CPP_FLAGS ASM_FLAGS CC_FLAGS LD_FLAGS OBJDIR OBJECT_FILES DEBUG_TYPE DEBUG_LEVEL LINKER_RELAXATIONS -LUFA_BUILD_PROVIDED_VARS += -LUFA_BUILD_PROVIDED_MACROS += +LUFA_BUILD_PROVIDED_VARS += +LUFA_BUILD_PROVIDED_MACROS += # ----------------------------------------------------------------------------- # LUFA GCC Compiler Buildsystem Makefile Module. @@ -163,14 +163,14 @@ OBJECT_FILES += $(addsuffix .o, $(basename $(SRC))) ifneq ($(OBJDIR),.) # Prefix all the object filenames with the output object file directory path OBJECT_FILES := $(addprefix $(patsubst %/,%,$(OBJDIR))/, $(notdir $(OBJECT_FILES))) - + # Check if any object file (without path) appears more than once in the object file list ifneq ($(words $(sort $(OBJECT_FILES))), $(words $(OBJECT_FILES))) $(error Cannot build with OBJDIR parameter set - one or more object file name is not unique) endif # Create the output object file directory if it does not exist and add it to the virtual path list - $(shell mkdir $(OBJDIR) 2> /dev/null) + $(shell mkdir $(OBJDIR) 2> /dev/null) VPATH += $(dir $(SRC)) endif @@ -223,7 +223,7 @@ build_begin: @echo $(MSG_INFO_MESSAGE) Begin compilation of project \"$(TARGET)\"... @echo "" @$(CROSS)-gcc --version - + # Post-build informational target, to project name information when building has completed build_end: @echo $(MSG_INFO_MESSAGE) Finished building project \"$(TARGET)\". @@ -239,7 +239,7 @@ symbol-sizes: $(TARGET).elf @echo $(MSG_NM_CMD) Extracting \"$<\" symbols with decimal byte sizes $(CROSS)-nm --size-sort --demangle --radix=d $< -# Cleans intermediatary build files, leaving only the compiled application files +# Cleans intermediary build files, leaving only the compiled application files mostlyclean: @echo $(MSG_REMOVE_CMD) Removing object files of \"$(TARGET)\" rm -f $(OBJECT_FILES) @@ -285,7 +285,7 @@ $(OBJDIR)/%.o: %.c $(MAKEFILE_LIST) $(OBJDIR)/%.o: %.cpp $(MAKEFILE_LIST) @echo $(MSG_COMPILE_CMD) Compiling C++ file \"$(notdir $<)\" $(CROSS)-gcc -c $(BASE_CC_FLAGS) $(BASE_CPP_FLAGS) $(CC_FLAGS) $(CPP_FLAGS) -MMD -MP -MF $(@:%.o=%.d) $< -o $@ - + # Assembles an input ASM source file and generates a linkable object file for it $(OBJDIR)/%.o: %.S $(MAKEFILE_LIST) @echo $(MSG_ASSEMBLE_CMD) Assembling \"$(notdir $<)\" diff --git a/LUFA/DoxygenPages/BuildSystem.txt b/LUFA/DoxygenPages/BuildSystem.txt index 3ee524ba39..5640332006 100644 --- a/LUFA/DoxygenPages/BuildSystem.txt +++ b/LUFA/DoxygenPages/BuildSystem.txt @@ -8,8 +8,8 @@ * * \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. * * For details on the prerequisites needed for Linux and Windows machines to be able to use the LUFA @@ -44,8 +44,10 @@ * \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, @@ -95,11 +97,11 @@ * * * clean - * Remove all intermediatary files and binary output files. + * Remove all intermediary files and binary output files. * * * mostlyclean - * Remove all intermediatary files but preserve any binary output files. + * Remove all intermediary files but preserve any binary output files. * * * <filename>.s @@ -211,7 +213,7 @@ * * None * - * + * * * \section SSec_BuildModule_BUILD_ProvidedMacros Module Provided Macros * @@ -290,7 +292,7 @@ * * None * - * + * * * \section SSec_BuildModule_CORE_ProvidedMacros Module Provided Macros * @@ -365,7 +367,7 @@ * * None * - * + * * * \section SSec_BuildModule_ATPROGRAM_ProvidedMacros Module Provided Macros * @@ -441,7 +443,7 @@ * * None * - * + * * * \section SSec_BuildModule_AVRDUDE_ProvidedMacros Module Provided Macros * @@ -451,7 +453,7 @@ * * */ - + /** \page Page_BuildModule_CPPCHECK The CPPCHECK build module * * The CPPCHECK programming utility LUFA build system module, providing targets to statically @@ -533,7 +535,7 @@ * * None * - * + * * * \section SSec_BuildModule_CPPCHECK_ProvidedMacros Module Provided Macros * @@ -543,7 +545,7 @@ * * */ - + /** \page Page_BuildModule_DFU The DFU build module * * The DFU programming utility LUFA build system module, providing targets to reprogram an @@ -610,7 +612,7 @@ * * None * - * + * * * \section SSec_BuildModule_DFU_ProvidedMacros Module Provided Macros * @@ -620,7 +622,7 @@ * * */ - + /** \page Page_BuildModule_DOXYGEN The DOXYGEN build module * * The DOXYGEN code documentation utility LUFA build system module, providing targets to generate @@ -687,7 +689,7 @@ * * None * - * + * * * \section SSec_BuildModule_DOXYGEN_ProvidedMacros Module Provided Macros * @@ -697,7 +699,7 @@ * * */ - + /** \page Page_BuildModule_HID The HID build module * * The HID programming utility LUFA build system module, providing targets to reprogram an @@ -768,7 +770,7 @@ * * None * - * + * * * \section SSec_BuildModule_HID_ProvidedMacros Module Provided Macros * @@ -778,7 +780,7 @@ * * */ - + /** \page Page_BuildModule_SOURCES The SOURCES build module * * The SOURCES LUFA build system module, providing variables listing the various LUFA source files @@ -849,8 +851,8 @@ * * LUFA_SRC_PLATFORM * List of LUFA architecture specific platform management source files. - * - * + * + * * * \section SSec_BuildModule_SOURCES_ProvidedMacros Module Provided Macros * @@ -860,3 +862,122 @@ * * */ + +/** \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 "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 "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 "error: invalid suffix "x" on integer constant" shown when compiling a bootloader.This is usually caused by the bc.exe application not being found in the system's PATH variable. Make sure you have the bc.exe tool + * installed correctly (see \ref Sec_Prerequisites).
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. + */ \ No newline at end of file