Skip to content

technical-details.md

Latest commit

 

History

History
138 lines (102 loc) · 5.38 KB

technical-details.md

File metadata and controls

138 lines (102 loc) · 5.38 KB
Raw

Flakebox - Technical Introduction

Note: Due to immaturity this project is part-vision/TODO and part-documentation at this point.

Flakebox is published a Nix Flake in https://github.com/rustshop/flakebox repository. This way it can be easily included in any other Flake of any Rust project.

By the virtue of being a Nix Flake, project using Flakebox can easily lock its version, update it, override its own inputs, etc. in addition to the reproducibility that Nix provides.

The goal

Functionality of Flakebox is meant to offer a complete and consistent handling of all the common aspects of Rust project development:

  • building Rust projects with Rust,
  • setting up configuration files (e.g. git hooks, commit templates, justfile),
  • integrating all the best lints (e.g. typos, semgrep, formatters, etc.),
  • integrating all the best utilities,
  • setting up Github Actions workflow files,
  • providing standardized tools and scripts for handling Rust project.

with a possibility to customize and disable each part.

To make it clear: Flakebox doesn't just setup/install some tools. It fully integrates them into cohesive and convenient environment, so e.g. all relevant lints from all the enabled linters run both in git's pre-commit hook, and in the CI, etc. The goal is to get by default a level of end to end polish that only the largest and most mature projects usually have, all in just few lines of Nix code.

Pre-commit timing diagnostics

The generated pre-commit hook runs every enabled check with GNU Parallel. Each worker uses a monotonic clock around the check itself, so time spent waiting for a worker slot is excluded. A check that takes strictly longer than one second emits a diagnostic such as:

flakebox: warning: check_semgrep took 1.235s (>1s)

The fixed three-digit fraction reports the duration at millisecond precision. The strict threshold still uses the underlying monotonic measurement, and a barely-over-threshold result is displayed as 1.001s rather than a misleading 1.000s. Timing is diagnostic only: checks still run with the same concurrency, output, exit status, and signal behavior.

The generated hook keeps consecutive warnings compact and adds a separator only when check output lacks a final newline. The internal timer helper's standalone mode cannot inspect arbitrary inherited standard error portably, so it conservatively starts its warning with a newline instead.

Skipping generated commit hooks

Set FLAKEBOX_SKIP_GIT_HOOKS=1 to bypass Flakebox's generated pre-commit and commit-msg checks for one command or environment:

FLAKEBOX_SKIP_GIT_HOOKS=1 git commit

Only the exact value 1 enables the bypass; an unset variable or any other value runs the checks normally. This does not affect hooks not generated by Flakebox. Git's git commit --no-verify is also available as a one-shot alternative.

Disabling commit integration

Set git.enable = false in the Flakebox configuration to disable the complete Git commit integration. Flakebox then does not generate or install its pre-commit or commit-msg hooks, generate its commit-message template, or set Git's commit.template configuration. The existing git.pre-commit.enable, git.commit-msg.enable, and git.commit-template.enable options remain available for partial control when git.enable is true.

This option does not clean up state installed by an earlier configuration. After changing it, remove the old generated files:

rm -f misc/git-hooks/pre-commit \
  misc/git-hooks/commit-msg \
  misc/git-hooks/commit-template.txt

Remove installed hooks only after confirming they are Flakebox-owned:

hooks_dir="$(git rev-parse --git-common-dir)/hooks"
ls -l "$hooks_dir/pre-commit" "$hooks_dir/commit-msg"
rm -f "$hooks_dir/pre-commit" "$hooks_dir/commit-msg"

Finally, remove the template setting only when it still has the Flakebox value:

if [ "$(git config --get commit.template || true)" = \
  "misc/git-hooks/commit-template.txt" ]; then
  git config --unset commit.template
fi

Flakebox lib output

Flakebox's Flake exposes a lib flake output which allows:

  • creating Flakebox Nix development shells,
  • customizing all settings,
  • extending with own modules,
  • building project artifacts form Rust code using Nix derivations.

Flakebox Nix development shells

Flakebox Nix development shells are standard nix develop shells, but with all the integration and configuration taken care of.

To facilitate generation of tool/service/application specific files, and for other DX purposes a flakebox CLI tool is prided in development shells.

Flakebox will detect when its flake input, or desired configuration changed and prompt the user to run flakebox install to update all the generated files, which can then be committed into the project. This is done so that all the tools (like Github Actions) expecting files in certain places, and all the users viewing the project without using development shells find everything where they expect.

Updating Flakebox

To update flakebox version used by the project, one would start by updating its flake input, e.g. with nix flake update.

Then the Nix development shell will prompt the user to run flakebox install, which will then overwrite old files with their new versions. All changes can be then committed and pushed a PR to the project.