Generic Unix/Linux
Relevant source files
The following files were used as context for generating this wiki page:
The Generic Unix/Linux platform support in AtomVM allows the virtual machine to run on a wide variety of POSIX-compliant operating systems, including Linux kernels (various architectures), FreeBSD, and macOS. While AtomVM is primarily designed for microcontrollers like the ESP32, the Unix port serves as a vital environment for local development, testing, and debugging of Erlang and Elixir applications without requiring physical hardware.
Sources: doc/src/getting-started-guide.md:444-449, doc/src/welcome-to-atomvm.md:12-16
Within the project architecture, the Unix implementation provides a "facsimile" of a host operating system for the AtomVM core. It enables the execution of BEAM bytecode, memory management, and process scheduling on traditional computing hardware while maintaining the same concurrency-oriented model used in embedded deployments.
Sources: doc/src/atomvm-internals.md:39-47, doc/src/welcome-to-atomvm.md:43-51
System Requirements and Installation
To deploy AtomVM on a Generic Unix platform, several software components and libraries are required to build and run the virtual machine.
Build and Runtime Requirements
- Operating Systems: macOS or Linux (Windows is currently not supported for the Unix port).
- Compiler Toolchain: GCC or Clang (standard C11 support is required).
- Dependencies: Erlang/OTP and compatible Elixir runtime,
rebar3(for Erlang), andmix(for Elixir). - Optional Libraries:
zlibfor loading compressed BEAM files.
Sources: doc/src/getting-started-guide.md:462-472, src/libAtomVM/CMakeLists.txt:203-211
Installation Methods
The platform supports multiple installation avenues depending on the specific OS:
| Method | Target Platform | Description |
|---|---|---|
| Linux Binaries | Linux (x86_64, etc.) | Pre-built releases formatted as Atomvm-linux-<arch>-<version>. |
| MacPorts | macOS | Installed via sudo port install atomvm. |
| Homebrew | macOS | Installed via brew tap atomvm/atomvm and brew install atomvm. |
| Source Build | All Unix | Manual compilation using CMake; recommended for custom NIF/Port development. |
| Sources: doc/src/getting-started-guide.md:481-523 |
Architecture and Execution Model
The Unix port of AtomVM follows the project's core abstract machine design but interfaces with POSIX APIs for system-level operations.
Execution Flow
When running on Unix, the atomvm executable loads one or more .avm (packbeam) files provided via command-line arguments. The VM searches for a module exporting start/0 and begins execution.
The diagram shows the startup sequence from command-line invocation to the execution of Erlang processes on the Unix host.
Sources: doc/src/getting-started-guide.md:535-542, doc/src/atomvm-internals.md:63-68
JIT and Emulator Flavors
The Unix platform supports various execution modes for the emulator:
- Emulated (Default): Interprets BEAM bytecode.
- JIT: Compiles Erlang bytecode to native machine code at runtime (supported on x86_64 and aarch64).
- Hybrid: Executes both native precompiled code and emulated bytecode.
Sources: doc/src/atomvm-internals.md:144-162
System Interface and Hardware Facsimile
AtomVM on Unix abstracts system-level tasks into platform-specific implementations that satisfy the core VM requirements.
File and Directory Operations
The Unix port utilizes standard POSIX functions to manage module loading and file access. The build system checks for the existence of these functions during configuration:
open,close: File descriptors.opendir,readdir,closedir: Directory traversal for module discovery.mkfifo,unlink: Inter-process communication and file cleanup.
Sources: src/libAtomVM/CMakeLists.txt:175-184
Networking and Time
Networking on Unix leverages the standard socket API. The build environment defines HAVE_SOCKET and HAVE_SELECT to enable the Erlang networking stack. Time management is handled via clock_settime or settimeofday where available.
Sources: src/libAtomVM/CMakeLists.txt:191-195
Multi-Processing (SMP)
In SMP-enabled builds, the Unix platform runs one scheduler thread per CPU core. Each scheduler is implemented as a native pthread. Synchronization is managed through:
- Mutexes and Condition Variables: Provided by the host pthread library.
- Atomics: C11 atomics are used for lock-free mailboxes.
- RW Locks: Used for protecting the
GlobalContextand ETS tables.
Sources: doc/src/atomvm-internals.md:195-212, doc/src/atomvm-internals.md:310-318
Development and Contribution
For developers working on the Generic Unix/Linux platform, specific coding standards apply to ensure cross-platform compatibility.
Coding Style
- Line Endings: Must use
\n(Unix-style). - Indentation: Enforced via
clang-format-16using the AtomVM C Coding Style Guide (AVMCCS). - Documentation: Doxygen Javadoc style is used for C source files.
Sources: CONTRIBUTING.md:46-52, CONTRIBUTING.md:65-72
Build System (CMake)
The documentation and VM are built using a unified CMake structure. On Unix, the system can automatically detect ZLIB to support compressed BEAM files and Graphviz for generating internal architecture diagrams.
Sources: doc/CMakeLists.txt:105-115, src/libAtomVM/CMakeLists.txt:203-210
Summary
The Generic Unix/Linux port of AtomVM provides a high-performance, POSIX-compatible environment for running the BEAM. It serves as both a development tool and a viable deployment target for server-side or desktop Linux applications, utilizing standard Unix threading and networking primitives to implement the AtomVM actor model and scheduler.
Sources: doc/src/welcome-to-atomvm.md:12-25, doc/src/getting-started-guide.md:444-450