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 — uncommitted changes, the in-flight Python value-types plan, known-gaps triage list

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 — there is uncommitted work and unpushed commits at handover.
Skim the top-level README's "Key Concepts" if EPICS/PVAccess is new to you, then chapter 01 here.

Orientation in 60 seconds

Six crates, strict layering: types (pure data) → codec (wire format) → client/server → tools (CLIs + integration tests) and py (PyO3). 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 — is mid-flight; see chapter 08 before touching spvirit-py or spvirit-server/src/pv.rs.

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 the related spvirit-scry capture tool.