Path Resolution Rules

Keep paths predictable and portable by using placeholders and letting BPM resolve them.

Base Directory

  • Project mode: base is ctx.project_dir (from project.yaml:project_path).
  • Ad‑hoc mode: base is --out (no project changes; writes bpm.meta.yaml).

All renders go to: target = base / render.into after placeholder expansion, then normalized to an absolute path.

Placeholders in render.into

  • Use ${ctx.project.name}, ${ctx.template.id} and other ctx.* values.
  • Default pattern (if omitted): ${ctx.project.name}/${ctx.template.id}/.
  • Examples:
    • ${ctx.project.name}/${ctx.template.id}/ → 250903_TEST/hello/
    • results/${ctx.template.id} → results/hello

Examples (project mode)

Assume project_path=/abs/250903_TEST, name=250903_TEST, and template id hello.

  • render.into: "${ctx.project.name}/${ctx.template.id}/"
    • Resolves to /abs/250903_TEST/250903_TEST/hello/
  • render.into: "results/${ctx.template.id}"
    • Resolves to /abs/250903_TEST/results/hello
  • render.into: "."
    • Resolves to /abs/250903_TEST

Ad‑hoc mode (--out /tmp/out): treat paths relative to /tmp/out unless you use an absolute path.

Relative vs Absolute

  • Prefer relative render.into paths so templates work everywhere.
  • Absolute paths (e.g., /scratch/run1) are respected but reduce portability.
  • Avoid .. segments; BPM resolves the path, but leaving the project/out directory is discouraged.

Cross‑platform Tips

  • Use forward slashes in templates; Python normalizes them on Windows/Unix.
  • Don’t hard‑code drive letters or home shortcuts; prefer placeholders and relative paths.

Run Working Directory

  • bpm template run changes into the resolved render.into directory and executes run.entry there.
  • Inside scripts, prefer relative paths to the working directory, or use `` for absolute project references.

Quick Checklist

  • Keep render.into relative; rely on placeholders.
  • Include ${ctx.template.id} to avoid collisions between templates.
  • Use stable, filesystem‑safe names (see Naming & IDs).
  • In ad‑hoc mode, pass --out instead of embedding absolute locations.