Host Environment

This page describes the host environment used to develop, build, and test Dawn. It is intended as a reference for contributors and users setting up a new machine.

Note

Dawn has been developed and tested on Linux only. Other operating systems (macOS, Windows, WSL, BSD) have not been tested and most likely require additional work to be functional, especially for the QA pipeline (which depends on SocketCAN, tap/bridge networking, and host-side socat PTYs).

Help from users with testing or patches that add support for other host operating systems is very welcome.

This page is intentionally a general guide - it should grow over time as the project evolves and as more host setups are validated.

Supported host

  • Linux - primary and only fully supported development host. Recent mainstream distributions (Arch, Ubuntu LTS, Fedora, Debian stable) are expected to work.

  • Other POSIX systems - not tested. Some effort has been made to keep portable code free of OS-specific calls, but the host-side QA tooling is Linux-centric.

Base requirements

These are required to build Dawn and run the simulator / Dawn Shell:

  • git - repository checkout, submodule init.

  • cmake and ninja - NuttX build system.

  • A working C/C++ toolchain. Use gcc 14 or older for the current NuttX libcxx build path; gcc 15 does not currently build it cleanly. Add -e CXX=g++-14 -e CC=gcc-14 to dawnpy build invocations when your default host compiler is newer than gcc 14 (see Quick Start).

  • Cross toolchains for non-host targets you intend to build (e.g. arm-none-eabi-gcc for ARM boards). Not required for sim-only development.

  • Python 3.12 or newer with venv and pip - for dawnpy and the rest of the tooling. Check with python --version before creating the virtual environment. On distributions where python is unavailable or points to an older interpreter, use python3 or an explicit command such as python3.12. venv is recommended (isolates the install from the system Python and avoids permission issues), but installing dawnpy directly with pip --user also works.

  • kconfiglib - required by the NuttX Kconfig step. It is installed automatically with dawnpy when using pip install -e tools/dawnpy. If you install it manually, install it into the same Python environment used to run dawnpy; a system python3-kconfiglib package is not visible from an active virtual environment.

  • Standard NuttX build prerequisites (kconfig-frontends / kconfig-tools, flex, bison, gperf, make, genromfs). Refer to the NuttX documentation for the exact list for your distribution.

Documentation build

To build the Sphinx documentation locally:

  • python with the packages listed in Documentation/requirements.txt.

  • make (the documentation uses Documentation/Makefile).

QA / test requirements

The full QA pipeline (dawnpy-tests) runs unit tests inside the NuttX simulator (a NuttX build that runs as a regular Linux process) and integration tests (NTFC) against both the simulator and QEMU VMs. These layers depend on host facilities only available on Linux. See Host-based Development for the wider host-based workflow the QA pipeline plugs into.

The one-time environment bootstrap is performed by testenv_init.sh in the repository root. It needs sudo to configure kernel networking interfaces.

Tooling

  • socat - creates the PTY pair used to bridge the simulator’s serial output to host-side test clients.

  • iproute2 (ip command) - creates and configures the virtual CAN device, the bridge, and the tap interface.

  • sudo - required by testenv_init.sh to add kernel interfaces.

  • qemu-system-x86_64 with KVM - runs the qemu-intel64 target used for UDP and Modbus-TCP integration tests.

  • stty, arp - used by testenv_init.sh.

Kernel features

The Linux kernel must provide:

  • SocketCAN with the vcan module - required for all CAN-based integration tests. testenv_init.sh brings up a virtual can0 interface.

  • TUN/TAP and bridging (CONFIG_TUN, CONFIG_BRIDGE) - required to attach the QEMU guest to the host network for UDP / Modbus-TCP tests. testenv_init.sh creates br0 and tap0.

  • KVM (/dev/kvm accessible to the user) - recommended for QEMU.

For the per-suite breakdown of which host components each NTFC integration test depends on, see NTFC Integration Tests.

Help wanted

Contributions to broaden host support are welcome:

  • Reports of working / non-working setups on other Linux distributions.

  • Patches adding (or documenting workarounds for) macOS, BSD variants, WSL, or native Windows support.

  • Improvements to testenv_init.sh and dawnpy-tests so the QA pipeline can degrade gracefully on hosts that lack a particular facility (e.g. running only the suites that the host can support).

If you try Dawn on a non-Linux host, please open an issue describing what worked and what did not - it is the most useful starting point for adding proper support.