Skip to content

Add cargo-binstall Linux release support#189

Merged
leynos merged 4 commits intomainfrom
cargo-binstall-support
Apr 18, 2026
Merged

Add cargo-binstall Linux release support#189
leynos merged 4 commits intomainfrom
cargo-binstall-support

Conversation

@leynos
Copy link
Copy Markdown
Owner

@leynos leynos commented Apr 18, 2026

Add explicit cargo-binstall metadata to Cargo.toml and publish Linux release archives in the shape that binstall expects.

Build tagged releases for both x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu, package each binary into a versioned .tgz, and upload the full set of assets to the GitHub release. Document the new install path in README.md.

Keep the small html.rs match cleanup that Clippy required while validating the branch, and retain the repo-wide Markdown list-numbering normalisation from make fmt so the Markdown lint gate passes.

Summary by Sourcery

Add support for publishing Linux release archives consumable by cargo-binstall and document the new installation path while updating formatting and tooling to satisfy markdown linting and Clippy requirements.

New Features:

  • Expose pre-built Linux binaries for vk via cargo-binstall-compatible release archives for x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu, referenced in the installation instructions.

Enhancements:

  • Add cargo-binstall metadata to Cargo.toml, including package description, readme, repository URL, and archive layout configuration.
  • Adjust HTML collapsing logic to satisfy Clippy while preserving behavior.
  • Normalize Markdown formatting, tables, and ordered lists across documentation to align with the markdownlint configuration.

Build:

  • Extend the release GitHub Actions workflow to build, cross-compile, package, and upload versioned .tgz artifacts for both x86_64 and aarch64 Linux targets.
  • Update the Makefile markdownlint target to use markdownlint-cli2 and exclude target and node_modules directories from linting.

Documentation:

  • Document cargo-binstall-based installation and supported Linux targets in the README, while tightening various docs and guides formatting for consistency with markdown linting rules.

Add explicit `cargo-binstall` metadata to `Cargo.toml` and publish
Linux release archives in the shape that `binstall` expects.

Build tagged releases for both `x86_64-unknown-linux-gnu` and
`aarch64-unknown-linux-gnu`, package each binary into a versioned
`.tgz`, and upload the full set of assets to the GitHub release.
Document the new install path in `README.md`.

Keep the small `html.rs` match cleanup that Clippy required while
validating the branch, and retain the repo-wide Markdown list-numbering
normalisation from `make fmt` so the Markdown lint gate passes.
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 18, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ebae37cd-b198-48d4-ba77-d22dddf4c297

📥 Commits

Reviewing files that changed from the base of the PR and between 5341539 and 216c280.

📒 Files selected for processing (1)
  • .github/workflows/release.yml

Cargo-binstall Linux Release Support

This PR adds cargo-binstall integration for Linux releases, extends the release workflow to produce pre-built Linux binaries for two architectures, and includes documentation, linting and small code refinements.

Key Changes

Build & Release Workflow (.github/workflows/release.yml)

  • Builds tagged releases for both x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu using a matrix with fail-fast: false.
  • Adds per-target Rust setup (rustup target add) and caches that are target-scoped (cache keys include ${{ matrix.target }}).
  • Cross-compilation support for AArch64: installs gcc-aarch64-linux-gnu and exports CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER only for the AArch64 matrix entry (the build step is split so the linker override does not affect other targets).
  • Changes build invocation to cargo build --locked --release --target ${{ matrix.target }} --bin ${{ env.REPO_NAME }}.
  • Packages each target binary into a versioned .tgz archive laid out for cargo-binstall ({name}-{target}-v{version}/{bin}) and uploads those archives to the GitHub release.
  • The release job gathers built artifacts, ensures the GitHub release exists (creates it if missing), and uploads all *.tgz assets via gh release upload --clobber.

Package Metadata (Cargo.toml)

  • Adds package metadata fields description, readme, and repository.
  • Adds [package.metadata.binstall] configuring pkg-url, bin-dir, and pkg-fmt = "tgz" to support cargo-binstall installs.

Documentation (README.md)

  • Documents cargo-binstall-based installation (cargo binstall vk) and lists published Linux release targets (x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu).
  • Retains guidance for building from source with Cargo for other targets.

