workflows

A collection of useful workflows for getting a new Rust project up and running.

Usage

You'll need a Nix implementation installed on your system to work with this repo. If you don't have one already, we recommend setting up Lix.

Once installed, you can create a new project from this repo by running:

mkdir new-project
cd new-project
nix flake init -t git+https://codeberg.org/polyphony/workflows

From there, you can enter a development shell with all the tools needed to work in your project by running nix develop. If you have direnv setup on your machine, you can also run direnv allow to activate the included .envrc file, which will automatically activate the devshell while you're in the project folder.

The development shell will contain a Rust toolchain defined by the rust-toolchain.toml file polyphony.rust.toolchainFile points to in your flake. If you need specific components or targets added to the shell, add them to rust-toolchain.toml and re-enter the development shell.

CI

The repository ships a Forgejo Actions workflow (template/.forgejo/workflows/check.yml for new projects) that runs nix flake check on every push to main, and every pull request. Nix commands in the workflow fetch build outputs from the ci-polyphony-universal attic binary cache and cache.nixos.org, and transient network failures during those downloads occasionally make a job fail.

When a nix command fails with an unable to download error, the workflow retries it up to NIX_ATTEMPTS attempts (default 3, with a 10 second pause between attempts) before failing. All other failures fail the job immediately.

The retry logic lives in a script provided by this flake: nix run .#retry-nix -- <command>. It is provided by the flake, so changes to the retry behavior only ever need to be made in one place.

Tip

Set the NIX_ATTEMPTS variable on your repository or organization in Forgejo (Settings → Actions → Variables) to change the retry count. Set it to 1 to effectively disable retries.

The template is intended to be usable as-is for all projects, not just Rust-based ones.

Building

The module exposes a crane-backed Rust package build when the consumer flake sets perSystem.polyphony.rust.src to the project root (for example ./.) or a subdirectory containing a Cargo.toml. When src is null (the default), the module produces no rustBuild output.

Top-level options:

• polyphony.rust.enable — enables Rust workflows (default true)
• polyphony.rust.toolchainFile — path to rust-toolchain.toml
• polyphony.rust.hash — sha256 of the toolchain manifest

Per-system build options:

• perSystem.polyphony.rust.src — path to the Rust project source tree (set from the consumer flake, not this module)
• perSystem.polyphony.rust.commonArgs — crane attributes shared by buildDepsOnly and buildPackage (default {})
• perSystem.polyphony.rust.packageArgs — crane attributes passed only to buildPackage, after commonArgs and dependency artifacts (default {})
• perSystem.polyphony.rust.crossTargets — map from Rust target triples to cross-compilation Nixpkgs sets (default null)

When src is set, the build exposes packages.<system>.rustBuild. For each entry in crossTargets, it also exposes packages.<system>.rustBuildCross-<target>. Each cross build reuses the same src, commonArgs, and packageArgs; crane builds dependency artifacts separately per cross Nixpkgs set.

For CI pipelines that run several Nix-backed cargo derivations against the same dependency tree, the module also exposes dependency-only derivations under packages.<system>.rustDeps and, for each cross target, packages.<system>.rustDepsCross-<target>. These run crane's buildDepsOnly and produce the same cargoArtifacts store path that rustBuild consumes, so building .#rustDeps once (and pushing it to a Nix binary cache) lets every downstream Nix job that reuses that cargoArtifacts input substitute the prebuilt dependency artifacts instead of recompiling them.

The build filters src with crane's cleanCargoSource, which retains Cargo and Rust inputs (.rs, .toml, Cargo.lock, .cargo/config). To include other compile-time assets (protobuf schemas, SQL, fixtures, and so on), set commonArgs.src to a custom source or crane fileset.

Cross-compilation requires the desired target triples in rust-toolchain.toml as well as entries in crossTargets. See the Nixpkgs cross-compilation manual.

perSystem = { ... }: {
  polyphony.rust.src = ./.;
  polyphony.rust.commonArgs = {
    cargoExtraArgs = "--features foo";
  };
  polyphony.rust.packageArgs = {
    pname = "my-crate";
  };
};

Build the native package with nix build .#rustBuild.

treefmt, a tool for running multiple formatters over an entire repo, is configured as the flake's formatter. You can run it with either nix fmt, or by calling treefmt directly while in the development shell. By default, it's configured for the following languages:

• Rust: rustfmt
• Nix: nixfmt
• TOML: taplo (when polyphony.taplo.enable = true)

Taplo auto-discovers a taplo.toml (or .taplo.toml) from the repository root: The repo ships a default config, but a consuming repository can ship its own to override TOML formatting preferences.

The development shell also sets up pre-commit hooks using prek. Pre-commit hooks are not auto-installed. Run prek install after entering the devshell to activate them. By default, the following checks are configured:

• Run clippy on Rust files (when polyphony.rust.enable = true)
• Format all files with treefmt (when polyphony.treefmt.enable = true)
• Run REUSE license compliance checks (when polyphony.reuse.enable = true)

When perSystem.polyphony.rust.src is set, the Rust module also exposes checks.<system>.clippy. It runs cargo clippy --all-targets --all-features -- -D warnings with a separate, nightly toolchain. The toolchain selected by rust-toolchain.toml remains the toolchain used for builds and the development shell, while the pre-commit clippy hook uses the same dedicated nightly toolchain.

You can also run the configured checks at any time with nix flake check.

Each module can be toggled independently. See the generated docs for a full list of options.

The REUSE tool runs as a pre-commit hook and as part of nix flake check. To use REUSE compliance in your own repository:

• Add SPDX-FileCopyrightText and SPDX-License-Identifier headers to each source file. See the existing files in this repo for examples.
• For auto-generated files that cannot carry inline headers, create a .license sidecar file (see flake.lock.license).

Set polyphony.reuse.enable = false in your flake if you do not want REUSE checks.