Native development requires a C compiler with POSIX threads, CMake 3.20 or newer, Ninja, Python 3.10 or newer and PyYAML. The documentation toolchain uses Python 3.12 and pinned packages; it does not require compiling the kernel. See Building documentation.
Run the commands from your checkout. Configuration needs PyYAML, so give CMake a Python that has it, for example a virtual environment in the checkout (.venv is ignored by git):
python3 -m venv .venv && .venv/bin/pip install pyyaml
cmake --preset native-gcc -DPython3_EXECUTABLE=$PWD/.venv/bin/python3
cmake --build --preset native-gcc --parallel 4
ctest --preset native-gcc --output-on-failure --no-tests=errorPassing CTest reports 23 entries:
- 20 conformance executables, one per area, such as
test_sem,test_isr_stackandtest_crash; - the differential bridge against the reference model, its timer regressions, and the evidence workflow check.
Each executable's cases print a CASE ... outcome= line in its log (case evidence). A zero-test run is a setup failure.
Experimental Linux x86-64 presets can compile the kernel with EmbCC while GCC supplies the POSIX host and final link. See EmbCC native integration for compiler selection, the ABI guard and qualification limits.
The emulated boards run the same suites under QEMU (SIM-002). Install the cross compilers and QEMU:
- Debian or Ubuntu:
apt install gcc-arm-none-eabi libnewlib-arm-none-eabi qemu-system-arm gcc-riscv64-unknown-elf picolibc-riscv64-unknown-elf qemu-system-misc gcc-avr avr-libc; - macOS:
brew install qemu riscv64-elf-gcc osx-cross/avr/avr-gcc@14, Arm's GNU toolchain from developer.arm.com, and picolibc built forriscv64-elf-gcc. Name them as the toolchain files expect (arm-none-eabi-gcc,riscv64-unknown-elf-gcc,avr-gcc) on yourPATH.
Then use a board's preset, for example the Cortex-M4F board:
cmake --preset cm4-an386 -DPython3_EXECUTABLE=$PWD/.venv/bin/python3
cmake --build --preset cm4-an386
ctest --preset cm4-an386 --output-on-failure --no-tests=error
cmake --build --preset cm4-an386 --target run_first_execution # the sample, on your terminal| Preset | QEMU machine | Core |
|---|---|---|
cm0-microbit |
microbit |
Cortex-M0 |
cm3-an385 |
mps2-an385 |
Cortex-M3 |
cm4-an386 |
mps2-an386 |
Cortex-M4F |
cm7-an500 |
mps2-an500 |
Cortex-M7 |
cm33-an505 |
mps2-an505 |
Cortex-M33 |
rv32-virt |
virt |
RV32IMAC |
avr-uno |
arduino-uno |
ATmega328P |
run_<image> runs any sample, and any image of your own application, under the board's machine. Press Ctrl-A then X to leave QEMU. On the boards whose reset keeps RAM (the MPS2 machines, RV32 virt, EmbSIM and the physical boards), the misuse checks run too: each faults, resets the board and is settled on the next boot (A89). On the QEMU Uno and the micro:bit they are skipped.
The Arduino Uno build's conformance suite also runs on EmbSIM's
simulated Uno: the ATmega328P's core, timers and USART at its clock, with the board's circuit around it.
Build EmbSIM's command line, then configure the avr-uno-embsim preset with it:
cmake -S ../EmbSIM -B ../EmbSIM/build -G Ninja -DCMAKE_BUILD_TYPE=Release -DEMBSIM_SERVER=OFF
cmake --build ../EmbSIM/build --target embsim_cli
cmake --preset avr-uno-embsim -DEMB_EMBSIM="$PWD/../EmbSIM/build/bin/embsim"
cmake --build --preset avr-uno-embsim
ctest --preset avr-uno-embsim --output-on-failure --no-tests=errortools/embsim/run_embsim.py runs each test image with embsim run --target emblink/arduino_uno --image TEST.elf --until-text EMB_TEST_END --console and reads the console as tools/qemu/run_qemu.py reads
QEMU's. Runs are deterministic: an image gives the same console on every run. Any board that sets
EMB_BOARD_EMBSIM_TARGET in its board.cmake can use -DEMB_TEST_EMULATOR=embsim. As with QEMU,
simulated time is never timing evidence (SIM-003).
The NUCLEO-F446RE build does the same on EmbSIM's NUCLEO-F446RE (emblink/nucleo_f446re): the
STM32F446RE's Cortex-M4F, RCC, PWR, flash interface, GPIO and USART2 on the board's circuit, the
ST-LINK's MCO as the clock input and its virtual COM port as the console. Use the
cm4-nucleo-embsim preset with gcc-arm-none-eabi installed:
cmake --preset cm4-nucleo-embsim -DEMB_EMBSIM="$PWD/../EmbSIM/build/bin/embsim"
cmake --build --preset cm4-nucleo-embsim
ctest --preset cm4-nucleo-embsim --output-on-failure --no-tests=errorThe ESP32-C3-DevKitM-1 build runs on EmbSIM's DevKitM-1 (emblink/esp32c3_devkitm1) as the
board does: each test image is also written as <name>.bin, the flash image Espressif's boot
ROM loads from offset 0, and that is what EmbSIM flashes. Use the rv32-c3-embsim preset with
gcc-riscv64-unknown-elf and picolibc installed:
cmake --preset rv32-c3-embsim -DEMB_EMBSIM="$PWD/../EmbSIM/build/bin/embsim"
cmake --build --preset rv32-c3-embsim
ctest --preset rv32-c3-embsim --output-on-failure --no-tests=errorcd tools/model
python3 -m unittest discover -vOnly the standard library is needed for the basic suite. Install Hypothesis to include randomized scenario tests. The model's bounded scenario exploration and kernel bridge are complementary checks; neither demonstrates physical timing or complete C memory safety.
samples/first_execution/main.c shows static thread/object setup and execution. Build it with the native preset above, then run:
./build/native-gcc/samples/first_execution/first_executionThe native sample exits after its configured two-million A/B iterations and prints first_execution: switches A=... B=... ticks=.... Its A/B counters count loop iterations, not a hardware-measured context-switch total. Embedded versions continue running and print progress where the board console permits. The conformance target test_first_execution supplies a shorter assertion-based check. Native time is virtual and advances in idle, so host timing is not a board benchmark.
To build a program of your own, outside this tree, see Your own application. For a shorter application, follow Threads and periodic work, which exits after five iterations. Then try Synchronization and notifications and Debugging. These tutorials use existing native libraries and keep example outputs under ignored build/tutorials/.
For repeatable supported operations, start with the generated current API, core concepts, and configuration. Consult Project status before attempting a planned service or hardware workflow.