Skip to content

lockfile-format.md

Latest commit

 

History

History
101 lines (76 loc) · 3.79 KB

lockfile-format.md

File metadata and controls

101 lines (76 loc) · 3.79 KB

sgl.lock format (story 6b-13)

Reproducible builds need a lockfile: a record of exactly which version of every dependency was resolved when the build last succeeded. This document is the format spec and the v1.0 status.

Status

Path-only at 1.0. sgl add <name> --path <local> (story 6b-11) ships in v1.0; that's enough to compose multi-package Silicon projects on a single machine.

Git- and registry-backed deps (6b-12) require a registry / index. Once those are in flight, sgl.lock graduates from "format spec + stub generator" to "always-emitted, CI-checked artefact." Format is locked now so v1.x users see no churn when the resolver lands.

File layout

sgl.lock lives next to sgl.toml in the project root. It is machine-generated; commit it. Format: TOML.

# sgl.lock — generated by `sgl resolve`.  DO NOT edit by hand.
# Edit sgl.toml instead and re-run `sgl resolve`.

version = 1                   # lockfile format version, not the project version

[[package]]
name        = "scratch"        # the root project
version     = "0.0.1"
dependencies = ["helper"]

[[package]]
name        = "helper"
version     = "0.4.2"
source      = "path:../helper"  # at 1.0: only path: sources
# sha256 = "…"                  # registry+git deps add this in v1.x

Required fields per [[package]] entry:

Field Required? At 1.0 v1.x
name yes string string
version yes from the dep's sgl.toml from the dep's sgl.toml
source yes path:<rel> only path:, git:<url>#<sha>, registry:<name>:<version>
dependencies no array of names (resolved DAG) same
sha256 no absent (path sources have none) required for git: and registry:
checksum_algo no absent reserved; only sha256 defined at v1.x

[[package]] entries are sorted alphabetically by name so the file is diff-stable.

Resolution semantics

  • The root project's sgl.toml entries seed the resolution.
  • For each name = "path:<rel>" declaration, the resolver reads the pointee's sgl.toml, recursively.
  • Cycles error (sgl resolve: dependency cycle: a → b → a).
  • Conflicting versions of the same name error at 1.0; v1.x adds semver-aware deduplication.

CLI surface

Command Status Effect
sgl add <name> --path <rel> 1.0 Adds entry to [dependencies] in sgl.toml
sgl add <name> rejects with pointer to --path Registry resolution pending 6b-12
sgl resolve stub at 1.0 Generates sgl.lock from current sgl.toml
sgl install v1.x Fetches git / registry sources; path sources are no-ops
sgl update [name] v1.x Bumps within semver constraints

sgl resolve exists as a stub at 1.0 (writes a version = 1 file and the root-package entry) so projects can wire CI lockfile-up-to-date checks before v1.x adds the full resolver.

Why TOML

  • Already the format of sgl.toml; consistent reader/writer.
  • Human-readable diffs are crucial for review.
  • Reserved-comment header tells humans not to edit; tools enforce it.

Why version field

The version = 1 header lets v1.x evolve the format. A lockfile written by v1.0 with version = 1 is read forward; a v1.x lockfile with version = 2 makes v1.0 print a clean upgrade message rather than silently mis-parse.

What this is NOT

  • Not a package-resolution algorithm spec — that's part of 6b-12.
  • Not a build-cache description — Sigil's build is fast enough at 1.0 that an artefact cache is post-1.0 work.
  • Not an integrity-attestation format — sha256 is a v1.x field with registry/git sources; path sources don't carry one because path sources are by definition local.

See docs/v1.1-user-stories.html for the v1.x registry + resolver work that fills in the gaps above.