Repository navigation
Releases: lukewilliamboswell/roc-blueprint
Release list
roc-blueprint 0.6.0-rc1
This release makes Nix one source among several. A Blueprint.roc now says
where each thing comes from: a program downloaded from a URL and checked
against a digest in Blueprint.lock, a tool the machine already has, or a
tool from a Nix package source the project declares. blueprint starts Nix
only for an environment that has a tool from a Nix source, and for a build.
A project that fetches its compiler and expects git runs its tasks with no
Nix installed.
That matters most in CI. A job that ran one Roc script through blueprint
spent about 40 seconds on Nix before the script started. The same task in a
project with no Nix source takes 3 to 7 seconds on an empty cache and under a
second after that, measured on x86_64 Linux.
Every Blueprint.roc written for 0.5 must be edited, and its lock resolved
again. "If you used 0.5", below, has the steps.
Use this release
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.6.0-rc1/UMnTgKxbYavSsoeQUGPM7Vde2WHEFzES2VaFcX1qtYj.tar.zst" }The blueprint binary is attached for x86_64 Linux, arm64 Linux and Apple
Silicon macOS, with SHA-256 sums in blueprint.sha256. It needs no Roc: it
downloads the compiler that reads Blueprint.roc into its own store and
checks it against a digest it records. It needs Nix only for what a project
takes from Nix. Use this release's binary with this release's platform URL.
Fetch a program
Fetch inside Programs puts a downloaded program on an environment's
PATH. A recipe, a function from the system to a download, says where it
comes from; Blueprint.lock holds its SHA-256 and length for every declared
system.
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.6.0-rc1/UMnTgKxbYavSsoeQUGPM7Vde2WHEFzES2VaFcX1qtYj.tar.zst" }
import pf.Recipes
config = [
Name("my-package"),
Environment("dev", [
Programs([
Fetch("roc-stable", Recipes.roc_nightly("nightly-2026-10-13-b17d287")),
Fetch("blueprint-0-5", Recipes.file("https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.5.0/blueprint-{system}")),
]),
]),
Task("check", [Use("dev"), Run(["roc-stable", "check", "main.roc"])]),
]Recipes.roc_nightly(tag)is the Roc compiler of one release of
roc-lang/nightlies. When the tag is the nightlyblueprintitself runs on,
one download serves both.Recipes.file(template)is a program that is one file, at a URL in which
{system},{arch}and{os}stand for the system.- A recipe of your own is an ordinary function,
System -> Config.Download,
that answersFile(url),Archive(url, TarGz | TarXz | Zip, path),
Mirrored(download, alternate_urls)orUnavailable. - A URL, the path inside an archive, a system and a nightly tag are each
checked where they are written, byroc check.
A download is kept in a per-user store, blueprint/ under XDG_CACHE_HOME or
~/.cache, and hashed again before every use. An archive is unpacked whole
and the command is a link into it.
Expect a tool on the machine
Expect names programs the machine must already have. blueprint looks for
them on PATH before it downloads or runs anything, names every one that is
missing in one message, and installs nothing.
Environment("dev", [
Expect(["git", "gh"]),
]),Name the source of every tool
A tool from a package source is written "<source>#<name>", and the source is
declared. There is no default source:
Packages("nix", From(NixPackages("github:NixOS/nixpkgs/nixos-unstable"))),
Environment("host", [Tools(["nix#zig", "nix#pkg-config"])]),Only an environment with such a tool starts Nix. Other tasks of the same
project run without it.
Update without Nix
blueprint update starts Nix only when Blueprint.roc declares something Nix
resolves: a Nix package source, an input, an overlay or a build source. A
project that declares none is updated on a machine with no Nix.
- For each fetched program it downloads and hashes this machine's file. When
the URL is a GitHub release asset it also asks the release, once and with
no token, what digest it publishes. The two must agree, and the published
digest is recorded for the other systems without downloading them. The lock
says how each digest was obtained:Computed,PublishedorBoth. - When GitHub cannot be asked, which its limit of 60 requests an hour from
one address makes common on shared CI runners, the update says so and
downloads and hashes the file for every system instead. blueprint update PROGRAMresolves one fetched program again and nothing
else, and never needs Nix.- After writing the lock it prints every download host the new lock names and
the old one did not.
Ask what tasks need
blueprint requirements [--json] [TASK...] reads Blueprint.roc alone and
says, for each task, whether it needs Nix, which programs it fetches and
which it expects of the machine. A CI job can install Nix exactly when it is
needed:
blueprint requirements --json check | jq -e '.providers | index("nix")'blueprint shell works without Nix too: for an environment with no Nix tool
it starts your own $SHELL with the fetched programs on PATH.
If you used 0.5
- Replace the platform URL in the
appheader with this release's, and use
this release'sblueprintbinary. - Declare a package source, and write its name before every tool:
"git"
becomes"nix#git", inTools,ToolsFor,CommandandToolWith. A
0.5 project that declared no source used
github:NixOS/nixpkgs/nixos-unstable; declare that to keep the same
packages. RemovePackages(name, Auto). - Or take the tool off Nix: move a program that is published as a download
toPrograms([Fetch(...)]), and a tool every machine has toExpect.
roc check Blueprint.rocreports each remaining tool with no source and
shows both ways out. - Run
blueprint updateand commit the newBlueprint.lock. A 0.5 lock is
refused until then. Read the diff: it gains afetchedentry for each
program and system. - In CI, install Nix only where
blueprint requirementssays a task needs
it, and cache thev1/artifactsdirectory of the store, keyed on
Blueprint.lock.
A pure package
Before, for 0.5:
config = [
Name("my-package"),
Overlay("roc", "github:roc-lang/roc-overlay"),
Environment("dev", [
Overlays(["roc"]),
Command("roc-stable", "rocpkgs.nightly-2026-10-13-b17d287"),
Tools(["git", "gh"]),
RocPackages([
"https://github.com/roc-lang/basic-cli/releases/download/0.26.0-rc2/Gj3zVDr3qrQa6aTh7Z1zgUfe9NeBE6R76T5ho3xrc8af.tar.zst",
"https://github.com/roc-lang/http/releases/download/1.0.0/6ZUwqYhCS8PU9Mo6MF7oV82ET2o7KYb57CLKDq4cq4sS.tar.zst",
]),
]),
Task("check", [Use("dev"), Run(["scripts/check_all.roc"])]),
]After. Nothing in it is Nix's, so no command starts Nix:
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.6.0-rc1/UMnTgKxbYavSsoeQUGPM7Vde2WHEFzES2VaFcX1qtYj.tar.zst" }
import pf.Recipes
config = [
Name("my-package"),
Environment("dev", [
Programs([Fetch("roc-stable", Recipes.roc_nightly("nightly-2026-10-13-b17d287"))]),
Expect(["git", "gh"]),
RocPackages([
"https://github.com/roc-lang/basic-cli/releases/download/0.26.0-rc2/Gj3zVDr3qrQa6aTh7Z1zgUfe9NeBE6R76T5ho3xrc8af.tar.zst",
"https://github.com/roc-lang/http/releases/download/1.0.0/6ZUwqYhCS8PU9Mo6MF7oV82ET2o7KYb57CLKDq4cq4sS.tar.zst",
]),
]),
Task("check", [Use("dev"), Run(["scripts/check_all.roc"])]),
]A platform with a Zig toolchain from Nix
Before, for 0.5:
config = [
Name("my-platform"),
Overlay("roc", "github:roc-lang/roc-overlay"),
Overlay("zig", "github:mitchellh/zig-overlay"),
Environment("dev", [
Overlays(["roc", "zig"]),
Command("roc-stable", "rocpkgs.nightly-2026-10-13-b17d287"),
Tools(["git", "zigpkgs.\"0.16.0\""]),
]),
Task("check", [Use("dev"), Run(["scripts/check_all.roc"])]),
Task("build-host", [Use("dev"), Run(["zig", "build"])]),
]After. The scripts' environment needs no Nix; the environment that builds the
host extends it and takes Zig from a declared source:
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.6.0-rc1/UMnTgKxbYavSsoeQUGPM7Vde2WHEFzES2VaFcX1qtYj.tar.zst" }
import pf.Recipes
config = [
Name("my-platform"),
Packages("nix", From(NixPackages("github:NixOS/nixpkgs/nixos-unstable"))),
Overlay("zig", "github:mitchellh/zig-overlay"),
Environment("dev", [
Programs([Fetch("roc-stable", Recipes.roc_nightly("nightly-2026-10-13-b17d287"))]),
Expect(["git"]),
]),
Environment("host", [
Extend("dev"),
Overlays(["zig"]),
Tools(["nix#zigpkgs.\"0.16.0\""]),
]),
Task("check", [Use("dev"), Run(["scripts/check_all.roc"])]),
Task("build-host", [Use("host"), Run(["zig", "build"])]),
]blueprint update needs Nix in this project, because it declares a Nix
source. After it, blueprint run check starts no Nix and
blueprint run build-host does.
Breaking changes
- Every tool names its source. A tool is
"<source>#<name>"inTools,
ToolsFor,CommandandToolWith."git"alone is an error at the
literal, with both fixes in the message. - No default source and no
Auto.Packages(name, Auto)is refused, and a
project that declares no source has none. A project with no tool from a
package source declares none. - The first declared Nix source has the roles
defaulthad. An
environment Nix must build although it has no tool of its own, such as the
sandbox of a build with an empty environment, uses the first Nix source in
the order ofBlueprint.roc. So does thenixpkgsinput the generated
flake givesnix developfor its bash. A source calleddefaultis no
longer preferred for either. - *
Systemsaccepts known system...
roc-blueprint 0.5.0
This release puts everything a project needs in one place: the platform, the
core package it depends on and the blueprint binaries are now published
together under one version. It is also the first release with a manual and an
archive of the examples.
A Blueprint.roc written for 0.4 needs only the new platform URL.
Use this release
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.5.0/CupqPH9snWf11g7tWgcJf4Yg5cJ3K9fhL7fSgqDcqJQH.tar.zst" }The blueprint binary is attached for x86_64 Linux, arm64 Linux and Apple
Silicon macOS, with SHA-256 sums in blueprint.sha256. It needs Nix, and
fetches its own Roc compiler through Nix. Use this release's binary with this
release's platform URL.
The core package moves into this release
roc-blueprint-core, the package that defines the Spec and its S-expression
format, used to have releases of its own under core-X.Y.Z tags. It is now an
asset of each roc-blueprint release:
core: "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.5.0/roc-blueprint-core-3AUcy5rhahtfyWxW6KBonhobWR4N7pzz2KCJzDes1TQN.tar.zst"A program that imports the core package must change its URL to this form. Roc
identifies a package by its URL, so this is a different package from the one
under the core- tags, and the two cannot be mixed in one program. There will
be no further core-X.Y.Z releases.
Configure a tool
ToolWith adds a tool built with options its package takes. A platform host
that cross-compiles Rust can now declare its toolchain's targets and
components:
Overlay("rust", "github:oxalica/rust-overlay"),
Environment("host", [
Overlays(["rust"]),
ToolWith("rust-bin.stable.\"1.95.0\".default", [
("targets", List([Str("x86_64-unknown-linux-musl"), Str("aarch64-unknown-linux-musl")])),
("extensions", List([Str("rust-src")])),
]),
]),The options are data passed to the package's override, never an
expression. The Spec is now format 2.6, and a configuration that uses
ToolWith requires the feature configured-tools, which a blueprint older
than this release refuses by name.
Changes to the tool
blueprintwrites a.gitignoreinto the directory it generates
(.blueprint/unless you moved it), so generated state stays out of a
commit even when the repository's own.gitignoredoes not list it. A
directory that is already tracked stays tracked until you run
git rm -r --cached .blueprint.- On Intel macOS
blueprintnow stops with a message that names the supported
systems, where it used to fail inside Nix.x86_64-darwinremains a system
a configuration may list. nix run github:lukewilliamboswell/roc-blueprint/0.5.0works on arm64
Linux.- The code that will run tasks on Windows without Nix is included, but this
release has no Windows binary and its platform has no Windows target, so
Windows cannot use it yet.
Documentation and examples
- The project has a manual, published as a site and attached to this release
asroc-blueprint-0.5.0.pdf. The reference that was in the README is now
there. roc-blueprint-examples-0.5.0.zipholds the example projects with their
platform set to this release, and the Spec each one printed when the
release was made.roc-blueprint-docs-0.5.0.zipholds the rendered manual.
Built from
- Roc
nightly-2026-10-04-130536dand Zig0.16.0; release scripts run withroc-stableRoc compiler version nightly-2026-10-04-130536d - Compiler archives from roc-overlay
fb02fef7a45ddf115f558c8eaf32bd1ce2f9912f: x86_64-linuxsha256-iTyG0toKTDkMvb1CWM5F1obl7BW0Lu64Ef0axEU3cU8=, aarch64-darwinsha256-4BR/YvByowlRnLwqbr+hHku4useQPV/rr3oRLR/ChC8= - nixpkgs
6774f7bc253789b113a4f39285dc0fa100abeacc - roc-blueprint-core
https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.5.0/roc-blueprint-core-3AUcy5rhahtfyWxW6KBonhobWR4N7pzz2KCJzDes1TQN.tar.zst - Roc packages in the CLI: basic-cli 0.24.0
AEjfyaMFFbh8FJrkkHJy68riVNPr3Qp6c6PawWQjBwMH, http 1.0.06ZUwqYhCS8PU9Mo6MF7oV82ET2o7KYb57CLKDq4cq4sS, weaver 0.9.07j6KBFBEZ8pNMLQHkx9xiwyZ2PmwQPgKNDPUih6gKe77, roc-ansi 0.13.0JXLM47L6CzrLXB5HBfqc27VnU6CD4jMm5Mk6dgbbovL, path 4.0.07YfABZPwJAXtLBY2vm8FqMyGAtNxncCJ65HdNKHFGNnE - Linker inputs: roc-platform-template-zig release
link-inputs-sha256-2df3df339dfb1ad4ae1fad0f382cc100c5b31b3921cdeff939f6aea51457886d(link-inputs.lock.jsonsha25615dd986a3612502330528738395c1f612d2bc7538ef9a291c059dc16e523eb6e)
roc-blueprint 0.4.1
Platform (use in Blueprint.roc):
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.4.1/3Cev8eY9VdEbPazJcBUnsjNnUgdauMod46Q25uKodLUe.tar.zst" }The blueprint CLI is attached for x86_64 Linux, arm64 Linux and Apple Silicon macOS, with sha256 sums in blueprint.sha256. It needs Nix, and fetches its own Roc compiler through Nix. The platform supports x64musl, arm64musl, arm64mac and x64mac.
Built from:
- Roc
nightly-2026-10-04-130536dand Zig0.16.0 - Compiler archives from roc-overlay
fb02fef7a45ddf115f558c8eaf32bd1ce2f9912f: x86_64-linuxsha256-iTyG0toKTDkMvb1CWM5F1obl7BW0Lu64Ef0axEU3cU8=, aarch64-darwinsha256-4BR/YvByowlRnLwqbr+hHku4useQPV/rr3oRLR/ChC8= - nixpkgs
6774f7bc253789b113a4f39285dc0fa100abeacc - roc-blueprint-core
https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.1/DL8qEfetKXQkfGomAiy2HHj1WC4T4LQfxVFY4HaCXSqP.tar.zst - Roc packages in the CLI: basic-cli 0.24.0
AEjfyaMFFbh8FJrkkHJy68riVNPr3Qp6c6PawWQjBwMH, http 1.0.06ZUwqYhCS8PU9Mo6MF7oV82ET2o7KYb57CLKDq4cq4sS, weaver 0.9.07j6KBFBEZ8pNMLQHkx9xiwyZ2PmwQPgKNDPUih6gKe77, roc-ansi 0.13.0JXLM47L6CzrLXB5HBfqc27VnU6CD4jMm5Mk6dgbbovL, path 4.0.07YfABZPwJAXtLBY2vm8FqMyGAtNxncCJ65HdNKHFGNnE - Linker inputs: roc-platform-template-zig release
link-inputs-sha256-2df3df339dfb1ad4ae1fad0f382cc100c5b31b3921cdeff939f6aea51457886d(link-inputs.lock.jsonsha25615dd986a3612502330528738395c1f612d2bc7538ef9a291c059dc16e523eb6e)
roc-blueprint-core 0.4.1
The blueprint Spec and its S-expression format.
core: "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.1/DL8qEfetKXQkfGomAiy2HHj1WC4T4LQfxVFY4HaCXSqP.tar.zst"Built with Roc nightly-2026-10-04-130536d.
roc-blueprint 0.4.0
Platform (use in Blueprint.roc):
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.4.0/4jmnCGtQeuXTJJYc1rPrnA1pQFPRqUecY5oau1te8cYn.tar.zst" }The blueprint CLI is attached for x86_64 Linux, arm64 Linux and Apple Silicon macOS, with sha256 sums in blueprint.sha256. It needs Nix, and fetches its own Roc compiler through Nix. The platform supports x64musl, arm64musl, arm64mac and x64mac.
Built from:
- Roc
nightly-2026-10-04-130536dand Zig0.16.0 - Compiler archives from roc-overlay
fb02fef7a45ddf115f558c8eaf32bd1ce2f9912f: x86_64-linuxsha256-iTyG0toKTDkMvb1CWM5F1obl7BW0Lu64Ef0axEU3cU8=, aarch64-darwinsha256-4BR/YvByowlRnLwqbr+hHku4useQPV/rr3oRLR/ChC8= - nixpkgs
6774f7bc253789b113a4f39285dc0fa100abeacc - roc-blueprint-core
https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.0/915JXd6z7anN5SZ4xurPAnJnKT4VQ9dd7CtYajyh9GKV.tar.zst - Roc packages in the CLI: basic-cli 0.24.0
AEjfyaMFFbh8FJrkkHJy68riVNPr3Qp6c6PawWQjBwMH, http 1.0.06ZUwqYhCS8PU9Mo6MF7oV82ET2o7KYb57CLKDq4cq4sS, weaver 0.9.07j6KBFBEZ8pNMLQHkx9xiwyZ2PmwQPgKNDPUih6gKe77, roc-ansi 0.13.0JXLM47L6CzrLXB5HBfqc27VnU6CD4jMm5Mk6dgbbovL, path 4.0.07YfABZPwJAXtLBY2vm8FqMyGAtNxncCJ65HdNKHFGNnE - Linker inputs: roc-platform-template-zig release
link-inputs-sha256-2df3df339dfb1ad4ae1fad0f382cc100c5b31b3921cdeff939f6aea51457886d(link-inputs.lock.jsonsha25615dd986a3612502330528738395c1f612d2bc7538ef9a291c059dc16e523eb6e)
roc-blueprint-core 0.4.0
The blueprint Spec and its S-expression format.
core: "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.0/915JXd6z7anN5SZ4xurPAnJnKT4VQ9dd7CtYajyh9GKV.tar.zst"Built with Roc nightly-2026-10-04-130536d.
roc-blueprint 0.4.0-rc2
Platform (use in Blueprint.roc):
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.4.0-rc2/9msYMu8nctrogjAf8f8Zfbz9URua95CYivJfXTL2w4F9.tar.zst" }The blueprint CLI is attached for x86_64 Linux, arm64 Linux and Apple Silicon macOS, with sha256 sums in blueprint.sha256. It needs Nix, and fetches its own Roc compiler through Nix. The platform supports x64musl, arm64musl, arm64mac and x64mac.
Built from:
- Roc
nightly-2026-10-04-130536dand Zig0.16.0 - Compiler archives from roc-overlay
fb02fef7a45ddf115f558c8eaf32bd1ce2f9912f: x86_64-linuxsha256-iTyG0toKTDkMvb1CWM5F1obl7BW0Lu64Ef0axEU3cU8=, aarch64-darwinsha256-4BR/YvByowlRnLwqbr+hHku4useQPV/rr3oRLR/ChC8= - nixpkgs
6774f7bc253789b113a4f39285dc0fa100abeacc - roc-blueprint-core
https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.0-rc2/7ghFBPv8KfqxWT8HuwFtDGXkPaP5RBn4cD5HwEcKBDK9.tar.zst - Roc packages in the CLI: basic-cli 0.24.0
AEjfyaMFFbh8FJrkkHJy68riVNPr3Qp6c6PawWQjBwMH, http 1.0.06ZUwqYhCS8PU9Mo6MF7oV82ET2o7KYb57CLKDq4cq4sS, weaver 0.9.07j6KBFBEZ8pNMLQHkx9xiwyZ2PmwQPgKNDPUih6gKe77, roc-ansi 0.13.0JXLM47L6CzrLXB5HBfqc27VnU6CD4jMm5Mk6dgbbovL, path 4.0.07YfABZPwJAXtLBY2vm8FqMyGAtNxncCJ65HdNKHFGNnE - Linker inputs: roc-platform-template-zig release
link-inputs-sha256-2df3df339dfb1ad4ae1fad0f382cc100c5b31b3921cdeff939f6aea51457886d(link-inputs.lock.jsonsha25615dd986a3612502330528738395c1f612d2bc7538ef9a291c059dc16e523eb6e)
roc-blueprint-core 0.4.0-rc2
The blueprint Spec and its S-expression format.
core: "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.0-rc2/7ghFBPv8KfqxWT8HuwFtDGXkPaP5RBn4cD5HwEcKBDK9.tar.zst"Built with Roc nightly-2026-10-04-130536d.
roc-blueprint 0.4.0-rc1
Platform (use in Blueprint.roc):
app [config] { pf: platform "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/0.4.0-rc1/DWAeBdDr2vi43QDRpaq8t1C8UTvdyKUHR6aSaewNaKRx.tar.zst" }The blueprint CLI for x86_64 Linux is attached.
Uses roc-blueprint-core https://github.com/lukewilliamboswell/roc-blueprint/releases/download/core-0.4.0-rc1/BQZiW1Y6EJAwN1fL6ZmrD1nBMqquewEbvQsz8kmFAtTz.tar.zst. Built with Roc nightly-2026-09-23-c7852fd. The platform supports x64musl and arm64mac.
roc-blueprint-ir 0.3.0
The blueprint IR and its S-expression format.
ir: "https://github.com/lukewilliamboswell/roc-blueprint/releases/download/ir-0.3.0/2y9CmJqu4BJpiP8qmD9xF81fxkHBn2BYH6zQSWRnYs2N.tar.zst"Built with Roc nightly-2026-09-23-c7852fd.