Skip to content

docs: support for stores and bins #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
upils wants to merge 6 commits into
base: main
Choose a base branch
from
+194 −31
Draft

docs: support for stores and bins #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4e343b5
docs: support for stores and bins
upils Jul 1, 2026
0c7ee63
docs: update wordlist
upils Jul 1, 2026
e6325c7
docs: add format v4
upils Jul 15, 2026
e725683
docs: fix default-track example
upils Jul 15, 2026
fdd5516
fix: review
upils Jul 17, 2026
94bd200
fix: review
upils Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/.custom_wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,11 @@ jaotc
jsonwall
libs
linters
lookups
manpages
openssl
optimize
prepended
recognized
repo
rootfs
Expand Down
15 changes: 9 additions & 6 deletions docs/explanation/mode-of-operation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
myst:
html_meta:
description: "Explanation of how Chisel works: reading chisel-releases, fetching packages from Ubuntu archives, and extracting selected files into a root file system."
description: "Explanation of how Chisel works: reading chisel-releases, fetching packages from Ubuntu archives and stores, and extracting selected files into a root file system."

@asanvaq asanvaq Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Metadata should be max. 160 characters long. This updated increased it to 163, so I propose the following:

Suggested change
description: "Explanation of how Chisel works: reading chisel-releases, fetching packages from Ubuntu archives and stores, and extracting selected files into a root file system."
description: "Explanation of how Chisel works: reading chisel-releases, fetching packages from Ubuntu archives and stores, and extracting files into a root file system."

@upils upils Jul 17, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should keep the "selected" term as this is an important concept in Chisel. Using slices is doing a selection of files from packages. Chisel only extract the selected files.

@asanvaq asanvaq Jul 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about this?

Suggested change
description: "Explanation of how Chisel works: reading chisel-releases, fetching packages from Ubuntu archives and stores, and extracting selected files into a root file system."
description: "Explanation of how Chisel works: read chisel-releases, fetch packages from Ubuntu archives and stores, and extract selected files into a root file system."

---

(chisel_mo_explanation)=
Expand Down Expand Up @@ -53,11 +53,14 @@ definitions<slice_definitions_ref>` while validating the release and checking fo
</td>
<td>

Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly.
It fetches, validates and parses their `InRelease` files.
It then resolves which archive holds the **requested** packages and fetches
the corresponding package tarballs.

Chisel resolves the source of each **requested** package and fetches it.
Packages are typically fetched from {ref}`archives<chisel_yaml_format_spec_archives>`,
which are Debian archives Chisel talks to directly by fetching, validating and
parsing their `InRelease` files. Packages may also be fetched from
{ref}`stores<chisel_yaml_format_spec_stores>`, which serve packages via a store
Comment thread
asanvaq marked this conversation as resolved.
API rather than from a Debian archive. Stores are used to distribute packages
that are not available in the standard Ubuntu archives, such as `bin` packages.

</td>
</tr>

Expand Down
13 changes: 9 additions & 4 deletions docs/explanation/slices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,16 @@ myst:

## What are package slices?

Since Debian packages are simply archives that can be inspected, navigated and
deconstructed, it is possible to define slices of packages that contain
Packages are collections of files that can be inspected, navigated and
deconstructed. It is possible to define slices of packages that contain
minimal, complementary, loosely-coupled sets of files based on package metadata
and content. Such **package slices** are subsets of Debian packages, with their
own content and set of dependencies to other internal and external slices.
and content. Such **package slices** are subsets of packages, with their own
content and set of dependencies to other internal and external slices.

Packages are typically fetched from Debian archives as `.deb` files, but Chisel
also supports fetching packages from {ref}`stores<chisel_yaml_format_spec_stores>`,
Comment thread
asanvaq marked this conversation as resolved.
which serve packages via a store API rather than from a Debian archive. The
slicing mechanism is the same regardless of the package source.

The use of package slices provides the ability to build minimal root file
system from the wider set of Ubuntu packages.
Expand Down
114 changes: 96 additions & 18 deletions docs/reference/chisel-releases/chisel.yaml.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ directory.

### `format`

| Field | Type | Required | Supported values |
| -------- | -------- | -------- | ---------------- |
| `format` | `string` | Required | `v1`, `v2`, `v3` |
| Field | Type | Required | Supported values |
| -------- | -------- | -------- | ---------------------- |
| `format` | `string` | Required | `v1`, `v2`, `v3`, `v4` |

Used to define the supported schemas for the {ref}`chisel-releases_ref`.
For example:
Expand All @@ -55,21 +55,23 @@ that support said `format`.

```{eval-rst}

