move details on channels into the dedicated page #11434
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| @@ -1,26 +1,41 @@ | ||||||||||
| ## Channels | ||||||||||
|
|
||||||||||
| Channels are a mechanism for obtaining Nix expressions over the web. | ||||||||||
|
|
||||||||||
| The moving parts of channels are: | ||||||||||
| - The official channels listed at <https://nixos.org/channels> | ||||||||||
| - The user-specific list of [subscribed channels](#subscribed-channels) | ||||||||||
| - The [downloaded channel contents](#channel-contents) | ||||||||||
| - The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path) | ||||||||||
|
|
||||||||||
| > **Note** | ||||||||||
| > | ||||||||||
| > The state of a subscribed channel is external to the Nix expressions relying on it. | ||||||||||
| > This may limit reproducibility. | ||||||||||
| > | ||||||||||
| > Dependencies on other Nix expressions can be declared explicitly with: | ||||||||||
| > - [`fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl), [`fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball), or [`fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) in Nix expressions | ||||||||||
|
Comment on lines
+16
to
+17
There was a problem hiding this comment.
Suggested change
This is going off topic. The answer to "how do I fetch?" should probably not be on the Channels page, and mention all options, not just the eval-time fetchers.
There was a problem hiding this comment. There's NixOS/nix.dev#750 to address this, which needs some focus time to write down cleanly. I agree this would not be about channels but essentially a concept page. |
||||||||||
| > - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations for explicitly determining the value of [lookup paths](@docroot@/language/constructs/lookup-path.md) | ||||||||||
fricklerhandwerk marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
|
||||||||||
| ## Subscribed channels | ||||||||||
|
|
||||||||||
| The list of subscribed channels is stored in a file: | ||||||||||
|
|
||||||||||
| - `~/.nix-channels` | ||||||||||
| - `$XDG_STATE_HOME/nix/channels` if [`use-xdg-base-directories`](@docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories) is set to `true` | ||||||||||
|
|
||||||||||
| Each line maps a channel name to a URL in the following format: | ||||||||||
|
|
||||||||||
| ``` | ||||||||||
| <url> <name> | ||||||||||
| ``` | ||||||||||
|
|
||||||||||
| ## Channels contents | ||||||||||
|
|
||||||||||
| The [`nix-channel`](@docroot@/command-ref/nix-channel.md) command uses a [profile](@docroot@/command-ref/files/profiles.md) to keep track of channels: | ||||||||||
|
|
||||||||||
| - `$XDG_STATE_HOME/nix/profiles/channels` for regular users | ||||||||||
| - `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root` | ||||||||||
|
Comment on lines
+37
to
+38
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. I'm not sure what this is supposed to achieve 🤔 |
||||||||||
|
|
||||||||||
| Each generation of that profile is a directory with symlinks to channel contents. | ||||||||||
| Each entry in this directory corresponds to the name of a [subscribed channel](#subscribed-channels) at that time. | ||||||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can confidently state that this is a problem for reproducibility and make it slightly more actionable.
I would like to link a resource that helps with deciding the kind of lock file, but I don't want to derail this review, so I'd prefer to settle for an incremental improvement here, as far as my input is concerned. I'd be happy to accept a suggestion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We'd be opening up quite the rabbit hole here. I generally agree with the direction, but my aspiration would be to point people to The Right Way of doing things, and that to my knowledge still doesn't exist. The current version says something that is at least not wrong: use fetchers explicitly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess a pin is not necessarily in a lock file. Fair enough.
We could confidently say that pinning and/or locking is The Right Way, but it might be a distraction.
Initially I thought nix.dev had a suitable article about this, but they seem to be about specific solutions, which is good for tutorials; was looking for a guide.
Let's not get ourselves stuck on this and fill this gap later.