minor changes

* add building doc (closes #23)
* fix esp timestamp in panic.zig
* build.zig: updated gcc-version

README.md

@@ -9,6 +9,8 @@
 
 This project aims to integrate Zig language and toolchain with the [Espressif IoT Development Framework](https://github.com/espressif/esp-idf) for enhanced development capabilities on ESP32 and its variants.
 
+More information about building and using Zig with ESP-IDF can be found in the [documentation](docs/build-internals.md).
+
 ## Prerequisites
 
 - [Zig](https://ziglang.org/download) toolchain - v0.13.0 or master

build.zig

@@ -47,7 +47,7 @@ fn includeDeps(b: *std.Build, lib: *std.Build.Step.Compile) !void {
                 ".espressif",
                 "tools",
                 archtools,
-                "esp-13.2.0_20240530",
+                "esp-14.2.0_20241119",
                 archtools,
                 "include",
             }),
@@ -58,7 +58,7 @@ fn includeDeps(b: *std.Build, lib: *std.Build.Step.Compile) !void {
                 ".espressif",
                 "tools",
                 archtools,
-                "esp-13.2.0_20240530",
+                "esp-14.2.0_20241119",
                 archtools,
                 archtools,
                 "sys-include",
@@ -70,7 +70,7 @@ fn includeDeps(b: *std.Build, lib: *std.Build.Step.Compile) !void {
                 ".espressif",
                 "tools",
                 archtools,
-                "esp-13.2.0_20240530",
+                "esp-14.2.0_20241119",
                 archtools,
                 archtools,
                 "include",

docs/build-internals.md

@@ -0,0 +1,65 @@
+## How does the mixin build-system work?
+
+#### Intro
+
+ESP-IDF uses `idf.py` script is a wrapper around CMake and is responsible for creating the build environment and running CMake to generate the build files, with ninja to build the project.
+However, zig build-system (`build.zig`) is a wrapper around the zig compiler.
+
+For more details about zig commands, see [doc/zig-xtensa](zig-xtensa.md)
+
+#### Building this project
+
+After cloning this project, you need to install ESP-IDF and set up the environment:
+
+1. Install ESP-IDF by following the official guide:
+   - Clone ESP-IDF repository: `git clone --recursive https://github.com/espressif/esp-idf.git`
+   - Run the installation script:
+     - Windows: `install.bat`|`install.ps1`
+     - Posix: `./install.sh`
+
+2. Set up the ESP-IDF environment variables:
+   - Windows: run `export.bat`|`./export.ps1`
+   - Posix: `. ./export.sh`
+
+   Once the environment is set up, you can build the project using this scheme:
+
+   ![](build-scheme.png)
+
+
+3. Set the target ESP device (if not already set):
+
+   ```bash
+   idf.py set-target (esp-device)
+   ```
+   Supported targets: esp32, esp32s2, esp32s3, esp32c3, esp32h2, esp32c2, esp32c6, esp32p4
+
+4. Build the project:
+   ```bash
+   idf.py build
+   ```
+
+5. Flash the firmware to your device:
+   ```bash
+   idf.py -p PORT flash
+   ```   
+   Replace PORT with your device's serial port (e.g., COM3 on Windows or /dev/ttyUSB0 on Linux)
+
+6. Monitor the device output:
+   ```bash
+   idf.py monitor
+   ```
+Additional useful commands:
+- Clean the project: `idf.py clean`
+- Full clean and rebuild: `idf.py fullclean`
+- Build and flash in one command: `idf.py -p PORT flash monitor`
+- Show all targets: `idf.py --list-targets`
+- Configure project: `idf.py menuconfig`
+
+
+## `build.zig` details
+
+- `searched_idf_libs`: checks and append all builded object-files (`*.obj`) from esp-idf and collect to `libapp_zig.a` - increase library size.
+- `includeDeps`: get and append esp-idf and espressif-(xtensa|riscv32)-gcc (sys-)includes to zig build.
+   - `searched_idf_include`: append components include files from esp-idf to zig build.
+- `idf_wrapped_modules`: get all imported zig modules (esp-idf bindings)
+   `esp_idf` is a zig module that contains all esp-idf bindings, and `sys` is private module low-level bindings to esp-idf. Avoid duplicate imports!

docs/zig-xtensa.md

@@ -5,7 +5,7 @@ Like [esp-rs](https://github.com/espressif/rust-esp32-example/blob/main/docs/rus
 **Current version:**
 
 - **Zig**: v0.14.0 ([bootstrap fork](https://github.com/kassane/zig-espressif-bootstrap))
-- **LLVM**: v19.0.2 ([espressif-fork](https://github.com/espressif/llvm-project))
+- **LLVM**: v19.1.2 ([espressif-fork](https://github.com/espressif/llvm-project))
 
 
 ### Commands

imports/panic.zig

@@ -3,7 +3,7 @@ const log = @import("log");
 
 /// panic handler for esp-idf
 pub fn panic(msg: []const u8, _: ?*@import("std").builtin.StackTrace, _: ?usize) noreturn {
-    sys.esp_log_write(log.default_level, "panic_handler", "PANIC: caused by %s - timestamp: %ul\n", msg.ptr, sys.esp_log_system_timestamp());
+    sys.esp_log_write(log.default_level, "panic_handler", "PANIC: caused by %s - timestamp: %ul\n", msg.ptr, sys.esp_log_timestamp());
 
     //TODO: get the stack trace and print it!