Streamline ESP32 image creation

UncleGrumpy · UncleGrumpy · commit f56d0d5fb767 · 2025-11-19T23:55:01.000Z
Modifies the ESP32 build configuration and mkimage tool to automatically detect the image flavor
based on the partition table used. By checking the offset of the application partition the correct
flavor of language support is used when creating images. Adds a config option to configure an
Elixir supported build by using `idf.py -DAVM_ELIXIR_BOOT=on set-target ${CHIP}`.

Signed-off-by: Winford &lt;winford@object.stream&gt;
diff --git a/.github/workflows/esp32-mkimage.yaml b/.github/workflows/esp32-mkimage.yaml
@@ -125,7 +125,7 @@ jobs:
       shell: bash
       working-directory: ./src/platforms/esp32/
       run: |
-        cp sdkconfig.release-defaults sdkconfig.defaults
+        cp sdkconfig.release-defaults.in sdkconfig.defaults.in
 
     - name: "Build ${{ matrix.soc }}${{ matrix.flavor }} with idf.py"
       shell: bash
@@ -138,19 +138,14 @@ jobs:
           mv partitions${{ matrix.flavor }}.csv partitions.csv
         fi
         idf.py set-target ${{ matrix.soc }}
-        idf.py reconfigure
         idf.py build
 
     - name: "Create a ${{ matrix.soc }}${{ matrix.flavor }} image"
       working-directory: ./src/platforms/esp32/build
       run: |
-        if [ -z "${{ matrix.flavor }}" ]
+        ./mkimage.sh
+        if [ -n "${{ matrix.flavor }}" ]
         then
-          ./mkimage.sh
-        else
-          FLAVOR_SUFFIX=$(echo "${{ matrix.flavor }}" | sed 's/-//g')
-          BOOT_FILE="../../../../build/libs/esp32boot/${FLAVOR_SUFFIX}_esp32boot.avm"
-          ./mkimage.sh --boot "$BOOT_FILE"
           mv atomvm-${{ matrix.soc }}.img atomvm-${{ matrix.soc }}${{ matrix.flavor }}.img
         fi
         ls -l *.img
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -64,6 +64,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `proc_lib`
 - Added gen_server support for timeout tuples in callback return actions introduced in OTP-28.
 - Added `sys`
+- Added ESP32 `-DATOMVM_ELIXIR_SUPPORT=on` configuration option
 
 ### Changed
 
@@ -82,6 +83,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `binary_to_integer` and `list_to_integer` do not raise anymore `overflow` error, they raise
 instead `badarg`.
 - ESP32 cmake build options are now also exposed in `idf.py menuconfig`.
+- ESP32 Elixir support is determined automatically from the offset of `boot.avm` in the partiton
+table.
 
 ### Fixed
 
diff --git a/UPDATING.md b/UPDATING.md
@@ -19,6 +19,17 @@ bitshifts: e.g. `(16#FFFF band 0xF) bsl 252`.
 - `binary_to_integer` and `list_to_integer` do not raise `overflow` error anymore, they instead
 raise `badarg` when trying to parse an integer that exceeds 256 bits. Update any relevant error
 handling code.
+- ESP32 builds with Elixir support may be configured without making changes to git tracked files
+using `idf.py -DATOMVM_ELIXIR_SUPPORT=on set-target ${CHIP}` instead of copying
+partitions-elixir.csv to partitions.csv. This configures the build to use partitions-elixir.csv for
+the partition table. The `main.avm` offset in the partition table will determine which flavor of
+esp32boot libraries to include for the `idf.py flash` task and the image assembled by
+`build/mkimage.sh`.
+- ESP32 release builds may be configured with `idf.py -DATOMVM_RELEASE=on set-target ${CHIP}`
+rather than copy sdkconfig.release-defaults.in to sdkconfig.defaults.in (which still requires a
+`reconfigure` or `set-target` to be run to pick up the changes), this may also be combined with the
+`ATOMVM_ELIXIR_SUPPORT` option. For example, an Elixir supported release build is configured using:
+`idf.py -DATOMVM_ELIXIR_SUPPORT=on -DATOMVM_RELEASE=on set-target ${CHIP}`
 
 ## v0.6.4 -> v0.6.5
 
