The AVR software framework includes its own build system consisting of a large number of Makefiles. This page intends to explain how those Makefiles work together, and how they are used to build applications.
To build an application, simply enter the appropriate directory under apps/ and type "make". This results in a new directory being created under build/ where the results of the build process will be stored, if it didn't exist already. After performing this step once, subsequent builds can be done either by running "make" from the application directory as before, or by running "make" from the build directory.
Each application has a default board for which the application will be built unless otherwise specified. To build the application for a different board, simply set the BOARD environment variable to the name of the desired board when running "make", for example like this:
By default, the build process is quite silent, only listing which files are being built, not the full command lines used to build them. To see the full commands, enable verbose mode by setting the environment variable V to 1:
If no target is specified on the "make" command line, the application will simply be built as an ELF file. Other possibilities are:
- clean - Delete the ELF file and all intermediate build products.
- program - Build the ELF file and program it into flash on the target.
- reset - Reset the target.
- run - Start executing code on the target.
Several targets may be specified on the command line -- they will be executed in the order specified. For example, the following command will build the ELF file, program it into the target, and start running from the reset vector:
Each subdirectory contains a Makefile fragment specifying which source files that are to be built into objects, and sometimes which additional subdirectories to include in the build. This Makefile fragment is usually called
subdir.mk, but there are some exceptions to this rule:
- Application subdirectory Makefiles are named $(app).mk
- Chip-, cpu-, arch- and board-specific Makefiles are named chip.mk, cpu.mk, arch.mk and board.mk respectively.
The subdirectory Makefiles are usually very small, only appending to a single variable, obj-y, which specifies which objects to build, but there are other variables that may be altered by subdirectory Makefiles as well:
- cppflags-y - C preprocessor flags for all files
- cflags-y - C compiler flags for all files
- ldflags-y - Linker flags for the final link
- ldlibs-y - Libraries to include in the final link
The reason why all these variables have the suffix -y is to make it easier to support conditional compilation and conditional flags. For example, if a certain object is to be built only when CONFIG_USB is set to 'y', this can be achieved as follows:
obj-$(CONFIG_USB) += drivers/usb/usb.o
Each application found under the apps/ subdirectory contains its own top-level Makefile which can be used to build that particular application. It is usually very simple, delegating the vast majority of the work to the build system core.
- Example: apps/hello/Makefile
The following variables must be defined by the top-level Application Makefile:
- src - The relative path to the top-level source directory
- app - The name of the application. $(src)/apps/$(app) must resolve to the directory in which the Makefile resides.
- DEFAULT_BOARD - The name of the board to build for when the user doesn't specify any particular board.
After defining these variables, the Makefile should simply include $(src)/make/app.mk to take care of the rest.
Each application must provide one or more configuration files for the build system. These are named
config-board.mk, for each supported board. All applications must provide a configuration file for the default board; configuration files for any other boards is optional.
The configuration files may contain all kinds of Makefile variable definitions, but its primary purpose is to specify configuration variables. These variables are available both to the build system and to the source files, so they need to follow a few special rules:
- The variable name must begin with
CONFIG_ - The variable name must be followed by a '=' character and a value with no spaces in between.
- String values must be surrounded by double quotes.
- Boolean values must be either 'y' or 'n'.
- Integer values are expressed using any valid C syntax.
During the build process, this file is used as a source for generating the autoconf.h file, which is included implicitly in all source files. The variables are converted as follows:
- Boolean variables set to 'y' become preprocessor symbols defined as 1.
- Boolean variables set to 'n' are not defined (so #ifdef can be used to test the value of boolean configuration variables.)
- String and integer variables become preprocessor symbols defined as their respective literal values (including the quotes for string variables.)
The application must include a file named
$(app).mk specifying any application-specific object files and flags. This file follows the syntax described in the section
Subdirectory Makefiles.
