Improve local-overlay docs in a few ways

[Ericson2314]

Motivation

@pwaller, let me know if this helps, and what I can change further!

Context

In response to https://discourse.nixos.org/t/super-colliding-nix-stores/28462/24

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/super-colliding-nix-stores/28462/25

[pwaller]

I'm still a bit puzzled by what .real is and whether it's separate from lower-store, and whether it is an internal detail or one exposed to the user. A usage example might help elucidate this.

[pwaller]

This does improve things a bit for me.

This sentence confuses things for me, and suggests I'm missing something:

"depending on the type of lower store chosen"

I presume this refers to: https://nixos.org/manual/nix/unstable/store/types/

But I can't see how any type of lower store makes sense other than the local store, other than perhaps the mounted-ssh-store, or some daemon socket. Again I wonder if some usage examples would help.

I'm interested in the usecase of providing a fuse or automounter filesystem as the lower layer which auto-unpacks nar files from a binary cache on access for example. Which it seems like I should be able to achieve, but I'm a little unclear on how you might provide the metadata for this concept, or if it's even possible/straightforward without significant additional changes to nix.

[Ericson2314]

I'm still a bit puzzled by what .real is and whether it's separate from lower-store

The current syntax sucks: local store takes another URL, so what we have is a "query param within a query param". I hope there will be better syntax for this eventually; see #8373 . I guess that makes this dotted syntax somewhat aspirational in the meantime.

other than perhaps the mounted-ssh-store, or some daemon socket.

Yes, those are valid other options!

I'm interested in the usecase of providing a fuse or automounter filesystem as the lower layer which auto-unpacks nar files from a binary cache on access for example. Which it seems like I should be able to achieve, but I'm a little unclear on how you might provide the metadata for this concept, or if it's even possible/straightforward without significant additional changes to nix.

It's very doable. Internally the lower story is any store which subclasses LocalFSStore, so you can implement the missing methods however you want. One can also reuse unix:// / mounted-ssh-ng:// as clients (no new C++) and implement the daemon protocol. See also #9551