|
| 1 | +# Pixi workspace and pre-submit conventions |
| 2 | + |
| 3 | +This document describes how pixi and the pre-submit pipeline are configured for this package. The same structure is shared across the `mojo-*` libraries so behaviour is predictable. |
| 4 | + |
| 5 | +## Workspace configuration |
| 6 | + |
| 7 | +- `platforms = ["linux-64", "linux-aarch64", "osx-arm64"]` |
| 8 | +- `channels = ["conda-forge", "https://conda.modular.com/max"]` |
| 9 | +- `name = "mojo-*"` (per-repository) |
| 10 | +- `MOJO_PATH` is set via activation to `$PIXI_PROJECT_ROOT/src` so `mojo -I src` works consistently. |
| 11 | + |
| 12 | +## Core tasks |
| 13 | + |
| 14 | +### Development |
| 15 | + |
| 16 | +- `mojo-version` – prints the Mojo compiler version available in the pixi environment. |
| 17 | + |
| 18 | +### Tests |
| 19 | + |
| 20 | +- `test-all` runs `python scripts/run_tests.py`. |
| 21 | +- The Python runner: |
| 22 | + - auto-discovers `tests/test_*.mojo` files, |
| 23 | + - runs each with `mojo -I src`, and |
| 24 | + - reports a summary at the end. |
| 25 | + |
| 26 | +Individual `test-*` tasks may exist for focused development, but `test-all` is the canonical entry point and is what pre-submit uses. |
| 27 | + |
| 28 | +### Build |
| 29 | + |
| 30 | +- `build-package` runs `mojo package` to produce a `.mojopkg` artefact under `dist/`. |
| 31 | +- `clean` removes build and test artefacts (`dist`, `__pycache__`, `.pytest_cache`, and the local `.mojopkg` file). |
| 32 | + |
| 33 | +### Code quality |
| 34 | + |
| 35 | +- `pre-commit` – runs all pre-commit hooks for this repository. |
| 36 | +- `pre-commit-install` – installs the git hooks for local development. |
| 37 | + |
| 38 | +### Pre-submit for modular-community |
| 39 | + |
| 40 | +There are two equivalent tasks: |
| 41 | + |
| 42 | +- `pre-submit` |
| 43 | +- `pre-submit-modular-community` |
| 44 | + |
| 45 | +Both run `python scripts/pre_submit_checklist.py`, which performs: |
| 46 | + |
| 47 | +1. **Tests** – `pixi run test-all` for the full test suite. |
| 48 | +2. **Recipe validation** – `./scripts/validate-recipe.sh recipe.yaml` against the modular-community schema. |
| 49 | +3. **Package build** – `./scripts/build-recipe.sh`, using `rattler-build` with tests disabled (tests are already covered by `test-all`). |
| 50 | +4. **Git tag check** – ensures a `v<version>` tag exists and matches `HEAD`. |
| 51 | +5. **Install check** – creates a temporary pixi project, adds a file:// channel pointing at `output/`, and verifies that the built package can be installed and that the expected files appear under `.pixi/envs/default/lib/mojo`. |
| 52 | +6. **Optional modular-community build** – when invoked with `--modular-community` (or when the environment is configured accordingly), runs `pixi run build-all` in a local clone of the `modular-community` repository to mirror CI behaviour. |
| 53 | + |
| 54 | +The script prints a summary of all checks and a short list of next steps (push tag, update modular-community recipe, trigger CI) when everything passes. |
| 55 | + |
| 56 | +## Core dependencies |
| 57 | + |
| 58 | +The shared core dependencies across the `mojo-*` libraries are: |
| 59 | + |
| 60 | +- `max` – the Modular toolchain (`">=25.7.0,<26"`). |
| 61 | +- `python` – used for the test runner, benchmarks, and pre-submit tooling (`">=3.11,<4"`). |
| 62 | +- `pre-commit` – for local code quality checks (`">=4.5.1,<5"`). |
| 63 | +- `rattler-build` – for building conda packages (`">=0.55.1,<0.56"`). |
| 64 | + |
| 65 | +Each repository may add extra dependencies (for example benchmark counterparts such as `asciichartpy`, `python-dotenv`, `pyyaml`, or `tomli-w`) but the core tooling above is consistent. |
| 66 | + |
| 67 | +## Relationship to modular-community |
| 68 | + |
| 69 | +- The `pre-submit` / `pre-submit-modular-community` task is designed as a local analogue of the modular-community CI pipeline. |
| 70 | +- A successful run means: |
| 71 | + - tests pass, |
| 72 | + - the recipe is structurally valid, |
| 73 | + - the package can be built locally with `rattler-build`, |
| 74 | + - the git tag and version are aligned, and |
| 75 | + - the built artefact can be installed into a fresh environment. |
| 76 | +- When the optional modular-community step is enabled, the same `build-all` pipeline that CI uses will be exercised locally, reducing surprises when opening or updating a recipe PR. |
| 77 | + |
| 78 | +This document should stay in sync with the `pixi.toml` and `scripts/pre_submit_checklist.py` files; when those change in a material way, please update this file as part of the same change set. |
0 commit comments