config.yaml.j2.j2

project:
  software: "[[ software ]]"
  # A specific version string or "dynamic" if provided by the "pre_pixi" hook.
  version: "dynamic"

  # Optional: a command that prints the *runtime* version string for the
  # deployed software.
  #
  # This command is run via `pixi run -m <pixi.toml> -- bash -c <cmd>` *before*
  # the load script activates the environment, so it can safely `return` on
  # mismatch without changing your shell environment.
  #
  # The command should print a single version string on stdout that matches
  # `project.version` exactly.
  #
  # Examples:
  #   runtime_version_cmd: "python -c 'import importlib.metadata as m; print(m.version(\"mache\"))'"
  #   runtime_version_cmd: "e3sm_diags --version"
  runtime_version_cmd: null

  # Optional: value exported as <SOFTWARE>_BRANCH by the generated load script.
  #
  # Default behavior when this key is omitted entirely is to preserve the
  # legacy export of the target repository root for downstream compatibility.
  #
  # Set to:
  #   - null to suppress the export entirely
  #   - an explicit shared path to export a different location
  branch_path: null

  # Machine name selection.
  # Priority order in `mache deploy run`:
  #   1. CLI --machine
  #   2. this value (project.machine)
  #   3. automatic detection (if this is "dynamic")
  machine: "dynamic"

machines:
  # Optional path containing machine config files in ini format.
  #
  # This MUST be a filesystem path (not a Python package) because we need to
  # read machine configs before the target software (and its dependencies)
  # have been installed into the pixi environment.
  #
  # Should be a relative path, relative to the target software repo root.
  #
  # Files should be named like "<machine>.cfg" (e.g. "chrysalis.cfg").
  #
  # Machine config is loaded in this order:
  #   1. mache.machines/default.cfg
  #   2. mache.machines/<machine>.cfg (if a known machine is selected)
  #   3. <machines.path>/default.cfg (if machines.path is set)
  #   4. <machines.path>/<machine>.cfg (if present)
  path: null

pixi:
  # Whether to deploy the pixi environment
  deploy: true

  # Where to install the pixi project (and its .pixi directory).
  # Absolute path is recommended for shared deployments.
  # Environment variables will be expanded at runtime (e.g. $SCRATCH).
  prefix: pixi-env

  # Optional: how generated load scripts should find the pixi executable.
  #
  # Supported values:
  #   - omitted: preserve the legacy behavior and embed the pixi path passed
  #     to `mache deploy run` (mainly for backward compatibility)
  #   - shared: copy pixi into the deployed prefix/prefixes and use that
  #   - null (or "path"): use $PIXI or `pixi` on PATH at load-script runtime
  #   - /explicit/path/to/pixi: use that path in the generated load script
  #
  # New templates default to `null` so per-user deployments pick up each
  # user's own pixi install unless a downstream opts into another mode.
  load_script_exe: null

  # Channels used by pixi for this environment.
  channels:
    - conda-forge

  # MPI provider for conda packages.
  # Supported values in `mache deploy run`:
  #   - null if MPI is not used in the target software
  #   - nompi
  #   - mpich
  #   - openmpi
  #   - hpc (E3SM-Unified only)
  #   - dynamic (determine by the "pre_pixi" hook)
  mpi: nompi

  # Optional alternate MPI provider for login nodes.
  #
  # If set, mache may deploy a second pixi environment for login-node use and
  # the generated load script will auto-select between login and compute
  # environments based on common batch-job environment variables.
  login_mpi: null

  # Optional install location for the login-node pixi environment.
  #
  # Default behavior:
  #   - same as `prefix` if login_mpi resolves to the same MPI as `mpi`
  #   - otherwise `<prefix>_login`
  login_prefix: null

  # Whether to install the target software in editable/development mode.
  install_dev_software: false

# System toolchain selection (primarily for Spack-based dependencies).
#
# These values are resolved in `mache deploy run` with the following priority:
#   1. CLI flags: --compiler / --mpi
#   2. Values here
#   3. Machine config defaults from [deploy] in merged machine config:
#        compiler = <name>
#        mpi_<compiler> = <mpilib>
#
# Use "dynamic" to request defaults from machine config.
toolchain:
  # One or more compiler names. Examples:
  #   compiler: [gnu]
  #   compiler: [gnu, intel]
  #
  # If empty (or "dynamic"), defaults come from merged machine config:
  #   [deploy] compiler
  compiler: []

  # One or more MPI libraries. Examples:
  #   mpi: [openmpi]
  #   mpi: [mpich, openmpi]
  #
  # Pairing rules in `mache deploy run`:
  #   - If both lists have the same length, they are zipped.
  #   - If one list has length 1, it is broadcast across the other.
  #   - If mpi is empty (or "dynamic"), defaults come from machine config:
  #       [deploy] mpi_<compiler> (preferred)
  #       [deploy] mpi (fallback)
  mpi: []

