docs: clarify package and module option naming #31668
Conversation
This attempts to briefly clarify the current naming conventions of attribute names in `all-packages.nix` and module option names.
|
One example of lisp case being preferred over snake case: fd565ce#commitcomment-25726655 (although apparently it wasn't in master for long) |
|
Kind of related: #30452 (comment) |
|
This one goes from camel case to lisp case: 695027f#commitcomment-26188346 Edit: my bad, I only read the title, not the actual commit. The renaming is from |
|
I'm not sure why the attribute name is |
Because There are a few such suffixes separated by a dash or underscore, but camel case is most common. |
|
I would prefer to 1) unify case in directory name, derivation name, and top-level attribute name, 2) use whatever upstream has come up with instead of inventing our own version of the name. I believe that would make Nixpkgs much easier to work with, because no one would have to learn the attribute name in Nix, only the actual package name. Similarly, if someone wants to find an artifact in Nix store, they could use the same name. It also might improve searchability. It would be simpler, too: there would be only one name instead of several that may or may not be different depending on the context. |
|
@rycee This PR looks good, except that "The hyphenated style is preferred in all three package names.", while true, is not applicable to package naming because we don't choose the names of upstream packages. |
|
@orivej I think the three package names are directory name, derivation name, and top-level attribute name. Upstream name (case, rather) seems to be ignored. |
|
The quality that I optimize names for, and which I observe to be optimized for most often in Nixpkgs, is memorability: we choose the most natural name, the one we would type without looking it up online or searching through the list of available packages. It would also be the one most frequently used in discussions about or issues of the project; the name of the directory we would choose to store some files related to the project. Sometimes it differs from an official name in casing, but it does not differ in hyphens or underscores. Note that upstreams themselves use different case in different official names, e.g. |
|
I agree. |
|
After a lot of changes to nixpkgs I think those rules should be
simplified to:
* camelCase for library functions and variables,
* lisp-style for everything else (because everything else usually refers
to packages, and you don't want to mangle package names).
For instance, I think the package arguments/options should be lispified
too. Reasoning:
* both `withX` and `x11Support` (or `withJack` and `jackSupport`, etc)
are equally bad:
* `with*` in camelCase mangles package names,
* `*Support` is bad for sorting (e.g. when you want to generate a man
which lists all packages with all their options).
The latter is not implemented yet, but see #32424 for how I use that
kind of sorting for configuration.nix(5) manpage.
After a lot of options added to a lot of packages (see my other PRs, I
do that a lot, see my comments in #12877 for why) I would prefer package
options to be named with `with-<package>` or even just Gentoo-like
`use-<package>` scheme (because they are exactly like Gentoo use flags
as #12877 says).
|
This is not the currently used convention. This pull request is more or less an unopinionated description of the currently used convention. And if one wants to change the convention itself, that should probably be separate from this pull request. I admit I was wrong too, in my previous comment. I now also think that using dashed names for almost all attribute names except where it makes sense not to do so is a good idea, that our suffixes should be in camel case, like they currently are, and that camel case for options is nice and makes it easy to distinguish options from derivations. |
So, lately I've been entertaining myself by thinking about package attribute and module names. There is, from what I can tell, a general agreement about these but I was thinking it may be good to clarify it in the documentation. So, I put together this PR to try to roughly codify the current convention as I understand it.
My understanding comes from these observations:
The 12.1. Syntax section of the Nixpkgs manual states
It also says
In 12.2. Package naming it says
which I've taken to hold also for package attribute names but I don't know if the above text actually states this. Especially considering the TODO mentioned previously.
The issue tracker includes some discussions about attribute naming and my feeling is that there is a general consensus that package attribute names should be hyphenated. See, e.g., Rename
inotifyToolstoinotify-tools#9456.For NixOS modules I haven't been able to find any authoritative source for naming modules. Looking at the names in NixOS today it seems clear that camel case is used in general but the hyphenated style is used whenever a specific package is referenced.
For example, we have
services.dd-agent.jmxConfig(and interestingly alsoservices.dd-agent.api_key).I found one example of moving from a hyphenated to a "camelized" module name. Namely, programs.zsh: rename oh-my-zsh to ohMyZsh #26083, where
programs.zsh.oh-my-zshwas aliased toprograms.zsh.ohMyZsh. Are there further examples? This is relatively recent so would this indicate a emerging preference? In my PR I have followed the more common hyphenated style.