François
a4f8254cb3
DESIGN.md: libbsdl dependency and --batch headless mode; bsdl_model/bsdl_check in the layout; the attach-bsdl command and the `B` persist tag; PinSpec is now BSDL-populated; verify's five passes incl. the model-driven and JTAG checks and the new AnomalyKinds. README: libbsdl dependency, --batch usage, tutorial link. New doc/user/tutorial.md: end-to-end batch and TUI walkthroughs (load → tag → connect → attach-bsdl → verify, with the pin/JTAG findings explained). Regenerated commands.md (adds attach-bsdl); index.md links the tutorial. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
105 lines
3.4 KiB
Markdown
105 lines
3.4 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
|
|
```
|
|
|
|
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 at configure time via `FetchContent` (nothing to
|
|
install): **FTXUI** v6.1.9 and **doctest** v2.4.11.
|
|
- Optional, only for the `doc` target: **doxygen** and **python3**.
|
|
|
|
## Tests
|
|
|
|
```sh
|
|
./build/essim_tests
|
|
# or
|
|
ctest --test-dir build
|
|
```
|
|
|
|
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/system/ domain model (Module/Part/Pin/Signal, Connection, Transform, …)
|
|
src/imports/ Mentor / Altium / ODS netlist importers
|
|
src/tui/ FTXUI shell (commands, screens, completion, history)
|
|
tests/ doctest suite
|
|
doc/ api/ + user/ Markdown trees, 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
|