env_vars:
  # Placeholder: env vars to export in the "load" script
  set: {}

permissions:
  # Optional shared-filesystem permission policy applied after a successful
  # deployment.
  #
  # Priority order in `mache deploy run`:
  #   1. Hook/runtime overrides:
  #        ctx.runtime["permissions"]["group"]
  #        ctx.runtime["permissions"]["world_readable"]
  #   2. Values here
  #   3. Machine config defaults from [deploy]:
  #        group = <unix-group>
  #        world_readable = true|false
  #
  # If no group is resolved, mache skips the permission update step.
  group: null

  # Whether deployed files should be readable by users outside the shared
  # group. Directories keep execute permission when needed for traversal.
  world_readable: true

spack:
  # Whether to deploy Spack environments at all.
  #
  # Behavior:
  #   - If true, deploy ALL supported Spack environments.
  #   - If false, deploy none.
  #
  # This can be forced on at runtime with the `mache deploy run` CLI flag:
  #   --deploy-spack
  #
  # Passing --no-spack disables all Spack use for a single run, including
  # reuse of pre-existing environments for load scripts.
  deploy: false

  # Whether this target repository supports a Spack *library* environment.
  #
  # If true, mache will deploy one library env per toolchain pair.
  supported: false

  # Optional: deploy an additional "software" spack environment.
  #
  # This environment is built once (not per toolchain) with a single compiler
  # and MPI from the merged machine config:
  #   [deploy] software_compiler
  #   [deploy] mpi_<software_compiler>
  #
  # Load scripts do NOT activate this environment; they add its view's `bin`
  # directory to PATH.
  software:
    # Whether this target repository supports a Spack *software* environment.
    supported: false

    # Optional override for the environment name.
    # Default: "<software>_software"
    env_name: null

  # Base path for the spack checkout used for deployment.
  # If it does not exist, mache will clone the E3SM spack repo.
  #
  # In practice, most target repositories should set this dynamically in the
  # `pre_spack()` hook (e.g., based on machine config) by writing:
  #   ctx.runtime['spack']['spack_path'] = <path>
  # Hooks may also disable Spack for a single run by returning:
  #   ctx.runtime['spack']['supported'] = False
  #   ctx.runtime['spack']['software']['supported'] = False
  # This config value is a fallback.
  #
  # Required (either via hook/runtime or here) when spack.deploy (or
  # --deploy-spack) is used and at least one supported spack environment is
  # enabled, or when an existing Spack environment will be reused for load
  # scripts.
  # Can also be overridden temporarily via: --spack-path <path>
  # To bypass Spack entirely for one run, pass: --no-spack
  spack_path: null

  # Prefix for spack environment names.
  # Final env name is computed as: "<env_name_prefix>_<compiler>_<mpi>".
  env_name_prefix: "spack_env"

  # Jinja2-templated YAML file in the target repo containing a YAML list of
  # spack specs. This is inserted into the appropriate mache spack env
  # template for the selected machine/compiler/mpi.
  #
  # Expected format: a YAML mapping with keys "library" and/or "software",
  # each containing a list of spec strings.
  specs_template: "deploy/spack.yaml.j2"

  # Optional list of machine-provided Spack packages to suppress so Spack can
  # build them instead.
  #
  # Typical examples:
  #   exclude_packages:
  #     - cmake
  #
  # To opt out of the machine-provided HDF5/NetCDF bundle, prefer:
  #   exclude_packages:
  #     - hdf5_netcdf
  #
  # In some target repositories, this list is set dynamically in `pre_spack()`
  # based on merged machine config, for example when [deploy]
  # use_e3sm_hdf5_netcdf = false should map to excluding the bundle.
  exclude_packages: []

  # Optional spack build settings
  tmpdir: null
  mirror: null
  custom_spack: ""

jigsaw:
  # If true, build/install JIGSAW + JIGSAW-Python into the pixi env
  enabled: false

  # Relative path in the target repo where JIGSAW-Python lives.
  # If this is a submodule, `mache deploy run` will initialize it.
  # If it is not, `mache deploy run` will clone it from the main JIGSAW-Python
  # repo if missing.
  jigsaw_python_path: jigsaw-python

# Optional deployment hooks.
#
# Hooks run ONLY during `mache deploy run` and execute arbitrary Python code
# from the target repository. Use only with trusted repositories.
# Custom CLI flags from deploy/custom_cli_spec.json are available on ctx.args
# inside hooks when routed to "run".
#
# hooks:
#   file: "deploy/hooks.py"   # default
#   entrypoints:
#     pre_pixi: "pre_pixi"        # optional
#     post_pixi: "post_pixi"      # optional
#     pre_spack: "pre_spack"      # optional
#     post_spack: "post_spack"    # optional
#     post_deploy: "post_deploy"  # optional