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, as well as a default toolchain to use. To build the application for a different board, simply set the CONFIG environment variable to the name of the desired board when running "make", for example like this:
make CONFIG=atstk1005
To use a different toolchain than the default, set the TOOLCHAIN variable to either "GNU" or "IAR", for example like this:
make TOOLCHAIN=GNU
The build results will be placed in build/application/board/toolchain. For example, when building the led-chaser application for the ATEVK1104 board using the IAR toolchain, the result will end up in the directory build/led-chaser/atevk1104/IAR
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:
make V=1
If no target is specified on the "make" command line, the application will simply be built as an ELF file. Other possibilities are:
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:
make program reset run
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:
CONFIG_ 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:
There are also similar configuration files for each supported board, chip, cpu and architecture named config.mk and placed in the respective board-, chip-, cpu- and architecture-specific subdirectories. These provide reasonable defaults which can be overridden by the application config file.
Compiler and linker optimization is controlled through configuration symbols. By default, all files are compiled with maximum size optimization, but this can be customized on a per-application basis.
To optimize for speed instead of size, set CONFIG_OPTIMIZE_SIZE to 'n'. To select a different optimization level, set CONFIG_OPTIMIZE_LEVEL to the desired level (a number from 0 to 3). The following table summarizes the various possibilities
| CONFIG_OPTIMIZE_SIZE | CONFIG_OPTIMIZE_LEVEL | GCC option | IAR option |
| y | 0 | -Os | -z2 |
| y | 1 | -Os | -z3 |
| y | 2 | -Os | -z6 |
| y | 3 | -Os | -z9 |
| n | 0 | -O0 | -s2 |
| n | 1 | -O1 | -s3 |
| n | 2 | -O2 | -s6 |
| n | 3 | -O3 | -s9 |
In addition, two forms of link-time optimizations are enabled by default when using the GNU toolchain. These are:
To disable any of those optimizations, set the corresponding configuration symbol to 'n'.
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:
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:
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.
src := ../.. app := led-chaser DEFAULT_CONFIG := xplain DEFAULT_TOOLCHAIN := GNU include $(src)/make/app.mk
The following variables must be defined by the top-level Application Makefile:
After defining these variables, the Makefile should simply include $(src)/make/app.mk to take care of the rest.
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.
1.6.3