Mache

User's guide

• Quick Start
  • Installing mache
  • Example usage
  • Public Functions
  • JIGSAW note
• Deploying target software
  • What mache deploy gives you
  • Add deploy support to a downstream package
  • What belongs in deploy/
  • Adding a custom CLI flag
  • The three deployment phases
  • The command-line contract
  • Updating a target repository to a new mache version
  • Troubleshooting
• JIGSAW
  • When ./deploy.py installs JIGSAW automatically
  • Installing JIGSAW into an existing environment
  • Pixi workflow
  • Conda workflow
  • The build cache
  • Source requirements
  • Troubleshooting
• Parallel execution with mache.parallel
  • Typical downstream workflow
  • Example: build a launcher command
  • GPU-per-task flags
  • Hyperthreading
  • Using this in generated job scripts
  • Slurm distribution options
  • Selecting scheduler options by node count
  • Requesting a specific queue, partition or QOS
  • Requesting a target without naming its axis
  • Wall-clock limits that depend on job size
• Building and Using Spack Environments with mache.spack
  • Overview
  • make_spack_env
  • get_spack_script
  • get_modules_env_vars_and_mpi_compilers
  • Example: How Downstream Packages Use These Functions
  • Notes
• Synchronize diagnostics between machines (mache sync diags)
  • Prerequisites
  • Recommended workflow
  • Command reference
  • Troubleshooting

Developer's guide

• Quick Start for Developers
  • Setting up for Development
  • Code Styling and Linting
  • Running Tests
  • Contributing
• Contributing to mache
  • How to Contribute
  • Development Environment
  • Code Style and Linting
  • Testing
  • Documentation
  • Pull Request Checklist
• mache.deploy developer guide
  • Goals and boundaries
  • Module layout
  • Template lifecycle
  • Why the double-template files exist
  • Which files are target-owned versus generated
  • The command-line contract from the maintainer side
  • Changing starter-kit generation
  • Changing runtime deployment behavior
  • Public API surface to keep documented
  • Recommended checklist for mache.deploy changes
• Automated config_machines.xml updates
  • Goal
  • Pieces of the automation
  • How config_machines.xml gets updated
  • What Copilot is told to do
  • Why this does not create a new issue every day
  • Reviewer workflow
  • Manual dry run for maintainers
  • Operational notes
• Adding a New Machine to Mache
  • Adding a new config file
  • Adding the new machine to discover.py
• Adding Spack Support for a New Machine
  • Overview
  • YAML Template Files
  • Automatic shell script generation (preferred)
  • Testing
  • Further Reading
• JIGSAW integration
  • Responsibilities
  • Relationship to mache.deploy
  • Module layout
  • Build and install pipeline
  • Backend-specific notes
  • Changing behavior safely
• Building the Documentation
• Previewing the Documentation
• Releasing a New Version
  • Building the Conda Package Locally with Rattler Build
  • Version Bump and Dependency Updates
  • Tagging and Publishing a Release Candidate
  • Updating the conda-forge Feedstock for a Release Candidate
  • Releasing a Stable Version
  • Updating the conda-forge Feedstock for a Stable Release
  • Post Release Actions
• API reference
  • discover
  • permissions
  • parallel
  • spack
  • sync
  • jigsaw
  • deploy
  • MachineInfo

Design documents

• Design Document: mache.deploy
  • Summary
  • Requirements
  • Conceptual Design
  • CLI Design and Sharing
  • Starter Templates and Initialization
  • Package Organization
  • Closing Notes
  • Testing