From 7e5fa5c25ce585da5399038bc92980fddbb65d8b Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Sat, 13 Jan 2024 20:00:06 +0100 Subject: [PATCH] doc/glossary: Define package and package attribute set A small step towards https://github.com/NixOS/nix/issues/6507 I believe this incomplete definition is one that can be agreed on. It would be nice to define more, but considering that the issue also proposes changes to the design, I believe we should hold off on those. As for the wording, we're dealing with some very general and vague terms, that have to be treated with exactly the right amount of vagueness to be effective. I start out with a fairly abstract definition of package. 1. to establish a baseline so we know what we're talking about 2. so that we can go in and clarify that we have an extra, Nix-specific definition. "Software" is notoriously ill-defined, so it makes a great qualifier for package, which we don't really want to pin down either, because that would just get us lost in discussion. We can come back to this after we've done 6057 and a few years in a desert cave. Then comes the "package attribute set" definition. I can already hear Valentin say "That's not even Nix's responsibility!" and on some days I might even agree. However, in our current reality, we have `nix-env`, `nix-build` and `nix profile`, which query the `outputName` attribute - among others - which just don't exist in the derivation. For those who can't believe what they're reading: $ nix-build --expr 'with import ./. {}; bind // {outputName = "lib";}' --no-out-link this path will be fetched (1.16 MiB download, 3.72 MiB unpacked): /nix/store/rfk6klfx3z972gavxlw6iypnj6j806ma-bind-9.18.21-lib copying path '/nix/store/rfk6klfx3z972gavxlw6iypnj6j806ma-bind-9.18.21-lib' from 'https://cache.nixos.org'... /nix/store/rfk6klfx3z972gavxlw6iypnj6j806ma-bind-9.18.21-lib and let me tell you that bind is not a library. So anyway, that's also proof of why calling this a "derivation attrset" would be wrong, despite the type attribute. --- doc/manual/src/glossary.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 1fdb8b4dd..5e3c0e024 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -271,6 +271,21 @@ The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute. +- [package]{#package} + + 1. A software package; typically a collection of programs, files and data. + + 2. A [package attribute set]. + +- [package attribute set]{#package-attribute-set} + + An [attribute set] containing the attribute `type = "derivation";` (derivation for historical reasons), as well as other attributes, such as + - attributes that refer to the files of a [package], typically in the form of [derivation outputs](#output), + - attributes that declare something about how the package is supposed to be installed or used, + - other metadata or arbitrary attributes. + + [package attribute set]: #package-attribute-set + - [string interpolation]{#gloss-string-interpolation} Expanding expressions enclosed in `${ }` within a [string], [path], or [attribute name].