This example demonstrates a basic project for using the Zigler
library to
write low-level NIFs for a Nerves device. This project demonstrates
Zig code embedded into an Elixir module and how to call
out to a zig code file external to the embedded Elixir module.
Notably, no configuration is necessary to get proper cross-compilation between host and target architectures.
The only thing you need to activate zigler
is the dependency in your
mix.exs
:
{:zigler, "~> 0.10.1", runtime: false}
You might want to use Zig for any of the following things:
- Low-level code that requires interaction with OS syscalls not available directly through the BEAM.
- Performance-sensitive code which requires numerical computation
- Wrapping an existing C ABI
.so
or.a
library.
The example below assumes a Raspberry Pi 3 connected over the Wifi. Other official and many unofficial Nerves targets work as well. Please post cross-compilation bug reports to the zigler issue tracker.
-
Go to the
hello_zig
directory -
Set up your build environment
# Specify the target hardware. See the mix.exs for options # RISC-V targets like mangopi_mq_pro might not work. export MIX_TARGET=rpi3 # If using WiFi, you can set the SSID and password here export NERVES_NETWORK_SSID=your_wifi_name export NERVES_NETWORK_PSK=your_wifi_password
-
Get dependencies, build firmware, and burn it to an SD card
mix deps.get MIX_TARGET=host mix zig.get mix firmware mix firmware.burn
-
Insert the SD card into your target board and power up
-
Wait to finish booting.
-
SSH into the board:
ssh nerves.local
-
Execute
HelloZig.hello()
-
You should see it output the atom
:world
-
Official docs: https://hexdocs.pm/nerves/getting-started.html
-
Official website: https://nerves-project.org/
-
Zig language docs: https://ziglang.org/
-
Zigler docs: https://hexdocs.pm/zigler