ADR-0001: Embed templates in the binary at compile time

  • Status: Accepted
  • Date: 2026-06-02
  • Deciders: DecisionNerd (maintainer)

Context

DocSlime’s job is to write a tree of Markdown templates into a user’s repo. Those templates have to reach the user’s machine somehow. The tool’s requirements call for a portable, zero-runtime-dependency binary that works offline (NFR-1, FR-7) and installs cleanly via Homebrew, a shell script, or cargo install (NFR-3). Whatever mechanism delivers the templates must not require the user to also have a separate templates directory present, or network access, at runtime.

Options considered

Option A — Embed templates in the binary at compile time

  • Pros: Single self-contained artifact; works offline; nothing to locate or install alongside the binary; trivial to distribute via Homebrew / shell installer / cargo install.
  • Cons: Editing a template requires recompiling and re-releasing; templates can’t be customized by the user without a rebuild.

Option B — Ship templates as separate data files installed next to the binary

  • Pros: Templates editable in place; could allow user overrides without recompiling.
  • Cons: Must reliably locate the data directory across platforms and install methods; packaging is more complex; risk of the binary and its templates getting out of sync or the data files going missing.

Option C — Fetch templates from a remote source at runtime

  • Pros: Templates updatable without releasing a new binary.
  • Cons: Requires network access (violates the offline requirement); adds latency and a failure mode; introduces a hosting dependency for a tool that should be instant and local.

Decision

We will embed the entire template tree in the binary at compile time, using include_dir! for the init tree and include_str! for the standalone ADR template. This makes DocSlime a single self-contained binary with no runtime dependencies, satisfying the portability, offline, and distribution requirements directly.

Consequences

  • Positive: DocSlime ships as one artifact that runs anywhere with no setup, no network, and nothing to locate at runtime — which keeps installation and usage friction low.
  • Negative: Any template change requires recompiling and cutting a new release; users cannot customize the templates without rebuilding from source.
  • Follow-up: If user-customizable layouts become a requirement (tracked as an open question in ../../REQUIREMENTS.md), revisit with a new ADR that supersedes this one — e.g. allowing an external template directory to override the embedded default.
Next Overview