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.

Make targets

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

Overriding Variables

Dozens of variables in common.mk are assigned with ?= and can be overridden per-program or per-local-system.

Overriding per-program

For example, to override the entry point (pre-main routine) for your program:

TARGET=myprogram
ENTRY_SYMBOL=wrap_call_user_start
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.