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 an alphanumeric character.

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>.symlink`¶

Field	Type	Required
`symlink`	`string`	Optional

The symlink field is used to create symbolic links. If specified, Chisel creates a symlink to the target path specified by the symlink value. The value must be an absolute path with no wildcards.

In the following example, Chisel creates the symlink /link which points to /file.

    contents:
      /link: {symlink: /file}

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>.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:

Slice definitions¶

Location¶

Format specification¶

package¶

archive¶

essential¶

slices¶

slices.<name>.essential¶

slices.<name>.contents¶

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

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

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

slices.<name>.contents.<path>.symlink¶

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

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

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

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

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

slices.<name>.mutate¶

Example¶

`package`¶

`archive`¶

`essential`¶

`slices`¶

`slices.<name>.essential`¶

`slices.<name>.contents`¶

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

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

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

`slices.<name>.contents.<path>.symlink`¶

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

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

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

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

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

`slices.<name>.mutate`¶