From 8a93b5a55184d9d34effdd94d58429c9ad1a3d14 Mon Sep 17 00:00:00 2001 From: Alexander Bantyev Date: Fri, 17 Feb 2023 21:57:15 +0400 Subject: Document user files of nix --- doc/manual/local.mk | 7 + doc/manual/src/SUMMARY.md.in | 5 +- doc/manual/src/command-ref/files/channels.md | 26 ++ .../command-ref/files/default-nix-expression.md | 52 ++++ .../src/command-ref/files/user-profile-link.md | 16 ++ doc/manual/src/command-ref/files/user-profiles.md | 273 +++++++++++++++++++++ doc/manual/src/command-ref/nix-channel.md | 31 +-- doc/manual/src/command-ref/nix-env.md | 46 +--- 8 files changed, 385 insertions(+), 71 deletions(-) create mode 100644 doc/manual/src/command-ref/files/channels.md create mode 100644 doc/manual/src/command-ref/files/default-nix-expression.md create mode 100644 doc/manual/src/command-ref/files/user-profile-link.md create mode 100644 doc/manual/src/command-ref/files/user-profiles.md (limited to 'doc') diff --git a/doc/manual/local.mk b/doc/manual/local.mk index 63e7e61e4..94efe3536 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -11,6 +11,7 @@ man-pages := $(foreach n, \ nix-prefetch-url.1 nix-channel.1 \ nix-hash.1 nix-copy-closure.1 \ nix.conf.5 nix-daemon.8 \ + nix-user-profiles.5 \ , $(d)/$(n)) # man pages for subcommands @@ -85,6 +86,12 @@ $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ @rm $^.tmp +$(d)/nix-user-profiles.5: $(d)/src/command-ref/files/user-profiles.md + @printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp + @cat $^ >> $^.tmp + $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ + @rm $^.tmp + $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md @cp $< $@ @$(call process-includes,$@,$@) diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index f783d5908..1dbd15742 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -91,7 +91,10 @@ {{#include ./command-ref/new-cli/SUMMARY.md}} - [Files](command-ref/files.md) - [nix.conf](command-ref/conf-file.md) -- [Architecture](architecture/architecture.md) + - [User profiles](command-ref/files/user-profiles.md) + - [Channels](command-ref/files/channels.md) + - [Default Nix expression](command-ref/files/default-nix-expression.md) +- [Archititecture](architecture.md) - [Glossary](glossary.md) - [Contributing](contributing/contributing.md) - [Hacking](contributing/hacking.md) diff --git a/doc/manual/src/command-ref/files/channels.md b/doc/manual/src/command-ref/files/channels.md new file mode 100644 index 000000000..6ef2527e5 --- /dev/null +++ b/doc/manual/src/command-ref/files/channels.md @@ -0,0 +1,26 @@ +# Channels + +A directory containing symlinks to Nix channels, managed by [`nix-channel`]. + +- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root` +- `$XDG_STATE_HOME/nix/profiles/channels` for regular users + +[`nix-channel`] uses a [profile](@docroot@/command-ref/files/user-profiles.md) to store channels. +This profile contains symlinks to the contents of those channels. + +## Subscribed channels + +The list of subscribed channels is stored in + +- `~/.nix-channels` +- `$XDG_STATE_HOME/nix/channels` if [`use-xdg-base-directories`] is set to `true` + +in the following format: + +``` + +... +``` + +[`nix-channel`]: @docroot@/command-ref/nix-channel.md +[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories diff --git a/doc/manual/src/command-ref/files/default-nix-expression.md b/doc/manual/src/command-ref/files/default-nix-expression.md new file mode 100644 index 000000000..54b1101ed --- /dev/null +++ b/doc/manual/src/command-ref/files/default-nix-expression.md @@ -0,0 +1,52 @@ +# Default Nix expression + +The source for the default [Nix expressions](@docroot@/language/index.md) used by [`nix-env`]. + +- `~/.nix-defexpr` +- `$XDG_STATE_HOME/nix/defexpr` if [`use-xdg-base-directories`] is set to `true`. + +It is loaded as follows: + +- If the default expression is a file, it is loaded as a Nix expression. +- If the default expression is a directory containing a `default.nix` file, that `default.nix` file is loaded as a Nix expression. +- If the default expression is a directory without a `default.nix` file, then its contents (both files and subdirectories) are loaded as Nix expressions. + The expressions are combined into a single attribute set, each expression under an attribute with the same name as the original file or subdirectory. + Subdirectories without a `default.nix` file are traversed recursively in search of more Nix expressions, but the names of these intermediate directories are not added to the attribute paths of the default Nix expression. + +Then, the resulting expression is interpreted like this: + +- If the expression is an attribute set, it is used as the default Nix expression. +- If the expression is a function, an empty set is passed as argument and the return value is used as the default Nix expression. + + +For example, if the default expression contains two files, `foo.nix` and `bar.nix`, then the default Nix expression will be equivalent to + +```nix +{ + foo = import ~/.nix-defexpr/foo.nix; + bar = import ~/.nix-defexpr/bar.nix; +} +``` + +The file `manifest.nix` is always ignored. + +The command [`nix-channel`] places a symlink to the user's current [channels profile](@docroot@/command-ref/files/channels.md) in this directory. +This makes all subscribed channels available as attributes in the default expression. + +## User channel link + +A symlink that ensures that [`nix-env`] can find your channels. + +- `~/.nix-defexpr/channels` +- `$XDG_STATE_HOME/defexpr/channels` if [`use-xdg-base-directories`] is set to `true`. + +This symlink points to: + +- `$XDG_STATE_HOME/profiles/channels` for regular users +- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root` + +In a multi-user installation, you may also have `~/.nix-defexpr/channels_root`, which links to the channels of the root user.[`nix-env`]: ../nix-env.md + +[`nix-env`]: @docroot@/command-ref/nix-env.md +[`nix-channel`]: @docroot@/command-ref/nix-channel.md +[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories diff --git a/doc/manual/src/command-ref/files/user-profile-link.md b/doc/manual/src/command-ref/files/user-profile-link.md new file mode 100644 index 000000000..439446b40 --- /dev/null +++ b/doc/manual/src/command-ref/files/user-profile-link.md @@ -0,0 +1,16 @@ +# User profile link + +A symbolic link to the user's current profile. + +- `~/.nix-profile` +- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. + +By default, this symlink points to: + +- `$XDG_STATE_HOME/nix/profiles/default` for regular users +- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` + +The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. +The [installer](@docroot@/installation/installing-binary.md) sets this up by default. + +[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md new file mode 100644 index 000000000..f3d28266a --- /dev/null +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -0,0 +1,273 @@ +# User profiles + +A directory that contains links to user profiles managed by [`nix-env`] and [`nix profile`]. + +- `$NIX_STATE_DIR/profiles/per-user/root` if the user is `root` +- `$XDG_STATE_HOME/nix/profiles` otherwise + +A profile is a directory of symlinks to files in the Nix store. + +## Profile compatibility + +> **Warning** +> +> `nix profile` is experimental. +> Once you have used `nix profile` you can no longer use `nix-env` without first deleting `$XDG_STATE_HOME/nix/profiles/profile` + +Once you installed a package with `nix profile`, you get the following +error message when using `nix-env`: + +```console +$ nix-env -f '' -iA 'hello' +error: --- Error ----------------------------------------------------------------------------------------------------------------- nix-env +profile '/home/alice/.local/state/nix/profiles/profile' is incompatible with 'nix-env'; please use 'nix profile' instead +``` + +To migrate back to `nix-env` you can delete your current profile: + +> **Warning** +> +> This will delete packages that have been installed before, so you may want to back this information before running the command. + +```console + $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile" +``` + +## Filesystem layout + +Profiles are versioned as follows. When using profile *path*, *path* +is a symlink to *path*`-`*N*, where *N* is the current *version* of +the profile. In turn, *path*`-`*N* is a symlink to a path in the Nix +store. For example: + +```console +$ ls -l ~alice/.local/state/nix/profiles/profile* +lrwxrwxrwx 1 alice users 14 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile -> profile-7-link +lrwxrwxrwx 1 alice users 51 Oct 28 16:18 /home/alice/.local/state/nix/profiles/profile-5-link -> /nix/store/q69xad13ghpf7ir87h0b2gd28lafjj1j-profile +lrwxrwxrwx 1 alice users 51 Oct 29 13:20 /home/alice/.local/state/nix/profiles/profile-6-link -> /nix/store/6bvhpysd7vwz7k3b0pndn7ifi5xr32dg-profile +lrwxrwxrwx 1 alice users 51 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile-7-link -> /nix/store/mp0x6xnsg0b8qhswy6riqvimai4gm677-profile +``` + +Each of these symlinks is a root for the Nix garbage collector. + +The contents of the store path corresponding to each version of the +profile is a tree of symlinks to the files of the installed packages, +e.g. + +```console +$ ll -R ~eelco/.local/state/nix/profiles/profile-7-link/ +/home/eelco/.local/state/nix/profiles/profile-7-link/: +total 20 +dr-xr-xr-x 2 root root 4096 Jan 1 1970 bin +-r--r--r-- 2 root root 1402 Jan 1 1970 manifest.json +dr-xr-xr-x 4 root root 4096 Jan 1 1970 share + +/home/eelco/.local/state/nix/profiles/profile-7-link/bin: +total 20 +lrwxrwxrwx 5 root root 79 Jan 1 1970 chromium -> /nix/store/ijm5k0zqisvkdwjkc77mb9qzb35xfi4m-chromium-86.0.4240.111/bin/chromium +lrwxrwxrwx 7 root root 87 Jan 1 1970 spotify -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/bin/spotify +lrwxrwxrwx 3 root root 79 Jan 1 1970 zoom-us -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/bin/zoom-us + +/home/eelco/.local/state/nix/profiles/profile-7-link/share/applications: +total 12 +lrwxrwxrwx 4 root root 120 Jan 1 1970 chromium-browser.desktop -> /nix/store/4cf803y4vzfm3gyk3vzhzb2327v0kl8a-chromium-unwrapped-86.0.4240.111/share/applications/chromium-browser.desktop +lrwxrwxrwx 7 root root 110 Jan 1 1970 spotify.desktop -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/share/applications/spotify.desktop +lrwxrwxrwx 3 root root 107 Jan 1 1970 us.zoom.Zoom.desktop -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/share/applications/us.zoom.Zoom.desktop + +… +``` + +## Manifest + +The manifest file records the provenance of the packages that are installed in this version of the profile. +It is different between [`nix-env`] and [`nix profile`]. + +### `manifest.nix` + +Used by [`nix-env`]. This is an example of how this file might look like after installing `hello` from nixpkgs. + +```nix +[{ + meta = { + available = true; + broken = false; + changelog = + "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v2.12.1"; + description = "A program that produces a familiar, friendly greeting"; + homepage = "https://www.gnu.org/software/hello/manual/"; + insecure = false; + license = { + deprecated = false; + free = true; + fullName = "GNU General Public License v3.0 or later"; + redistributable = true; + shortName = "gpl3Plus"; + spdxId = "GPL-3.0-or-later"; + url = "https://spdx.org/licenses/GPL-3.0-or-later.html"; + }; + longDescription = '' + GNU Hello is a program that prints "Hello, world!" when you run it. + It is fully customizable. + ''; + maintainers = [{ + email = "edolstra+nixpkgs@gmail.com"; + github = "edolstra"; + githubId = 1148549; + name = "Eelco Dolstra"; + }]; + name = "hello-2.12.1"; + outputsToInstall = [ "out" ]; + platforms = [ + "i686-cygwin" + "x86_64-cygwin" + "x86_64-darwin" + "i686-darwin" + "aarch64-darwin" + "armv7a-darwin" + "i686-freebsd13" + "x86_64-freebsd13" + "aarch64-genode" + "i686-genode" + "x86_64-genode" + "x86_64-solaris" + "js-ghcjs" + "aarch64-linux" + "armv5tel-linux" + "armv6l-linux" + "armv7a-linux" + "armv7l-linux" + "i686-linux" + "m68k-linux" + "microblaze-linux" + "microblazeel-linux" + "mipsel-linux" + "mips64el-linux" + "powerpc64-linux" + "powerpc64le-linux" + "riscv32-linux" + "riscv64-linux" + "s390-linux" + "s390x-linux" + "x86_64-linux" + "mmix-mmixware" + "aarch64-netbsd" + "armv6l-netbsd" + "armv7a-netbsd" + "armv7l-netbsd" + "i686-netbsd" + "m68k-netbsd" + "mipsel-netbsd" + "powerpc-netbsd" + "riscv32-netbsd" + "riscv64-netbsd" + "x86_64-netbsd" + "aarch64_be-none" + "aarch64-none" + "arm-none" + "armv6l-none" + "avr-none" + "i686-none" + "microblaze-none" + "microblazeel-none" + "msp430-none" + "or1k-none" + "m68k-none" + "powerpc-none" + "powerpcle-none" + "riscv32-none" + "riscv64-none" + "rx-none" + "s390-none" + "s390x-none" + "vc4-none" + "x86_64-none" + "i686-openbsd" + "x86_64-openbsd" + "x86_64-redox" + "wasm64-wasi" + "wasm32-wasi" + "x86_64-windows" + "i686-windows" + ]; + position = + "/nix/store/7niq32w715567hbph0q13m5lqna64c1s-nixos-unstable.tar.gz/nixos-unstable.tar.gz/pkgs/applications/misc/hello/default.nix:34"; + unfree = false; + unsupported = false; + }; + name = "hello-2.12.1"; + out = { + outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1"; + }; + outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1"; + outputs = [ "out" ]; + system = "x86_64-linux"; + type = "derivation"; +}] +``` + +Each element in this list corresponds to an installed package. +It incorporates some attributes of the original package derivation, including `meta`, `name`, `out`, `outPath`, `outputs`, `system`. +This is used by Nix for querying and updating the package. + +### `manifest.json` + +Used by [`nix profile`]. This is an example of what the file might look like after installing `zoom-us` from nixpkgs: + +```json +{ + "version": 1, + "elements": [ + { + "active": true, + "attrPath": "legacyPackages.x86_64-linux.zoom-us", + "originalUrl": "flake:nixpkgs", + "storePaths": [ + "/nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927" + ], + "uri": "github:NixOS/nixpkgs/13d0c311e3ae923a00f734b43fd1d35b47d8943a" + }, + … + ] +} +``` + +Each object in the array `elements` denotes an installed package and +has the following fields: + +* `originalUrl`: The [flake reference](@docroot@/command-ref/new-cli/nix3-flake.md) specified by + the user at the time of installation (e.g. `nixpkgs`). This is also + the flake reference that will be used by `nix profile upgrade`. + +* `uri`: The locked flake reference to which `originalUrl` resolved. + +* `attrPath`: The flake output attribute that provided this + package. Note that this is not necessarily the attribute that the + user specified, but the one resulting from applying the default + attribute paths and prefixes; for instance, `hello` might resolve to + `packages.x86_64-linux.hello` and the empty string to + `packages.x86_64-linux.default`. + +* `storePath`: The paths in the Nix store containing the package. + +* `active`: Whether the profile contains symlinks to the files of this + package. If set to false, the package is kept in the Nix store, but + is not "visible" in the profile's symlink tree. + +## User profile link + +A symbolic link to the user's current profile. + +- `~/.nix-profile` +- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. + +By default, this symlink points to: + +- `$XDG_STATE_HOME/nix/profiles/profile` for regular users +- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` + +The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. +The [installer](@docroot@/installation/installing-binary.md) sets this up by default, unless you enable [`use-xdg-base-directories`]. + +[`nix-env`]: @docroot@/command-ref/nix-env.md +[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md +[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md index 2027cc98d..9f7246661 100644 --- a/doc/manual/src/command-ref/nix-channel.md +++ b/doc/manual/src/command-ref/nix-channel.md @@ -22,6 +22,9 @@ This command has the following operations: channels. If *name* is omitted, it defaults to the last component of *url*, with the suffixes `-stable` or `-unstable` removed. + A channel URL must point to a directory containing a file `nixexprs.tar.gz`. + At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point. + - `--remove` *name*\ Removes the channel named *name* from the list of subscribed channels. @@ -49,6 +52,7 @@ The list of subscribed channels is stored in `~/.nix-channels`. {{#include ./env-common.md}} + # Examples To subscribe to the Nixpkgs channel and install the GNU Hello package: @@ -71,30 +75,3 @@ switching from generation 483 to 482 $ nix-instantiate --eval -E '(import {}).lib.version' "14.04.526.dbadfad" ``` - -# Files - - - `${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/channels`\ - `nix-channel` uses a `nix-env` profile to keep track of previous - versions of the subscribed channels. Every time you run `nix-channel - --update`, a new channel generation (that is, a symlink to the - channel Nix expressions in the Nix store) is created. This enables - `nix-channel --rollback` to revert to previous versions. - - - `~/.nix-defexpr/channels`\ - This is a symlink to - `${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/channels`. It ensures that - `nix-env` can find your channels. In a multi-user installation, you - may also have `~/.nix-defexpr/channels_root`, which links to the - channels of the root user. - -# Channel format - -A channel URL should point to a directory containing the following -files: - - - `nixexprs.tar.xz`\ - A tarball containing Nix expressions and files referenced by them - (such as build scripts and patches). At the top level, the tarball - should contain a single directory. That directory must contain a - file `default.nix` that serves as the channel’s “entry point”. diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index 42b5bca77..09d699903 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -83,46 +83,6 @@ match. Here are some examples: # Files - - `~/.nix-defexpr`\ - The source for the default Nix expressions used by the - `--install`, `--upgrade`, and `--query --available` operations to - obtain derivations. The `--file` option may be used to override - this default. - - If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If - the expression is a set, it is used as the default Nix expression. - If the expression is a function, an empty set is passed as argument - and the return value is used as the default Nix expression. - - If `~/.nix-defexpr` is a directory containing a `default.nix` file, - that file is loaded as in the above paragraph. - - If `~/.nix-defexpr` is a directory without a `default.nix` file, - then its contents (both files and subdirectories) are loaded as Nix - expressions. The expressions are combined into a single set, each - expression under an attribute with the same name as the original - file or subdirectory. - - For example, if `~/.nix-defexpr` contains two files, `foo.nix` and - `bar.nix`, then the default Nix expression will essentially be - - ```nix - { - foo = import ~/.nix-defexpr/foo.nix; - bar = import ~/.nix-defexpr/bar.nix; - } - ``` - - The file `manifest.nix` is always ignored. Subdirectories without a - `default.nix` file are traversed recursively in search of more Nix - expressions, but the names of these intermediate directories are not - added to the attribute paths of the default Nix expression. - - The command `nix-channel` places symlinks to the downloaded Nix - expressions from each subscribed channel in this directory. - - - `~/.nix-profile`\ - A symbolic link to the user's current profile. By default, this - symlink points to `prefix/var/nix/profiles/default`. The `PATH` - environment variable should include `~/.nix-profile/bin` for the - user environment to be visible to the user. +{{#include ./files/default-nix-expression.md}} + +{{#include ./files/user-profiles.md}} \ No newline at end of file -- cgit v1.2.3 From a1c996dc7ea32563605c75eae6c209786ac3b9b2 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 10:56:35 +0200 Subject: list information regular users first this is to make it consistent everywhere --- doc/manual/src/command-ref/files/channels.md | 2 +- doc/manual/src/command-ref/files/user-profiles.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/channels.md b/doc/manual/src/command-ref/files/channels.md index 6ef2527e5..2d1c2c160 100644 --- a/doc/manual/src/command-ref/files/channels.md +++ b/doc/manual/src/command-ref/files/channels.md @@ -2,8 +2,8 @@ A directory containing symlinks to Nix channels, managed by [`nix-channel`]. -- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root` - `$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/user-profiles.md) to store channels. This profile contains symlinks to the contents of those channels. diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index f3d28266a..c054a7808 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -2,8 +2,8 @@ A directory that contains links to user profiles managed by [`nix-env`] and [`nix profile`]. +- `$XDG_STATE_HOME/nix/profiles` for regular users - `$NIX_STATE_DIR/profiles/per-user/root` if the user is `root` -- `$XDG_STATE_HOME/nix/profiles` otherwise A profile is a directory of symlinks to files in the Nix store. -- cgit v1.2.3 From 9d386fe2ee79d5fadea3c29559687bd0df4c8e5b Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 10:57:41 +0200 Subject: add colons to connect listings with descriptions --- doc/manual/src/command-ref/files/channels.md | 2 +- doc/manual/src/command-ref/files/default-nix-expression.md | 4 ++-- doc/manual/src/command-ref/files/user-profiles.md | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/channels.md b/doc/manual/src/command-ref/files/channels.md index 2d1c2c160..88db66165 100644 --- a/doc/manual/src/command-ref/files/channels.md +++ b/doc/manual/src/command-ref/files/channels.md @@ -1,6 +1,6 @@ # Channels -A directory containing symlinks to Nix channels, managed by [`nix-channel`]. +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` diff --git a/doc/manual/src/command-ref/files/default-nix-expression.md b/doc/manual/src/command-ref/files/default-nix-expression.md index 54b1101ed..daf21e56f 100644 --- a/doc/manual/src/command-ref/files/default-nix-expression.md +++ b/doc/manual/src/command-ref/files/default-nix-expression.md @@ -1,6 +1,6 @@ # Default Nix expression -The source for the default [Nix expressions](@docroot@/language/index.md) used by [`nix-env`]. +The source for the default [Nix expressions](@docroot@/language/index.md) used by [`nix-env`]: - `~/.nix-defexpr` - `$XDG_STATE_HOME/nix/defexpr` if [`use-xdg-base-directories`] is set to `true`. @@ -35,7 +35,7 @@ This makes all subscribed channels available as attributes in the default expres ## User channel link -A symlink that ensures that [`nix-env`] can find your channels. +A symlink that ensures that [`nix-env`] can find your channels: - `~/.nix-defexpr/channels` - `$XDG_STATE_HOME/defexpr/channels` if [`use-xdg-base-directories`] is set to `true`. diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index c054a7808..034743e7f 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -1,6 +1,6 @@ # User profiles -A directory that contains links to user profiles managed by [`nix-env`] and [`nix profile`]. +A directory that contains links to user profiles managed by [`nix-env`] and [`nix profile`]: - `$XDG_STATE_HOME/nix/profiles` for regular users - `$NIX_STATE_DIR/profiles/per-user/root` if the user is `root` @@ -84,7 +84,7 @@ It is different between [`nix-env`] and [`nix profile`]. ### `manifest.nix` -Used by [`nix-env`]. This is an example of how this file might look like after installing `hello` from nixpkgs. +Used by [`nix-env`]. Here is an example of how this file might look like after installing `hello` from Nixpkgs: ```nix [{ @@ -211,7 +211,7 @@ This is used by Nix for querying and updating the package. ### `manifest.json` -Used by [`nix profile`]. This is an example of what the file might look like after installing `zoom-us` from nixpkgs: +Used by [`nix profile`]. Here is an example of what the file might look like after installing `zoom-us` from Nixpkgs: ```json { @@ -255,7 +255,7 @@ has the following fields: ## User profile link -A symbolic link to the user's current profile. +A symbolic link to the user's current profile: - `~/.nix-profile` - `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. -- cgit v1.2.3 From 7770d82240ffecabf0022aee21e2ba62b6d11876 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 11:01:12 +0200 Subject: fix typos and wording --- doc/manual/src/command-ref/files/user-profiles.md | 7 +++---- doc/manual/src/command-ref/nix-channel.md | 1 - 2 files changed, 3 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index 034743e7f..9a9ec627b 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -14,8 +14,7 @@ A profile is a directory of symlinks to files in the Nix store. > `nix profile` is experimental. > Once you have used `nix profile` you can no longer use `nix-env` without first deleting `$XDG_STATE_HOME/nix/profiles/profile` -Once you installed a package with `nix profile`, you get the following -error message when using `nix-env`: +Once you installed a package with `nix profile`, you get the following error message when using `nix-env`: ```console $ nix-env -f '' -iA 'hello' @@ -27,7 +26,7 @@ To migrate back to `nix-env` you can delete your current profile: > **Warning** > -> This will delete packages that have been installed before, so you may want to back this information before running the command. +> This will delete packages that have been installed before, so you may want to back up this information before running the command. ```console $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile" @@ -207,7 +206,7 @@ Used by [`nix-env`]. Here is an example of how this file might look like after i Each element in this list corresponds to an installed package. It incorporates some attributes of the original package derivation, including `meta`, `name`, `out`, `outPath`, `outputs`, `system`. -This is used by Nix for querying and updating the package. +This information is used by Nix for querying and updating the package. ### `manifest.json` diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md index 9f7246661..72d3e422b 100644 --- a/doc/manual/src/command-ref/nix-channel.md +++ b/doc/manual/src/command-ref/nix-channel.md @@ -52,7 +52,6 @@ The list of subscribed channels is stored in `~/.nix-channels`. {{#include ./env-common.md}} - # Examples To subscribe to the Nixpkgs channel and install the GNU Hello package: -- cgit v1.2.3 From bb8e3b5d86635b318de7e2d24503eba4990d042e Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 13:57:42 +0200 Subject: update description on how profiles work adapt to the example listing --- doc/manual/src/command-ref/files/user-profiles.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index 9a9ec627b..6075bf125 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -34,10 +34,9 @@ To migrate back to `nix-env` you can delete your current profile: ## Filesystem layout -Profiles are versioned as follows. When using profile *path*, *path* -is a symlink to *path*`-`*N*, where *N* is the current *version* of -the profile. In turn, *path*`-`*N* is a symlink to a path in the Nix -store. For example: +Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile. +In turn, *path*`-`*N*`-link` is a symlink to a path in the Nix store. +For example: ```console $ ls -l ~alice/.local/state/nix/profiles/profile* -- cgit v1.2.3 From 219aaf5a0b78e09891557f15c16d3376d401c471 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 15:07:26 +0200 Subject: increase heading level otherwise the headings won't match at the point where they are included. this is a bit hacky and brittle, but works for now. --- doc/manual/src/command-ref/files/channels.md | 2 +- doc/manual/src/command-ref/files/default-nix-expression.md | 2 +- doc/manual/src/command-ref/files/user-profile-link.md | 2 +- doc/manual/src/command-ref/files/user-profiles.md | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/channels.md b/doc/manual/src/command-ref/files/channels.md index 88db66165..c680c747a 100644 --- a/doc/manual/src/command-ref/files/channels.md +++ b/doc/manual/src/command-ref/files/channels.md @@ -1,4 +1,4 @@ -# Channels +## Channels A directory containing symlinks to Nix channels, managed by [`nix-channel`]: diff --git a/doc/manual/src/command-ref/files/default-nix-expression.md b/doc/manual/src/command-ref/files/default-nix-expression.md index daf21e56f..1ce40f019 100644 --- a/doc/manual/src/command-ref/files/default-nix-expression.md +++ b/doc/manual/src/command-ref/files/default-nix-expression.md @@ -1,4 +1,4 @@ -# Default Nix expression +## Default Nix expression The source for the default [Nix expressions](@docroot@/language/index.md) used by [`nix-env`]: diff --git a/doc/manual/src/command-ref/files/user-profile-link.md b/doc/manual/src/command-ref/files/user-profile-link.md index 439446b40..1a7d15e44 100644 --- a/doc/manual/src/command-ref/files/user-profile-link.md +++ b/doc/manual/src/command-ref/files/user-profile-link.md @@ -1,4 +1,4 @@ -# User profile link +## User profile link A symbolic link to the user's current profile. diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index 6075bf125..4296d473c 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -1,4 +1,4 @@ -# User profiles +## User profiles A directory that contains links to user profiles managed by [`nix-env`] and [`nix profile`]: @@ -7,7 +7,7 @@ A directory that contains links to user profiles managed by [`nix-env`] and [`ni A profile is a directory of symlinks to files in the Nix store. -## Profile compatibility +### Profile compatibility > **Warning** > @@ -32,7 +32,7 @@ To migrate back to `nix-env` you can delete your current profile: $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile" ``` -## Filesystem layout +### Filesystem layout Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile. In turn, *path*`-`*N*`-link` is a symlink to a path in the Nix store. -- cgit v1.2.3 From be7c236565ae981a5b0f5a952bfb8380418cea41 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 15:37:08 +0200 Subject: move compatibility info to `nix profile` docs --- doc/manual/src/command-ref/files/user-profiles.md | 25 ----------------------- 1 file changed, 25 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index 4296d473c..1862caff8 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -7,31 +7,6 @@ A directory that contains links to user profiles managed by [`nix-env`] and [`ni A profile is a directory of symlinks to files in the Nix store. -### Profile compatibility - -> **Warning** -> -> `nix profile` is experimental. -> Once you have used `nix profile` you can no longer use `nix-env` without first deleting `$XDG_STATE_HOME/nix/profiles/profile` - -Once you installed a package with `nix profile`, you get the following error message when using `nix-env`: - -```console -$ nix-env -f '' -iA 'hello' -error: --- Error ----------------------------------------------------------------------------------------------------------------- nix-env -profile '/home/alice/.local/state/nix/profiles/profile' is incompatible with 'nix-env'; please use 'nix profile' instead -``` - -To migrate back to `nix-env` you can delete your current profile: - -> **Warning** -> -> This will delete packages that have been installed before, so you may want to back up this information before running the command. - -```console - $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile" -``` - ### Filesystem layout Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile. -- cgit v1.2.3 From da0dbf36cbf5aebe559af08d3b9a83b880af1673 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 26 Apr 2023 15:37:23 +0200 Subject: move manifest information to the bottom of the page --- .../command-ref/files/default-nix-expression.md | 2 +- doc/manual/src/command-ref/files/user-profiles.md | 38 +++++++++++----------- 2 files changed, 20 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/manual/src/command-ref/files/default-nix-expression.md b/doc/manual/src/command-ref/files/default-nix-expression.md index 1ce40f019..1c857b0b1 100644 --- a/doc/manual/src/command-ref/files/default-nix-expression.md +++ b/doc/manual/src/command-ref/files/default-nix-expression.md @@ -28,7 +28,7 @@ For example, if the default expression contains two files, `foo.nix` and `bar.ni } ``` -The file `manifest.nix` is always ignored. +The file [`manifest.nix`](@docroot@/command-ref/files/user-profiles.md#manifest.nix) is always ignored. The command [`nix-channel`] places a symlink to the user's current [channels profile](@docroot@/command-ref/files/channels.md) in this directory. This makes all subscribed channels available as attributes in the default expression. diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md index 1862caff8..be590883e 100644 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ b/doc/manual/src/command-ref/files/user-profiles.md @@ -50,6 +50,25 @@ lrwxrwxrwx 3 root root 107 Jan 1 1970 us.zoom.Zoom.desktop -> /nix/store/wbhg2 … ``` +## User profile link + +A symbolic link to the user's current profile: + +- `~/.nix-profile` +- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. + +By default, this symlink points to: + +- `$XDG_STATE_HOME/nix/profiles/profile` for regular users +- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` + +The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. +The [installer](@docroot@/installation/installing-binary.md) sets this up by default, unless you enable [`use-xdg-base-directories`]. + +[`nix-env`]: @docroot@/command-ref/nix-env.md +[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md +[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories + ## Manifest The manifest file records the provenance of the packages that are installed in this version of the profile. @@ -225,22 +244,3 @@ has the following fields: * `active`: Whether the profile contains symlinks to the files of this package. If set to false, the package is kept in the Nix store, but is not "visible" in the profile's symlink tree. - -## User profile link - -A symbolic link to the user's current profile: - -- `~/.nix-profile` -- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. - -By default, this symlink points to: - -- `$XDG_STATE_HOME/nix/profiles/profile` for regular users -- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` - -The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. -The [installer](@docroot@/installation/installing-binary.md) sets this up by default, unless you enable [`use-xdg-base-directories`]. - -[`nix-env`]: @docroot@/command-ref/nix-env.md -[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md -[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories -- cgit v1.2.3 From f8620758aad1e3b61bc2d10a913bfd07c6d21df6 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 27 Apr 2023 11:56:52 +0200 Subject: display documentation on manifest files separately it's probably better not to show the manifest file documentation in the command-specific pages, because these are implementation details that are not really practically useful. this means no additional hassle for building the manual, but clutters the table of contents a bit. --- doc/manual/local.mk | 4 +- doc/manual/src/SUMMARY.md.in | 4 +- doc/manual/src/command-ref/files/channels.md | 2 +- .../command-ref/files/default-nix-expression.md | 2 +- doc/manual/src/command-ref/files/manifest.json.md | 45 ++++ doc/manual/src/command-ref/files/manifest.nix.md | 128 +++++++++++ doc/manual/src/command-ref/files/profiles.md | 74 +++++++ .../src/command-ref/files/user-profile-link.md | 16 -- doc/manual/src/command-ref/files/user-profiles.md | 246 --------------------- doc/manual/src/command-ref/nix-env.md | 2 +- 10 files changed, 255 insertions(+), 268 deletions(-) create mode 100644 doc/manual/src/command-ref/files/manifest.json.md create mode 100644 doc/manual/src/command-ref/files/manifest.nix.md create mode 100644 doc/manual/src/command-ref/files/profiles.md delete mode 100644 doc/manual/src/command-ref/files/user-profile-link.md delete mode 100644 doc/manual/src/command-ref/files/user-profiles.md (limited to 'doc') diff --git a/doc/manual/local.mk b/doc/manual/local.mk index 94efe3536..b4b7283ef 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -11,7 +11,7 @@ man-pages := $(foreach n, \ nix-prefetch-url.1 nix-channel.1 \ nix-hash.1 nix-copy-closure.1 \ nix.conf.5 nix-daemon.8 \ - nix-user-profiles.5 \ + nix-profiles.5 \ , $(d)/$(n)) # man pages for subcommands @@ -86,7 +86,7 @@ $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ @rm $^.tmp -$(d)/nix-user-profiles.5: $(d)/src/command-ref/files/user-profiles.md +$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md @printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp @cat $^ >> $^.tmp $(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@ diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index 1dbd15742..17a4fe232 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -91,7 +91,9 @@ {{#include ./command-ref/new-cli/SUMMARY.md}} - [Files](command-ref/files.md) - [nix.conf](command-ref/conf-file.md) - - [User profiles](command-ref/files/user-profiles.md) + - [Profiles](command-ref/files/profiles.md) + - [manifest.nix](command-ref/files/manifest.nix.md) + - [manifest.json](command-ref/files/manifest.json.md) - [Channels](command-ref/files/channels.md) - [Default Nix expression](command-ref/files/default-nix-expression.md) - [Archititecture](architecture.md) diff --git a/doc/manual/src/command-ref/files/channels.md b/doc/manual/src/command-ref/files/channels.md index c680c747a..7b1f27128 100644 --- a/doc/manual/src/command-ref/files/channels.md +++ b/doc/manual/src/command-ref/files/channels.md @@ -5,7 +5,7 @@ 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/user-profiles.md) to store channels. +[`nix-channel`] uses a [profile](@docroot@/command-ref/files/profiles.md) to store channels. This profile contains symlinks to the contents of those channels. ## Subscribed channels diff --git a/doc/manual/src/command-ref/files/default-nix-expression.md b/doc/manual/src/command-ref/files/default-nix-expression.md index 1c857b0b1..620f7035c 100644 --- a/doc/manual/src/command-ref/files/default-nix-expression.md +++ b/doc/manual/src/command-ref/files/default-nix-expression.md @@ -28,7 +28,7 @@ For example, if the default expression contains two files, `foo.nix` and `bar.ni } ``` -The file [`manifest.nix`](@docroot@/command-ref/files/user-profiles.md#manifest.nix) is always ignored. +The file [`manifest.nix`](@docroot@/command-ref/files/manifest.nix.md) is always ignored. The command [`nix-channel`] places a symlink to the user's current [channels profile](@docroot@/command-ref/files/channels.md) in this directory. This makes all subscribed channels available as attributes in the default expression. diff --git a/doc/manual/src/command-ref/files/manifest.json.md b/doc/manual/src/command-ref/files/manifest.json.md new file mode 100644 index 000000000..bcfe7373d --- /dev/null +++ b/doc/manual/src/command-ref/files/manifest.json.md @@ -0,0 +1,45 @@ +## `manifest.json` + +The manifest file records the provenance of the packages that are installed in a [profile](./profiles.md) managed by [`nix profile`](@docroot@/command-ref/new-cli/nix3-profile.md) (experimental). + +Here is an example of what the file might look like after installing `zoom-us` from Nixpkgs: + +```json +{ + "version": 1, + "elements": [ + { + "active": true, + "attrPath": "legacyPackages.x86_64-linux.zoom-us", + "originalUrl": "flake:nixpkgs", + "storePaths": [ + "/nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927" + ], + "uri": "github:NixOS/nixpkgs/13d0c311e3ae923a00f734b43fd1d35b47d8943a" + }, + … + ] +} +``` + +Each object in the array `elements` denotes an installed package and +has the following fields: + +* `originalUrl`: The [flake reference](@docroot@/command-ref/new-cli/nix3-flake.md) specified by + the user at the time of installation (e.g. `nixpkgs`). This is also + the flake reference that will be used by `nix profile upgrade`. + +* `uri`: The locked flake reference to which `originalUrl` resolved. + +* `attrPath`: The flake output attribute that provided this + package. Note that this is not necessarily the attribute that the + user specified, but the one resulting from applying the default + attribute paths and prefixes; for instance, `hello` might resolve to + `packages.x86_64-linux.hello` and the empty string to + `packages.x86_64-linux.default`. + +* `storePath`: The paths in the Nix store containing the package. + +* `active`: Whether the profile contains symlinks to the files of this + package. If set to false, the package is kept in the Nix store, but + is not "visible" in the profile's symlink tree. diff --git a/doc/manual/src/command-ref/files/manifest.nix.md b/doc/manual/src/command-ref/files/manifest.nix.md new file mode 100644 index 000000000..d7d1b605b --- /dev/null +++ b/doc/manual/src/command-ref/files/manifest.nix.md @@ -0,0 +1,128 @@ +## `manifest.nix` + +The manifest file records the provenance of the packages that are installed in a [profile](./profiles.md) managed by [`nix-env`](@docroot@/command-ref/nix-env.md). + +Here is an example of how this file might look like after installing `hello` from Nixpkgs: + +```nix +[{ + meta = { + available = true; + broken = false; + changelog = + "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v2.12.1"; + description = "A program that produces a familiar, friendly greeting"; + homepage = "https://www.gnu.org/software/hello/manual/"; + insecure = false; + license = { + deprecated = false; + free = true; + fullName = "GNU General Public License v3.0 or later"; + redistributable = true; + shortName = "gpl3Plus"; + spdxId = "GPL-3.0-or-later"; + url = "https://spdx.org/licenses/GPL-3.0-or-later.html"; + }; + longDescription = '' + GNU Hello is a program that prints "Hello, world!" when you run it. + It is fully customizable. + ''; + maintainers = [{ + email = "edolstra+nixpkgs@gmail.com"; + github = "edolstra"; + githubId = 1148549; + name = "Eelco Dolstra"; + }]; + name = "hello-2.12.1"; + outputsToInstall = [ "out" ]; + platforms = [ + "i686-cygwin" + "x86_64-cygwin" + "x86_64-darwin" + "i686-darwin" + "aarch64-darwin" + "armv7a-darwin" + "i686-freebsd13" + "x86_64-freebsd13" + "aarch64-genode" + "i686-genode" + "x86_64-genode" + "x86_64-solaris" + "js-ghcjs" + "aarch64-linux" + "armv5tel-linux" + "armv6l-linux" + "armv7a-linux" + "armv7l-linux" + "i686-linux" + "m68k-linux" + "microblaze-linux" + "microblazeel-linux" + "mipsel-linux" + "mips64el-linux" + "powerpc64-linux" + "powerpc64le-linux" + "riscv32-linux" + "riscv64-linux" + "s390-linux" + "s390x-linux" + "x86_64-linux" + "mmix-mmixware" + "aarch64-netbsd" + "armv6l-netbsd" + "armv7a-netbsd" + "armv7l-netbsd" + "i686-netbsd" + "m68k-netbsd" + "mipsel-netbsd" + "powerpc-netbsd" + "riscv32-netbsd" + "riscv64-netbsd" + "x86_64-netbsd" + "aarch64_be-none" + "aarch64-none" + "arm-none" + "armv6l-none" + "avr-none" + "i686-none" + "microblaze-none" + "microblazeel-none" + "msp430-none" + "or1k-none" + "m68k-none" + "powerpc-none" + "powerpcle-none" + "riscv32-none" + "riscv64-none" + "rx-none" + "s390-none" + "s390x-none" + "vc4-none" + "x86_64-none" + "i686-openbsd" + "x86_64-openbsd" + "x86_64-redox" + "wasm64-wasi" + "wasm32-wasi" + "x86_64-windows" + "i686-windows" + ]; + position = + "/nix/store/7niq32w715567hbph0q13m5lqna64c1s-nixos-unstable.tar.gz/nixos-unstable.tar.gz/pkgs/applications/misc/hello/default.nix:34"; + unfree = false; + unsupported = false; + }; + name = "hello-2.12.1"; + out = { + outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1"; + }; + outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1"; + outputs = [ "out" ]; + system = "x86_64-linux"; + type = "derivation"; +}] +``` + +Each element in this list corresponds to an installed package. +It incorporates some attributes of the original derivation, including `meta`, `name`, `out`, `outPath`, `outputs`, `system`. +This information is used by Nix for querying and updating the package. diff --git a/doc/manual/src/command-ref/files/profiles.md b/doc/manual/src/command-ref/files/profiles.md new file mode 100644 index 000000000..b5c737880 --- /dev/null +++ b/doc/manual/src/command-ref/files/profiles.md @@ -0,0 +1,74 @@ +## Profiles + +A directory that contains links to profiles managed by [`nix-env`] and [`nix profile`]: + +- `$XDG_STATE_HOME/nix/profiles` for regular users +- `$NIX_STATE_DIR/profiles/per-user/root` if the user is `root` + +A profile is a directory of symlinks to files in the Nix store. + +### Filesystem layout + +Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile. +In turn, *path*`-`*N*`-link` is a symlink to a path in the Nix store. +For example: + +```console +$ ls -l ~alice/.local/state/nix/profiles/profile* +lrwxrwxrwx 1 alice users 14 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile -> profile-7-link +lrwxrwxrwx 1 alice users 51 Oct 28 16:18 /home/alice/.local/state/nix/profiles/profile-5-link -> /nix/store/q69xad13ghpf7ir87h0b2gd28lafjj1j-profile +lrwxrwxrwx 1 alice users 51 Oct 29 13:20 /home/alice/.local/state/nix/profiles/profile-6-link -> /nix/store/6bvhpysd7vwz7k3b0pndn7ifi5xr32dg-profile +lrwxrwxrwx 1 alice users 51 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile-7-link -> /nix/store/mp0x6xnsg0b8qhswy6riqvimai4gm677-profile +``` + +Each of these symlinks is a root for the Nix garbage collector. + +The contents of the store path corresponding to each version of the +profile is a tree of symlinks to the files of the installed packages, +e.g. + +```console +$ ll -R ~eelco/.local/state/nix/profiles/profile-7-link/ +/home/eelco/.local/state/nix/profiles/profile-7-link/: +total 20 +dr-xr-xr-x 2 root root 4096 Jan 1 1970 bin +-r--r--r-- 2 root root 1402 Jan 1 1970 manifest.nix +dr-xr-xr-x 4 root root 4096 Jan 1 1970 share + +/home/eelco/.local/state/nix/profiles/profile-7-link/bin: +total 20 +lrwxrwxrwx 5 root root 79 Jan 1 1970 chromium -> /nix/store/ijm5k0zqisvkdwjkc77mb9qzb35xfi4m-chromium-86.0.4240.111/bin/chromium +lrwxrwxrwx 7 root root 87 Jan 1 1970 spotify -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/bin/spotify +lrwxrwxrwx 3 root root 79 Jan 1 1970 zoom-us -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/bin/zoom-us + +/home/eelco/.local/state/nix/profiles/profile-7-link/share/applications: +total 12 +lrwxrwxrwx 4 root root 120 Jan 1 1970 chromium-browser.desktop -> /nix/store/4cf803y4vzfm3gyk3vzhzb2327v0kl8a-chromium-unwrapped-86.0.4240.111/share/applications/chromium-browser.desktop +lrwxrwxrwx 7 root root 110 Jan 1 1970 spotify.desktop -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/share/applications/spotify.desktop +lrwxrwxrwx 3 root root 107 Jan 1 1970 us.zoom.Zoom.desktop -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/share/applications/us.zoom.Zoom.desktop + +… +``` + +Each profile version contains a manifest file: +- [`manifest.nix`](@docroot@/command-ref/files/manifest.nix.md) used by [`nix-env`](@docroot@/command-ref/nix-env.md). +- [`manifest.json`](@docroot@/command-ref/files/manifest.json.md) used by [`nix profile`](@docroot@/command-ref/new-cli/nix3-profile.md) (experimental). + +## User profile link + +A symbolic link to the user's current profile: + +- `~/.nix-profile` +- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. + +By default, this symlink points to: + +- `$XDG_STATE_HOME/nix/profiles/profile` for regular users +- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` + +The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. +The [installer](@docroot@/installation/installing-binary.md) sets this up by default, unless you enable [`use-xdg-base-directories`]. + +[`nix-env`]: @docroot@/command-ref/nix-env.md +[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md +[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories diff --git a/doc/manual/src/command-ref/files/user-profile-link.md b/doc/manual/src/command-ref/files/user-profile-link.md deleted file mode 100644 index 1a7d15e44..000000000 --- a/doc/manual/src/command-ref/files/user-profile-link.md +++ /dev/null @@ -1,16 +0,0 @@ -## User profile link - -A symbolic link to the user's current profile. - -- `~/.nix-profile` -- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. - -By default, this symlink points to: - -- `$XDG_STATE_HOME/nix/profiles/default` for regular users -- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` - -The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. -The [installer](@docroot@/installation/installing-binary.md) sets this up by default. - -[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md deleted file mode 100644 index be590883e..000000000 --- a/doc/manual/src/command-ref/files/user-profiles.md +++ /dev/null @@ -1,246 +0,0 @@ -## User profiles - -A directory that contains links to user profiles managed by [`nix-env`] and [`nix profile`]: - -- `$XDG_STATE_HOME/nix/profiles` for regular users -- `$NIX_STATE_DIR/profiles/per-user/root` if the user is `root` - -A profile is a directory of symlinks to files in the Nix store. - -### Filesystem layout - -Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile. -In turn, *path*`-`*N*`-link` is a symlink to a path in the Nix store. -For example: - -```console -$ ls -l ~alice/.local/state/nix/profiles/profile* -lrwxrwxrwx 1 alice users 14 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile -> profile-7-link -lrwxrwxrwx 1 alice users 51 Oct 28 16:18 /home/alice/.local/state/nix/profiles/profile-5-link -> /nix/store/q69xad13ghpf7ir87h0b2gd28lafjj1j-profile -lrwxrwxrwx 1 alice users 51 Oct 29 13:20 /home/alice/.local/state/nix/profiles/profile-6-link -> /nix/store/6bvhpysd7vwz7k3b0pndn7ifi5xr32dg-profile -lrwxrwxrwx 1 alice users 51 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile-7-link -> /nix/store/mp0x6xnsg0b8qhswy6riqvimai4gm677-profile -``` - -Each of these symlinks is a root for the Nix garbage collector. - -The contents of the store path corresponding to each version of the -profile is a tree of symlinks to the files of the installed packages, -e.g. - -```console -$ ll -R ~eelco/.local/state/nix/profiles/profile-7-link/ -/home/eelco/.local/state/nix/profiles/profile-7-link/: -total 20 -dr-xr-xr-x 2 root root 4096 Jan 1 1970 bin --r--r--r-- 2 root root 1402 Jan 1 1970 manifest.json -dr-xr-xr-x 4 root root 4096 Jan 1 1970 share - -/home/eelco/.local/state/nix/profiles/profile-7-link/bin: -total 20 -lrwxrwxrwx 5 root root 79 Jan 1 1970 chromium -> /nix/store/ijm5k0zqisvkdwjkc77mb9qzb35xfi4m-chromium-86.0.4240.111/bin/chromium -lrwxrwxrwx 7 root root 87 Jan 1 1970 spotify -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/bin/spotify -lrwxrwxrwx 3 root root 79 Jan 1 1970 zoom-us -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/bin/zoom-us - -/home/eelco/.local/state/nix/profiles/profile-7-link/share/applications: -total 12 -lrwxrwxrwx 4 root root 120 Jan 1 1970 chromium-browser.desktop -> /nix/store/4cf803y4vzfm3gyk3vzhzb2327v0kl8a-chromium-unwrapped-86.0.4240.111/share/applications/chromium-browser.desktop -lrwxrwxrwx 7 root root 110 Jan 1 1970 spotify.desktop -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/share/applications/spotify.desktop -lrwxrwxrwx 3 root root 107 Jan 1 1970 us.zoom.Zoom.desktop -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/share/applications/us.zoom.Zoom.desktop - -… -``` - -## User profile link - -A symbolic link to the user's current profile: - -- `~/.nix-profile` -- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`. - -By default, this symlink points to: - -- `$XDG_STATE_HOME/nix/profiles/profile` for regular users -- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root` - -The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user. -The [installer](@docroot@/installation/installing-binary.md) sets this up by default, unless you enable [`use-xdg-base-directories`]. - -[`nix-env`]: @docroot@/command-ref/nix-env.md -[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md -[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories - -## Manifest - -The manifest file records the provenance of the packages that are installed in this version of the profile. -It is different between [`nix-env`] and [`nix profile`]. - -### `manifest.nix` - -Used by [`nix-env`]. Here is an example of how this file might look like after installing `hello` from Nixpkgs: - -```nix -[{ - meta = { - available = true; - broken = false; - changelog = - "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v2.12.1"; - description = "A program that produces a familiar, friendly greeting"; - homepage = "https://www.gnu.org/software/hello/manual/"; - insecure = false; - license = { - deprecated = false; - free = true; - fullName = "GNU General Public License v3.0 or later"; - redistributable = true; - shortName = "gpl3Plus"; - spdxId = "GPL-3.0-or-later"; - url = "https://spdx.org/licenses/GPL-3.0-or-later.html"; - }; - longDescription = '' - GNU Hello is a program that prints "Hello, world!" when you run it. - It is fully customizable. - ''; - maintainers = [{ - email = "edolstra+nixpkgs@gmail.com"; - github = "edolstra"; - githubId = 1148549; - name = "Eelco Dolstra"; - }]; - name = "hello-2.12.1"; - outputsToInstall = [ "out" ]; - platforms = [ - "i686-cygwin" - "x86_64-cygwin" - "x86_64-darwin" - "i686-darwin" - "aarch64-darwin" - "armv7a-darwin" - "i686-freebsd13" - "x86_64-freebsd13" - "aarch64-genode" - "i686-genode" - "x86_64-genode" - "x86_64-solaris" - "js-ghcjs" - "aarch64-linux" - "armv5tel-linux" - "armv6l-linux" - "armv7a-linux" - "armv7l-linux" - "i686-linux" - "m68k-linux" - "microblaze-linux" - "microblazeel-linux" - "mipsel-linux" - "mips64el-linux" - "powerpc64-linux" - "powerpc64le-linux" - "riscv32-linux" - "riscv64-linux" - "s390-linux" - "s390x-linux" - "x86_64-linux" - "mmix-mmixware" - "aarch64-netbsd" - "armv6l-netbsd" - "armv7a-netbsd" - "armv7l-netbsd" - "i686-netbsd" - "m68k-netbsd" - "mipsel-netbsd" - "powerpc-netbsd" - "riscv32-netbsd" - "riscv64-netbsd" - "x86_64-netbsd" - "aarch64_be-none" - "aarch64-none" - "arm-none" - "armv6l-none" - "avr-none" - "i686-none" - "microblaze-none" - "microblazeel-none" - "msp430-none" - "or1k-none" - "m68k-none" - "powerpc-none" - "powerpcle-none" - "riscv32-none" - "riscv64-none" - "rx-none" - "s390-none" - "s390x-none" - "vc4-none" - "x86_64-none" - "i686-openbsd" - "x86_64-openbsd" - "x86_64-redox" - "wasm64-wasi" - "wasm32-wasi" - "x86_64-windows" - "i686-windows" - ]; - position = - "/nix/store/7niq32w715567hbph0q13m5lqna64c1s-nixos-unstable.tar.gz/nixos-unstable.tar.gz/pkgs/applications/misc/hello/default.nix:34"; - unfree = false; - unsupported = false; - }; - name = "hello-2.12.1"; - out = { - outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1"; - }; - outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1"; - outputs = [ "out" ]; - system = "x86_64-linux"; - type = "derivation"; -}] -``` - -Each element in this list corresponds to an installed package. -It incorporates some attributes of the original package derivation, including `meta`, `name`, `out`, `outPath`, `outputs`, `system`. -This information is used by Nix for querying and updating the package. - -### `manifest.json` - -Used by [`nix profile`]. Here is an example of what the file might look like after installing `zoom-us` from Nixpkgs: - -```json -{ - "version": 1, - "elements": [ - { - "active": true, - "attrPath": "legacyPackages.x86_64-linux.zoom-us", - "originalUrl": "flake:nixpkgs", - "storePaths": [ - "/nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927" - ], - "uri": "github:NixOS/nixpkgs/13d0c311e3ae923a00f734b43fd1d35b47d8943a" - }, - … - ] -} -``` - -Each object in the array `elements` denotes an installed package and -has the following fields: - -* `originalUrl`: The [flake reference](@docroot@/command-ref/new-cli/nix3-flake.md) specified by - the user at the time of installation (e.g. `nixpkgs`). This is also - the flake reference that will be used by `nix profile upgrade`. - -* `uri`: The locked flake reference to which `originalUrl` resolved. - -* `attrPath`: The flake output attribute that provided this - package. Note that this is not necessarily the attribute that the - user specified, but the one resulting from applying the default - attribute paths and prefixes; for instance, `hello` might resolve to - `packages.x86_64-linux.hello` and the empty string to - `packages.x86_64-linux.default`. - -* `storePath`: The paths in the Nix store containing the package. - -* `active`: Whether the profile contains symlinks to the files of this - package. If set to false, the package is kept in the Nix store, but - is not "visible" in the profile's symlink tree. diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index 09d699903..b4a3dce49 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -85,4 +85,4 @@ match. Here are some examples: {{#include ./files/default-nix-expression.md}} -{{#include ./files/user-profiles.md}} \ No newline at end of file +{{#include ./files/profiles.md}} -- cgit v1.2.3 From 992be330ab31be4fe226b09fb602ced18fda788c Mon Sep 17 00:00:00 2001 From: Alexander Bantyev Date: Fri, 12 May 2023 16:58:01 +0400 Subject: Update doc/manual/src/SUMMARY.md.in Co-authored-by: Valentin Gagarin --- doc/manual/src/SUMMARY.md.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index 17a4fe232..766ec79d0 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -96,7 +96,7 @@ - [manifest.json](command-ref/files/manifest.json.md) - [Channels](command-ref/files/channels.md) - [Default Nix expression](command-ref/files/default-nix-expression.md) -- [Archititecture](architecture.md) +- [Architecture](architecture/architecture.md) - [Glossary](glossary.md) - [Contributing](contributing/contributing.md) - [Hacking](contributing/hacking.md) -- cgit v1.2.3