Support installing specific AtomVM releases

[mnishiguchi]

Summary

Add a --version option to mix atomvm.esp32.install for installing a specific AtomVM release, including prereleases.

mix atomvm.esp32.install --version v0.7.0-alpha.1

When omitted, the task continues to install the latest stable release.

Testing

• mix test
• Installed v0.7.0-alpha.1 on an ESP32-C5 and verified it boots successfully

Notes

• mix test reports an existing failure unrelated to this change. The tests covering the new --version behavior pass.

Closes #78

[petermm]

Just nitpicks:

PR Review: Support installing specific AtomVM releases

Reviewed commit 2d0f7ae.

Verdict

Approve with one Low-severity fix recommended. I found no blocking correctness, security, or compatibility issues in the change.

The new --version path preserves the existing latest-release behavior, rejects the mutually exclusive --image combination before touching hardware, URL-encodes a tag as one path segment, and uses GitHub's documented tagged-release endpoint. The endpoint was also checked against the example prerelease tag and returned the expected release.

Findings

Low — A nonexistent version fails late with a generic HTTP error

run_with_release/2 initializes esptool and asks the user to select a connected device before get_release/2 checks whether the requested GitHub release exists. For example, --version v0.7.0-notthere.1 receives a 404 from GitHub but only reports GitHub API returned status 404; on a machine without a usable device, the command can fail even earlier without identifying the invalid version.

Ideally, fetch and validate the release metadata before esptool setup/device selection, then select the chip-specific asset after the device is known. At minimum, distinguish a missing requested tag from other GitHub failures:

diff --git a/lib/mix/tasks/esp32.install.ex b/lib/mix/tasks/esp32.install.ex
@@
     else
       {:error, reason} ->
         raise "Failed to fetch release: #{inspect(reason)}"
 
+      %{status: 404} when is_binary(version) ->
+        Mix.raise("AtomVM release not found: #{inspect(version)}")
+
       %{status: status} ->
         raise "GitHub API returned status #{status}"

This minimum fix makes the error actionable, but it does not fix the ordering: the API request would still occur after device selection. Splitting release metadata retrieval from chip-specific asset selection is necessary if invalid tags must be diagnosed independently of connected hardware. The current ordering does not risk erasing or flashing the device because both destructive operations occur only after get_release/2 succeeds.

Non-blocking suggestion

Make a missing asset error identify the requested release

If a valid release does not contain an Elixir image for the detected chip, the current error only says No matching release found for ESP32. Now that users can request an exact tag, including that tag and referring to the missing image would make the failure easier to diagnose.

diff --git a/lib/mix/tasks/esp32.install.ex b/lib/mix/tasks/esp32.install.ex
@@
       nil ->
-        raise "No matching release found for #{chip_family}"
+        release = version || "the latest release"
+        raise "No matching Elixir image found for #{chip_family} in #{release}"
     end
   end

This is a user-experience improvement only and should not block merging.

Oracle cross-check

Oracle independently reviewed the commit and this document. It confirmed the invalid-version finding and safety analysis, including that a 404 occurs before erase/flash, and found no additional actionable regressions. It also confirmed that the existing tests do not exercise HTTP error handling.

Verification

• mix format --check-formatted lib/mix/tasks/esp32.install.ex test/esp32_install_test.exs — passed.
• mix test test/esp32_install_test.exs — 4 tests passed.
• git diff --check HEAD^ HEAD — passed.
• Full mix test — 12 of 13 tests passed; the unrelated pre-existing ExAtomVMTest fails because ExAtomVM.hello/0 is undefined.

[petermm]

thank you!