Getting started

Prerequisites

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.

Use the existing checkout. Build outputs go under build/ and virtual environments stay ignored. The cloud environment already has native tools in .venv; activate it for native commands. On another machine install the prerequisites with its supported package manager and Python environment.

cd /workspace/EmbLinkRTOS
source .venv/bin/activate
cmake --preset native-gcc
cmake --build --preset native-gcc --parallel 4
ctest --preset native-gcc --output-on-failure --no-tests=error

For a local checkout, replace /workspace/EmbLinkRTOS with your checkout directory. Passing CTest should report twelve targets: nine conformance executables, the differential bridge, timer regressions and evidence workflow check. Individual case counts and skipped model scenarios are inside the runner logs. 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.

Embedded tests on EmbSIM

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=error

tools/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=error

Reference model

cd tools/model
python3 -m unittest discover -v

Only 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.

First sample

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_execution

The 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.

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.