Skip to content

JUSTFILE.md

Latest commit

 

History

History
76 lines (56 loc) · 4.06 KB

JUSTFILE.md

File metadata and controls

76 lines (56 loc) · 4.06 KB
Raw

Justfile Guide

What & Why

Developers use command runners like make and just as CLI macros... named shortcuts for repeatable development tasks.

Just is simpler for task automation: it has cleaner syntax, clearer errors, and avoids Make’s build-system quirks. Make is better when you need dependency-based incremental builds; Just is better for commands like test, lint, and release.

@anthonywu proposed JustFile in a MFlux-Community Discussion in August 2026: "This is the modern alternative to Makefiles, the syntax is much more readable to humans. In my two years working with just, AI assistants big and small have had no trouble helping me write these files."

Installing

as MFlux is targeting - we presume you are running on M-Series Mac - ie aarch64

brew install just

Common MFLux Workflow

just install
just lint
just test-fast

just install creates .venv, synchronizes dependencies, and installs pre-commit hooks. If pre-commit is not installed, the recipe installs it as a uv tool.

Recipes

Command Purpose
just List public recipes.
just all Install dependencies, then run the default test selection.
just install Create the environment, synchronize dependencies, and install pre-commit hooks.
just venv-init Create a clean Python 3.13 virtual environment after checking the platform and uv.
just lint Run Ruff checks without changing files.
just lint-justfile Verify that just --fmt would not reformat the justfile.
just format Run Ruff's formatter and show a summary of changed files.
just check Run all pre-commit hooks, including auto-fixes and formatters. Review changes afterwards.
just test Run the default pytest selection, which excludes slow model tests.
just test-fast Run tests marked fast; these do not generate images.
just test-slow Run tests marked slow; these generate images.
just test-all Run all tests except those marked high_memory_requirement. This can download model weights.
just build Build sdist/wheel into dist/, then report artifact sizes and flag any oversized files in the sdist (a check that image assets weren't accidentally bundled).
just release Trigger the release.yml GitHub Actions workflow via gh, then watch the run. Publishing happens on GitHub via PyPI trusted publishing (OIDC); no local credentials are used.
just clean Remove .venv. Run just install to recreate it.

Test recipes first synchronize the locked environment with all extras, then run pytest with MFLUX_PRESERVE_TEST_OUTPUT=1 so generated outputs remain available for inspection. They do not update golden images.

just build removes any stale dist/mflux-* artifacts, builds fresh sdist and wheel packages with uv build, then reports their sizes (expected under 1MB) and lists the five largest files inside the sdist — a quick sanity check that no image outputs got swept into the package by mistake.

Releasing to PyPI

Releases publish from GitHub Actions using PyPI trusted publishing (OIDC) — there are no PyPI credentials to configure locally. Either run just release, or trigger the workflow from the GitHub UI:

  1. Go to https://github.com/mflux-community/mflux/actions/workflows/release.yml
  2. Click the Run workflow dropdown (top right of the runs list)
  3. Leave the branch as main, type publish in the Type "publish" to confirm release field, and click Run workflow

Internal Recipes

expect-arm64, expect-uv, ensure-pre-commit, and _test-run are private helpers used by public recipes. They are not intended to be invoked directly.

Saturday 15 August - v0.1   |   by @ianscrivener, GPT 5.6 Terra & Claude Sonnet 5