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