Using Zig Language & Toolchain with ESP-IDF

Supported Targets	ESP32	ESP32-C2	ESP32-C3	ESP32-C6	ESP32-H2	ESP32-P4	ESP32-S2	ESP32-S3

STATUS: Experimental

Description

This project aims to integrate Zig language and toolchain with the Espressif IoT Development Framework for enhanced development capabilities on ESP32 and its variants.

Prerequisites

• Zig toolchain - v0.12.0 or master
• ESP-IDF - v4.4 or v5.2 or master

Targets Allowed

target	commands
esp32	-Dtarget=xtensa-freestanding-none -Dcpu=esp32
esp32-s2	-Dtarget=xtensa-freestanding-none -Dcpu=esp32s2
esp32-s3	-Dtarget=xtensa-freestanding-none -Dcpu=esp32s3
esp32-c2/c3	-Dtarget=riscv32-freestanding-none -Dcpu=generic_rv32+c+m
esp32-h2/c5/c6	-Dtarget=riscv32-freestanding-none -Dcpu=generic_rv32+a+c+m
esp32-p4	-Dtarget=riscv32-freestanding-eabihf -Dcpu=generic_rv32+a+c+f+m

Warning

Zig upstream (LLVM-Codegen) does not have xtensa support. Like esp-rs, it is necessary to use the zig-xtensa - toolchain forked.

Key Features:

• Zig Language Integration: Use the Zig programming language to write firmware code. It provides modern language features such as comptime, meta-programming, and error handling.

• Zig Toolchain Integration: The Zig toolchain can be used to build zig libraries and executables, and can also be integrated with the ESP-IDF build system. Also, system compiler and linker can be replaced to zig cc/zig c++.

  • Note: For C++ support, zig toolchain uses llvm-libc++ ABI by default.

• ESP-IDF Compatibility: Seamlessly integrate Zig with the ESP-IDF framework, allowing developers to leverage the rich set of APIs and functionalities provided by ESP-IDF for IoT development.

• Build System Configuration: Using CMake to build Zig libraries allows easy integration with existing ESP-IDF projects while providing efficient dependency management and build configuration.

• Cross-Platform Development: Facilitate development across various ESP32 variants including ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-P4, ESP32-S2, and ESP32-S3, ensuring broad compatibility and versatility.

About Allocators

Note

Asserts allocations are within @alignOf(std.c.max_align_t) and directly calls malloc/free. Does not attempt to utilize malloc_usable_size.

• std.heap.raw_c_allocator allocator is safe to use as the backing allocator with std.heap.ArenaAllocator for example and is more optimal in such a case than std.heap.c_allocator. - ref.: std-doc

• std.heap.ArenaAllocator takes an existing allocator, wraps it, and provides an interface where you can allocate without freeing, and then free it all together. - ref.: std-doc

Custom Allocators (based on std.heap.raw_c_allocator)

• idf.heap.HeapCapsAllocator - ref.: espressif-doc
• idf.heap.MultiHeapAllocator - ref.: espressif-doc
• idf.heap.vPortAllocator - ref.: FreeRTOS-doc

License

This project is licensed twice:

• Apache
• MIT-0