diff --git a/doc/src/build-instructions.md b/doc/src/build-instructions.md
@@ -239,29 +239,31 @@ $ cd <atomvm-source-tree-root>
 $ cd src/platforms/esp32
 ```
 
-If you want to build an image with Elixir modules included you must first have a version of Elixir installed that is compatible with your OTP version, then add the following line to sdkconfig.defaults:
+Start by configuring the default build configuration of local `sdkconfig` for your target device:
+
 ```shell
-CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions-elixir.csv"
+$ idf.py set-target ${CHIP}
 ```
 
-Start by updating the default build configuration of local `sdkconfig` file via the `idf.py reconfigure` command:
+If you want to build a deployment with Elixir modules included you must first have a version of Elixir
+installed that is compatible with your OTP version, and instead use the command:
 
 ```shell
-$ idf.py set-target esp32
-$ idf.py reconfigure
+idf.py -DATOMVM_ELIXIR_SUPPORT=on set-target ${CHIP}`
 ```
 
 ```{tip}
-For those familiar with esp-idf the build can be customized using `menuconfig` instead of
-`reconfigure`:
+For those familiar with esp-idf the build can be customized using `menuconfig`:
 
+    $ idf.py set-target ${CHIP}
     $ idf.py menuconfig
 
 This command will bring up a curses dialog box where you can make adjustments such as not including
 AtomVM components that are not desired in a particular build. You can also change the behavior of a
-crash in the VM to print the error and reboot, or halt after the error is printed. Extreme caution
-should be used when changing any non AtomVM settings. You can quit the program by typing `Q`.
-Save the changes, and the program will exit.
+crash in the VM to print the error and reboot, or halt after the error is printed. To configure an
+Elixir supported build under the "Partition Table" setting select the Custom partitions CSV file and
+set this to `partitions-elixir.csv`. Extreme caution should be used when changing any non AtomVM
+settings. You can quit the program by typing `Q`. Save the changes, and the program will exit.
 ```
 
 You can now build AtomVM using the build command:
@@ -482,9 +484,17 @@ core Erlang libraries will be written to the `build/libs` directory in the AtomV
 you target a different build directory when running CMake.
 ```
 
-Running this script will generate a single `atomvm-<sha>.img` file in the `build` directory of the esp32 source tree, where `<sha>` is the git hash of the current checkout.  This image contains the ESP32 bootloader, AtomVM executable, and the `eavmlib` and `estdlib` Erlang libraries in one file, which can then be flashed to address `0x1000` for the esp32. The bootloader address varies for other chip variants. See the [flashing a binary image to ESP32](./getting-started-guide.md#flashing-a-binary-image-to-esp32) section of the [Getting Started Guide](./getting-started-guide.md) for a chart with the bootloader offset address of each model.
+Running this script will generate a single `atomvm-<target-chip>.img` file in the `build` directory
+of the esp32 source tree, where `<target-chip>` is the device configured with `set-target`.  This
+image contains the ESP32 bootloader, AtomVM executable, and the `eavmlib` and `estdlib` Erlang
+libraries (and `exavmlib` Elixir libraries if configured for Elixir support) in one file, which can
+then be flashed to address `0x1000` for the esp32. The bootloader address varies for other chip
+variants. See the
+[flashing a binary image to ESP32](./getting-started-guidemd#flashing-a-binary-image-to-esp32)
+section of the [Getting Started Guide](./getting-started-guide.md) for a chart with the bootloader
+offset address of each model.
 
-To build a thin image with only Erlang libraries `mkimage.sh` script is run from the `src/platform/esp32` directory as follows:
+To build a complete image use this command from the `src/platform/esp32` directory as follows:
 
 ```shell
 $ ./build/mkimage.sh
