I’m trying out NixOS in a VM, saw that Git isn’t installed by default, and went straight to the package search. Sure enough, there are four different packages which provide git… but they all have the same description:
Distributed version control system
Git, a popular distributed version control system designed to handle very large projects with speed and efficiency.
The package names provide some basic information (“gitMinimal” → “git” → “gitFull” is pretty clear), but don’t really provide any detail about the differences between them. I could read the Nix source for the packages to get the details with enough effort, but that sounds like an exhausting amount of research to do for more than a handful of packages, especially when I’m only starting out with Nix.
Is there a way to learn about the Nix packages themselves (for example, how they differ from similar ones) rather than the software packages they contain?
Some packages have a meta.description that varies based on the package arguments. That might be the optimal way to deal with some of these variants, because it puts all the description logic in one place.
Other packages, like the git series, have a lot of switches that can be toggled on or off, and for those cases maybe it would be better to hand-craft descriptions in top-level.nix instead of generating them in the package file:
gitFull: This package includes all optional features, including support for SVN, SSH, sending emails, and a GUI. gitSVN: Relative to git, this package adds SVN support. gitMinimal: Relative to git, this package excludes a manual and integration with Perl, Python, and PCRE.
I know of no packages that do this, though. Maybe we should create another override variant, overrideWithDescription, that accepts a string argument in addition to the new args attrset, and appends that string to meta.description or meta.longDescription.
I agree with @rhendric’s comment, and I think that this could be another motivation and usecase for a mini module system for packages, such as introduced here.
Not sure what a mini-module system would solve here as this is about conveying what the defaults mean in a more abstract sense which I think can only be done through manual documentation.
I was thinking about this: If every build option has a description in the module system, we can put make the module system put this information in the meta.longDescription automatically. For example for the git variants, the long description could get appended:
Enabled features:
- svn: support bidirectional operations between a Subversion repository and Git
- ssh: support advanced ssh operations (made this one up)
- email: support git commands that send emails
...
Disabled features:
- perl: support perl based git- utilities
...
Some features are os/system-conditional–if we were just trying to enumerate these in some interface we’d probably end up with rough edges around either having:
a number of platform-specific descriptions
descriptions that ~lie about some feature being enabled if you aren’t on the platform the description was evaluated on
That, and sometimes the thing being overridden is a whole package, and so a complete accounting would include detailed descriptions of every transitive dependency.
Hmm right I didn’t thought about it… The website’s description are probably evaluated by an x86_64-linux system. Perhaps the module system could be aware of such non trivial default values?