Gleam Support

Relevant source files

The following files were used as context for generating this wiki page:

• examples/gleam/hello_atomvm/gleam.toml
• libs/gleam_avm/gleam.toml
• examples/gleam/hello_atomvm/README.md
• libs/gleam_avm/CMakeLists.txt
• examples/gleam/hello_atomvm/CMakeLists.txt
• examples/gleam/supervise_actor/gleam.toml
• doc/src/welcome-to-atomvm.md
• examples/gleam/supervise_actor/manifest.toml
• examples/gleam/hello_atomvm/manifest.toml

Gleam Support in AtomVM allows developers to leverage the Gleam programming language to build IoT applications for resource-constrained microcontrollers. As a statically typed language that compiles to BEAM bytecode, Gleam fits into the AtomVM ecosystem alongside Erlang and Elixir, providing a memory-managed, concurrency-oriented environment based on the actor model.

Sources: doc/src/welcome-to-atomvm.md:32-44, doc/src/welcome-to-atomvm.md:88-92

Architecture and Integration

The integration of Gleam with AtomVM relies on Gleam's ability to target the Erlang ecosystem. AtomVM executes the BEAM bytecode generated by the Gleam compiler. A dedicated library, gleam_avm, provides specific bindings for the AtomVM API, enabling Gleam code to interact with AtomVM-specific features.

Compilation and Build Flow

The following diagram illustrates how Gleam source code is processed and packaged for execution on AtomVM.

The build process typically involves exporting the Gleam project as an Erlang shipment, which generates .beam files. These files, along with necessary standard libraries, are then packed into an .avm (AtomVM) file using the PackBEAM tool for deployment.

Sources: examples/gleam/hello_atomvm/README.md:16-25, libs/gleam_avm/CMakeLists.txt:23-27

Project Configuration

Gleam projects targeting AtomVM use standard Gleam configuration files (gleam.toml) and manifests, but include specific dependencies and entry points.

Dependency Management

Gleam projects for AtomVM typically depend on the gleam_stdlib and the gleam_avm bindings. More complex applications may also pull in Erlang-specific Gleam libraries.

Dependency	Purpose	Source
gleam_stdlib	Core Gleam data structures and functions	Hex
gleam_avm	Bindings for AtomVM-specific APIs	Local/AtomVM Libs
gleam_erlang	Erlang interop for Gleam	Hex
gleam_otp	OTP abstractions (Supervisors, Actors)	Hex

Sources: examples/gleam/hello_atomvm/gleam.toml:22-26, examples/gleam/supervise_actor/gleam.toml:25-27, examples/gleam/supervise_actor/manifest.toml:24-30

Entry Points

AtomVM requires a module to export a start/0 function to begin execution. In Gleam projects, this is typically handled by creating a start function in the main module that calls Gleam's standard main() function.

Sources: examples/gleam/hello_atomvm/README.md:11-13

Library and Example Structure

The repository includes both the core Gleam-AtomVM bindings and example projects demonstrating usage.

gleam_avm Library

This library serves as the interface between Gleam and the AtomVM runtime.

• Modules: Includes gleam_avm/atomvm for core runtime interactions.
• Build System: Uses CMake with the BuildGleam module to compile .gleam files into BEAM and package them into gleam_avm.avm.

Sources: libs/gleam_avm/CMakeLists.txt:19-27, libs/gleam_avm/gleam.toml:19-23

Example: hello_atomvm

A basic demonstration of running Gleam on AtomVM.

• Configuration: Uses a local path dependency to libs/gleam_avm.
• Packaging: Uses pack_gleam_runnable in CMake to bundle the application with estdlib and gleam_avm.

Sources: examples/gleam/hello_atomvm/gleam.toml:26, examples/gleam/hello_atomvm/CMakeLists.txt:22

Example: supervise_actor

A more advanced example demonstrating the use of OTP patterns (Supervisors and Actors) within the Gleam environment on AtomVM.

• Dependencies: Requires gleam_otp and gleam_erlang version ~> 1.2 and ~> 1.3 respectively.

Sources: examples/gleam/supervise_actor/gleam.toml:25-27, examples/gleam/supervise_actor/manifest.toml:24-27

Deployment Summary

Gleam Support ensures that the safety and expressiveness of Gleam can be applied to IoT development. By following the standard BEAM compilation path and providing AtomVM-specific bindings, the project enables Gleam to run alongside Erlang and Elixir on microcontrollers like the ESP32 and STM32.

Sources: doc/src/welcome-to-atomvm.md:88-100, examples/gleam/hello_atomvm/README.md:15-26