LUFA Library  151115
Configuring the Demos, Bootloaders and Projects

If the target microcontroller model, architecture, clock speed, board or other settings are different from the current settings, they must be changed and the project recompiled from the source code before being programmed into the microcontroller. Most project configuration options are located in the makefile build script inside each LUFA application's folder, however some demo or application-specific configuration settings are located in one or more of the source files of the project. See each project's individual documentation for application-specific configuration values.

Each project "makefile" contains all the script and configuration data required to compile each project. When opened with any regular basic text editor such as Notepad or WordPad (ensure that the save format is a pure ASCII text format) the build configuration settings may be altered.

See also
The LUFA Build System for information on the LUFA build system.

The Default Application Makefile Template

Below is a copy of the default LUFA application makefile, which can be used as a template for each application.

#
#             LUFA Library
#     Copyright (C) Dean Camera, 2015.
#
#  dean [at] fourwalledcubicle [dot] com
#           www.lufa-lib.org
#
# --------------------------------------
#         LUFA Project Makefile.
# --------------------------------------

# Run "make help" for target help.

MCU          = at90usb1287
ARCH         = AVR8
BOARD        = USBKEY
F_CPU        = 8000000
F_USB        = $(F_CPU)
OPTIMIZATION = s
TARGET       = Target
SRC          = $(TARGET).c $(LUFA_SRC_USB) $(LUFA_SRC_USBCLASS) $(LUFA_SRC_PLATFORM)
LUFA_PATH    = ../../LUFA
CC_FLAGS     = -DUSE_LUFA_CONFIG_HEADER -IConfig
LD_FLAGS     =

# Default target
all:

# Include LUFA build script makefiles
include $(LUFA_PATH)/Build/lufa_core.mk
include $(LUFA_PATH)/Build/lufa_sources.mk
include $(LUFA_PATH)/Build/lufa_build.mk
include $(LUFA_PATH)/Build/lufa_cppcheck.mk
include $(LUFA_PATH)/Build/lufa_doxygen.mk
include $(LUFA_PATH)/Build/lufa_dfu.mk
include $(LUFA_PATH)/Build/lufa_hid.mk
include $(LUFA_PATH)/Build/lufa_avrdude.mk
include $(LUFA_PATH)/Build/lufa_atprogram.mk

Inside each makefile, a number of configuration variables are listed with the syntax "<VARIABLE NAME> = <VALUE>". For each application, the important standard variables which should be altered are:

  • MCU, the target processor model
  • ARCH, the target microcontroller architecture
  • BOARD, the target board hardware
  • F_CPU, the target CPU master clock frequency, after any prescaling
  • F_USB, the target raw input clock to the USB module of the processor
  • OPTIMIZATION, the level of optimization to compile with
  • TARGET, the name of the target output binary and other files
  • SRC, the list of source files to compile/assemble/link
  • LUFA_PATH, the path to the LUFA library core source code
  • CC_FLAGS, the common command line flags to pass to the C/C++ compiler, assembler and linker
  • LD_FLAGS, the command line flags to pass to the linker

These values should be changed to reflect the build hardware.

The MCU Parameter

This parameter indicates the target microcontroller model for the compiled application. This should be set to the model of the target microcontroller (such as the AT90USB1287, or the ATMEGA32U4), in all lower-case (e.g. "at90usb1287"). Note that not all demos support all the microcontroller models and architectures, as they may make use of peripherals or modes only present in some devices.

For supported processor models, see Device and Hardware Support.

The ARCH Parameter

This parameter indicates the target microcontroller architecture the library is to be compiled for. Different microcontroller architectures require different source files to be compiled into the final binary, and so this option must be set to the correct architecture for the selected platform.

For supported processor architectures, see Device and Hardware Support.

The BOARD Parameter

This parameter indicates the target board hardware for the compiled application. Some LUFA library drivers are board-specific, such as the LED driver, and the library needs to know the layout of the target board. If you are using one of the board models listed on the main library page, change this parameter to the board name in all UPPER-case.

If you are not using any board-specific drivers in the LUFA library, or you are using a custom board layout, change this to read "USER" (no quotes) instead of a standard board name. If the USER board type is selected and the application makes use of one or more board-specific hardware drivers inside the LUFA library, then the appropriate stub drives files should be copied from the /CodeTemplates/DriverStubs/ directory into a /Board/ folder inside the application directory, and the stub driver completed with the appropriate code to drive the custom board's hardware.

