dockerTools: prune and improve examples

[roberth]

Describe the bug

The dockerTools examples are bad.

• It has too many examples that are really only test cases and
• it abuses contents in one or more instances. It is for adding to the filesystem root, not for adding/combining packages. Use buildEnv for that.

Expected behavior

Examples are correct, representative and focused.
Test cases are in a separate file.
The examples are still tested.

Notify maintainers

@roberth @utdemir

Maintainer information:

# a list of nixpkgs attributes affected by the problem
attribute:
 - dockerTools
 - dockerTools.examples
# a list of nixos modules affected by the problem
module:

[stale]

I marked this as stale due to inactivity. → More info

[chasecaleb]

@roberth Can you elaborate on why using contents instead of buildEnv is wrong? Looking through the nixpkgs manual, I see that although examples for dockerTools.buildImage use copyToRoot = pkgs.buildEnv { .. }, the example for dockerTools.buildLayeredImage uses contents = [ pkgs.hello ].

[roberth]

When you copy a self-referential path to the root, the original store path must still be added, in order to satisfy the self-reference. This generally wastes space.

buildEnv does not suffer from this problem, because it probably does not create such outputs that refer to themselves by path, and even if it did, only some symlinks would end up in the store, which would be an insignificant use of space.

buildLayeredImage implicitly adds this indirection with symlinkJoin, so it doesn't suffer from the same problem.

Perhaps the functions could be harmonized, so that both support copyToRoot and a new symlinkToRoot based on symlinkJoin.