Standard Libraries
Relevant source files
The following files were used as context for generating this wiki page:
AtomVM includes a small but functional subset of the Erlang/OTP standard libraries, optimized to run on resource-constrained micro-controllers. These libraries provide the necessary interfaces for application logic, hardware interaction, and networking, allowing developers to use functional programming patterns on tiny devices.
Sources: doc/src/index.rst:11-14, doc/src/welcome-to-atomvm.md:12-25
The libraries are categorized into high-level Erlang/Elixir libraries (such as estdlib and eavmlib) and low-level C APIs (libAtomVM) that implement the core virtual machine functionality and Native Implemented Functions (NIFs).
Sources: doc/src/api-reference-documentation.rst:11-66, src/libAtomVM/CMakeLists.txt:28-105
Library Architecture and Components
The AtomVM environment relies on a layered architecture where Erlang/Elixir code interacts with the hardware through specialized libraries. These libraries are often distributed as packed AtomVM (.avm) files.
Component Overview
| Library | Category | Description |
|---|---|---|
| estdlib | Erlang | Standard Erlang library subset containing core modules. |
| eavmlib | Erlang | AtomVM specific extensions and hardware interface modules. |
| alisp | Erlang | Lisp implementation/integration for AtomVM. |
| etest | Erlang | Testing framework for AtomVM applications. |
| libAtomVM | C API | The core runtime implementing the BEAM emulator, memory management, and NIFs. |
Sources: doc/CMakeLists.txt:77-82, doc/src/api-reference-documentation.rst:15-60, doc/src/getting-started-guide.md:281-285
Library Loading Flow
When AtomVM starts, it can load multiple AVM files. Modules defined in earlier AVM files on the command line take precedence over those appearing later.
The diagram shows the sequence of loading standard libraries alongside the application.
Sources: doc/src/getting-started-guide.md:520-525, doc/src/getting-started-guide.md:110-115
Erlang Standard Libraries
estdlib
estdlib serves as the primary standard library for Erlang on AtomVM. It contains essential modules required for functional programming and system interaction that mimic standard OTP behavior, albeit in a reduced capacity to save memory.
Sources: doc/src/api-reference-documentation.rst:15-25, doc/CMakeLists.txt:78
eavmlib
eavmlib contains AtomVM-specific functionality, particularly for interfacing with micro-controller peripherals and protocols. This includes:
- GPIO: General Purpose Input/Output.
- I2C/SPI/UART: Common industry peripheral interfaces.
- Networking: WiFi and Bluetooth stack interfaces (specific to platforms like ESP32).
Sources: doc/src/welcome-to-atomvm.md:61-63, doc/src/api-reference-documentation.rst:27-37
Core C Library (libAtomVM)
The libAtomVM library is the foundation of the system, written in C. It provides the low-level implementations that the Erlang standard libraries call via BIFs (Built-In Functions) and NIFs.
Core Modules and Headers
The following header files define the primary interfaces of the internal library:
atom.h/atom_table.h: Management of atoms and the global atom table.bif.h/nifs.h: Interfaces for Built-In and Native Implemented Functions.context.h/scheduler.h: Process context management and the pre-emptive scheduler.memory.h/refc_binary.h: Memory management, garbage collection, and reference-counted binaries.term.h: Representation of Erlang terms (integers, lists, maps, etc.).
Sources: src/libAtomVM/CMakeLists.txt:28-85
NIF and BIF Hashing
The build system uses gperf to generate efficient hash tables for BIFs and NIFs, ensuring fast lookups during execution.
The diagram illustrates the build-time generation of lookup tables for standard library functions.
Sources: src/libAtomVM/CMakeLists.txt:220-230
Documentation Generation
The standard libraries use multiple tools to generate comprehensive documentation for developers:
- Sphinx: The main documentation framework for HTML and ePUB output.
- Doxygen: Used specifically for
libAtomVMC API documentation. - Rebar3/Edoc: Used for generating documentation from Erlang source files (
estdlib,eavmlib, etc.).
Sources: doc/README.md:12-18, doc/CMakeLists.txt:84-95, CONTRIBUTING.md:73-82
API Documentation Structure
| API Type | Tool | Source Location |
|---|---|---|
| Erlang APIs | Edoc -> Markdown | libs/{libname}/src |
| C Library APIs | Doxygen | src/libAtomVM/ |
| Internal Docs | Doxygen | doc/doxygen/ |
Sources: doc/CMakeLists.txt:87-95, doc/doxygen/README.md:12-18, CONTRIBUTING.md:73-80
Summary
The AtomVM Standard Libraries provide a bridge between the high-level Erlang/Elixir programming model and the low-level hardware of micro-controllers. By partitioning functionality into estdlib for general Erlang support and eavmlib for hardware-specific tasks, AtomVM maintains a modular architecture that supports efficient execution on devices with as little as 128KB of RAM.
Sources: doc/src/welcome-to-atomvm.md:12-25, doc/src/welcome-to-atomvm.md:86-90