Tooling & Linting

  • Switches Markdown linting to markdownlint-cli2 and updates .markdownlint-cli2.jsonc (adds **/.uv-cache/** to ignores).
  • Updates Makefile markdownlint target to use markdownlint-cli2 and to exclude */target/* and */node_modules/*.

Code Refinement & Bug Tracking (src/html.rs)

  • Applies a small Clippy-driven cleanup to collapse_node (restructured match guards for <details> and text node handling).
  • Maintainer reported this change exposes a behavioural bug: a details match arm with an empty body causes non-collapsed <details> elements to drop their children instead of rendering them. An issue documenting the bug and suggested fix (recurse into children when should_collapse_details is false) was opened as issue #190: collapse_node silently drops children of non-collapsed <details> elements #190.

Repository-wide formatting

  • Normalises Markdown list numbering and applies Markdown formatting adjustments across docs (multiple files under docs/ and README) so markdownlint passes; content and semantics are preserved.

Notes for reviewers

  • The release workflow changes are the largest surface-area change (target-scoped caching, cross-compilation, packaging and release upload).
  • The src/html.rs change is small but behavioural; follow-up is tracked in issue #190 and likely requires a patch so expanded <details> still render their children.

Walkthrough

Summarise the workflow and documentation changes: add a GitHub Actions matrix build for x86_64 and AArch64, perform target-specific setup and caching, build and package per-target .tgz artifacts, upload release archives via gh, add binstall metadata to Cargo.toml, update markdown lint tooling, and apply widespread Markdown formatting edits.

Changes

Cohort / File(s) Summary
CI / Release Workflow
\.github/workflows/release.yml
Add matrix build for x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu; run rustup target add, conditionally install cross-linker for AArch64, use target-scoped cargo cache keys, build with --target and --locked, install binary into versioned dir and create per-target *.tgz artifacts, ensure/create GitHub release and upload all *.tgz.
Package Metadata & Installer
Cargo.toml
Add description, readme, repository metadata and package.metadata.binstall with pkg-url, bin-dir, and pkg-fmt = "tgz" for binstall integration.
Linting & Makefile
Makefile, .markdownlint-cli2.jsonc
Switch Makefile MDLINT to markdownlint-cli2, refine find exclusions and xargs invocation; remove MD046 rule and add **/.uv-cache/** to lint ignores.
User Documentation
README.md
Update Installing section to recommend cargo binstall vk and list published Linux targets; clarify source build via cargo install --path ..
Docs Formatting
docs/... (multiple files)
docs/execplans/adopt-ortho-config-v0-8-0.md, docs/github-token.md, docs/ortho-config-*.md, docs/vk-design.md, docs/vk-end-to-end-testing-guide.md, docs/ortho-config-v0-6-0-migration-guide.md, docs/ortho-config-v0-7-0-migration-guide.md
Apply Markdown formatting changes: table alignment, line-wrapping, and list renumbering across many docs; no behavioural or API changes.
Source Cleanup
src/html.rs
Refactor pattern matching in collapse_node to consolidate guards and add explicit no-op arm for <details>, and simplify Text arm; preserve behaviour.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor Developer
    participant GitHubActions as GitHub Actions (matrix)
    participant Runner as Runner
    participant Rustup as rustup
    participant Apt as apt (optional)
    participant Cargo as cargo
    participant Tar as tar
    participant GH as gh (GitHub CLI)

    Developer->>GitHubActions: push / create release
    GitHubActions->>Runner: start matrix jobs (x86_64, aarch64)
    Runner->>Rustup: rustup target add ${matrix.target}
    alt matrix.target == aarch64-unknown-linux-gnu
        Runner->>Apt: install gcc-aarch64-linux-gnu
        Apt-->>Runner: cross-linker available
        Runner->>Runner: set CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER
    end
    Runner->>Cargo: cargo build --locked --release --target ${matrix.target} --bin ${REPO_NAME}
    Runner->>Runner: install binary into ${REPO_NAME}-${TARGET}-v${version}/
    Runner->>Tar: create ${REPO_NAME}-${matrix.target}-${github.ref_name}.tgz
    Runner->>GitHubActions: upload artifact (tgz)
    GitHubActions->>GH: download all artifacts into release-artifacts/
    GH->>GH: ensure release exists (create if needed)
    GH->>GH: gh release upload --clobber *.tgz
    GH-->>Developer: release artifacts published
Loading

Poem

🎩 Two targets march in parallel stride,
Binaries packed and versioned with pride,
AArch64 and x86 unite,
Docs tidied up, the linter right,
Releases uploaded — ship and glide!

🚥 Pre-merge checks | ✅ 3 | ❌ 4

❌ Failed checks (4 warnings)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Testing ⚠️ Warning PR introduces HTML processing with a known bug in details element handling, causing non-collapsed elements to silently discard children without recursion. Add unit tests validating expanded details elements render children correctly, replace empty match arm with recursive logic, update existing test to reflect correct behaviour.
User-Facing Documentation ⚠️ Warning The PR introduces a user-facing behaviour regression in collapse_node that silently drops children of non-collapsed
Details elements, causing expanded details sections to disappear from terminal output without documentation.
Document the expected behaviour of expanded
Details blocks in vk-design.md or README.md, or fix the bug by implementing proper recursion for non-collapsed
elements.
Developer Documentation ⚠️ Warning PR introduces significant build, tooling and cross-compilation requirements without updating AGENTS.md or docs/ as mandated by the developer guide. Update AGENTS.md to document the multi-target build matrix, cross-compilation prerequisites (gcc-aarch64-linux-gnu), markdownlint-cli2 requirement, and cargo-binstall configuration with developer build instructions.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title directly reflects the primary objective: adding cargo-binstall support for Linux releases, which is the main feature across Cargo.toml metadata, release workflow, and documentation.
Description check ✅ Passed The description comprehensively covers all significant changes: cargo-binstall metadata, multi-target Linux release builds, packaging, documentation, HTML cleanup, and Markdown normalisation.
Module-Level Documentation ✅ Passed All modules in the repository maintain appropriate module-level docstrings, including src/html.rs with its documented purpose. The PR modifies only implementation details within src/html.rs without altering, removing, or adding any module-level documentation, and no new undocumented modules are introduced.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch cargo-binstall-support

Comment @coderabbitai help to get the list of available commands and usage tips.

codescene-delta-analysis[bot]

This comment was marked as outdated.

@sourcery-ai
Copy link
Copy Markdown
Contributor

sourcery-ai Bot commented Apr 18, 2026

Reviewer's Guide

Adds Linux release support for cargo-binstall by enriching Cargo.toml metadata, extending the GitHub release workflow to build and package architecture-specific tgz archives, tightens HTML details-collapse logic, and normalizes Markdown formatting and ordered lists across docs while documenting the new install path.

File-Level Changes

Change Details Files
Enable cargo-binstall installation via release archives and package metadata.
  • Add description, readme, and repository fields to the package manifest to satisfy binstall expectations.
  • Add [package.metadata.binstall] configuration specifying pkg-url template, archive layout (bin-dir), and tgz format so cargo-binstall can locate vk binaries in GitHub releases.
  • Document cargo-binstall installation in README, including supported Linux targets and keeping cargo install from source as the fallback.
Cargo.toml
README.md
Extend the release workflow to build, package, and upload per-target Linux archives.
  • Introduce a build matrix for x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu with fail-fast disabled.
  • Install the aarch64 cross-linker and add the target via rustup, wiring CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER for cross-builds.
  • Change the cargo build step to a locked, target-specific release build of the vk binary and package each target into a versioned tgz under dist/ using a {name}-{target}-v{version} directory layout.
  • Adjust artifact upload to upload per-target tgz files named vk-{target}-{tag}.tgz and update the release job to find all tgz artifacts and upload them to the GitHub release with gh release upload --clobber.
.github/workflows/release.yml
Tighten HTML details-collapse logic to couple tag matching and collapse predicate evaluation.
  • Refactor collapse_node match arms so the
    Details tag check and should_collapse_details predicate are combined in a single guarded branch that writes a collapsed summary and skips children when collapsing.
  • Add a separate no-op branch for non-collapsed
    Details elements, and simplify the text-node arm using a guard that only emits text when not in a details context.
src/html.rs
Normalize Markdown formatting, tables, and ordered lists to satisfy markdownlint and keep docs consistent.
  • Reformat tables in user guides and migration guides to consistent column alignment and spacing without changing semantics.
  • Correct ordered list numbering to be sequential where explicitly referenced in prose (e.g., configuration precedence and processing steps).
  • Tidy wrapped lines and footnotes in various docs for better mdformat/markdownlint compliance and clarify some phrasing without altering meaning.
  • Update the Makefile markdownlint target to use markdownlint-cli2 and to exclude target and node_modules directories more robustly.
docs/ortho-config-users-guide.md
docs/vk-end-to-end-testing-guide.md
docs/ortho-config-v0-6-0-migration-guide.md
docs/ortho-config-v0-7-0-migration-guide.md
docs/execplans/adopt-ortho-config-v0-8-0.md
docs/github-token.md
docs/vk-design.md
Makefile

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

Switch the `markdownlint` Make target to the same
`markdownlint-cli2`-based invocation used in `rstest-bdd` so the
default repo gate no longer depends on a missing `markdownlint` binary.

Update `.markdownlint-cli2.jsonc` to match the shared ignore set and
rule set from that repository, including `.uv-cache/` handling.
@leynos leynos marked this pull request as ready for review April 18, 2026 14:07
codescene-delta-analysis[bot]

This comment was marked as outdated.

sourcery-ai[bot]

This comment was marked as resolved.

@leynos
Copy link
Copy Markdown
Owner Author

leynos commented Apr 18, 2026

@coderabbitai please create a new GitHub issue for the following:

  • In collapse_node the new details branch with an empty body means non-collapsed <details> elements no longer have their children traversed or rendered; consider keeping the recursive descent for details when should_collapse_details is false so expanded sections still output content.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 18, 2026

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@coderabbitai coderabbitai Bot added the Roadmap label Apr 18, 2026
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/release.yml:
- Around line 102-106: The workflow fails because gh release upload is called
without ensuring the release exists; modify the step that currently runs gh
release upload (the "Upload release" step invoking gh release upload and using
"${{ github.ref_name }}") to first check/create the release (e.g., run gh
release view "${{ github.ref_name }}" and if missing run gh release create "${{
github.ref_name }}" --verify-tag --generate-notes) before mapping assets and
calling gh release upload; keep the same env GITHUB_TOKEN and ensure the step
name reflects creation (e.g., "Create or update release").
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 218d5027-75cf-44d2-bc44-069d213199e8

📥 Commits

Reviewing files that changed from the base of the PR and between 116ba72 and 49858bb.

📒 Files selected for processing (13)
  • .github/workflows/release.yml
  • .markdownlint-cli2.jsonc
  • Cargo.toml
  • Makefile
  • README.md
  • docs/execplans/adopt-ortho-config-v0-8-0.md
  • docs/github-token.md
  • docs/ortho-config-users-guide.md
  • docs/ortho-config-v0-6-0-migration-guide.md
  • docs/ortho-config-v0-7-0-migration-guide.md
  • docs/vk-design.md
  • docs/vk-end-to-end-testing-guide.md
  • src/html.rs

Comment thread .github/workflows/release.yml Outdated
Verify the reported release workflow finding against the current YAML
and fix only the missing release-creation path.

Before uploading assets, check whether the GitHub release already
exists for the tag and create it with `--verify-tag` and
`--generate-notes` when it does not. Keep the existing token handling
and upload behaviour unchanged otherwise.
codescene-delta-analysis[bot]

This comment was marked as outdated.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/release.yml:
- Around line 64-66: The workflow currently sets
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER unconditionally; scope that
environment variable so it only applies when building the aarch64 target by
moving or applying the env to the step that runs when matrix.target ==
"aarch64-unknown-linux-gnu" (or use a conditional/matrix property) so the run
step that executes cargo build for matrix.target uses the linker env only for
the AArch64 matrix entry; reference the env key
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER and the cargo build step (run:
cargo build --locked --release --target ${{ matrix.target }} --bin ${{
env.REPO_NAME }}) when making the change.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f93196ab-bae2-45bc-82c3-8eb795b05744

📥 Commits

Reviewing files that changed from the base of the PR and between 49858bb and 5341539.

📒 Files selected for processing (1)
  • .github/workflows/release.yml

Comment thread .github/workflows/release.yml
Verify the reported workflow finding against the current release YAML
and narrow the linker override only where it is needed.

Split the release build step so
`CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER` is exported only for
the `aarch64-unknown-linux-gnu` matrix entry while the existing
`cargo build --locked --release --target ...` command stays unchanged.
@leynos leynos merged commit 0f7def4 into main Apr 18, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant