# essim — system digital twin

Interactive simulator for the inter-card connections inside a system. Built
around a domain model of **modules → parts → pins / signals → connections**,
with importers for Mentor Graphics, Altium and ODS pinout sheets, a TUI shell
with scripting, snapshots and BFS net analysis.

Status: early work-in-progress.

## Quick start

```sh
cmake -S . -B build
cmake --build build -j
./build/essim
```

The build is **layered**: `essim_core` is the frontend-agnostic business
library (domain + importers + operations); the `essim` binary comes from a
**frontend** under `src/frontends/<name>/` that links it. Select one with
`-DESSIM_FRONTEND=<name>` (default `tui`); `-DESSIM_FRONTEND=none` builds the
core + tests only, with no GUI toolkit fetched. Architecture in
[`DESIGN.md`](DESIGN.md).

Inside the shell, type `help` for the live command list — or read the
auto-generated reference at [`doc/user/commands.md`](doc/user/commands.md).
A worked bring-up script is at [`test/system.essim`](test/system.essim);
load it with `source test/system.essim`.

To run a script without the TUI and print its output to stdout (CI-friendly):

```sh
./build/essim --batch --source bring-up.essim
```

Step-by-step walkthroughs for both the batch and TUI workflows are in
[`doc/user/tutorial.md`](doc/user/tutorial.md).

## Dependencies

- **C++17 compiler** and **CMake 3.14+**.
- System libraries **libzip** and **pugixml** — install the *development*
  packages:
  - Debian/Ubuntu — `sudo apt install libzip-dev libpugixml-dev`
  - Arch — `sudo pacman -S libzip pugixml`
  - Fedora — `sudo dnf install libzip-devel pugixml-devel`
- **libbsdl** — the standalone BSDL parser, a sibling repo expected at
  `../libbsdl`, pulled in via `add_subdirectory` and linked dynamically.
  Override its location with `-DBSDL_DIR=/path/to/libbsdl`. Powers the
  `attach-bsdl` command and the pin/JTAG checks.
- Fetched automatically via `FetchContent` (nothing to install): **FTXUI**
  v6.1.9 — only when building the **tui** frontend — and **doctest** v2.4.11
  for the tests.
- Optional, only for the `doc` target: **doxygen** and **python3**.

libzip, pugixml and libbsdl are the **core** dependencies; FTXUI belongs to the
tui frontend, so a `-DESSIM_FRONTEND=none` build needs none of it.

## Tests

```sh
./build/essim_tests
# or
ctest --test-dir build
```

`ctest` runs `essim_tests` (core — links `essim_core`, no GUI toolkit) and
`essim_tui_tests` (the FTXUI frontend's tests, under `tests/tui/`).

Skip building tests entirely:

```sh
cmake -S . -B build -DBUILD_TESTING=OFF
```

## Documentation

- [`doc/user/`](doc/user/) — user guide, command reference, scripting.
- [`doc/api/`](doc/api/) — auto-generated C++ API reference.
- [`DESIGN.md`](DESIGN.md) — implementation notes (domain conventions, TUI
  internals, gotchas).
- [`doc/README.md`](doc/README.md) — how the doc pipeline is wired.

Regenerate auto-generated parts after substantive code changes:

```sh
cmake --build build --target doc      # needs doxygen + python3
```

## Project layout

```
src/
  core/                 business logic, NO GUI toolkit (→ libessim_core)
    domain/             model (Module/Part/Pin/Signal, Connection, Transform…) + analyses
    imports/            Mentor / Altium / ODS netlist importers + ODS writer
    app/                use-case operations (export → CSV/ODS, …)
  frontends/            one dir per GUI/TUI engine, each links essim_core
    tui/                FTXUI shell + main.cpp (→ libessim_tui + the `essim` binary)
tests/                  core tests (link essim_core)
  tui/                  frontend tests (link essim_tui)
doc/                    api/ + user/ Markdown, Doxyfile.in, gen_api_md.py
test/                   sample netlists + system.essim bring-up script
```

Full layout & rationale in [`DESIGN.md`](DESIGN.md).

## Licence

Copyright (c) 2026 François Dausseur

Licensed under the **European Union Public Licence (EUPL), Version 1.2** —
the "Licence". You may not use this work except in compliance with the
Licence. You may obtain a copy of the Licence in the [`LICENSE`](LICENSE)
file or at <https://joinup.ec.europa.eu/software/page/eupl>.

Unless required by applicable law or agreed to in writing, software
distributed under the Licence is distributed on an "AS IS" basis,
**WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND**, either express or
implied. See the Licence for the specific language governing permissions
and limitations under the Licence.

SPDX-License-Identifier: EUPL-1.2