Slice definitions

Slices are described in slice definitions files (aka SDFs). These are YAML files, named after the package name.

Location

The slice definitions files are located in the slices/ directory of chisel-releases. And the slices for a given package hello are defined in slices/hello.yaml.

Tip

Although the hello.yaml file can be placed in a sub-directory of slices/ e.g. slices/dir/hello.yaml, it is generally recommended to keep them at slices/hello.yaml. The chisel-releases repository follows the latter.

Format specification

package

Field

Type

Required

package

string

Required

Indicates the package name. It must follow the Debian policy for package name.

As indicated above, the value must also match the YAML file basename. For example:

package: hello

archive

Field

Type

Required

Supported values

archive

string

Optional

Archive name, from archives.

Specifies a particular archive from where this package should be fetched from. If specified, Chisel fetches this package from that archive despite the archives.<name>.default and archives.<name>.priority settings in chisel.yaml.

The archive name must be defined in archives. For example:

archive: ubuntu

essential

Field

Type

Required

Supported values

essential

array<string>

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 slices.<name>.essential, but applicable for every slice within the package.

In the following example, the hello_copyright slice is an essential for every slice including the hello_bins slice.

package: hello
essential:
  - hello_copyright
slices:
  bins:
    contents:
      ...
  copyright:
    ...

slices

Field

Type

Required

slices

object

Required

Defines the slices of a package.

The slice names must consist only of lower case letters(a-z), digits(0-9) and minus (-) signs. They must be at least three characters long and must start with a letter(a-z).

For example, a slice definition called data, for the ca-certificates package, could look like the following:

slices:
  data:
    essential:
      - openssl_data
    contents:
      /etc/ssl/certs/ca-certificates.crt: {text: FIXME, mutable: true}
      /usr/share/ca-certificates/mozilla/: {until: mutate}
      /usr/share/ca-certificates/mozilla/**: {until: mutate}
    mutate: |
      certs_dir = "/usr/share/ca-certificates/mozilla/"
      certs = [
        content.read(certs_dir + path) for path in content.list(certs_dir)
      ]
      content.write("/etc/ssl/certs/ca-certificates.crt", "".join(certs))

slices.<name>.essential

Field

Type

Required

Supported values

essential

array<string>

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 essential, but only applicable for the current slice.

In the following example, libc6_libs is a requirement for the bins slice and must be installed when installing the bins slice.

slices:
  bins:
    essential:
      - libc6_libs

slices.<name>.contents

Field

Type

Required

contents

object

Optional

Describes the paths that come from this slice.

Note

Paths must be absolute and must start with /.

Also, paths can have wildcard characters (?, * and **), where

  • ? matches any one character, except for /,

  • * matches zero or more characters, except for /, and

  • ** matches zero or more characters, including /.

slices.<name>.contents.<path>.copy

Field

Type

Required

copy

string

Optional

The copy field refers to the path Chisel should copy the target path from.

In the following example, Chisel copies the /bin/original file from the package onto /bin/moved.

    contents:
      /bin/moved: {copy: /bin/original}

Note

This field is only applicable to paths with no wildcards, and its value must also be an absolute path with no wildcards.

slices.<name>.contents.<path>.make

Field

Type

Required

Supported values

make

boolean

Optional

true, false

If make is true, Chisel creates the specified directory path. Note that, the path must be an absolute directory path with a trailing /. If mode is not specified, Chisel creates the directory with 0755.

    contents:
      /path/to/dir/: {make: true}

Note

This field is only applicable for paths with no wildcards.

slices.<name>.contents.<path>.text

Field

Type

Required

text

string

Optional

The text field instructs Chisel to create a text file with the specified value as the file content. If empty, Chisel creates an empty file of 0 bytes.

In the following example, /file is created with the content Hello world!. If mode is not specified, Chisel creates the file with 0644.

    contents:
      /file: {text: "Hello world!"}

Note

This field is only applicable for paths with no wildcards.

slices.<name>.contents.<path>.mode

Field

Type

Required

mode

integer

Optional

The mode field is used to specify the permission bits for any path Chisel creates. It takes in a 32 bit unsigned integer, preferably in an octal value format e.g. 0755 or 0o755. For example:

    contents:
      /file: {text: "Hello world!", mode: 0755}

Note

It can only be used with copy, make and text.

This field is only applicable for paths with no wildcards.

slices.<name>.contents.<path>.arch

Field

Type

Required

Supported values

arch

string or array<string>

Optional

amd64, arm64, armhf, i386, ppc64el, riscv64, s390x

Used to specify the package architectures a path should be installed for. This field can take a single architecture string or a list, as its value.

In the following example, /foo will be installed for i386 installations and /bar will be installed for amd64 or arm64 installations.

    contents:
      /foo: {arch: i386}
      /bar: {arch: [amd64, arm64]}

slices.<name>.contents.<path>.mutable

Field

Type

Required

Supported values

mutable

boolean

Optional

true, false

If mutable f set to true, indicates that this path can be later mutated (modified) by the mutation scripts .

slices.<name>.contents.<path>.until

Field

Type

Required

Supported values

until

string

Optional

mutate

The until field indicates that the path will be available until a certain event takes place. The file is eventually removed as soon as no other slices need it.

It currently accepts only one value - mutate. If specified, it means the corresponding slice needs it to be available only until the mutation scripts execute. It is removed afterwards, if no slices need it.

In the following example, /file will not be installed in the final root file system but will exist throughout the execution of the mutation scripts .

    contents:
      /file: {until: mutate}

slices.<name>.contents.<path>.generate

Field

Type

Required

Supported values

generate

string

Optional

manifest

Used to specify the location where Chisel should produce metadata at. The path this field applies to must not have any other fields applied to it.

The specified path must be a directory and must end with double-asterisks (**). Additionally, the path must not contain any other wildcard characters except the trailing double-asterisks (**).

Currently, generate only accepts one value - manifest. If specified, Chisel creates the Chisel Manifest file in that directory.

In the following example, Chisel creates the /var/lib/chisel directory with 0755 mode and produces a “manifest.wall” file within the directory.

    contents:
      /var/lib/chisel/**: {generate: manifest}

slices.<name>.contents.<path>.prefer

Field

Type

Required

prefer

string

Optional

Used to resolve a path conflict across multiple packages.

The same path may be declared in multiple packages without a conflict if, and only if Chisel can guarantee that the paths’ content will be the same, without downloading the packages. For all other cases, Chisel raises a conflict error, unless the conflict is resolved via the prefer field.

The value of the prefer field must match the name of an existing package in the release, and it can be used to specify which package should take precedence, in a linear sequence, such that when there are multiple occurrences of the same path across multiple packages, Chisel will install the one from the package that appears last in the linear chain.

For example:

package: hyena
slices:
  bins:
    content:
      /usr/bin/eat: { text: FOO, prefer: lion }
---
package: lion
slices:
  bins:
    content:
      /usr/bin/eat:  { text: FOO, prefer: hippo }
---
package: hippo
slices:
  bins:
    content:
      /usr/bin/eat:

With the above, the following behavior is observed:

  • chisel cut … <pkg>_bins would get the path from <pkg> (regardless of it being hyena, lion or hippo),

  • chisel cut … hyena_bins lion_bins would get the path from lion, and

  • chisel cut … hyena_bins lion_bins hippo_bins would get the path from hippo.

Note

Since prefer can only be used for inter-package conflicts, its value must be the same for all occurrences of the path within the same package.

Note

The prefer field cannot be used with globs.

slices.<name>.mutate

Field

Type

Required

Supported values

mutate

string

Optional

Starlark script

Describes a slice’s mutation scripts. The mutation scripts are conceptually similar to Debian’s maintainer script.

The mutation scripts are written in Google’s Starlark language and are executed after the files of every slice have been installed in the root file system. The mutation scripts are run once per each installed slice, in the same order of slices.

In addition to Starlark’s native syntax, Chisel introduces the following functions:

Function

Return type

Description

content.list(d)

array<string>

Lists and returns directory d’s contents (similar to GNU ls)

content.read(f)

string

Reads a text file f and returns its contents

content.write(f, s)

-

Writes the text content s to a file f

Reusing the above “ca-certificates_data” example, Chisel initially creates the /etc/ssl/certs/ca-certificates.crt text file with FIXME as its content. When the mutation scripts execute, Chisel concatenates the contents of every file in the /usr/share/ca-certificates/mozilla/ directory and writes the concatenated data to the previously created /etc/ssl/certs/ca-certificates.crt file.

    contents:
      /etc/ssl/certs/ca-certificates.crt: {text: FIXME, mutable: true}
      /usr/share/ca-certificates/mozilla/: {until: mutate}
      /usr/share/ca-certificates/mozilla/**: {until: mutate}
    mutate: |
      certs_dir = "/usr/share/ca-certificates/mozilla/"
      certs = [
        content.read(certs_dir + path) for path in content.list(certs_dir)
      ]
      content.write("/etc/ssl/certs/ca-certificates.crt", "".join(certs))

Due to the usage of until, the /usr/share/ca-certificates/mozilla/ directory and the files inside are not present in the final root file system.

Example

The slice definitions files can be found in the chisel-releases repository , or inspected via the info command. Here is a short example of the hello package slice definitions:

package: hello

essential:
  - hello_copyright

slices:
  bins:
    essential:
      - libc6_libs
    contents:
      /usr/bin/hello:

  copyright:
    contents:
      /usr/share/doc/hello/copyright: