diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index b56f38d..e2768ac 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -24,7 +24,7 @@ directory. | Field | Type | Required | Supported values | | -------- | -------- | -------- | ---------------- | -| `format` | `string` | Required | `v1`, `v2` | +| `format` | `string` | Required | `v1`, `v2`, `v3` | Used to define the supported schemas for the {ref}`chisel-releases_ref`. For example: @@ -33,11 +33,40 @@ For example: format: v1 ``` -```{note} +```{important} New formats are typically introduced with new _chisel-releases_ and may introduce disruptive changes to the previous formats. ``` + +(chisel_yaml_format_spec_compatibility_matrix)= + +#### Compatibility matrix + +In this table, you'll find the designated `format` for all existing +and supported {ref}`chisel-releases_ref`, alongside the Chisel tool versions +that support said `format`. + +```{eval-rst} + ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| chisel-release | .. centered:: Format | ++=============================================================================+=======================================================+===================================================================+===================================================================+ +| | **V1** | **V2** | **V3** | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `20.04 `_ | `all `_ | x | x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `22.04 `_ | `all `_ | x | x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `24.04 `_ | `all `_ | x | x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `25.10 `_ | x | >= `v1.2.0 `_| x | ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ +| `26.04 `_ | x | x | >= `v1.4.0 `_| ++-----------------------------------------------------------------------------+-------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ + +``` + (chisel_yaml_format_spec_archives)= ### `archives` @@ -120,7 +149,7 @@ the archive behaviour. Lists the archive suites to fetch packages from. Read more about suites in the [Ubuntu packaging -guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest/explanation/archive/#suite). +guide](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/package-archive/#suite). (chisel_yaml_format_spec_archives_components)= @@ -133,7 +162,7 @@ guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest Lists the components of the archive suites to fetch packages from. Read more about components in the [Ubuntu packaging -guide](https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest/explanation/archive/#components). +guide](https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/package-archive/#components). Chisel reads the `InRelease` files from each `(suite, component)` combination to locate packages. @@ -380,3 +409,5 @@ public-keys: =9AdM -----END PGP PUBLIC KEY BLOCK----- ``` + + diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 1f1b4ab..32d2572 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -67,15 +67,56 @@ archive: ubuntu ### `essential` +This field is similar to {ref}`slice_definitions_format_slices_essential`, +but applicable for every slice within the package. + +```{note} +`essential` has different types across different +{ref}`formats`. +``` + +`````{tab-set} + +````{tab-item} Format **v3** +| Field | Type | Required | +| ----------- | -------- | -------- | +| `essential` | `object` | Optional | + +A map of slices, in their full name (e.g. `hello_copyright`), +alongside their `essential`-specific properties. + +#### `essential..arch` + +| Field | Type | Required | Supported values | +| ------ | --------------------------- | -------- | ---------------------------------------------------------------- | +| `arch` | `string` or `array` | Optional | `amd64`, `arm64`, `armhf`, `i386`, `ppc64el`, `riscv64`, `s390x` | + +Used to specify the package architectures an _essential_ dependency should be +installed for. This field can take a single architecture string or a list, as its +value. + +In the following example, `hello_copyright` will be installed for every installation +of every slice of the `hello` package, while `foo_bar` will only be installed +for `arm64` installations of any slice within `hello`. + +```yaml +package: hello +essential: + hello_copyright: {} + foo_bar: {arch: arm64} +slices: + ... +``` + +```` + +````{tab-item} Formats **v1** and **v2** | Field | Type | Required | Supported values | | ----------- | --------------- | -------- | ------------------ | | `essential` | `array` | Optional | An existing slice. | -Lists the slices that are needed for **every slice** of the -current package. Slices in this list must be written in their full name, e.g. -`hello_copyright`. This field is similar to -{ref}`slice_definitions_format_slices_essential`, but applicable for every slice -within the package. +Slices in this list must be written in their full name, e.g. +`hello_copyright`. In the following example, the `hello_copyright` slice is an _essential_ for every slice including the `hello_bins` slice. @@ -91,6 +132,9 @@ slices: copyright: ... ``` +```` +````` + (slice_definitions_format_slices)= @@ -130,15 +174,60 @@ slices: ### `slices..essential` +This field is similar to {ref}`slice_definitions_format_essential`,but only applicable for the current +slice. + +```{note} +`slices..essential` has different types across different +{ref}`formats`. +``` + +`````{tab-set} + +````{tab-item} Format **v3** +| Field | Type | Required | +| ----------- | -------- | -------- | +| `essential` | `object` | Optional | + +A map of slices, and their `essential`-specific properties, that are needed and that must be installed before +the current slice. +These slice names must be written in their full name e.g. `hello_copyright`. + + +#### `slices..essential..arch` + +| Field | Type | Required | Supported values | +| ------ | --------------------------- | -------- | ---------------------------------------------------------------- | +| `arch` | `string` or `array` | Optional | `amd64`, `arm64`, `armhf`, `i386`, `ppc64el`, `riscv64`, `s390x` | + +Used to specify the package architectures an _essential_ dependency should be +installed for. This field can take a single architecture string or a list, as its +value. + +In the following example: + - `gcc-aarch64-linux-gnu_gcc` is a requirement for the `gcc` slice, only on `arm64` installations, + - `gcc-x86-64-linux-gnu_gcc` is a requirement for the `gcc` slice, only on `amd64` installations, and + - `gcc-15_gcc-15` is a requirement for the `gcc` slice, for all installations. + +```yaml +slices: + gcc: + essential: + gcc-aarch64-linux-gnu_gcc: {arch: [arm64]} + gcc-x86-64-linux-gnu_gcc: {arch: [amd64]} + gcc-15_gcc-15: + +``` +```` + +````{tab-item} Formats **v1** and **v2** | Field | Type | Required | Supported values | | ----------- | --------------- | -------- | ------------------ | | `essential` | `array` | Optional | An existing slice. | Lists the slices that are needed and that must be installed before the current slice. Slices in this list must be written in their full name -e.g. `hello_copyright`. This field is similar to -{ref}`slice_definitions_format_essential`, but only applicable for the current -slice. +e.g. `hello_copyright`. In the following example, `libc6_libs` is a requirement for the `bins` slice and must be installed when installing the `bins` slice. @@ -149,6 +238,11 @@ slices: essential: - libc6_libs ``` +```` + + +````` + (slice_definitions_format_slices_contents)= @@ -374,9 +468,9 @@ In the following example, Chisel creates the `/var/lib/chisel` directory with ### `slices..contents..prefer` -| Field | Type | Required | -| ---------- | -------- | -------- | -| `prefer` | `string` | Optional | +| Field | Type | Required | Introduced in format | +| ---------- | -------- | -------- | -------- | +| `prefer` | `string` | Optional | {ref}`v2` | Used to resolve a path conflict across multiple packages. @@ -481,9 +575,9 @@ and the files inside are not present in the final root file system. ### `slices..hint` -| Field | Type | Required | -| ------ | -------- | -------- | -| `hint` | `string` | Optional | +| Field | Type | Required | Introduced in format | +| ------ | -------- | -------- | -------------------- | +| `hint` | `string` | Optional | {ref}`v3` | Provides a concise and unopinionated discriminator to help the user select slices. It focuses on describing the *subset* of contents coming from this slice. It does