> Documentation version: main. [HTML page](https://lukewilliamboswell.github.io/roc-blueprint/examples.html)

<a id="learn-from-the-examples"></a>

# Learn from the examples

Four complete projects live in
[` examples/ `](https://github.com/lukewilliamboswell/roc-blueprint/blob/main/examples). In the repository they use the platform in the
working tree, so they follow ` main `. To start a project of your own, download
` roc-blueprint-examples-<version>.zip ` from a [release](https://github.com/lukewilliamboswell/roc-blueprint/releases): the same
projects with that release’s platform URL, as they were tested for it, and the
Spec each one prints.

- **all-settings**: Two Nix package sources, each tool written with its source, a named overlay
  scoped to ` dev `, parent-first environment inheritance, shell aliases,
  argument-list tasks, a Roc package, two fetched programs
  (` Recipes.roc_nightly ` and ` Recipes.file `), an expected tool and raw Nix
  settings. ` ci ` uses ` base ` without the overlay.

- **composition**: Imports ` ProjectTasks.roc `, whose pure
  ` settings : EnvName -> List(Config.Setting) ` function supplies ` fmt `, ` test `
  and ` args ` tasks. The application concatenates them into ` config `; all use
  ` dev ` directly. Inherited ` git ` is deduplicated before the child’s ` python3 `.
  The tasks print tool versions or their arguments as JSON; they do not format
  files or run a test suite. No plugin registration, generated command line,
  implicit tool installation or runtime code loading is involved. It also
  imports ` Releases.roc `, whose ` blueprint : Str -> (System -> Config.Download) `
  is a recipe written by hand: given a release, a function from the System to
  where that release’s ` blueprint ` is downloaded, or ` Unavailable `, which a
  ` Fetch ` in ` Programs ` takes.

- **artifacts**: A complete local locked source, a sandboxed library and application that
  depends on it, and a typed workflow of tasks and builds. Its
  [README](https://github.com/lukewilliamboswell/roc-blueprint/blob/main/examples/artifacts/README.md) shows usage and output, including
  explicit resolver ownership, named executor selection, update, and the read-only source and artifact locations.

- **extensions**: Custom extension blocks and raw values. The platform emits them, and
  ` blueprint check ` refuses the project with ` needs features: extensions `,
  because no provider implements them. That refusal is what the example shows.

<a id="run-an-example"></a>

## Run an example

In an unpacked examples archive, with the ` blueprint ` binary of the same
release:

``` sh
cd composition
blueprint check
blueprint update
blueprint run fmt
blueprint run args -- 'two words' '' '--literal'
```

Only an explicit ` update ` creates or changes ` Blueprint.lock `. ` gen `, ` shell `,
` run `, ` build ` and ` workflow ` require a lock that matches and leave it as it
is; the generated ` .blueprint/flake.lock ` is derived from it. Every example
declares a Nix package source, so ` blueprint update ` needs Nix in each;
[Work without a provider](no-provider.md#a-project-that-never-starts-a-provider) has a
project that needs none.

In a checkout of the repository the examples need the platform host built
first; see [Build and test](contributing.md#build-and-test).

<a id="consume-a-lock-report-in-pure-roc"></a>

## Consume a lock report in pure Roc

The official checked consumer in
[` fixtures/lock-snapshot/ `](https://github.com/lukewilliamboswell/roc-blueprint/tree/main/fixtures/lock-snapshot)
shows how downstream tools import ` core.LockSnapshot ` from the existing core
package. It includes pure fetched-program pin checks, provider-qualified source
identity comparisons and inert Nix metadata extraction, plus a small executable
that reads and round-trips a saved JSON report. Its README gives checkout and
pinned-release commands. This consumer is tested against the actual release
core bundle with both supported compiler pins; it is separate from the four
configuration projects in the examples archive. Start with
[Consume lock inspection in pure Roc](lock-snapshot.md#consume-lock-inspection-in-roc)
for the end-to-end invocation and API contract.