@@ -496,18 +506,6 @@ Wrote AtomVM Virtual Machine at offset 0x10000 (65536)
 Wrote AtomVM Core BEAM Library at offset 0x1D0000 (1114112)
 ```
 
-To build a full image with Erlang and Elixir libraries the path to the previously (during the generic_unix build) built `elixir_esp32boot.avm` must be passed to the `mkimage.sh` script as follows (Note: this is still run from the AtomVM/src/platforms/esp32 directory for the relative path to work - feel free to use the absolute path to this file):
-
-```shell
-$ ./build/mkimage.sh --boot ../../../build/libs/esp32boot/elixir_esp32boot.avm
-Writing output to /home/joe/AtomVM/src/platforms/esp32/build/atomvm-esp32.img
-=============================================
-Wrote bootloader at offset 0x1000 (4096)
-Wrote partition-table at offset 0x8000 (32768)
-Wrote AtomVM Virtual Machine at offset 0x10000 (65536)
-Wrote AtomVM Core BEAM Library at offset 0x1D0000 (1114112)
-```
-
 Users can then use the `esptool.py` directly to flash the entire image to the ESP32 device, and then flash their applications to the `main.app` partition at address `0x210000`, (or `0x250000` for Elixir images)
 
 But first, it is a good idea to erase the flash, e.g.,
@@ -602,7 +600,7 @@ applications for the AtomVM platform.
 
 #### Flashing the core libraries
 
-If you are doing development work on the core Erlang/Elixir libraries and wish to test changes that do not involve the `C` code in the core VM you may flash `esp32boot.avm` (or `elixir_esp32boot.avm` when using an Elixir partition table) to the boot.avm partition (offset 0x1D0000) by using the `flash.sh` script in the esp32 build directory as follows:
+If you are doing development work on the core Erlang/Elixir libraries and wish to test changes that do not involve the `C` code in the core VM you may flash `esp32boot.avm` or `elixir_esp32boot.avm` to the boot.avm partition by using the `flash.sh` script in the esp32 build directory as follows:
 
 ```shell
 $ build/flash.sh -l ../../../build/libs/esp32boot.avm
@@ -636,6 +634,13 @@ Leaving...
 Hard resetting via RTS pin...
 ```
 
+```{attention}
+It is important that you flash the `esp32boot` variant that matches the configuration used to
+create the build currently on the device. Flashing `elixir_esp32boot.avm` to a device that was not
+flashed with an Elixir support build will not work, AtomVM will still try to load an application
+from an address that is now occupied by the `exavmlib` modules.
+```
+
 ### Adding custom Nifs, Ports, and third-party components
 
 While AtomVM is a functional implementation of the Erlang virtual machine, it is nonetheless designed to allow developers to extend the VM to support additional integrations with peripherals and protocols that are not otherwise supported in the core virtual machine.
@@ -651,7 +656,9 @@ documentation.
 The instructions for adding custom Nifs and ports differ in slight detail, but are otherwise quite similar.  In general, they involve:
 
 1. Adding the custom Nif or Port to the `components` directory of the AtomVM source tree.
-1. Run `idf.py reconfigure` to pick up any menuconfig options, many extra drivers have an option to disable them (they are enabled by default). Optionally use `idf.py menuconfig` and confirm the driver is enabled and save when quitting.
+1. Run `idf.py set-target ${CHIP}` to pick up any menuconfig options, many extra drivers have an
+option to disable them (they are enabled by default). Optionally use `idf.py menuconfig` and
+confirm the driver is enabled and save when quitting.
 1. Building the AtomVM binary.
 
 ```{attention}
diff --git a/src/platforms/esp32/.gitignore b/src/platforms/esp32/.gitignore
@@ -0,0 +1,7 @@
+# Copyright 2017-2025 Davide Bettio <davide@uninstall.it>
+# Copyright 2025 Winford (UncleGrumpy) <winford@object.stream>
+#
+# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+
+sdkconfig.defaults
+sdkconfig.old
diff --git a/src/platforms/esp32/CMakeLists.txt b/src/platforms/esp32/CMakeLists.txt
@@ -54,6 +54,19 @@ set(AVM_SELECT_IN_TASK ON)
 # JIT is not available yet on esp32
 set(AVM_DISABLE_JIT ON)
 
