Skip to content

Commit e19b03d

Browse files
bettiobettio
authored
Merge pull request #7 from pxp9/main
add nix setup for esp32 atomvm development
2 parents a13a2b9 + 103f036 commit e19b03d

2 files changed

Lines changed: 265 additions & 1 deletion

File tree

‎tutorials.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,8 @@ title: Tutorials
44
permalink: /tutorials/
55
---
66

7-
Coming soon!
7+
Welcome to the AtomVM tutorials! Here you'll find step-by-step guides to help you get started with AtomVM development.
8+
9+
## Build and Development Environment
10+
11+
[Build AtomVM with Nix Flake](/tutorials/nix-flake-esp32) Learn how to set up a reproducible development environment for ESP32 development with AtomVM using Nix Flakes. Perfect for teams who want identical development environments across different machines and operating systems.

‎tutorials/nix-flake-esp32.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
---
2+
layout: post
3+
title: "Nix Flake Setup for ESP32 Development with AtomVM"
4+
---
5+
6+
This tutorial shows you how to set up a reproducible development environment for ESP32 development with AtomVM using Nix Flakes. This approach ensures that all developers on your team have identical development environments, regardless of their host operating system.
7+
8+
## Prerequisites
9+
10+
Before starting, you need:
11+
12+
* [Nix package manager](https://nixos.org/download.html) installed with flakes enabled
13+
* Basic familiarity with command line tools
14+
* An ESP32 development board
15+
16+
## Enable Nix Flakes
17+
18+
[here you will find instructions to enable it](https://nixos.wiki/wiki/Flakes)
19+
20+
## Creating the Flake
21+
22+
Create a `flake.nix` file in your AtomVM project directory:
23+
24+
```nix
25+
{
26+
description = "AtomVM ESP32 development environment";
27+
28+
inputs = {
29+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
30+
nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
31+
};
32+
33+
outputs =
34+
{ nixpkgs, nixpkgs-unstable, ... }:
35+
let
36+
# Configurable AtomVM tag/branch for documentation dependencies
37+
atomvmTag = "main"; # Change to "release-0.6" or other tag as needed
38+
39+
supportedSystems = [
40+
"x86_64-linux"
41+
"aarch64-linux"
42+
"x86_64-darwin"
43+
"aarch64-darwin"
44+
];
45+
46+
overlays = [ ];
47+
48+
forEachSupportedSystem =
49+
f:
50+
nixpkgs.lib.genAttrs supportedSystems (
51+
system:
52+
f {
53+
pkgs = import nixpkgs-unstable {
54+
inherit system;
55+
config = {
56+
allowUnfree = true;
57+
permittedInsecurePackages = [ "mbedtls-2.28.10" ];
58+
};
59+
inherit overlays;
60+
};
61+
pkgs-stable = import nixpkgs {
62+
inherit system;
63+
config.allowUnfree = true;
64+
};
65+
}
66+
);
67+
in
68+
{
69+
devShells = forEachSupportedSystem (
70+
{ pkgs, pkgs-stable }:
71+
{
72+
default = pkgs.mkShell {
73+
packages =
74+
with pkgs;
75+
[
76+
# Core build tools
77+
autoconf
78+
automake
79+
curl
80+
git
81+
82+
# Erlang/Elixir toolchain
83+
beamMinimal27Packages.erlang
84+
beamMinimal27Packages.elixir_1_18
85+
beamMinimal27Packages.rebar3
86+
87+
# ESP-IDF dependencies
88+
wget
89+
flex
90+
bison
91+
ccache
92+
libffi
93+
openssl
94+
dfu-util
95+
libusb1
96+
pkg-config
97+
python3
98+
python3.pkgs.pip
99+
python3.pkgs.virtualenv
100+
gperf
101+
102+
# AtomVM build dependencies
103+
gcc-arm-embedded
104+
mbedtls_2
105+
zlib
106+
ninja
107+
doxygen
108+
graphviz
109+
]
110+
++ [
111+
pkgs-stable.cmake
112+
];
113+
114+
shellHook = ''
115+
# Create a local lib directory for symlinks
116+
mkdir -p .nix-shell-libs
117+
118+
# Create symlinks for mbedtls with the expected soname
119+
ln -sf ${pkgs.mbedtls_2}/lib/libmbedtls.so.14 .nix-shell-libs/libmbedtls.so.10
120+
ln -sf ${pkgs.mbedtls_2}/lib/libmbedcrypto.so.7 .nix-shell-libs/libmbedcrypto.so.1
121+
ln -sf ${pkgs.mbedtls_2}/lib/libmbedx509.so.1 .nix-shell-libs/libmbedx509.so.1
122+
123+
export LD_LIBRARY_PATH="$PWD/.nix-shell-libs:${
124+
pkgs.lib.makeLibraryPath [
125+
pkgs.zlib
126+
pkgs.mbedtls_2
127+
pkgs.libusb1
128+
pkgs.libffi
129+
pkgs.openssl
130+
]
131+
}:$LD_LIBRARY_PATH"
132+
133+
# ESP-IDF setup
134+
export ESP_DIR="$PWD/.esp"
135+
export IDF_PATH="$ESP_DIR/esp-idf"
136+
137+
# Clone and setup ESP-IDF if not already present
138+
if [ ! -d "$IDF_PATH" ]; then
139+
echo "Setting up ESP-IDF v5.5.2..."
140+
mkdir -p "$ESP_DIR"
141+
git clone --single-branch --branch v5.5.2 --recursive https://github.com/espressif/esp-idf.git "$IDF_PATH"
142+
cd "$IDF_PATH"
143+
./install.sh esp32,esp32s2,esp32s3,esp32c2,esp32c3,esp32c6,esp32h2,esp32p4
144+
cd - > /dev/null
145+
fi
146+
147+
# Source ESP-IDF export script to set up environment
148+
if [ -f "$IDF_PATH/export.sh" ]; then
149+
source "$IDF_PATH/export.sh" > /dev/null 2>&1
150+
echo "ESP-IDF environment activated"
151+
echo "You can now build AtomVM for ESP32!"
152+
fi
153+
154+
# Install AtomVM doc requirements into ESP-IDF Python environment
155+
REQUIREMENTS_URL="https://raw.githubusercontent.com/atomvm/AtomVM/${atomvmTag}/doc/requirements.txt"
156+
echo "Installing AtomVM documentation dependencies (tag: ${atomvmTag})..."
157+
curl -sL "$REQUIREMENTS_URL" | pip install -q -r /dev/stdin
158+
'';
159+
};
160+
}
161+
);
162+
};
163+
}
164+
```
165+
166+
## Understanding the Flake
167+
168+
### Inputs
169+
170+
The flake uses two nixpkgs inputs:
171+
- `nixos-23.11`: Stable release for reliable packages
172+
- `nixos-unstable`: Latest packages for newer Erlang/Elixir versions
173+
174+
### Key Packages
175+
176+
**Erlang/Elixir Toolchain**
177+
Change this to whatever versions are required for your build, AtomVM supports 1.19
178+
```nix
179+
beamMinimal27Packages.erlang
180+
beamMinimal27Packages.elixir_1_18
181+
beamMinimal27Packages.rebar3
182+
```
183+
184+
You can switch to Erlang 28 by using `beamMinimal28Packages` instead.
185+
186+
**ESP-IDF Dependencies**
187+
All the necessary packages for ESP-IDF are included: `flex`, `bison`, `gperf`, `python3`, etc.
188+
189+
**AtomVM Build Tools**
190+
- `gcc-arm-embedded`: ARM cross-compiler
191+
- `mbedtls_2`: TLS library (this requirement is for pico, but you should be able to change the version of mbedtls for ESP32 builds)
192+
- `ninja`: Build system
193+
- `cmake`: Build configuration
194+
195+
### Shell Hook Magic
196+
197+
The `shellHook` section performs several important tasks:
198+
199+
1. **MbedTLS Library Linking**: Creates symlinks for the correct mbedtls version that AtomVM expects
200+
2. **Library Path Setup**: Configures `LD_LIBRARY_PATH` for all required shared libraries
201+
3. **ESP-IDF Auto-Setup**: Automatically clones and installs ESP-IDF v5.5.2 on first run
202+
4. **Environment Activation**: Sources the ESP-IDF environment variables
203+
204+
## Using the Flake
205+
206+
### Enter the Development Shell
207+
208+
```bash
209+
cd your-atomvm-project
210+
nix develop
211+
```
212+
213+
The first time you run this:
214+
- It will download all the packages
215+
- Clone ESP-IDF v5.5.2
216+
- Install toolchains for all ESP32 variants
217+
- This may take 5-10 minutes depends on your machine.
218+
219+
Subsequent runs are instant!
220+
221+
## Add to .gitignore
222+
223+
Add these to your `.gitignore`:
224+
225+
```
226+
# Nix build artifacts
227+
.nix-shell-libs/
228+
229+
# ESP-IDF
230+
.esp/
231+
```
232+
233+
## Troubleshooting
234+
235+
### Permission Denied on USB Device
236+
237+
Add your user to the `dialout` group:
238+
239+
Then log out and back in.
240+
241+
### Library Version Errors
242+
243+
If you see mbedtls version errors, ensure the symlinks in `.nix-shell-libs` are created correctly. Exit and re-enter the shell.
244+
245+
## Benefits of This Approach
246+
247+
1. **Reproducible**: Everyone gets the same environment
248+
2. **Isolated**: Doesn't pollute your system with development tools
249+
3. **Documented**: The flake.nix serves as documentation
250+
4. **Cross-platform**: Works on Linux and macOS
251+
5. **Version Controlled**: Check the flake into git
252+
253+
## Next Steps
254+
255+
- Explore the [AtomVM documentation](https://doc.atomvm.org/latest/)
256+
- Check out [example applications](https://github.com/atomvm/AtomVM/tree/main/examples)
257+
258+
Happy hacking with AtomVM and Nix!
259+
260+
Notes: this was tested in NixOS, if you find any bugs in this setup, please report it.

0 commit comments

Comments
 (0)