Open sliedes opened 1 month ago
The Synopsis is given as nix eval [option...] installable, which I think is actually not correct for many forms of the command; in the given example of nix eval --expr '1 + 2', I believe '1 + 2' is an argument to --expr, and there is no installable, of which there should be exactly one according to the Synapsis.
As you point out, the term "installable" is incredibly ill-defined, but in current usage in both implementation and documentation, I'm sorry to say that --expr '1 +2'
is an installable — like, the whole thing together. In fact, even /nix/store/xsqpns8p3czs19dcsl7iri48lqz2mlg9-neovim-0.10.0
is also an installable. The concept could definitely use some rework.
If you want an overview of the current reality of What Installables Are, and what the 'foo#bar' syntax means, we wrote an overview in the Lix docs, https://docs.lix.systems/manual/lix/stable/command-ref/new-cli/nix.html#installables, which explains the different forms installables can take and their syntaxes
Problem/background/motivation
I was reading the
nix eval
manual: https://nix.dev/manual/nix/2.23/command-ref/new-cli/nix3-eval. It had this text:I have been aware of this
something#something
syntax, but never quite understood what it is (and if it's a Nix expression—now I know it's not—and how I could evaluatelib.version + "-foo"
).I wanted to do a web search for information, but the man page gives fairly little to go on with. Things that confused me:
nixpkgs#lib.version
apparently is not.nix eval [option...] _installable_
, which I think is actually not correct for many forms of the command; in the given example ofnix eval --expr '1 + 2'
, I believe'1 + 2'
is an argument to--expr
, and there is no installable, of which there should be exactly one according to the Synapsis.nixpkgs#lib.version
syntax is. Is the second part a Nix expression? (I now know it's not.) What's the first part? It's not really given a name, unless "installable" is that name, but I find it hard to believe thatnixpkgs#lib.version
is an installable. I asked in the NixOS channel, and names like "flake URI" and "attr-path, but not really" got also thrown around.Proposal
I've been told that multiple Nix tools use a syntax like this (although I'm not sure I can name many). I think it should be given a formal, unified name, and that name should be used in the documentation. Now, maybe it's installable, though it seems like a very confusing name if that's it.
Perhaps something like BNF crould be used in the manpage; that probably would have resolved my next question of whether I can replace
lib.version
with any Nix expression. Something like:This would have the advantage of allowing me to do a web search for the individual parts (here "flake" and "attr-path") to figure out what I can put in them.
Checklist