Spvirit Developer Guide

Internal handover documentation for developers taking over Spvirit — a pure-Rust implementation of the EPICS PVAccess protocol (client, server, codec, CLI tools, Python bindings).

This guide covers internals: architecture, per-crate deep dives with file/line references, testing, release process, and the exact state of in-flight work. For the user-facing API story, read Part I through Part III of this site first, and spvirit-py/README.md for the full Python reference. The top-level README.md is a landing page that points here.

Chapters

#	Chapter	Read it when
01	Architecture Overview	Day one — the crate graph, the two protocol layers, server data flow, and the invariants everything relies on
02	spvirit-types & spvirit-codec	Before touching the data model or wire format
03	spvirit-server	Before touching the server: Source model, store, protocol runtime, handles, alarms/deadbands
04	spvirit-client & spvirit-tools	Before touching search/get/put/monitor or the CLI tools
05	spvirit-py	Before touching the Python bindings — especially the threading model
06	Testing Guide	Before writing tests; how to run the interop suites
07	Build, CI, and Release	Before releasing anything; repo conventions
08	Current State & Roadmap	First, if you're picking up work — known-gaps triage list and roadmap
09	The record-processing engine	Before touching `spvirit-ioc`: lock sets, load-time diagnostics, scanning (capped at 64 distinct periods), and what sub-projects C and D still owe

Day-one checklist

git clone https://github.com/ISISNeutronMuon/spvirit && cd spvirit
cargo build --release
cargo test --all                                   # should be green

# See it work — two terminals:
cargo run -p spvirit-server --example simple_server
cargo run -p spvirit-client --example pvget -- SIM:TEMPERATURE

# Python bindings:
cd spvirit-py && python -m venv .venv
.venv\Scripts\Activate.ps1                         # Windows; source .venv/bin/activate elsewhere
pip install maturin && maturin develop
python tests/test_pv_handles.py                    # expect ALL OK

Then:

Read chapter 08 and run git status / git log origin/main..main to see whether anything is uncommitted or unpushed before you start.
Skim EPICS in 10 minutes if EPICS/PVAccess is new to you, then chapter 01 here.

Orientation in 60 seconds

Nine crates, strict layering: types (pure data) → codec (wire format) → client/server → ioc (record processing, server-only) and gateway (client + server) → tools (CLIs + integration tests) and py (PyO3). calc (CALC expressions) stands apart. Everything on the wire is a Normative Type; the server offers an IOC-style record level (records, alarms, deadbands, auto-timestamps) as sugar over a raw-NT level (put_nt/get_nt, custom Source providers). Default ports: TCP 5075, UDP 5076. Interop is validated against EPICS Base, p4p/pvxs, and PVAccessJava.

How work is planned here

Substantial features follow a spec → plan → TDD execution workflow: a design spec, then a checkbox implementation plan (exact commands, per-task commits, Conventional Commit messages), then task-by-task execution. Those working documents are kept out of the repository — the durable record is this guide, the commit history, and the tests. One such plan, Python NT value-type selection, has since landed; chapter 08 records how.

Where to get answers

Protocol questions: the pvAccess Protocol Specification and pvxs (the reference implementation this project most closely mirrors).
"Why is this code like this": the commit history is the archaeology — commits are per-task and carry the reasoning in their messages.
Wire debugging: spsearch (search traffic TUI), spget --raw / spmonitor --raw (hex dumps), spget_compare (byte-compare against captures), and spvirit-scry (passive packet capture, built from spvirit-tools with --features scry; see spvirit-scry).