+## Configure partition table based on boot flavor
+if (${ATOMVM_ELIXIR_SUPPORT})
+    set(AVM_PARTITION_TABLE_FILENAME "partitions-elixir.csv")
+else()
+    set(AVM_PARTITION_TABLE_FILENAME "partitions.csv")
+endif()
+
+if (${ATOMVM_RELEASE})
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/sdkconfig.release-defaults.in ${CMAKE_CURRENT_SOURCE_DIR}/sdkconfig.defaults @ONLY)
+else()
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/sdkconfig.defaults.in ${CMAKE_CURRENT_SOURCE_DIR}/sdkconfig.defaults @ONLY)
+endif()
+
 project(atomvm-esp32)
 
 # esp-idf does not use compile_feature but instead sets version in
diff --git a/src/platforms/esp32/GetBootAVM.cmake b/src/platforms/esp32/GetBootAVM.cmake
@@ -0,0 +1,29 @@
+#
+# This file is part of AtomVM.
+#
+# Copyright 2025 Winford (Uncle Grumpy) <winford@object.stream>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+#
+
+partition_table_get_partition_info(app_offset "--partition-name main.avm" "offset")
+set(AVM_APP_OFFSET "${app_offset}")
+if ("${app_offset}" STREQUAL "0x210000")
+    set(BOOT_LIBS "esp32boot.avm")
+elseif ("${app_offset}" STREQUAL "0x250000")
+    set(BOOT_LIBS "elixir_esp32boot.avm")
+else()
+    set(BOOT_LIBS "NONE")
+endif()
diff --git a/src/platforms/esp32/sdkconfig.defaults b/src/platforms/esp32/sdkconfig.defaults
diff --git a/src/platforms/esp32/sdkconfig.defaults.in b/src/platforms/esp32/sdkconfig.defaults.in
@@ -0,0 +1,6 @@
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+CONFIG_MBEDTLS_ECP_FIXED_POINT_OPTIM=y
+CONFIG_LWIP_IPV6=n
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="@AVM_PARTITION_TABLE_FILENAME@"
+CONFIG_PARTITION_TABLE_FILENAME="@AVM_PARTITION_TABLE_FILENAME@"
diff --git a/src/platforms/esp32/sdkconfig.defaults.in.license b/src/platforms/esp32/sdkconfig.defaults.in.license
diff --git a/src/platforms/esp32/sdkconfig.release-defaults.in b/src/platforms/esp32/sdkconfig.release-defaults.in
@@ -4,3 +4,5 @@ CONFIG_MBEDTLS_ECP_FIXED_POINT_OPTIM=y
 CONFIG_COMPILER_OPTIMIZATION_PERF=y
 CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT=y
 CONFIG_LWIP_IPV6=n
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="@AVM_PARTITION_TABLE_FILENAME@"
+CONFIG_PARTITION_TABLE_FILENAME="@AVM_PARTITION_TABLE_FILENAME@"
diff --git a/src/platforms/esp32/sdkconfig.release-defaults.in.license b/src/platforms/esp32/sdkconfig.release-defaults.in.license
diff --git a/src/platforms/esp32/tools/CMakeLists.txt b/src/platforms/esp32/tools/CMakeLists.txt
@@ -22,6 +22,7 @@ cmake_minimum_required (VERSION 3.13)
 project (ReleaseEsp32)
 include(../../../../version.cmake)
 include(../../../../CMakeModules/GetVersion.cmake)
+include(../GetBootAVM.cmake)
 
 ## Build image tools for target chip
 
@@ -45,9 +46,20 @@ elseif(${CONFIG_IDF_TARGET} STREQUAL "esp32p4")
     set(BOOTLOADER_OFFSET "0x2000")
 endif()
 
+if ("${BOOT_LIBS}" STREQUAL "NONE")
+    message(WARNING "This appears to be a custom partition map using application offset: ${app_offset}, no AtomVM libraries will be included.")
+else()
+    if (NOT EXISTS ../../../../build/libs/esp32boot/${BOOT_LIBS})
+        message(WARNING "A generic_unix build must be done first in the top level AtomVM/build directory! \n\
+        Consult https://doc.atomvm.org/main/build-instructions.html for build instructions.")
+    endif()
+endif()
+
+set(ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../")
+
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage.config.in ${CMAKE_BINARY_DIR}/mkimage.config)
 
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/../../../../tools/dev/flash.sh ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/flash.sh COPYONLY)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/flash.sh.in ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/flash.sh @ONLY)
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage.erl ${CMAKE_BINARY_DIR}/mkimage.erl COPYONLY)
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/flashimage.sh.in ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/flashimage.sh @ONLY)
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage.sh.in ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/mkimage.sh @ONLY)
@@ -64,7 +76,3 @@ file(COPY ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/flash.sh
     FILE_PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE
 )
 
