Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update lookup-path.md #11276

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update lookup-path.md #11276

wants to merge 1 commit into from

Conversation

toraritte
Copy link
Contributor

Motivation

Updated this entry with 2 sentence taken from the nix.dev tutorial's lookup paths section as that resource makes it way easier to understand this concept.

Also added "file system" in front of "path value" because I found it an important clarification as "path" is an overloaded term.

Context

Trivial change; providing minor clarification.

Priorities and Process

Add 👍 to pull requests you find important.

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

Updated this entry with 2 sentence taken from the `nix.dev` tutorial's [lookup paths](https://nix.dev/tutorials/nix-language#lookup-paths) section as that resource makes it way easier to understand this concept.

Also added "_file system_" in front of "_path value_" because I found it an important clarification as "_path_" is an overloaded term.
@@ -4,14 +4,16 @@
>
> *lookup-path* = `<` *identifier* [ `/` *identifier* ]... `>`

A lookup path is an identifier with an optional path suffix that resolves to a [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.
A lookup path is an identifier with an optional path suffix that resolves to a file system [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also added "file system" in front of "path value" because I found it an important clarification as "path" is an overloaded term.

I understand the desire, but they won't have to point to the actual file system, so this addition could be misinterpreted as a restriction on which kinds of path values are ok to resolve to. While it currently somewhat accurate, it certainly won't be after either of:

Suggested change
A lookup path is an identifier with an optional path suffix that resolves to a file system [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.
A lookup path is an identifier with an optional path suffix that resolves to a [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.


The value of a lookup path is determined by [`builtins.nixPath`](@docroot@/language/builtins.md#builtins-nixPath).

See [`builtins.findFile`](@docroot@/language/builtins.md#builtins-findFile) for details on lookup path resolution.

> **Example**
>
> Generally, `<nixpkgs>` points to the file system path of some revision of [Nixpkgs](https://nix.dev/reference/glossary#term-Nixpkgs).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Generally, `<nixpkgs>` points to the file system path of some revision of [Nixpkgs](https://nix.dev/reference/glossary#term-Nixpkgs).
> Generally, if `<nixpkgs>` exists, it points to the file system path of some revision of [Nixpkgs](https://nix.dev/reference/glossary#term-Nixpkgs).

@@ -20,6 +22,8 @@ See [`builtins.findFile`](@docroot@/language/builtins.md#builtins-findFile) for

> **Example**
>
> `<nixpkgs/lib>` points to the subdirectory `nixos` of the file system path `<nixpkgs>` points to:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you meant

Suggested change
> `<nixpkgs/lib>` points to the subdirectory `nixos` of the file system path `<nixpkgs>` points to:
> `<nixpkgs/nixos>` points to the subdirectory `nixos` of the file system path `<nixpkgs>` points to:

@fricklerhandwerk
Copy link
Contributor

I understand this is a confusing corner of the landscape, and we're in the process of further clarifying the lookup path mechanism and making the information easier to find. The example in the current form is certainly not ideal, but I think that, right now, trying to add more contextual information raises the amount of pedantry required to keep it correct beyond what's practical.

In the nix.dev tutorial we're free to be vague on the details in order to orient users. Here we must be precise, and for the sake of efficiency I suggest we focus on just that, which is why I also suggest to close this PR and keep in mind that this particular part still needs polish.

@roberth
Copy link
Member

roberth commented Aug 13, 2024

@fricklerhandwerk are you sure? I don't see how adding context makes it less precise. Less dense perhaps, but also more useful.

This decision feels too dogmatic. How are users supposed to find that information if they landed on "the authoritative Nix documentation" (my words, unfortunately not accurate) and it isn't there?

we're in the process of further clarifying the lookup path mechanism

I feel like it's pretty complete in terms of reference documentation, not just because we should steer people away from it. If anything is missing it's the context: what users need to know in practice in a world where channels and NIX_PATH are on the way out. I'm not a fan of undocumenting things, but focusing on the "need to know" things is exactly what a de facto soft-deprecated feature needs. (Plus some recommendations not to use it)

@roberth
Copy link
Member

roberth commented Aug 13, 2024

@fricklerhandwerk
Copy link
Contributor

Are these issues up to date? https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+NIX_PATH+label%3Adocumentation

Pretty much, yes. The top ones also document what needs to be done for better discoverability and completeness. I opened #11288 to finally address one of them.

what users need to know in practice in a world where channels and NIX_PATH are on the way out. [...] focusing on the "need to know" things is exactly what a de facto soft-deprecated feature needs.

That's what I'm aiming at, too. But maybe we can be more precise here rather than saying "if this and that exists, maybe we get a value"?

How can @toraritte help with this?

There's an information gap in how the contents of what <nixpkgs> resolves to come into being -- that's done by the installer, but we never say that. Adding that bit somewhere (maybe writing down the details on one of the installer pages and linking from this page to there) would help a lot to demystify what's going on. Then we don't need to be fuzzy about it any more.

By the way, me closing a PR is not a final verdict. Feel free to re-open it if you have a strong opinion.

@roberth
Copy link
Member

roberth commented Aug 13, 2024

I think the latter two edits are good additions.

me closing a PR is not a final verdict.

It does look that way though. I wouldn't have guessed that.

Maybe marking as draft would be ok in a situation like this, when also giving context for it, but more importantly we should try to make feedback actionable one way or another.

@roberth roberth reopened this Aug 13, 2024
@toraritte
Copy link
Contributor Author

Yes, I should have either a draft PR or ask first, I'm sorry. I thought that I firm grasp of the basics, but skipping almost a year in Nix/OS seems to mean that I have missed quite a lot - but that's a good thing that things are moving ahead so quickly! Thank you for both of your work!

@fricklerhandwerk
Copy link
Contributor

#11437 addresses some of #11276 (comment)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants