Step 10 of 13

Your own project, outside the repo

Don't edit an example. Treat the repository as an SDK: source export.sh once, then scaffold a self-contained project anywhere on disk, with no runtime source copied in and no paths baked into any file.

Source the SDK, scaffold, run

. ~/ada-bare-metal-esp32s3/export.sh   # once per shell (add to ~/.bashrc)
mkdir ~/myblink && cd ~/myblink
esp32-ada init                        # scaffold app.gpr, board.ads, src/main.adb
#  ... edit src/main.adb ...
esp32-ada run -p /dev/ttyACM0         # build + flash + monitor

That one export.sh does three things: it puts esp32-ada on your PATH, exports ESP32S3_ADA_SDK so a project anywhere can find the SDK, and adds the runtime and HAL projects to GPR_PROJECT_PATH — so both gprbuild and the Ada Language Server resolve with "esp32s3_rts.gpr" with no path in your project.

What init writes

myblink/
  app.gpr            # withs esp32s3_rts.gpr + esp32s3_hal.gpr (resolved by name)
  board.ads          # this project's flash / PSRAM sizes
  src/main.adb       # your code (procedure Main; boots both cores, then idles)
  build.sh flash.sh  # thin shims into the SDK's shared bare-boot
  main/              # your C natives, if any (starts empty)
  .vscode/           # ALS project + build/flash/run tasks driving esp32-ada

Nothing from the SDK is copied in. app.gpr references the runtime and HAL by name, and the build shims reach the shared bare-boot through $ESP32S3_ADA_SDK. Check the folder into its own git repository if you like; it stays portable. To use another SDK library, add with "<name>.gpr"; to app.gpr for anything under the SDK's libs/.

A fresh project defaults to the embedded profile, set by an ESP32S3_RTS_PROFILE line in its build.sh. Change that line for light-tasking or full.

The verbs

Every esp32-ada verb mirrors the matching ./x one. The only difference is the target: ./x build gpio0_blink names an example inside the clone, while esp32-ada build operates on the folder you are standing in.

-p/--port defaults to $ESPPORT or /dev/ttyACM0; -C dir runs as if from dir.

Lifting an example out of tree

Copying a whole example directory elsewhere will not build. Examples are wired to their location: an Alire path-pin in alire.toml, a <name>.gpr, and build shims relative to examples/common/bare/.

Scaffold a fresh project and bring the sources across instead. The scaffold already supplies the app.gpr, board config and shims that make them build:

. /path/to/ada-bare-metal-esp32s3/export.sh
esp32-ada init ~/myblink && cd ~/myblink
SDK=$ESP32S3_ADA_SDK
cp "$SDK"/examples/esp32s3_gpio0_blink/src/*.ad? src/   # the Ada sources, incl. main.adb
esp32-ada build
esp32-ada run -p /dev/ttyACM0

Four things make that copy build cleanly:

• Only src/ is yours. The scaffold's app.gpr already sets Source_Dirs => "src" and Main => "main.adb", so the example's units drop straight in. Overwrite the scaffold's src/main.adb.
• Match the profile. The scaffold defaults to embedded, which is what most examples assume. An example written for light-tasking (shown by ./x list and in its README) needs the ESP32S3_RTS_PROFILE line changed.
• Bring board config and C natives if customized. Copy the example's board.ads if it sets a non-default size, and its glue.c if it has C natives.
• Extra libraries. If the example withs more of the SDK's libs/ beyond the HAL, add the matching with "<name>.gpr";.

There is no fixed "project location" and no idf.py. The SDK is found through $ESP32S3_ADA_SDK, so your project folder lives wherever you want it.