For boards with built in hardware driver support within the LUFA library, see Device and Hardware Support.

The F_CPU Parameter

This parameter indicates the target microcontroller's main CPU clock frequency, in Hz. This is used by many libraries (and applications) for timing related purposes, and should reflect the actual CPU speed after any prescaling or adjustments are performed.

The F_USB Parameter

This parameter indicates the raw input clock frequency to the USB module within the microcontroller in Hz. This may be very different on some platforms to the main CPU clock or other peripheral/bus clocks.

Note
On AVR8 platforms, this must be equal to 8000000 or 16000000.
On XMEGA platforms, this must be equal to a multiple of 6000000 from 6000000 to 48000000.
On UC3 platforms, this must be equal to a multiple of 12000000 from 12000000 to 48000000.

The OPTIMIZATION Parameter

This parameter indicates the level of optimization to use when compiling the application. This will allow you to compile with an optimization level supported by GCC, from 0 (no optimization) to 3 (fastest runtime optimization) or s (smallest size).

The TARGET Parameter

This parameter indicates the application target name, which is used as the base filename for the build binary and debugging files. This will be the name of the output files once linked together into the final application, ready to load into the target.

The SRC Parameter

This parameter indicates the source files used to compile the application, as a list of C (*.c), C++ (*.cpp) and Assembly (*.S) files. Note that all assembly files must end in a capital .S extension, as lowercase .s files are reserved for GCC intermediate files.

The LUFA_PATH Parameter

As each LUFA program requires the LUFA library source code to compile correctly, the application must know where the LUFA library is located. This value specifies the path to the LUFA library core. This path may be relative or absolute, however note than even under Windows based systems the forward-slash (/) path separator must be used.

The CC_FLAGS Parameter

This parameter lists the compiler flags passed to the C/C++ compiler, the assembler and the linker. These are used as-is directly to GCC and thus must match GCC's command line options as given in the GCC manual. This variable may be used to define tokens directly on the command line, enable or disable warnings, adjust the target-specific tuning parameters or other options.

The LD_FLAGS Parameter

This parameter lists the linker flags passed exclusively to the linker. These are used as-is directly to GCC and thus must match GCC's command line linker options as given in the GCC manual. This variable may be used to create or relocate custom data sections, or enable linker specific behaviors.

Example Application Makefile Configurations

Below is an example makefile for an AVR8 based AT90USB1287 running at 8MHz, to compile a program called "MyApplication":

MCU          = at90usb1287
ARCH         = AVR8
BOARD        = NONE
F_CPU        = 8000000
F_USB        = $(F_CPU)
OPTIMIZATION = s
TARGET       = MyApplication
SRC          = MyApplication.c Descriptors.c $(LUFA_SRC_USB) $(LUFA_SRC_USBCLASS)
LUFA_PATH    = ../../../../LUFA
CC_FLAGS     = -DUSE_LUFA_CONFIG_HEADER -IConfig/
LD_FLAGS     =

Below is an example makefile for an XMEGA based ATXMEGA128A1U running at 32MHz, to compile a program called "MyApplication":

MCU          = atxmega128a1u
ARCH         = XMEGA
BOARD        = NONE
F_CPU        = 32000000
F_USB        = 48000000
OPTIMIZATION = s
TARGET       = MyApplication
SRC          = MyApplication.c Descriptors.c $(LUFA_SRC_USB) $(LUFA_SRC_USBCLASS)
LUFA_PATH    = ../../../../LUFA
CC_FLAGS     = -DUSE_LUFA_CONFIG_HEADER -IConfig/
LD_FLAGS     =

Below is an example makefile for a UC3 based AT32UC3A0512 running at 50MHz, to compile a program called "MyApplication":

MCU          = uc3a0512
ARCH         = UC3
BOARD        = NONE
F_CPU        = 50000000
F_USB        = 48000000
OPTIMIZATION = s
TARGET       = MyApplication
SRC          = MyApplication.c Descriptors.c $(LUFA_SRC_USB) $(LUFA_SRC_USBCLASS)
LUFA_PATH    = ../../../../LUFA
CC_FLAGS     = -DUSE_LUFA_CONFIG_HEADER -IConfig/
LD_FLAGS     =