JIGSAW integration

This page covers the developer-facing layout of mache.jigsaw and the points where it interacts with mache.deploy.

For downstream target-software usage, see the user’s guide pages on deploy and JIGSAW.

Responsibilities

mache.jigsaw has two distinct jobs:

  1. Build a local conda package for jigsawpy and the bundled JIGSAW library.

  2. Install that package into either a pixi environment or a conda environment.

The top-level orchestration entry point is mache.jigsaw.deploy_jigsawpy(). That function resolves the backend, builds the local package channel if needed, and installs jigsawpy into the target environment.

Relationship to mache.deploy

mache.deploy.run.run_deploy() can invoke JIGSAW automatically when a target repository enables it in deploy/config.yaml.j2:

jigsaw:
  enabled: true
  jigsaw_python_path: jigsaw-python

At runtime, mache deploy run:

  1. Creates the base pixi environment from deploy/pixi.toml.j2.

  2. Calls deploy_jigsawpy() with backend="pixi".

  3. Targets the generated pixi manifest at <prefix>/pixi.toml.

  4. Continues with any Spack and load-script work.

That means changes in mache.jigsaw can affect both direct mache jigsaw install usage and downstream ./deploy.py workflows.

Module layout

mache/jigsaw/cli.py

Thin CLI wiring for mache jigsaw install. Keep this file limited to argument parsing and dispatch.

mache/jigsaw/__init__.py

Implementation module for build, cache, pixi install, and conda install logic.

The public API is documented in the API reference.

Build and install pipeline

The normal call graph is:

  1. deploy_jigsawpy()

  2. detect_install_backend()

  3. build_jigsawpy_package()

  4. install_jigsawpy_package()

The build step:

  • Ensures jigsaw-python source is available, cloning it when necessary.

  • Computes a cache key from the source tree and selected Python/platform.

  • Reuses cached output under .mache_cache/jigsaw when valid.

  • Runs rattler-build through pixi or conda, depending on the selected backend.

The install step:

  • Uses pixi when the backend resolves to pixi.

  • Uses conda when the backend resolves to conda.

  • Accepts explicit backend selection or auto detection.

Backend-specific notes

Pixi

The pixi install path can either mutate a chosen manifest directly or work through a local copied manifest under .mache_cache/jigsaw/pixi-local.

The local-manifest path exists to avoid source-controlled manifest changes and to isolate JIGSAW from unrelated pixi environments when a project defines multiple features or Python variants.

Conda

The conda install path resolves conda and CONDA_PREFIX, ensures a local channel is available, and installs jigsawpy directly into the active or requested prefix.

Changing behavior safely

When changing mache.jigsaw, keep these contracts aligned:

  1. The user’s guide examples for mache jigsaw install.

  2. The jigsaw section consumed by mache.deploy.run.

  3. The generated runtime behavior of downstream ./deploy.py flows.

  4. The public API documented on API reference.

In practice, that usually means updating both the relevant code and the downstream-facing docs whenever backend detection, cache semantics, or pixi manifest mutation rules change.