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.

Sign up for GitHub

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

move details on channels into the dedicated page #11434

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

move details on channels into the dedicated page #11434

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a7cdc90
move details on channels into the dedicated page
fricklerhandwerk Sep 5, 2024
21ea502
wording
fricklerhandwerk Sep 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 28 additions & 13 deletions doc/manual/src/command-ref/files/channels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,41 @@
## Channels

A directory containing symlinks to Nix channels, managed by [`nix-channel`]:

- `$XDG_STATE_HOME/nix/profiles/channels` for regular users
- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`

[`nix-channel`] uses a [profile](@docroot@/command-ref/files/profiles.md) to store channels.
This profile contains symlinks to the contents of those 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.
Comment on lines +13 to +14
Copy link
Member

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.

Suggested change
> The state of a subscribed channel is external to the Nix expressions relying on it.
> This may limit reproducibility.
> The state of a subscribed channel is external to the Nix expressions relying on it.
> This limits reproducibility, and may be a reason to use a lock file instead of channels.

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.

Copy link
Contributor Author

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.

Copy link
Member

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.

>
> 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
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
> 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

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.

  • nix-channel
  • FODs, best fed to derivations
  • builtin fetchers, best fed to import and friends

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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 modifying the value of [lookup paths](@docroot@/language/constructs/lookup-path.md)

## Subscribed channels

The list of subscribed channels is stored in
The list of subscribed channels is stored in a file:

- `~/.nix-channels`
- `$XDG_STATE_HOME/nix/channels` if [`use-xdg-base-directories`] is set to `true`
- `$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`

in the following format:
Each line maps a channel name to a URL in the following format:

```
<url> <name>
...
```

[`nix-channel`]: @docroot@/command-ref/nix-channel.md
[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
## 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
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
- `$XDG_STATE_HOME/nix/profiles/channels` for regular users
- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`
- profile `$XDG_STATE_HOME/nix/profiles/channels` for regular users
- profile `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`

Copy link
Contributor Author

@fricklerhandwerk fricklerhandwerk Sep 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

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.
24 changes: 6 additions & 18 deletions doc/manual/src/command-ref/nix-channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,19 @@
# Name

`nix-channel` - manage Nix channels
`nix-channel` - manage [channels](#channels)

# Synopsis

`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--list-generations` | `--rollback` [*generation*] }

# Description

Channels are a mechanism for referencing remote Nix expressions and conveniently retrieving their latest version.
This command allows
- Managing a list of [subscribed channels](#subscribed-channels)
- Retrieval of the [contents](#channel-contents) of subscribed channels
- Restoring the contents of channels to previously retrieved versions

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](#channels)
- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-i) or the [`NIX_PATH` environment variable](#env-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
> - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations

This command has the following operations:
It has the following operations:

- `--add` *url* \[*name*\]

Expand Down
Loading