LUFA/DoxygenPages/BuildSystem.txt

   1 /** \file
   2  *
   3  *  This file contains special DoxyGen information for the generation of the main page and other special
   4  *  documentation pages. It is not a project source file.
   5  */
   6
   7 /** \page Page_BuildSystem The LUFA Build System
   8  *
   9  *  \section Sec_BuildSystem_Overview Overview of the LUFA Build System
  10  *  The LUFA build system was originally an attempt at making a set of
  11  *  re-usable, modular build make files which could be referenced in a LUFA
  12  *  powered project, to minimize the amount of code required in an
  13  *  application makefile.
  14  *
  15  *  As it turned out to be fairly generic in nature, it was split out into its
  16  *  own separate project, called DMBS (<i>Dean's Makefile Build System</i>)
  17  *  which is released into the public domain. LUFA-specific portions of the
  18  *  LUFA build system extend DMBS, and provide a universal build system for all
  19  *  LUFA projects.
  20  *
  21  *  The latest DMBS project information and documentation can be found at:
  22  *  https://github.com/abcminiuser/dmbs
  23  *
  24  *  DMBS is written in GNU Make, and each module is independent of one-another.
  25  *
  26  *  LUFA now uses DMBS for its build system, with some LUFA specific extension
  27  *  modules.
  28  *
  29  *  If you have problems building using LUFA, see \subpage Page_BuildTroubleshooting for resolution steps.
  30  *
  31  *  \li \subpage Page_BuildModule_LUFA_SOURCES - The LUFA SOURCES extension module for DMBS
  32  *  \li \subpage Page_BuildModule_LUFA_GCC - The LUFA GCC extension module for DMBS
  33  */
  34
  35 /** \page Page_BuildModule_LUFA_SOURCES LUFA SOURCES extension module for DMBS
  36  *
  37  *  The LUFA SOURCES extension more for DMBS provides LUFA specific variables
  38  *  listing the various LUFA source files required to be build by a project for
  39  *  a given LUFA module. This module gives a way to reference LUFA source files
  40  *  symbolically, so that changes to the library structure do not break the
  41  *  library makefile.
  42  *
  43  *  To use this module in your application makefile, add the following code:
  44  *  \code
  45  *  include $(LUFA_PATH)/Build/LUFA/lufa-sources.mk
  46  *  \endcode
  47  *
  48  *  \section SSec_BuildModule_LUFA_SOURCES_Requirements Requirements
  49  *  None.
  50  *
  51  *  \section SSec_BuildModule_LUFA_SOURCES_Targets Targets
  52  *
  53  *  <table>
  54  *   <tr>
  55  *    <td><i>None</i></td>
  56  *   </tr>
  57  *  </table>
  58  *
  59  *  \section SSec_BuildModule_LUFA_SOURCES_MandatoryParams Mandatory Parameters
  60  *
  61  *  <table>
  62  *   <tr>
  63  *    <td><tt>LUFA_PATH</tt></td>
  64  *    <td>Path to the LUFA library core, either relative or absolute (e.g. <tt>../LUFA-000000/LUFA/</tt>).</td>
  65  *   </tr>
  66  *   <tr>
  67  *    <td><tt>ARCH</tt></td>
  68  *    <td>Architecture of the target processor (see \ref Page_DeviceSupport).</td>
  69  *   </tr>
  70  *  </table>
  71  *
  72  *  \section SSec_BuildModule_LUFA_SOURCES_OptionalParams Optional Parameters
  73  *
  74  *  <table>
  75  *   <tr>
  76  *    <td><i>None</i></td>
  77  *   </tr>
  78  *  </table>
  79  *
  80  *  \section SSec_BuildModule_LUFA_SOURCES_ProvidedVariables Module Provided Variables
  81  *
  82  *  <table>
  83  *   <tr>
  84  *    <td><tt>LUFA_SRC_USB</tt></td>
  85  *    <td>List of LUFA USB driver source files.</td>
  86  *   </tr>
  87  *   <tr>
  88  *    <td><tt>LUFA_SRC_USBCLASS</tt></td>
  89  *    <td>List of LUFA USB Class driver source files.</td>
  90  *   </tr>
  91  *   <tr>
  92  *    <td><tt>LUFA_SRC_TEMPERATURE</tt></td>
  93  *    <td>List of LUFA temperature sensor driver source files.</td>
  94  *   </tr>
  95  *   <tr>
  96  *    <td><tt>LUFA_SRC_SERIAL</tt></td>
  97  *    <td>List of LUFA Serial U(S)ART driver source files.</td>
  98  *   </tr>
  99  *   <tr>
 100  *    <td><tt>LUFA_SRC_TWI</tt></td>
 101  *    <td>List of LUFA TWI driver source files.</td>
 102  *   </tr>
 103  *   <tr>
 104  *    <td><tt>LUFA_SRC_PLATFORM</tt></td>
 105  *    <td>List of LUFA architecture specific platform management source files.</td>
 106  *   </tr>
 107  *  </table>
 108  *
 109  *  \section SSec_BuildModule_LUFA_SOURCES_ProvidedMacros Module Provided Macros
 110  *
 111  *  <table>
 112  *   <tr>
 113  *    <td><i>None</i></td>
 114  *   </tr>
 115  *  </table>
 116  */
 117
 118 /** \page Page_BuildModule_LUFA_GCC LUFA GCC extension module for DMBS
 119  *
 120  *  The LUFA GCC extension module for the standard DMBS GCC module extends the
 121  *  latter to support the compilation of LUFA powered projects. It should be
 122  *  imported into your LUFA powered project makefiles to ensure that the correct
 123  *  build settings are used for the project's configuration.
 124  *
 125  *  To use this module in your application makefile, add the following code:
 126  *  \code
 127  *  include $(LUFA_PATH)/Build/LUFA/lufa-gcc.mk
 128  *  \endcode
 129  *
 130  *  \section SSec_BuildModule_LUFA_GCC_Requirements Requirements
 131  *  This module should be included in your makefile *after* the DMBS GCC module.
 132  *
 133  *  \section SSec_BuildModule_LUFA_GCC_Targets Targets
 134  *
 135  *  <table>
 136  *   <tr>
 137  *    <td><i>None</i></td>
 138  *   </tr>
 139  *  </table>
 140  *
 141  *  \section SSec_BuildModule_LUFA_GCC_MandatoryParams Mandatory Parameters
 142  *
 143  *  <table>
 144  *   <tr>
 145  *    <td><tt>LUFA_PATH</tt></td>
 146  *    <td>Path to the LUFA library core, either relative or absolute (e.g. <tt>../LUFA-000000/LUFA/</tt>).</td>
 147  *   </tr>
 148  *  </table>
 149  *
 150  *  \section SSec_BuildModule_LUFA_GCC_OptionalParams Optional Parameters
 151  *
 152  *  <table>
 153  *   <tr>
 154  *    <td><tt>BOARD</tt></td>
 155  *    <td>LUFA board hardware drivers to use (see \ref Page_DeviceSupport).</td>
 156  *   </tr>
 157  *  </table>
 158  *
 159  *  \section SSec_BuildModule_LUFA_GCC_ProvidedVariables Module Provided Variables
 160  *
 161  *  <table>
 162  *   <tr>
 163  *    <td><i>None</i></td>
 164  *   </tr>
 165  *  </table>
 166  *
 167  *  \section SSec_BuildModule_LUFA_GCC_ProvidedMacros Module Provided Macros
 168  *
 169  *  <table>
 170  *   <tr>
 171  *    <td><i>None</i></td>
 172  *   </tr>
 173  *  </table>
 174  */
 175
 176 /** \page Page_BuildTroubleshooting Troubleshooting Information
 177  *
 178  *  LUFA uses a lot of advanced features of the AVR-GCC compiler, linker, and
 179  *  surrounding binaries. This can sometimes lead to problems compiling
 180  *  applications if one of these features is buggy in the version of the tools
 181  *  used in a build environment. Missing utilities and incorrectly set makefile
 182  *  configuration options can also result in different errors being produced
 183  *  when compilation or other operations are attempted. The table below lists a
 184  *  set of commonly encountered errors and their resolutions.
 185  *
 186  *  <table>
 187  *    <tr>
 188  *    <th>Problem</th>
 189  *    <th>Resolution</th>
 190  *   </tr>
 191  *   <tr>
 192  *    <td>Error &quot;<b><tt>relocation truncated to fit: R_AVR_13_PCREL against symbol <i>{X}</i></tt></b>&quot; shown when compiling.</td>
 193  *    <td>Try compiling with the setting <tt>LINKER_RELAXATIONS=N</tt> in your LUFA Build System 2.0 makefile, or remove the line <tt>-Wl,--relax</tt>
 194  *        from other makefiles. Alternatively, make sure you have the latest version of the Atmel Toolchain installed for your system.</td>
 195  *   </tr>
 196  *   <tr>
 197  *    <td>Error &quot;<b><tt>error: ld terminated with signal 11 [Segmentation fault]</tt></b>&quot; shown when compiling.</td>
 198  *    <td>Try compiling with the setting <tt>DEBUG_LEVEL=2</tt> in your LUFA Build System 2.0 makefile, or make sure you are using <tt>binutils</tt> version 2.22 or later.</td>
 199  *   </tr>
 200  *   <tr>
 201  *    <td>Error &quot;<b><tt>EMERGENCY ABORT: INFINITE RECURSION DETECTED</tt></b>&quot; shown when compiling.</td>
 202  *    <td>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
 203  *        GNU make or other variants of Make causing an infinitely recursive build.</td>
 204  *   </tr>
 205  *   <tr>
 206  *    <td>Error &quot;<b><tt>Unsupported architecture &quot;<i>{X}</i>&quot;</tt></b>&quot; shown when compiling.</td>
 207  *    <td>Ensure your makefile's <tt>ARCH</tt> setting is set to one of the architecture names (case-sensitive) supported by the version of LUFA you are compiling against.</td>
 208  *   </tr>
 209  *   <tr>
 210  *    <td>Error &quot;<b><tt>Makefile <i>{X}</i> value not set</tt></b>&quot; shown when compiling.</td>
 211  *    <td>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
 212  *        build system modules. Define the value in your project makefile and try again.</td>
 213  *   </tr>
 214  *   <tr>
 215  *    <td>Error &quot;<b><tt>Makefile <i>{X}</i> option cannot be blank</tt></b>&quot; shown when compiling.</td>
 216  *    <td>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
 217  *        option, an empty value is not allowed. Define the nominated setting to a correct non-blank value and try again.</td>
 218  *   </tr>
 219  *   <tr>
 220  *    <td>Error &quot;<b><tt>Makefile <i>{X}</i> option must be Y or N</tt></b>&quot; shown when compiling.</td>
 221  *    <td>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").
 222  *        This configuration option is required to be one of the aforementioned boolean values, and other values are invalid. Set this option to either Y or N and try again.</td>
 223  *   </tr>
 224  *   <tr>
 225  *    <td>Error &quot;<b><tt>Unknown input source file formats: <i>{X}</i></tt></b>&quot; shown when compiling.</td>
 226  *    <td>The nominated source files, specified in your project's makefile in the <tt>SRC</tt> configuration option, has an extension that the LUFA build system does not
 227  *        recognise. The file extensions are case sensitive, and must be one of the supported formats (<tt>*.c</tt>, <tt>*.cpp</tt> or <tt>*.S</tt>).</td>
 228  *   </tr>
 229  *   <tr>
 230  *    <td>Error &quot;<b><tt>Cannot build with OBJDIR parameter set - one or more object file name is not unique</tt></b>&quot; shown when compiling.</td>
 231  *    <td>When a project is built with a non-empty <tt>OBJDIR</tt> object directory name set, all input source files must have unique names, excluding extension and path.
 232  *        This means that input files that are named identically and differ only by their path or extension are invalid when this mode is used.</td>
 233  *   </tr>
 234  *   <tr>
 235  *    <td>Error &quot;<b><tt>Source file does not exist: <i>{X}</i></tt></b>&quot; shown when compiling.</td>
 236  *    <td>The nominated input source file, specified in the user project's <tt>SRC</tt> parameter, could not be found. Ensure the source file exists and the absolute or
 237  *        relative path given in the user project makefile is correct and try again.</td>
 238  *   </tr>
 239  *   <tr>
 240  *    <td>Error &quot;<b><tt>Doxygen configuration file <i>{X}</i> does not exist</tt></b>&quot; shown when upgrading a Doxygen configuration file.</td>
 241  *    <td>The nominated Doxygen configuration file, specified in the user project's <tt>DOXYGEN_CONF</tt> parameter, could not be found. Ensure the configuration file exists
 242  *        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
 243  *        file.</td>
 244  *   </tr>
 245  *   <tr>
 246  *    <td>Error &quot;<b><tt>avr-gcc: error: unrecognized option '<i>{X}</i>'</tt></b>&quot; shown when compiling.</td>
 247  *    <td>An unrecognised option was supplied to the compiler, usually in the <tt>C_FLAGS</tt>, <tt>CPP_FLAGS</tt>, <tt>ASM_FLAGS</tt> or <tt>CC_FLAGS</tt> configuration
 248  *        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
 249  *        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.</td>
 250  *   </tr>
 251  *   <tr>
 252  *    <td>Error &quot;<b><tt>makefile:{X}: {Y}.mk: No such file or directory</tt></b>&quot; shown when make is invoked.</td>
 253  *    <td>The path to the nominated makefile module was incorrect. This usually indicates that the makefile <tt>LUFA_PATH</tt> option is not set to a valid relative or
 254  *        absolute path to the LUFA library core.</td>
 255  *   </tr>
 256  *   <tr>
 257  *    <td>Error &quot;<b><tt>fatal error: LUFAConfig.h: No such file or directory</tt></b>&quot; shown when compiling.</td>
 258  *    <td>The <tt>USE_LUFA_CONFIG_HEADER</tt> compile time option was set in the user project makefile, but the user supplied <tt>LUFAConfig.h</tt> header could not be
 259  *        found. Ensure that the directory that contains this configuration file is correctly passed to the compiler via the -I switch in the makefile <tt>CC_FLAGS</tt>
 260  *        parameter.</td>
 261  *   </tr>
 262  *   <tr>
 263  *    <td>Error &quot;<b><tt>ld.exe: section .apitable_trampolines loaded at <i>{X}</i> overlaps section .text</tt></b>&quot; shown when compiling a bootloader.</td>
 264  *    <td>The bootloader is compiling too large for the given <tt>FLASH_SIZE_KB</tt> and <tt>BOOT_SECTION_SIZE_KB</tt> parameters set in the bootloader makefile. This
 265  *        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
 266  *        compiler may need to be used to ensure that the bootloader is built within the section size constraints of the target device.</td>
 267  *   </tr>
 268  *   <tr>
 269  *    <td>Error &quot;<b><tt>unknown MCU '<i>{X}</i>' specified</tt></b>&quot; shown when compiling.</td>
 270  *    <td>The specified microcontroller device model name set in the user application's makefile as the <tt>MCU</tt> parameter is incorrect, or unsupported by the
 271  *        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.</td>
 272  *   </tr>
 273  *   <tr>
 274  *    <td>Error &quot;<b><tt>undefined reference to `<i>{X}</i>'</tt></b>&quot; shown when compiling.</td>
 275  *    <td>This is usually caused by a missing source file in the user application's <tt>SRC</tt> configuration parameter. If the indicated symbol is one from the LUFA
 276  *        library, you may be missing a LUFA source makefile module (see \ref Page_BuildModule_LUFA_SOURCES).</td>
 277  *   </tr>
 278  *  </table>
 279  *
 280  *  For troubleshooting other errors you encounter, please see \ref Sec_ProjectHelp.
 281  */