François
76807b0307
Document the wxWidgets GUI frontend (wx dependency + -DESSIM_FRONTEND=wx in README; layout tree + architecture note in DESIGN) and the factored essim_add_frontend() per-frontend CMake helper. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
131 lines
4.8 KiB
Markdown
131 lines
4.8 KiB
Markdown
# 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.
|
|
- **wxWidgets** (≥ 3.2) — only for the **wx** GUI frontend
|
|
(`-DESSIM_FRONTEND=wx`). Install the development package:
|
|
- Debian/Ubuntu — `sudo apt install libwxgtk3.2-dev`
|
|
- Arch — `sudo pacman -S wxwidgets-gtk3`
|
|
- Fedora — `sudo dnf install wxGTK-devel`
|
|
- Optional, only for the `doc` target: **doxygen** and **python3**.
|
|
|
|
libzip, pugixml and libbsdl are the **core** dependencies; each frontend pulls
|
|
its own toolkit (FTXUI for tui, wxWidgets for wx), so a `-DESSIM_FRONTEND=none`
|
|
build needs neither. Pick a GUI/TUI with `-DESSIM_FRONTEND=tui|wx` (default
|
|
`tui`).
|
|
|
|
## 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
|