Required software

Everything that must be installed for the compiler to build and for the trials to run. The checkout brings the compiler binaries (binaries/), the trial tree and the board support files; the tools below come from outside the repository. Nothing here is a Rust toolchain: Silica’s compiler is written in Silica and builds itself.

Versions are the ones the project is built and tested with (September 2026). Newer versions of the same tools usually work; older ones are untested.

At a glance

Host tools (macOS on Apple Silicon)

Install the command line tools with:

xcode-select --install

Nothing else is needed for the host build or the host trials: binaries/silica-compiler is the newest compiler built for this host, and every build starts from it. If that link is missing or stale, bash binaries/update_silica_compiler_link.bash repairs it.

Host tools (Linux)

The same three things are needed on a Linux host: GNU Make, clang (or cc) to assemble the emitted .sams and link, and perl 5 plus the usual find, awk, sed, diff and xargs for the trial harness. GNU as and ld serve where clang’s integrated assembler is not used.

On a Debian-family host:

sudo apt install build-essential clang

Building across machines

An OS-hosted platform builds its own compiler on its own machine, so programmer_tools/build_all_platforms.sh and its siblings reach other machines over ssh. That needs rsync and public/private key ssh: the scripts run ssh in batch mode and never type a password.

ssh-keygen                       # if you have no key yet
ssh-copy-id user@host
ssh -o BatchMode=yes user@host true

A compiler build needs 6–8 GB of RAM for its heaviest unit, on every machine that runs one.

ESP32-S3 board tools

Needed to turn the ESP32-S3 compiler’s output into board images, and to load and run them. No ESP-IDF component, header or library is linked into a Silica program; only the toolchain and the flashing tool are used.

Both come from the ESP-IDF 6.2 installer, which puts them under ~/.espressif:

git clone -b v6.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32s3

The board tools look for them in those default places; if yours are elsewhere, point the tools at them:

(board/ is compiler/src/emitter/ESP32-S3_raw/board/.)

The ESP32-S3 compiler

Board programs and board trials are compiled by binaries/silica-compiler-ESP32-S3_raw: a compiler that runs on a hosted machine and emits ESP32-S3 (Xtensa) assembly. The ESP32-S3 has no OS and cannot host a compiler, so this cross compiler is built on whichever machine you start from:

bash programmer_tools/build_all_platforms.sh --targets ESP32-S3_raw

It is installed as binaries/silica-NNNNNN-ESP32_S3_raw-<platform>, with its own numbering, and binaries/silica-compiler-ESP32-S3_raw points at the newest one. It never replaces binaries/silica-compiler. (make TARGET=ESP32-S3_raw in compiler/src/ is what the script runs.)

The board

• An ESP32-S3 board whose UART0 (GPIO43/44) is wired to a USB serial bridge. The port was brought up and is tested on the board described in PORT_TEST_BOARD_byu_idaho_v4.0_feb26.md (BYU-I eBadge v4.0, ESP32-S3-MINI-1-N4R2, CP2102N bridge).
• A USB data cable (charge-only cables enumerate nothing). macOS’s built-in driver serves the CP2102N; the board appears as /dev/cu.usbserial-*. If the board has a power switch, it must be on.
• The trial runner and board/tools/run_app.sh use the one USB serial port they find. With several, set BOARD_PORT=/dev/cu.... (an interactive trial run asks). BOARD_MAC=<mac> makes a run refuse any board but that one.

Checking an installation

make --version | head -1          # GNU Make (3.81 on macOS, 4.x on Linux)
clang --version | head -1         # Apple clang 21 (or newer) on macOS; clang 18 or newer on Linux
perl -v | sed -n 2p               # perl 5

# ESP32-S3 board tools
~/.espressif/tools/xtensa-esp-elf/esp-16.1.0_20260609/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc --version | head -1
~/.espressif/python_env/idf6.2_py3.14_env/bin/python -c "import esptool, serial; print(esptool.__version__, serial.VERSION)"
~/.espressif/python_env/idf6.2_py3.14_env/bin/python \
    compiler/src/emitter/ESP32-S3_raw/board/tools/run_on_board.py --probe

The last command connects to the board and prints its port, chip and MAC address; it fails with a plain message when no board is connected.

See also

• Build and test the compiler: building the compiler and running the trials.
• trials/README.md and trials/targets/README.md: the trial tree, and running it on a board.
• board/README.md: the ESP32-S3 board support files, and how to run the Silica sample apps on the board with tools/run_app.sh.