Track SPVA version independently from PVXS; own the shared SPVA version number

[george-mcintyre]

Summary

SPVA (Secure PVAccess) needs to be released on its own cadence, decoupled from the PVXS library version. Today anything "SPVA-versioned" actually borrows the PVXS major.minor. We need a separate SPVA version number that is:

• owned by this repo (slac-epics/pvxs-tls, the pvxs source tree), since it is the lowest shared dependency, and
• referenced by the pvxs-cms build train (see companion issue, below).

Current behaviour (verified)

src/util.cpp derives the XDG path version from the PVXS version:

// src/util.cpp
std::string getXdgPvaConfigHome() {
    const std::string suffix = SB() << OSI_PATH_SEPARATOR << "pva" << OSI_PATH_SEPARATOR << versionString();
    return getXdgConfigHome() + suffix;          // -> ~/.config/pva/1.5
}
std::string getXdgPvaDataHome() {
    const std::string suffix = SB() << OSI_PATH_SEPARATOR << "pva" << OSI_PATH_SEPARATOR << versionString();
    return getXdgDataHome() + suffix;            // -> ~/.local/share/pva/1.5
}
std::string versionString() {
    return stringify(PVXS_MAJOR_VERSION) "." stringify(PVXS_MINOR_VERSION);   // "1.5"
}

So the default config/data dirs are ~/.config/pva/1.5 and ~/.local/share/pva/1.5, keyed off the PVXS version.

Requested changes

1. Introduce a dedicated SPVA version (e.g. SPVA_CONFIG_MAJOR/MINOR in a new configure/CONFIG_SPVA_CONFIG_VERSION + generated spvaVersionNum.h), independent of PVXS_*_VERSION. This is the single source of truth that pvxs-cms will also consume.

2. Default config/data locations change from pva/<pvxs-major.minor> to spva/<spva-n.n>:

   • ~/.config/spva/<n.n>
   • ~/.local/share/spva/<n.n>

   i.e. both the literal pva -> spva and the version source versionString() (PVXS) -> SPVA Config version.

3. Show the SPVA version in -V output, and fold it into the VCS-describe string:

   PVXS 1.5.1 (pvxs-1.5.1.20260518-2-gcf83e3db10fac20d2d6b)
   SPVA CONFIG<n.n>
   EPICS 7.0.10.1-DEV
   libevent 2.1.12-stable
   OpenSSL 3.6.2 7 Apr 2026
   

   (The VCS tag form becomes pvxs-<pvxs-ver>-spva-<n.n.n>.<date>-<n>-g<hash>.)

Impact / call sites (this repo)

getXdgPvaConfigHome() / getXdgPvaDataHome() resolve default keychain locations in src/config.cpp (client client.p12, server server.p12). Changing the directory moves where existing deployments look for their certs — needs a migration/back-compat story (fallback to the old pva/<ver> path when the new one is absent, or documented manual move).

Cross-repo

• Companion (pvxs-cms): the pvxs-cms build train must reference this shared SPVA number and show PVXS-CMS (pvxs-cms.<date>-<n>-g<hash>) plus the SPVA <n.n> line. Tracked in slac-epics/pvxs-cms (linked once filed).
• Phoebus (heads-up, not owned here): core/pva/src/main/java/org/epics/pva/PVASettings.java documents that it "Matches PVXS versionString()" for the same pva/<ver> directory convention. If clients are expected to share config/cert locations, the Java side needs a paired change to track spva/<n.n.n>.

Acceptance

• A new SPVA version exists and is bumpable independently of PVXS_*_VERSION.
• Defaults resolve to ~/.config/spva/<n.n> and ~/.local/share/spva/<n.n> (with migration handling).
• -V shows SPVA <n.n>.
• pvxs-cms consumes the same number (companion issue).

[george-mcintyre]

Companion / downstream consumer issue filed: slac-epics/pvxs-cms#32 — pvxs-cms references this repo's shared SPVA version, shows the SPVA <n.n> line and pvxs-cms... VCS-describe, and moves its keychain/ACF/cert-DB defaults to ~/.config/spva/<n.n> / ~/.local/share/spva/<n.n>. That work is blocked on this issue landing first.

[george-mcintyre]

Related SPVA version-tracking issues

This is the owner issue (defines the shared SPVA version). Tracked together with:

• slac-epics/pvxs-tls#27 — this issue (owner: SPVA version source, spva/<n.n> dirs, SPVA <n.n> / -spva-<n.n> describe)
• slac-epics/pvxs-cms#32 — PVACMS build train consumes the shared SPVA version; CMS -V line + cert/ACF/DB dirs
• ControlSystemStudio/phoebus#3865 — Java PVA (Phoebus) hard-codes the SPVA version and moves its keychain dir (can't share C++ code)

[kasemir]

SPVA (Secure PVAccess) needs to be released on its own cadence, decoupled from the PVXS library version.

Really? PVXS with SPVA hasn't been released. Once it is, wouldn't PVXS simply contain the TLS support, and they can share one version number?

[george-mcintyre]

SPVA (Secure PVAccess) needs to be released on its own cadence, decoupled from the PVXS library version.

Really? PVXS with SPVA hasn't been released. Once it is, wouldn't PVXS simply contain the TLS support, and they can share one version number?

Yes, they will. And once we resolve the XDG path naming (/spva/<spva_config_version>/) then everything will be coherent. Note in the XDG case we're now talking about a different version number than the protocol. So this Issue becomes about tracking the SPVA configuration version number.