Document (and (re?)name) the "installable" concept in e.g. `nix eval`

[sliedes]

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:

  · Get the current version of the nixpkgs flake:
    
      | # nix eval --raw nixpkgs#lib.version

  · Print the store path of the Hello package:
    
      | # nix eval --raw nixpkgs#hello

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 evaluate lib.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:

• The command description says "evaluate a Nix expression", which nixpkgs#lib.version apparently is not.
• 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.
• I am left baffled about what this 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 that nixpkgs#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:

nix eval <some-name>

<some-name> ::= <flake> "#" <attr-path>
<attr-path> ::= ...

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

• checked latest Nix manual (source)
• checked open documentation issues and pull requests for possible duplicates

[Qyriad]

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