Step 03 of 56

Getting the code

Two ways in: unzip a tagged release, or clone the repository. There are no submodules to remember — whatever the older instructions say.

Where it lives

This guide gets you running and explains each driver. The book is the design write-up behind it: the kernel and context switch, the interrupt model, the filesystems, the ACATS work, the full-profile limitations. Download it from the release page rather than building the LaTeX — book/main.pdf is gitignored, so a fresh checkout does not contain it.

Option A: unzip the latest release

Neither of these names a version, so they keep working as releases come and go. With the GitHub CLI:

gh release download --repo rowsail/ada_esp32s3 --archive=zip
unzip ada_esp32s3-*.zip && cd ada_esp32s3-*/

Or with nothing but curl and unzip — /releases/latest redirects to the current tag, so you can read the tag off the redirect and fetch that archive:

REPO=rowsail/ada_esp32s3
TAG=$(curl -sSLo /dev/null -w '%{url_effective}'         https://github.com/$REPO/releases/latest | sed 's|.*/||')
curl -LO https://github.com/$REPO/archive/refs/tags/$TAG.zip
unzip $TAG.zip && cd ada_esp32s3-${TAG#v}

About 11 MB, and it is a complete build tree — every file the tag contains, symlinks included. No git required, and you get a fixed, known version. If you only want to build and run, this is the simplest route.

Getting the book without a version either

Release assets have a stable redirect, so the PDF needs no tag at all:

curl -LO https://github.com/rowsail/ada_esp32s3/releases/latest/download/Bare-Metal-Ada-on-the-ESP32-S3.pdf

# or:
gh release download --repo rowsail/ada_esp32s3 --pattern '*.pdf'

Option B: clone

git clone https://github.com/rowsail/ada_esp32s3.git
cd ada_esp32s3

Choose this if you want git pull to bring updates, or intend to change anything and send it back.

You do not need --recurse-submodules. The repository has no submodules — there is no .gitmodules file, and git submodule status prints nothing. crates/bb-runtimes (1,541 files) and crates/xtensa-dynconfig are vendored as ordinary tracked directories. Older instructions in QUICKSTART.md, the README and the book still say the flag is "not optional"; passing it is harmless, but nothing breaks without it, and no amount of git submodule update will fix a build problem.

What the two vendored directories are

• crates/bb-runtimes — AdaCore's bare-board runtime sources, forked here to add an esp32s3 board. This is the raw material the Ada runtime is generated from (step 54).
• crates/xtensa-dynconfig — the Xtensa core-configuration plugin GNAT's Xtensa back end loads to learn the shape of this core. Building it is what needs a host C compiler, and it happens once.

What is in the tree

crates/
  esp32s3_rts/      the GNAT runtime crate (3 profiles) + gen_runtime.sh
  bb-runtimes/      AdaCore bb-runtimes fork with the esp32s3 board
  xtensa-dynconfig/ the Xtensa core-config plugin the toolchain needs
libs/
  esp32s3_hal/      the peripheral HAL + the pure-Ada ext4/FAT16 filesystems
  tls/              the pure-Ada TLS 1.3 stack
  esp32s3_wifi/     the Wi-Fi driver
examples/           96 flashable examples (each owns its board.ads)
  common/bare/      the shared FreeRTOS-free boot (bootloader, start.S, glue)
book/               the long-form guide (LaTeX sources)
x, export.sh        the ./x dispatcher and the esp32-ada launcher

Two entry points matter for now. ./x at the root drives every example inside the tree. export.sh turns the tree into an SDK you can build your own projects against from anywhere on disk — that is step 10.

Nothing is downloaded at build time except the Alire toolchains. The one exception is the optional Wi-Fi driver, whose lower-MAC and PHY blobs are Apache-2.0 binaries fetched (not committed) by tools/fetch-wifi-blobs.sh, pinned to exact upstream commits and verified by sha256.