Installation & Build Environment
Relevant source files
The following files were used as context for generating this wiki page:
AtomVM is a lightweight implementation of the Erlang Virtual Machine (BEAM) designed for microcontrollers and constrained systems. The installation and build environment encompasses several distinct platforms, including ESP32, STM32, Raspberry Pi RP2, Generic UNIX (Linux/macOS), and WebAssembly (Emscripten). Setting up the environment requires specific toolchains for cross-compilation to embedded hardware or local development environments for testing.
The project utilizes CMake as its primary build system to manage dependencies, platform-specific configurations, and documentation generation. Users can either flash pre-built binary images for quick deployment or build the virtual machine from source to implement custom Native Interface Functions (Nifs) or ports.
Sources: doc/src/welcome-to-atomvm.md:10-25, doc/src/getting-started-guide.md:12-25, src/platforms/generic_unix/CMakeLists.txt:23-25
General Build Requirements
The following table summarizes the common software requirements across different platforms:
| Component | Purpose | Relevant Platforms |
|---|---|---|
| Erlang/OTP | Compiling Erlang source to BEAM bytecode | All |
| rebar3 | Build tool for Erlang projects | ESP32, STM32, RP2, UNIX |
| mix | Build tool for Elixir projects | ESP32, STM32, RP2, UNIX |
| CMake | Project configuration and build management | All (Source builds) |
| Python 3 | Documentation and platform tools (esptool) | All |
Sources: doc/src/getting-started-guide.md:46-55, doc/README.md:18-25
Documentation Build Environment
The documentation system relies on a specific Python environment.
python3 -m venv $HOME/python-env/sphinx
. $HOME/python-env/sphinx/bin/activate
python3 -m pip install -r requirements.txt
Sources: doc/README.md:38-42
The requirements.txt file specifies the following dependencies for the documentation build:
sphinx,myst-parser,sphinx-rtd-themegitpython,breathe,pygments
Sources: doc/requirements.txt:6-12
Platform-Specific Installation
ESP32 Platform
The ESP32 deployment involves flashing a binary image that includes the bootloader, partition map, and the AtomVM virtual machine.
The virtual machine expects application code in the data partition starting at 0x210000 (thin images) or 0x250000 (Elixir-supported images).
Sources: doc/src/getting-started-guide.md:70-85, doc/src/getting-started-guide.md:120-135
Raspberry Pi RP2 (Pico/Pico 2)
Installation on RP2-based boards uses the UF2 bootloader format.
| File Type | Description |
|---|---|
Atomvm-pico-*.uf2 | The core Virtual Machine binary |
atomvmlib-pico-*.uf2 | Compiled Erlang/Elixir core libraries |
Deployment Steps:
- Boot device in
BOOTSELmode. - Mount as a USB drive (e.g.,
/Volumes/RPI-RP2). - Copy the VM UF2 file; the device will auto-unmount.
- Repeat for the core library UF2 file.
Sources: doc/src/getting-started-guide.md:270-300
Generic UNIX (Linux/macOS)
For local development, AtomVM can be installed via package managers or compiled as a standard executable.
- macOS (Homebrew):
brew tap atomvm/atomvmthenbrew install atomvm. - macOS (MacPorts):
sudo port install atomvm. - Linux: Download pre-built binaries and the
atomvmlib.avmcore library.
The UNIX build uses CMake to produce the AtomVM executable, typically installed in lib/atomvm with a wrapper in bin.
Sources: doc/src/getting-started-guide.md:410-435, src/platforms/generic_unix/CMakeLists.txt:66-72
Build System Architecture
The build process is managed by CMake and categorized into the VM build and the documentation build.
Key Build Targets
The documentation build supports specific targets:
make sphinx-html: Builds integrated C and Erlang API documentation.make sphinx-epub: Builds EPub version of the documentation.make doc: Builds all documentation formats.
Sources: doc/README.md:18-25, doc/CMakeLists.txt:139-141
Coding Standards & Contributing
The build environment is reinforced by style enforcement tools to ensure code quality across the multi-language codebase.
| Language | Tool | Style Guide |
|---|---|---|
| C | clang-format-16 | AtomVM C Coding Style (AVMCCS) |
| Erlang | erlfmt | Standard Erlang style |
| Elixir | Elixir Formatter | Standard Elixir style |
Sources: CONTRIBUTING.md:58-85
Documentation Formatting
C source files use Doxygen Javadoc-style comments. To appear in the correct API sections, entries must be manually added to .rst files in doc/src/apidocs/libatomvm/ (e.g., functions.rst, types.rst).
Sources: CONTRIBUTING.md:73-82
Summary
The AtomVM installation and build environment is designed for flexibility, supporting both quick-start binary deployments and deep source-level integration. By utilizing CMake and standard language build tools (rebar3/mix), it provides a consistent interface for developers across various embedded and desktop platforms. Proper environment setup requires attention to platform-specific bootloader offsets and the inclusion of the core AVM libraries.