+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
| chisel-release | .. centered:: Format |
+=============================================================================+=======================================================+===================================================================+===================================================================+
| | **V1** | **V2** | **V3** |
+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
| `20.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-20.04>`_ | `all <https://github.com/canonical/chisel/releases>`_ | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
| `22.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-22.04>`_ | `all <https://github.com/canonical/chisel/releases>`_ | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
| `24.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-24.04>`_ | `all <https://github.com/canonical/chisel/releases>`_ | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
| `25.10 <https://github.com/canonical/chisel-releases/tree/ubuntu-25.10>`_ | x | >= `v1.2.0 <https://github.com/canonical/chisel/releases/v1.2.0>`_| x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
| `26.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-26.04>`_ | x | x | >= `v1.4.0 <https://github.com/canonical/chisel/releases/v1.4.0>`_|
+-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| chisel-release | .. centered:: Format |
+=============================================================================+=======================================================+====================================================================+====================================================================+=====================================================================+
| | **V1** | **V2** | **V3** | **V4** |
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| `20.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-20.04>`_ | `all <https://github.com/canonical/chisel/releases>`_ | x | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| `22.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-22.04>`_ | `all <https://github.com/canonical/chisel/releases>`_ | x | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| `24.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-24.04>`_ | `all <https://github.com/canonical/chisel/releases>`_ | x | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| `25.10 <https://github.com/canonical/chisel-releases/tree/ubuntu-25.10>`_ | x | >= `v1.2.0 <https://github.com/canonical/chisel/releases/v1.2.0>`_ | x | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| `26.04 <https://github.com/canonical/chisel-releases/tree/ubuntu-26.04>`_ | x | x | >= `v1.4.0 <https://github.com/canonical/chisel/releases/v1.4.0>`_ | x |
+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+
| `26.10 <https://github.com/canonical/chisel-releases/tree/ubuntu-26.10>`_ | x | x | x | >= `v1.5.0 <https://github.com/canonical/chisel/releases/v1.5.0>`_ |

@upils upils Jul 15, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Note to reviewer]: I did this under the assumption the next minor version will be cut to release the whole feature supporting bins.

+-----------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------+

