nox manage cargo-binstall

Author: 2bndy5

docs/README.md

@@ -4,16 +4,11 @@ This folder is only for generating the documentation about CLI and runtime permi
 Please [visit our website][gh-pages] to see generated documentation.
 
 [gh-pages]: https://cpp-linter.github.io/cpp-linter-rs
-[uv]: https://docs.astral.sh/uv/
 
 ## Build and inspect locally
 
 To view the documentation locally, some software needs to be installed.
-This project's dependencies are managed with a tool called [`uv`][uv].
-So, [`uv`][uv] is the only software that needs to be manually installed beforehand.
 
-After [`uv`][uv] is installed, building (and viewing) the docs is as simple as
-
-```shell
-uvx nox -s docs -- --open
-```
+> [!IMPORTANT]
+> Please review of [Contributing doc](docs/getting-started.md)
+> which contains instruction about building and inspecting docs.

docs/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Contributing
+
+This project requires the following tools installed:
+
+- :simple-rust: [rust](https://rustup.rs/)
+- :simple-uv: [`uv` (Python Project management tool)](https://docs.astral.sh/uv/)
+
+## Getting started
+
+After checking out the repo locally, use
+
+```sh
+uv sync
+```
+
+This creates a venv at ".venv/" in repo root (if it doesn't exist).
+It also installs dev dependencies like `pre-commit`, `nox`, `ruff`, and `mypy`.
+
+See [`uv sync` docs](https://docs.astral.sh/uv/reference/cli/#uv-sync)
+for more detailed usage.
+
+<!-- markdownlint-disable MD028 -->
+
+> [!TIP]
+> To register the pre-commit hooks, use:
+>
+> ```shell
+> uv run pre-commit install
+> ```
+
+### Cargo-managed binaries
+
+The tasks run with `nox` will ensure cargo-managed binaries are installed as needed.
+
+### Running tests
+
+Use nox to run tests:
+
+```sh
+uv run nox -s test
+```
+
+Different test profiles are still defined in .config/nextest.toml.
+The above command uses the "default" profile, but to mimic the CI, use:
+
+```sh
+uv run nox -s test -- --profile ci
+```
+
+To generate a coverage report:
+
+```sh
+uv run nox -s llvm-cov -- --open
+```
+
+The `-- --open` part is optional. It opens the built coverage report in your default browser.
+
+The uploaded codecov report is generated with
+
+```sh
+uv run nox -s lcov
+```
+
+### Generating docs
+
+To view the docs locally, use
+
+```sh
+uv run nox -s docs -- --open
+```
+
+The `-- --open` part is optional. It opens the built docs in your default browser.
+
+In CI, docs are built using
+
+```sh
+uv run nox -s docs-build
+```

docs/mkdocs.yml

@@ -12,6 +12,7 @@ nav:
   - python.md
   - node.md
   - changelog.md
+  - getting-started.md
   - other-licenses.md
 
 theme:

noxfile.py

@@ -1,4 +1,6 @@
 import logging
+import platform
+import re
 import sys
 import nox
 
@@ -10,6 +12,73 @@
 
 nox.options.default_venv_backend = "uv"
 
+BIN_STALL_CARGO = re.compile(r"^([^\s]+)\s([^:]+):")
+CARGO_BINSTALL = "cargo-binstall"
+
+
+class CargoInstaller:
+    def __init__(self, session: nox.Session):
+        cargo_installed: str | None = session.run(
+            "cargo", "install", "--list", external=True, silent=True
+        )
+        assert cargo_installed is not None, "Is rust cargo installed?"
+        cargo_bins: dict[str, str] = {}
+        for line in cargo_installed.splitlines():
+            found = BIN_STALL_CARGO.match(line)
+            if found is not None:
+                name, version = found.groups()
+                cargo_bins.setdefault(name, version)
+        self.cargo_bins = cargo_bins
+        self.cargo_install_cmd: tuple[str, ...] = ("cargo", "install")
+
+        if CARGO_BINSTALL in cargo_bins:
+            ci_logger.info(
+                "Found %s: %s" % (CARGO_BINSTALL, cargo_bins[CARGO_BINSTALL])
+            )
+            self.cargo_install_cmd = ("cargo", "binstall", "-y")
+        else:
+            ci_logger.info("Installing %s" % CARGO_BINSTALL)
+            match platform.system():
+                case "Windows":
+                    one_liner = """Set-ExecutionPolicy Unrestricted -Scope Process; iex (iwr "https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.ps1").Content"""
+                    session.run(*one_liner.split(), external=True)
+                case "Linux" | "Darwin":
+                    one_liner = "curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash"
+                    session.run(*one_liner.split(), external=True)
+                case _:
+                    session.run(
+                        *self.cargo_install_cmd,
+                        CARGO_BINSTALL,
+                        "--locked",
+                        external=True,
+                    )
+
+    def check_install(self, req: str, session: nox.Session):
+        """Use cargo to ensure `req` is installed.
+
+        Parameters:
+            req: The package name (on crates.io) to check and install.
+                Supports explicit version in the form
+                    `[email protected]`.
+                Typically this is the project's name as published on crates.io.
+        """
+
+        ver = None
+        if "@" in req:
+            req, ver = req.split("@", 1)[:2]
+
+        def install():
+            ci_logger.info("Installing %s" % req)
+            dep = req if not ver else f"{req}@{ver}"
+            session.run(*self.cargo_install_cmd, dep, "--locked", external=True)
+
+        installed = False
+        if req in self.cargo_bins:
+            ci_logger.info("Found %s %s" % (req, self.cargo_bins[req]))
+            installed = True
+        if ver or not installed:
+            install()
+
 
 def uv_sync(session: nox.Session, *args: str):
     session.run_install(
@@ -79,6 +148,13 @@ def test(session: nox.Session):
     Otherwise, the default profile is used.
     """
     uv_sync(session, "--group", "test")
+    installer = CargoInstaller(session)
+    for req in [
+        "cargo-llvm-cov",
+        "cargo-nextest",
+    ]:
+        installer.check_install(req, session)
+
     session.run(
         "cargo",
         "llvm-cov",
@@ -102,6 +178,8 @@ def test_clean(session: nox.Session):
     This is useful if coverage data needs to be
     completely refreshed.
     """
+    installer = CargoInstaller(session)
+    installer.check_install("cargo-llvm-cov", session)
     session.run("cargo", "llvm-cov", "clean", external=True)
 
 
@@ -114,6 +192,8 @@ def llvm_cov(session: nox.Session):
 
     Otherwise, the default profile is used.
     """
+    installer = CargoInstaller(session)
+    installer.check_install("cargo-llvm-cov", session)
     session.run(
         "cargo",
         "llvm-cov",
@@ -135,6 +215,9 @@ def pretty_cov(session: nox.Session):
 
     Otherwise, the default profile is used.
     """
+    installer = CargoInstaller(session)
+    for req in ["cargo-llvm-cov", "llvm-cov-pretty"]:
+        installer.check_install(req, session)
     session.run(
         "cargo",
         "llvm-cov",
@@ -156,6 +239,8 @@ def lcov(session: nox.Session):
     Useful for codecov uploads and VSCode extensions
     like "Coverage Gutters".
     """
+    installer = CargoInstaller(session)
+    installer.check_install("cargo-llvm-cov", session)
     session.run(
         "cargo",
         "llvm-cov",
@@ -177,3 +262,13 @@ def lint(session: nox.Session):
         "cargo", "clippy", "--allow-staged", "--allow-dirty", "--fix", external=True
     )
     session.run("cargo", "fmt", external=True)
+
+
+@nox.session(python=False)
+def install(session: nox.Session):
+    """Install necessary software in global env"""
+
+    installer = CargoInstaller(session)
+
+    for req in session.posargs:
+        installer.check_install(req, session)