Projects

A project is a directory with a sprig.toml manifest. Single-file mode is available: explicit files outside a project source root bypass the manifest; files inside that root retain its dependency graph and require a current lock.

Layout and defaults

project/
├── sprig.toml
├── src/
│   └── main.spr
└── build/

[project]
name = "hello"
version = "0.1.0"
language = "0.8"

source defaults to src and entry to src/main.spr; both can be overridden in [project]. Package identity comes from the manifest — Sprig source files do not declare package.

Creating and inspecting

sprig init          # creates sprig.toml and src/main.spr, never overwriting
sprig project       # human-readable summary
sprig project --json

project --json reports root, name, version, language, source root, entry, binaries, exports, manifest and lockfile paths, lock status and declared dependencies, so agents do not have to parse TOML themselves.

Running a project

sprig check         # checks the project entry
sprig build
sprig run
sprig run --bin server
sprig run path/to/file.spr   # explicit file always wins over discovery
sprig test                   # ordinary programs under tests/

Discovery walks upward from the current directory. [[bin]] declares named entries:

[[bin]]
name = "server"
entry = "src/server.spr"

The Beta SDK's sprig test uses the same locked dependencies and checks expected compile failures by diagnostic code; see the testing contract.

Dependencies

Local and Git Sprig dependencies resolve for real. Edit sprig.toml, then run sprig resolve:

[[dependency]]
name = "math"
path = "../math"

[[dependency]]
name = "math"
git = "https://example.com/math.git"
branch = "main"

• Schema 5 identifies edges as root/@a/@util and records owner-relative locators for relative local dependencies (portable = true, the whole workspace can move); absolute declarations keep portable = false. Schemas 1–4 require explicit resolve. The lock checks compiler identity; bundled @std comes from the installed SDK and is not recorded in the project lock.
• Real paths confine symlinks; exported internal symlinks are allowed.
• Git cache reuse validates HEAD, marker and tracked/untracked contents; tampering fails.
• name is the package-local import alias; distinct packages may reuse it; the dependency's own [project] name is separate identity metadata.
• sprig resolve writes a deterministic sprig.lock (commit it). check, build and run refuse a missing or stale lock and never move a Git branch themselves — only resolve does.
• A Git dependency is locked to an exact commit SHA; a later branch move does not change a locked build.
• Import exported modules with import "@math/vector.spr" as vector. Only modules listed in the dependency's exports are importable; paths are canonicalized and cannot escape the dependency source root.
• --offline uses the Git cache only (~/.sprig/git); a missing cached revision fails with SPR-DEP-OFFLINE.
• Cycles and duplicate aliases are rejected with structured diagnostics.

Maven/JVM dependencies are implemented. Declare exact release coordinates in [[jvm]], run resolve, then use check/build/run/api/doctor without manually locating JARs. Apache Resolver handles parents/BOMs/transitives. Schema-5 locks record JAR/POM SHA-256, graph, order and local locators (owner-relative portable = true for relative declarations, canonical absolute with portable = false otherwise). Warm cache is required offline; consumers never re-resolve. See dependency contract.