158 lines
6.3 KiB
Markdown
158 lines
6.3 KiB
Markdown
# Development and packaging
|
|
|
|
## Rust compatibility
|
|
|
|
The bridge supports Rust 1.85.1 and newer. Rust does not publish long-term
|
|
support toolchains; 1.85.1 was chosen as a conservative distribution anchor
|
|
because it is shipped by Debian 13 stable. `Cargo.toml` declares the MSRV,
|
|
`Cargo.lock` pins an MSRV-compatible graph, and Jenkins checks that graph with
|
|
both Rust 1.85.1 and current stable.
|
|
|
|
Future dependency updates must preserve this check or deliberately update the
|
|
declared MSRV, documentation, and Jenkins value together. Cargo's MSRV-aware
|
|
resolver is enabled in `.cargo/config.toml` to avoid selecting newer compatible
|
|
crate releases that require a newer compiler.
|
|
|
|
## Bridge checks
|
|
|
|
Run the same core checks as Jenkins before submitting a bridge change:
|
|
|
|
```sh
|
|
cargo +1.85.1 check --locked --all-targets --all-features
|
|
cargo +1.85.1 test --locked --all-targets --all-features
|
|
cargo fmt --all -- --check
|
|
cargo check --locked --all-targets --all-features
|
|
cargo test --locked --all-targets --all-features
|
|
cargo clippy --locked --all-targets --all-features -- -D warnings
|
|
```
|
|
|
|
After installing a newly built companion VSG wheel, run the opt-in real-process
|
|
integration check as well:
|
|
|
|
```sh
|
|
VSG_EXECUTABLE=/path/to/venv/bin/vsg \
|
|
cargo test --test packaged_vsg -- --ignored
|
|
```
|
|
|
|
Normal unit tests use injected runners and do not depend on a developer's VSG
|
|
installation.
|
|
|
|
Run the two network-enabled dependency policy gates before the core checks:
|
|
|
|
```sh
|
|
cargo audit --deny warnings
|
|
cargo deny check
|
|
```
|
|
|
|
## Coverage
|
|
|
|
Jenkins uses pinned Cargo Tarpaulin 0.37.5 with its LLVM engine and the current
|
|
stable toolchain. To run the same 90% line-coverage gate locally:
|
|
|
|
```sh
|
|
rustup component add llvm-tools-preview
|
|
cargo install cargo-tarpaulin --locked --version 0.37.5
|
|
cargo tarpaulin --config tarpaulin.toml
|
|
```
|
|
|
|
CI uses a temporary JSON summary to render the coverage SVG badge. Its final
|
|
cleanup action obtains the package version from `cargo pkgid --locked`, with a
|
|
`Cargo.toml` fallback, and renders the test badge from a build-specific marker
|
|
written only after the test stage succeeds. If coverage did not complete, CI
|
|
renders a neutral `-%` badge instead of leaving a broken or stale image. Jenkins
|
|
archives only those three badges. The first behavior-test pass reached 84.38%
|
|
(81/96 lines); end-to-end byte-stream
|
|
and protocol lifecycle tests raised current coverage above 90%. The latest
|
|
coverage run measured 91.49%, allowing CI to enforce a 90% floor. Raise that
|
|
floor only after coverage remains stable under useful tests; never add brittle
|
|
tests or production branches merely to improve the number.
|
|
|
|
Standalone HTML, JSON, and LCOV files produced locally remain ignored. Badges
|
|
are generated only by Jenkins and are not tracked in the repository. Jenkins
|
|
does not retain precise reports; it keeps only `coverage/coverage.svg`,
|
|
`coverage/version.svg`, and `coverage/test.svg`.
|
|
|
|
For the public badge, the Jenkins worker exposes the shared `assets/` directory
|
|
at `/mnt/assets`, beside the existing `/mnt/books` mount. The pipeline sets
|
|
`BADGE_PUBLISH_ROOT` to `/mnt/assets/coverage`; the worker creates that
|
|
directory when needed, and its parent must be writable. The final cleanup action
|
|
atomically replaces all three badges after every `main` build, including failed
|
|
builds:
|
|
|
|
```text
|
|
MadGobblins/vsg-bridge-ls/main/coverage.svg
|
|
MadGobblins/vsg-bridge-ls/main/test.svg
|
|
MadGobblins/vsg-bridge-ls/main/version.svg
|
|
```
|
|
|
|
`main` is a real world-traversable directory, not a symlink. This avoids web
|
|
server symlink restrictions. Precise HTML, JSON, and LCOV reports are not
|
|
retained. The README uses these mutable CI badge URLs:
|
|
|
|
```text
|
|
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/coverage.svg
|
|
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/test.svg
|
|
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/version.svg
|
|
```
|
|
|
|
The web server should receive this mount read-only, disable directory listing,
|
|
serve SVG with a restrictive content security policy, and use a short cache or
|
|
revalidation for the mutable badge URL.
|
|
|
|
## Companion VSG fork
|
|
|
|
The fork keeps its stream-support patch small and rebases it onto upstream
|
|
`master`. From the fork checkout:
|
|
|
|
```sh
|
|
./update-fork.sh
|
|
./build-package.sh
|
|
```
|
|
|
|
To build and publish with an explicit Gitea token file:
|
|
|
|
```sh
|
|
chmod 600 ../gitea_token.txt
|
|
./build-package.sh ../gitea_token.txt --publish
|
|
```
|
|
|
|
The script builds both a wheel and source distribution and uploads only the
|
|
artifacts produced by that invocation. It also accepts `GITEA_TOKEN` or
|
|
`GITEA_TOKEN_FILE` when no positional token file is supplied.
|
|
|
|
## Jenkins package publishing
|
|
|
|
The VSG Jenkins pipeline publishes successful `master` builds automatically.
|
|
It fetches repository tags before setup so `setuptools-git-versioning` can
|
|
derive the package version, then publishes the same wheel and source archive
|
|
that passed the pip and uv installation checks. Other branches never receive
|
|
the publishing credential.
|
|
|
|
Create the credential in Jenkins:
|
|
|
|
1. Create a Gitea personal access token whose `package` permission is set to
|
|
**Read and Write**. Use an account allowed to publish packages owned by the
|
|
`MadGobblins` organization.
|
|
2. Open **Manage Jenkins → Credentials**, select the narrowest folder or system
|
|
store containing the multibranch job, and choose **Add Credentials**.
|
|
3. Select **Secret text**, paste the token into **Secret**, and set **ID** to
|
|
`vsg-gitea-package-token`.
|
|
4. Save it. The Credentials Binding plugin must be installed for the
|
|
`withCredentials` pipeline step.
|
|
|
|
The token exists only as `GITEA_TOKEN` inside the publish stage. Shell tracing
|
|
is disabled before it is mapped to uv's `UV_PUBLISH_PASSWORD`; it is never put
|
|
in a command argument or written into the workspace.
|
|
|
|
Published versions come from the existing Git-versioning backend. An exact
|
|
release version requires a version tag on the commit; untagged commits receive
|
|
the backend's post-release version. Because package versions are immutable in
|
|
Gitea, the pipeline uses uv's index check to skip files already present.
|
|
|
|
## References
|
|
|
|
- [Language Server Protocol 3.17](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/)
|
|
- [tower-lsp stdio example](https://github.com/ebkalderon/tower-lsp/blob/master/examples/stdio.rs)
|
|
- [upstream VSG](https://github.com/jeremiah-c-leary/vhdl-style-guide)
|
|
- [upstream VSG documentation](https://vhdl-style-guide.readthedocs.io/en/latest/)
|