Build Process

About the esp-open-rtos build process.

esp-open-rtos has a modular, parallelisable, build process based around GNU Make.

Per-program Makefile

Each individual esp-open-rtos program has its own Makefile. Each example subdirectory under the 'examples' directory is an example program with its own Makefile.

Most program makefiles are very simple:

TARGET=my_program
include path/to/common.mk

• TARGET is the name that will be used for the build output
• include ...common.mk pulls in the top-level common.mk makefile that handles the rest of the build. This has to include the path to the top level esp-open-rtos directory.

common.mk can be at an absolute or relative path. The program does not have to be in the same directory as esp-open-rtos.

The default for a simple Makefile is to build all .c directories in the same directory as the Makefile (the 'TARGET') directory. See below for details on how to add additional directories.

Make targets

Run make help in any program directory for a summary of Makefile targets.

Source directories

By default, all C files in the Makefile directory ("target" directory) are built along with the library components specified in common.mk (see below). To build C files in subdirectories, there are two approaches.

Specify the list of directories in the Makefile via the variable TARGET_SRC_DIR, like this:

TARGET=my_program
TARGET_SRC_DIR=. ./subdir
include path/to/common.mk

... in the above example, all .c files in both the Makefile directory and the subdirectory subdir will be built.

If you want to add extra source files, without adding all the files in a directory:

TARGET=my_program
TARGET_EXTRA_SRC_FILES=./subdir/subfile.c
include path/to/common.mk

... you can combine TARGET_SRC_DIR and TARGET_EXTRA_SRC_FILES in order to search some directories for all .c files, but include some specific source files from other directories.

Finally, as a third option, you can just specify a list of source files only:

TARGET=my_program
TARGET_SRC_FILES=./main.c ./subdir/subfile.c
include path/to/common.mk

... no directories are searched for .c files, only the files specified in the Makefile will be built.

Important: At the moment all files listed should be in subdirectories of the TARGET directory (ie the directory with the Makefile). Otherwise build paths may end up weird. If you want to build source files in totally unrelated directories, the best way is to make these into separate 'components' (see below). If there is a particular configuration that is hard to build, please open an issue here and we'll figure out together how to support it.

Overriding Variables

Dozens of variables in common.mk are assigned with ?= and can be overridden per-program or per-local-system by adding definitions in the program Makefile or a local.mk file.

Overriding per-program

For example, to override the build directory:

TARGET=myprogram
BUILD_DIR=/tmp/custombuild
include ../esp-open-rtos/common.mk

Overriding per-local-system

If you want to override a variable for all programs on your local computer, without editing common.mk, you can do this by creating a file local.mk in the same directory as common.mk.

For example, to override the default esptool.py serial port, create this local.mk:

ESPPORT=COM3

If you want to be very granular with your overrides then you can also create a local.mk file in the same directory as your program, which gets included after the top-level one.

Source Components

common.mk defines a list of source components to build:

# Source components to compile and link. Each of these are subdirectories                                                                               
# of the root, with a 'component.mk' file.                                                                                                         
COMPONENTS     ?= FreeRTOS lwip axtls

(The COMPONENTS variable can also be overriden as shown above.)

Each component is built from source along with the program. There is a component.mk file in each component directory that specifies the source file directories, include directories, and directories to be added to the global include list.

Binary libraries

Default binary libraries are specified in common.mk as well:

# binary esp-iot-rtos SDK libraries to link. These are pre-processed prior to linking.                                                                  
SDK_LIBS                ?= main net80211 phy pp wpa                                                                                                     
                                                                                                                                                        
# open source libraries linked in                                                                                                           
LIBS ?= gcc hal      

Libraries listed in SDK_LIBS are preprocessed by the build system to prefix sdk_ onto each symbol name. Libraries listed in LIBS are linked directly.

Build Output

Build output goes to a build subdirectory of the program directory. The ELF binary (for use with gdb or objdump) is build/<TARGET>.elf.

Raw binaries for flashing with esptool.py are output to the firmware subdirectory.