-if (NOT EXISTS ../../../../build/libs/esp32boot/${BOOT_LIBS})
-    message(WARNING "A generic_unix build must be done first in the top level AtomVM/build directory! \n\
-    Consult https://doc.atomvm.org/main/build-instructions.html for build instructions.")
-endif()
diff --git a/src/platforms/esp32/tools/flash.sh.in b/src/platforms/esp32/tools/flash.sh.in
@@ -23,7 +23,7 @@ set -e
 
 : "${FLASH_BAUD_RATE:=115200}"
 : "${FLASH_SERIAL_PORT:=/dev/ttyUSB0}"
-: "${FLASH_OFFSET:=0x210000}"
+: "${FLASH_OFFSET:=@AVM_APP_OFFSET@}"
 
 ESP_TOOL=`which esptool.py`
 if [ -z ${ESP_TOOL} ]; then
diff --git a/src/platforms/esp32/tools/mkimage.config.in b/src/platforms/esp32/tools/mkimage.config.in
@@ -33,12 +33,12 @@
         #{
             name => "AtomVM Virtual Machine",
             offset => "0x10000",
-            path => ["${BUILD_DIR}/atomvm-esp32.bin", "${ROOT_DIR}/src/platforms/esp32/build/atomvvm-esp32.bin"]
+            path => ["${BUILD_DIR}/atomvm-esp32.bin", "${ROOT_DIR}/src/platforms/esp32/build/atomvm-esp32.bin"]
         },
         #{
             name => "AtomVM Boot and Core BEAM Library",
             offset =>  "0x1D0000",
-            path => ["$[BOOT_FILE]"]
+            path => ["${ROOT_DIR}/build/libs/esp32boot/${BOOT_LIBS}"]
         }
     ]
 }.
diff --git a/src/platforms/esp32/tools/mkimage.erl b/src/platforms/esp32/tools/mkimage.erl
@@ -43,7 +43,9 @@ do_main(Argv) ->
                     try
                         Config = load_config(maps:get(config, Opts, "mkimage.config")),
                         BuildDir = get_build_dir(Opts, RootDir),
-                        BootFile = BuildDir ++ "/libs/esp32boot/esp32boot.avm",
+                        BootFile = maps:get(
+                            boot, Opts, BuildDir ++ "/libs/esp32boot/esp32boot.avm"
+                        ),
                         mkimage(
                             RootDir,
                             BuildDir,
diff --git a/src/platforms/esp32/tools/mkimage.sh.in b/src/platforms/esp32/tools/mkimage.sh.in
@@ -23,6 +23,7 @@ escript "@CMAKE_BINARY_DIR@/mkimage.erl" \
     --root_dir "@CMAKE_BINARY_DIR@/../../../.." \
     --config "@CMAKE_BINARY_DIR@/mkimage.config" \
     --out "@CMAKE_BINARY_DIR@/atomvm-@CONFIG_IDF_TARGET@.img" \
+    --boot "@CMAKE_BINARY_DIR@/../../../../build/libs/esp32boot/@BOOT_LIBS@" \
     "$@"
 
 if (test ${@} = "--help"); then
@@ -33,5 +34,5 @@ fi
 echo "============================================="
 
 echo ""
-echo "AtomVM @CONFIG_IDF_TARGET@ version @ATOMVM_VERSION@ image written to:"
+echo "AtomVM @CONFIG_IDF_TARGET@ version @ATOMVM_VERSION@ image with @BOOT_LIBS@ libraries written to:"
 echo "@CMAKE_BINARY_DIR@/atomvm-@CONFIG_IDF_TARGET@.img"

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +# Copyright 2017-2025 Davide Bettio <[email protected]>
 +# Copyright 2025 Winford (UncleGrumpy) <[email protected]>
 +#
 +# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
++
 +sdkconfig.defaults
 +sdkconfig.old