diff --git a/docs/explanation/slice-design-approaches.md b/docs/explanation/slice-design-approaches.md index 7edec4a..cc80883 100644 --- a/docs/explanation/slice-design-approaches.md +++ b/docs/explanation/slice-design-approaches.md @@ -1,55 +1,111 @@ --- myst: html_meta: - description: "Explanation of the two slice design approaches in Chisel: grouping by content type (bins, libs) or by functionality (minimal, core, standard)." + description: "Explanation of the three slice design approaches in Chisel: grouping by content type (bins, libs), function (crypto, internet) or tier (minimal, core)." --- (slice_design_approaches)= # Slice design approaches -There are two approaches to design slices: **grouping by content** and **grouping by function**. Depending on the package, one of these approaches might be more suitable. It is up to the user to choose a preferred approach. +There are three approaches to design slices: **grouping by type of content**, +**grouping by function** and **grouping by tier**. Depending on the package, +one of these approaches might be more suitable. It is up to the user to choose +a preferred approach. + +Whichever the approach, the slices do not have to cover all the contents of a +package. It is fine to leave out files that no slice needs, such as manual pages +or examples. + +```{note} +These approaches can be combined in one slice definitions file. For example, +the +[`systemd` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/systemd.yaml) +uses tier slices (`standard`, `dev`), function slices (`journal`, `login`, +`dbus-services`) and a content type slice (`config`). +``` + +(slice_design_approaches_content)= ## Grouping by type of content - This means putting all the binaries together in one slice, all the libraries together in another slice, and so on. - A good example is the [`dpkg` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/dpkg.yaml). +This means putting all the binaries together in one slice, all the libraries +together in another slice, and so on. A good example is the +[`dpkg` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/dpkg.yaml). + +In this case, the best practice is to create: - In this case, the best practice is to create: +- a `bins` slice which contains all the binaries +- a `libs` slice which contains all the libraries +- a `config` slice which contains all [configuration files](#create_sdf_inspect_pkg_conffiles) +- a `scripts` slice which contains ASCII executable scripts, e.g. Python, + Perl scripts +- other slices analogously (e.g. `data`, `modules`, `services`, etc) - - a `bins` slice which contains all the binaries - - a `libs` slice which contains all the libraries - - a `config` slice which contains all [configuration files](#create_sdf_inspect_pkg_conffiles) - - a `scripts` slice which contains ASCII executable scripts, e.g. Python, - Perl scripts - - other slices analogously (e.g. `data`, `modules`, `services`, etc) +You may split the above slices into more granular ones, but you should +reserve the above as a catch-all for their respective types. - You may split the above slices into more granular ones, but you should - reserve the above as a catch-all for their respective types. +(slice_design_approaches_function)= ## Grouping by function - This means grouping the contents into slices that deliver a specific - functionality. For example, the - [`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/python3.yaml) - has a `core` slice providing a very minimal `python3` runtime, but also a - `standard` slice with the additional libraries on top of `core`. - - In this case, the most common is to create: - - - A `minimal` slice that offers a stripped down installation, to the absolute essentials, to make the software - work. In most cases, such a minimal installation may only be useful if used as a base for another installation/ - build, where the developer adds their own additional dependencies. Taking the above `python3` example, this slice - would only contain the necessary dependencies to run a trivial "Hello World" script, and not much more. - - A `core` slice that offers a more complete, though still relatively slim installation. Although slightly larger - than minimal, core installations are meant to cover the majority of simple use cases, while also being a small and - ideal base to be extended for more complex use cases. Using `python3` as an example again, this slice could only - contain the topmost referenced modules in the standard library. - - A `standard` slice that provides a normal installation, supporting the full operation of the application, - including all the runtime libs/modules and additional utilities, but possibly still leaving out things like - debugging and development utilities. - - A `dev` slice which is the `standard` slice, plus all the debugging and dev utilities. A close-to full-size - installation, designed for development environments, but not production. - - Other slices which are scoped and named after the functionality they - provide (e.g. see the - [`libpython3.12-stdlib` slices](https://github.com/canonical/chisel-releases/blob/ubuntu-24.04/slices/libpython3.12-stdlib.yaml)). +This means grouping the contents into slices that deliver a specific +functionality, and naming each slice after the functionality it provides. For +example, the +[`libpython3.14-stdlib` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/libpython3.14-stdlib.yaml) +splits the Python standard library into slices such as `crypto`, +`concurrency` and `internet`. + +Such slices are best kept small and single-purpose, so that users can install +just the functionality they need on top of a base installation. + +(slice_design_approaches_tier)= + +## Grouping by tier + +This means grouping the contents into slices of increasing completeness, where +each tier is a superset of the previous one. For example, the +[`python3` slice definitions file](https://github.com/canonical/chisel-releases/blob/ubuntu-26.04/slices/python3.yaml) +has a `core` slice providing a small `python3` runtime, but also a +`standard` slice with the additional libraries on top of `core`. + +In this case, the most common approach is to create: + +- A `minimal` slice that offers a stripped down, base installation, with the + absolute bare minimum which still retains the identity of the package. In + most cases, such a minimal installation may only be useful if used as a base + for another installation/build, where the developer adds their own + additional dependencies. Taking the above `python3` example, this slice would + only contain a runtime with no standard library, able to run a trivial "Hello + World" script, and not much more. +- A `core` slice that offers what is needed for basic functionality, and + nothing more. Although slightly larger than `minimal`, `core` installations + are meant to cover the majority of simple use cases, while also being a small + and ideal base to be extended for more complex use cases. Using `python3` as + an example again, this slice could only contain the topmost referenced + modules in the standard library. +- A `standard` slice that provides what most users would expect from a normal + installation, supporting the full operation of the application, including all + the runtime libs/modules and additional utilities. It still does not include + everything, leaving out things like manual pages, examples, and debugging and + development utilities. +- A `dev` slice that includes all the debugging and dev utilities. A + close-to full-size installation, designed for development environments, but + not production. For example, the `systemd_dev` slice adds tools such as + `busctl` and `systemd-cgls` on top of `systemd_standard`. + +You should reserve the above names for their respective tiers, and not use +them for slices with a different purpose. + +Not all four tiers have to be present, so only define the ones that are +meaningful for the package. Each tier is a superset of the previous one. +Therefore, if more than one tier is present, the higher tier must list +the lower one in its `essential` dependencies. + +`standard` is the convenient choice when the package should behave like a +regular installation. Applications that only need part of a package should +instead install the `core` slice plus the +[function slices](#slice_design_approaches_function) they use, which keeps the +root file system smaller. For example, an application that only needs +Python's cryptographic modules can install `python3_core` and +`libpython3.14-stdlib_crypto` instead of `python3_standard`. diff --git a/docs/how-to/slice-a-package.md b/docs/how-to/slice-a-package.md index 9005afc..845d1c1 100644 --- a/docs/how-to/slice-a-package.md +++ b/docs/how-to/slice-a-package.md @@ -265,7 +265,7 @@ Your second task is to **design the slices**. There are a few considerations to be made, such as figuring out what slices we need and the contents of those slices. -There are **two approaches** when designing slices: "grouping by type of content" or "grouping by function". More information on them can be found {ref}`here `. This guide groups slices **by type of content**. +There are **three approaches** when designing slices: "grouping by type of content", "grouping by function" or "grouping by tier". More information on them can be found {ref}`here `. This guide groups slices **by type of content**. - [ ] 2.1 **Choose the design approach that aligns best with your package**