Add AtomVM support to gleam CLI

[pguyot]

Using specific rebar3 or mix plugins, Erlang and Elixir users can easily generate .avm or .uf2 files for their Erlang or Elixir app that can be flashed to microcontrollers, and they can also easily flash ESP32 and Pico directly from their Erlang or Elixir project.

Similar support would be welcome to help Gleam users run Gleam on microcontrollers.

Four steps can be defined:

1. Generate .avm and .uf2 files

Add one or two new export targets to generate .avm or .uf2 or both.

.avm files are binaries that are flashed on microcontrollers, including stm32 and esp32. They can also be executed on Generic Unix platforms by atomvm CLI.
.uf2 files are used for Raspberry Pi Pico and really are packed .avm with flash address information. An UF2 can be generated from an .avm using uf2tool.

.avm files are generated by AtomVM's PackBeam which exists in two flavors:

• C version bundled with AtomVM, and
• Erlang version which probably is more suitable here.

The new export targets could be invoked such as:

gleam export atomvm
or
gleam export atomvm-shipment
or
gleam export atomvm-avm
or
gleam export atomvm-uf2

depending on scenarios and naming taste.

2. Fix runtime

Gleam has a nice very strong requirement about main/0 function. Unfortunately, AtomVM uses start/0 which isn't configurable. This may change, but rather in favor of Erlang releases.

AtomVM 0.6 and current main branch search for the first start/0 exported function and calls this on startup.

As a result, the following code seems to work if no other module define start.

import gleam/io
import gleam_avm/atomvm

pub fn main() {
  io.println("Hello from Gleam !")
  io.println("The AtomVM platform we are running on is:")
  io.debug(atomvm.platform())
}

// AtomVM currently requires a start/0 function instead of main/0
pub fn start() {
    main()
}

With item 1 above, users will have to add this function. Noticeably, invoking start/0 is quite frequent with Erlang, it is the shortcut with erl -s (erl -s module will call module:start(), while erl -s module func will call module:func()).

Gleam's erlang-shipment uses a template script for sh(1) or PowerShell that invokes runtime differently, by evaluating $PACKAGE@@main:run($PACKAGE). Such invocation could be put in a specific module (entrypoint.erl) or even the ``$PACKAGE@@main` module within a start/0 function doing exactly this. It may also help with regular erlang shipments.

The trick here would be to put this module first when generating the .avm file or declare it as the start module if using the Erlang version of PackBEAM.

3. Allow users to directly flash using gleam CLI.

More gleam CLI commands could be added, including commands to flash the avm or the .uf2 files directly to the devices. This could invoke esptool following rebar3 plugin.

The syntax could be something like:
gleam atomvm esp32_flash -p /dev/cu.usb-something -b 115200

4. Gleam runs atomvm

Additionally, a new runtime (target in gleam parlance) could be defined so that gleam run --target atomvm would invoke atomvm on Generic Unix, with atomvmlibs, to run the project (or tests). The example above doesn't run using Erlang because atomvmlibs is missing and atomvm:platform() which is what is eventually invoked through gleam_avm/atomvm.platform isn't defined on BEAM.

[pguyot]

See this PR at AtomVM that introduces a basic example which can be flashed on ESP32:

atomvm/AtomVM#1524

[lpil]

What a lovely suggestion! This is fab.

Are there any particular differences between the C and Erlang versions of the PackBEAM program? Is one preferred in some way?

Gleam has a nice very strong requirement about main/0 function.

Gleam's tooling has a convenience for running a main function, but you can use any entrypoint you wish (though it would be more irritating to run). Having proper release support is something I want to have in future.

Allow users to directly flash using gleam CLI.

I'd like to defer this one to start and focus on the more Gleam specific parts.

Gleam runs atomvm

What a fun idea, and potentially quite useful. Would that not work on Windows? That's one of our core supported platforms.

Are the APIs that one would need to use here stable? Or would there be any changes in future?

[pguyot]

Are there any particular differences between the C and Erlang versions of the PackBEAM program? Is one preferred in some way?

I'd say the Erlang version is preferred as it's the one used by rebar3 and mix plugins.

Gleam runs atomvm

What a fun idea, and potentially quite useful. Would that not work on Windows? That's one of our core supported platforms.

AtomVM currently runs on many platforms but Windows is not one of them.

However, from the CLI, you could either use WSL2 or, more interestingly I guess, node. Indeed, one of AtomVM platforms is node using emscripten. On the command line it has a similar interface than the generic unix version.

Are the APIs that one would need to use here stable? Or would there be any changes in future?

Which API are you concerned about?

AtomVM hasn't reached 1.0 yet. However, having Gleam first class citizen, following Erlang and Elixir, would help AtomVM core team maintain compatibility, and these user stories would help.

[lpil]

Erlang it is ✨

Adding as a runtime without any Windows support would be an issue, we'll have to think about that one some more before we can do that part. Windows users are the largest group of developers so Gleam aims to give them an equal experience to maximise adoption, and just to be nice.

I'd presume we'd use command line APIs and Erlang APIs to perform everything. Ideally any API we use internally would never change.

I guess to understand what is best we'd need to understand what the workflow might be for developing AtomVM Gleam applications. Does the feedback loop typically involve flashing to the device? I imagine you'd want to run one command that compiles and flashes it in that case.

[pguyot]

To support Windows as well as other operating systems, is node a sensible option?

paul@yuzu ~/P/A/A/e/g/hello_atomvm (w06/add-gleam-example) [1]> node ../../../src/platforms/emscripten/build.node/src/AtomVM.js hello_atomvm.avm
Hello from Gleam !
The AtomVM platform we are running on is:
Emscripten
Return value: emscripten
paul@yuzu ~/P/A/A/e/g/hello_atomvm (w06/add-gleam-example) [1]> ../../../build/src/AtomVM hello_atomvm.avm
Hello from Gleam !
The AtomVM platform we are running on is:
GenericUnix
Return value: generic_unix

For some unknown reason, AtomVM 0.6.5 wasn't shipped with node binaries, but 0.6.4 was and the CI builds it on a regular basis. You need AtomVM.js and AtomVM.wasm.

Regarding development cycle, I believe the ideal would be:

1. Write Gleam code
2. Ensure it compiles, otherwise go back to step 1
3. Run tests using AtomVM or BEAM depending on usage of AtomVM libraries and API. Go back to step 1 if required.
4. Flash to device
5. Run on device using a serial console. Go back to step 1 if required.

So yes, being able to flash directly with gleam CLI would help.

[kwando]

I would love this, just got a microcontroller started with AtomVM and immediately thought it would be amazing to write gleam code for it :)

[karlsson]

Hi,
I made a small/simple utility that packs compiled beam files in a gleam project into a <application>.avm file (using packbeam).
I guess it covers part of the first point. I don't know how it plays with the other things/PR proposed here, but I could publish it on hex if it is of interest. For now it has to be cloned from github and included with a path in the dependencies.
I called it atomvm_packgleam. 😁