```

Expand Down Expand Up @@ -362,6 +364,82 @@ The `armor` field contains the multi-line armored ASCII data of OpenPGP public
key.


(chisel_yaml_format_spec_stores)=

### `stores`

| Field | Type | Required | Compatibility |
| ---------- | -------- | -------- | ------------- |
| `stores` | `object` | Optional | >= `v3` |

Tells Chisel which stores to fetch packages from. A store is an alternative
package source to {ref}`archives<chisel_yaml_format_spec_archives>`, serving
packages via a store API rather than from a Debian archive. Stores are used to
distribute packages that are not available in the standard Ubuntu archives,
such as `bin` packages.

For example:

```yaml
stores:
bin:
kind: bin
version: 26.10
default-prefix: "bin-"
```

```{note}
In format `v3`, bin slice definitions must be stored in a separate, top-level,
`bin-slices/` directory. This is a backwards compatibility mechanism for Chisel
versions that do not support stores: those old versions only read `slices/` and
are unaware of `bin-slices/`, so they are not affected by the new store fields.
From format `v4` onwards, bin slice definitions live in `slices/` alongside
regular ones, so `bin-slices/` is not read.
```


(chisel_yaml_format_spec_stores_version)=

### `stores.<name>.version`

| Field | Type | Required | Supported values | Compatibility |
| --------- | -------- | -------- | ------------------------------------------------------- | ------------- |
| `version` | `string` | Required | Ubuntu release in `xx.yy` format e.g. 22.04, 24.04 etc. | >= `v3` |
Comment thread
asanvaq marked this conversation as resolved.

Indicates the Ubuntu release this store should fetch the packages for.


(chisel_yaml_format_spec_stores_kind)=

### `stores.<name>.kind`

| Field | Type | Required | Supported values | Compatibility |
| ------ | -------- | -------- | ---------------- | ------------- |
| `kind` | `string` | Required | `bin` | >= `v3` |

Specifies the kind of store. The `bin` kind refers to bin packages
distributed via a store API.


(chisel_yaml_format_spec_stores_default_prefix)=

### `stores.<name>.default-prefix`

| Field | Type | Required | Compatibility |
| ---------------- | -------- | -------- | ------------- |
| `default-prefix` | `string` | Required | >= `v3` |

Specifies the prefix prepended to the bare package name (as defined by the
`package` field in the slice definitions file) to form the unique package
identifier used across the release. For example, with `default-prefix: "bin-"`
and a slice definitions file declaring `package: curl`, the unique package
identifier becomes `bin-curl`.

This unique identifier is used in slice references (e.g. in {ref}`essential<slice_definitions_format_slices_essential>`
dependencies and {ref}`prefer<slice_definitions_format_slices_contents_prefer>`), while the bare name is used for package lookups
in the store.


(chisel_yaml_example)=

## Example
Expand Down
17 changes: 14 additions & 3 deletions docs/reference/chisel-releases/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,23 @@ A _chisel-release_ is simply a directory with the following structure:

```
├── chisel.yaml
└── slices
├── pkgA.yaml
├── pkgB.yaml
├── slices
│ ├── pkgA.yaml
│ ├── pkgB.yaml
│ └── ...
└── bin-slices
├── bin-pkgC.yaml
└── ...
```

```{note}
The `bin-slices/` directory is only used in format `v3`. It contains slice
definitions for packages fetched from
{ref}`stores<chisel_yaml_format_spec_stores>`. From format `v4` onwards, bin
slice definitions live in `slices/` alongside regular ones, so `bin-slices/`
is not used.
```

The following pages provide more details on:

```{toctree}
Expand Down
64 changes: 64 additions & 0 deletions docs/reference/chisel-releases/slice-definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,17 @@ Although the `hello.yaml` file can be placed in a sub-directory of `slices/` e.g
`slices/hello.yaml`. The {{chisel_releases_repo}} follows the latter.
```

```{note}
In format `v3`, bin slice definitions (i.e. slice definitions for packages
fetched from a {ref}`store<slice_definitions_format_store>`) must be stored in
a separate, top-level, `bin-slices/` directory rather than in `slices/`. This
is a backwards compatibility mechanism for Chisel versions that do not support
stores: those old versions only read `slices/` and are unaware of
`bin-slices/`, so they are not affected by the new store fields. From format
`v4` onwards, bin slice definitions live in `slices/` alongside regular ones,
so `bin-slices/` is not read.
```

(slice_definitions_format)=

## Format specification
Expand Down Expand Up @@ -70,6 +81,9 @@ fetched from. If specified, Chisel fetches this package from that archive despit
{ref}`chisel_yaml_format_spec_archives_priority` settings in
{ref}`chisel_yaml_ref`.

The `archive` field and the {ref}`store<slice_definitions_format_store>`
field are mutually exclusive: a package must be fetched from either an
archive or a store, but not both.

The archive name must be defined in {ref}`chisel_yaml_format_spec_archives`.
For example:
Expand All @@ -78,6 +92,56 @@ For example:
archive: ubuntu
```


(slice_definitions_format_store)=

### `store`

| Field | Type | Required | Supported values | Compatibility |
| ------- | -------- | -------- | ----------------------------------------------------------------- | ------------- |
| `store` | `string` | Optional | Store name, from {ref}`stores<chisel_yaml_format_spec_stores>`. | >= `v3` |

Specifies a particular {ref}`store<chisel_yaml_format_spec_stores>` from
where this package should be fetched. If specified, Chisel fetches this
package from that store rather than from an archive. The store name must be
defined in {ref}`chisel_yaml_format_spec_stores`.

The `store` field is mutually exclusive with
{ref}`archive<slice_definitions_format_archive>`: a package must be fetched
from either an archive or a store, but not both.

When `store` is set, {ref}`default-track<slice_definitions_format_default_track>`
must also be set.

For example:

```yaml
store: bin
default-track: 3.1
```


(slice_definitions_format_default_track)=

### `default-track`

| Field | Type | Required | Supported values | Compatibility |
| --------------- | -------- | ----------------------------------------- | ---------------- | ------------- |
| `default-track` | `string` | Required when `store` is set. | A track name. | >= `v3` |

Specifies the default track for a {ref}`store<slice_definitions_format_store>`
package.

This field is required when {ref}`store<slice_definitions_format_store>` is
set, and must not be included when `store` is not set.

For example:

```yaml
store: bin
default-track: 3.1
```

(slice_definitions_format_essential)=

### `essential`
Expand Down
Loading