streamLayeredImage Details: Inputs, Popularity, and Customization

In case there are more objects to include than available layers, the function will put the most ["popular"](https://github.com/NixOS/nixpkgs/tree/release-23.11/pkgs/build-support/references-by-popularity) objects in their own layers, and group all remaining objects into a single layer. An additional layer will be created with symlinks to the store paths you specified to be included in the image. These symlinks are built with [`symlinkJoin`](#trivial-builder-symlinkJoin), so they will be included in the root of the image. See [](#ex-dockerTools-streamLayeredImage-exploringlayers) to understand how these symlinks are laid out in the generated image. `streamLayeredImage` allows scripts to be run when creating the additional layer with symlinks, allowing custom behaviour to affect the final results of the image (see the documentation of the `extraCommands` and `fakeRootCommands` attributes). The resulting repository tarball will list a single image as specified by the `name` and `tag` attributes. By default, that image will use a static creation date (see documentation for the `created` and `mtime` attributes). This allows the function to produce reproducible images. ### Inputs {#ssec-pkgs-dockerTools-streamLayeredImage-inputs} `streamLayeredImage` expects one argument with the following attributes: `name` (String) : The name of the generated image. `tag` (String or Null; _optional_) : Tag of the generated image. If `null`, the hash of the nix derivation will be used as the tag. _Default value:_ `null`. `fromImage`(Path or Null; _optional_) : The repository tarball of an image to be used as the base for the generated image. It must be a valid Docker image, such as one exported by `docker image save`, or another image built with the `dockerTools` utility functions. This can be seen as an equivalent of `FROM fromImage` in a `Dockerfile`. A value of `null` can be seen as an equivalent of `FROM scratch`. If specified, the created layers will be appended to the layers defined in the base image. _Default value:_ `null`. `contents` (Path or List of Paths; _optional_) []{#dockerTools-buildLayeredImage-arg-contents} : Directories whose contents will be added to the generated image. Things that coerce to paths (e.g. a derivation) can also be used. This can be seen as an equivalent of `ADD contents/ /` in a `Dockerfile`. All the contents specified by `contents` will be added as a final layer in the generated image. They will be added as links to the actual files (e.g. links to the store paths). The actual files will be added in previous layers. _Default value:_ `[]` `config` (Attribute Set or Null; _optional_) []{#dockerTools-buildLayeredImage-arg-config} : Used to specify the configuration of the containers that will be started off the generated image. Must be an attribute set, with each attribute as listed in the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions). If any packages are used directly in `config`, they will be automatically included in the generated image. See [](#ex-dockerTools-streamLayeredImage-configclosure) for an example. _Default value:_ `null`. `architecture` (String; _optional_) : Used to specify the image architecture. This is useful for multi-architecture builds that don't need cross compiling. If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker. According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`. _Default value:_ the same value from `pkgs.go.GOARCH`. `created` (String; _optional_) : Specifies the time of creation of the generated image.

This section describes additional features of `streamLayeredImage`, including how it handles more objects than available layers by prioritizing popular objects and grouping the rest. It explains that symlinks to specified store paths are created in an additional layer using `symlinkJoin`. Furthermore, it details how scripts can be run during layer creation to customize the image. The tarball output contains a single image with a static creation date for reproducibility. It lists the expected inputs for the `streamLayeredImage` function, including `name`, `tag`, `fromImage`, `contents`, `config`, `architecture`, and `created`, and their respective purposes and default values.