lix-project/lix-releng-staging
0
0
Fork 0
Code Packages Activity

Add 'nix profile' manpage

Browse source
This commit is contained in:
Eelco Dolstra 2020-12-18 14:25:36 +01:00
parent 0c09f63de8
commit 16e34085e8
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
7 changed files with 295 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
src/nix/profile-diff-closures.md Normal file
View file

@ -0,0 +1,28 @@
R""(
# Examples
* Show what changed between each version of the NixOS system
profile:
```console
# nix profile diff-closures --profile /nix/var/nix/profiles/system
Version 13 -> 14:
acpi-call: 2020-04-07-5.8.13 → 2020-04-07-5.8.14
aws-sdk-cpp: -6723.1 KiB
…
Version 14 -> 15:
acpi-call: 2020-04-07-5.8.14 → 2020-04-07-5.8.16
attica: -996.2 KiB
breeze-icons: -78713.5 KiB
brotli: 1.0.7 → 1.0.9, +44.2 KiB
```
# Description
This command shows the difference between the closures of subsequent
versions of a profile. See [`nix store
diff-closures`](nix3-store-diff-closures.md) for details.
)""

31
src/nix/profile-info.md Normal file
View file

@ -0,0 +1,31 @@
R""(
# Examples
* Show what packages are installed in the default profile:
```console
# nix profile info
0 flake:nixpkgs#legacyPackages.x86_64-linux.spotify github:NixOS/nixpkgs/c23db78bbd474c4d0c5c3c551877523b4a50db06#legacyPackages.x86_64-linux.spotify /nix/store/akpdsid105phbbvknjsdh7hl4v3fhjkr-spotify-1.1.46.916.g416cacf1
1 flake:nixpkgs#legacyPackages.x86_64-linux.zoom-us github:NixOS/nixpkgs/c23db78bbd474c4d0c5c3c551877523b4a50db06#legacyPackages.x86_64-linux.zoom-us /nix/store/89pmjmbih5qpi7accgacd17ybpgp4xfm-zoom-us-5.4.53350.1027
2 flake:blender-bin#defaultPackage.x86_64-linux github:edolstra/nix-warez/d09d7eea893dcb162e89bc67f6dc1ced14abfc27?dir=blender#defaultPackage.x86_64-linux /nix/store/zfgralhqjnam662kqsgq6isjw8lhrflz-blender-bin-2.91.0
```
# Description
This command shows what packages are currently installed in a
profile. The output consists of one line per package, with the
following fields:
* An integer that can be used to unambiguously identify the package in
invocations of `nix profile remove` and `nix profile upgrade`.
* The original ("mutable") flake reference and output attribute path
used at installation time.
* The immutable flake reference to which the mutable flake reference
was resolved.
* The store path(s) of the package.
)""

27
src/nix/profile-install.md Normal file
View file

@ -0,0 +1,27 @@
R""(
# Examples
* Install a package from Nixpkgs:
```console
# nix profile install nixpkgs#hello
```
* Install a package from a specific branch of Nixpkgs:
```console
# nix profile install nixpkgs/release-20.09#hello
```
* Install a package from a specific revision of Nixpkgs:
```console
# nix profile install nixpkgs/d73407e8e6002646acfdef0e39ace088bacc83da#hello
```
# Description
This command adds *installables* to a Nix profile.
)""

32
src/nix/profile-remove.md Normal file
View file

@ -0,0 +1,32 @@
R""(
# Examples
* Remove a package by position:
```console
# nix profile remove 3
```
* Remove a package by attribute path:
```console
# nix profile remove packages.x86_64-linux.hello
```
* Remove all packages:
```console
# nix profile remove '.*'
```
* Remove a package by store path:
```console
# nix profile remove /nix/store/rr3y0c6zyk7kjjl8y19s4lsrhn4aiq1z-hello-2.10
```
# Description
This command removes a package from a profile.
)""

41
src/nix/profile-upgrade.md Normal file
View file

@ -0,0 +1,41 @@
R""(
# Examples
* Upgrade all packages that were installed using a mutable flake
reference:
```console
# nix profile upgrade '.*'
```
* Upgrade a specific package:
```console
# nix profile upgrade packages.x86_64-linux.hello
```
* Upgrade a specific profile element by number:
```console
# nix profile info
0 flake:nixpkgs#legacyPackages.x86_64-linux.spotify …
# nix profile upgrade 0
```
# Description
This command upgrades a previously installed package in a Nix profile,
by fetching and evaluating the latest version of the flake from which
the package was installed.
> **Warning**
>
> This only works if you used a *mutable* flake reference at
> installation time, e.g. `nixpkgs#hello`. It does not work if you
> used an *immutable* flake reference
> (e.g. `github:NixOS/nixpkgs/13d0c311e3ae923a00f734b43fd1d35b47d8943a#hello`),
> since in that case the "latest version" is always the same.
)""

90
src/nix/profile.cc
View file

@ -151,22 +151,11 @@ struct CmdProfileInstall : InstallablesCommand, MixDefaultProfile
return "install a package into a profile";
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To install a package from Nixpkgs:",
"nix profile install nixpkgs#hello"
},
Example{
"To install a package from a specific branch of Nixpkgs:",
"nix profile install nixpkgs/release-19.09#hello"
},
Example{
"To install a package from a specific revision of Nixpkgs:",
"nix profile install nixpkgs/1028bb33859f8dfad7f98e1c8d185f3d1aaa7340#hello"
},
};
return
#include "profile-install.md"
;
}
void run(ref<Store> store) override
@ -257,26 +246,11 @@ struct CmdProfileRemove : virtual EvalCommand, MixDefaultProfile, MixProfileElem
return "remove packages from a profile";
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To remove a package by attribute path:",
"nix profile remove packages.x86_64-linux.hello"
},
Example{
"To remove all packages:",
"nix profile remove '.*'"
},
Example{
"To remove a package by store path:",
"nix profile remove /nix/store/rr3y0c6zyk7kjjl8y19s4lsrhn4aiq1z-hello-2.10"
},
Example{
"To remove a package by position:",
"nix profile remove 3"
},
};
return
#include "profile-remove.md"
;
}
void run(ref<Store> store) override
@ -310,18 +284,11 @@ struct CmdProfileUpgrade : virtual SourceExprCommand, MixDefaultProfile, MixProf
return "upgrade packages using their most recent flake";
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To upgrade all packages that were installed using a mutable flake reference:",
"nix profile upgrade '.*'"
},
Example{
"To upgrade a specific package:",
"nix profile upgrade packages.x86_64-linux.hello"
},
};
return
#include "profile-upgrade.md"
;
}
void run(ref<Store> store) override
@ -377,14 +344,11 @@ struct CmdProfileInfo : virtual EvalCommand, virtual StoreCommand, MixDefaultPro
return "list installed packages";
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To show what packages are installed in the default profile:",
"nix profile info"
},
};
return
#include "profile-info.md"
;
}
void run(ref<Store> store) override
@ -405,17 +369,14 @@ struct CmdProfileDiffClosures : virtual StoreCommand, MixDefaultProfile
{
std::string description() override
{
return "show the closure difference between each generation of a profile";
return "show the closure difference between each version of a profile";
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To show what changed between each generation of the NixOS system profile:",
"nix profile diff-closures --profile /nix/var/nix/profiles/system"
},
};
return
#include "profile-diff-closures.md"
;
}
void run(ref<Store> store) override
@ -429,7 +390,7 @@ struct CmdProfileDiffClosures : virtual StoreCommand, MixDefaultProfile
if (prevGen) {
if (!first) std::cout << "\n";
first = false;
std::cout << fmt("Generation %d -> %d:\n", prevGen->number, gen.number);
std::cout << fmt("Version %d -> %d:\n", prevGen->number, gen.number);
printClosureDiff(store,
store->followLinksToStorePath(prevGen->path),
store->followLinksToStorePath(gen.path),
@ -458,6 +419,13 @@ struct CmdProfile : NixMultiCommand
return "manage Nix profiles";
}
std::string doc() override
{
return
#include "profile.md"
;
}
void run() override
{
if (!command)

107
src/nix/profile.md Normal file
View file

@ -0,0 +1,107 @@
R""(
# Description
`nix profile` allows you to create and manage *Nix profiles*. A Nix
profile is a set of packages that can be installed and upgraded
independently from each other. Nix profiles are versioned, allowing
them to be rolled back easily.
# Default profile
The default profile used by `nix profile` is `$HOME/.nix-profile`,
which, if it does not exist, is created as a symlink to
`/nix/var/nix/profiles/per-user/default` if Nix is invoked by the
`root` user, or `/nix/var/nix/profiles/per-user/`*username* otherwise.
You can specify another profile location using `--profile` *path*.
# 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 /nix/var/nix/profiles/per-user/alice/profile*
lrwxrwxrwx 1 alice users 14 Nov 25 14:35 /nix/var/nix/profiles/per-user/alice/profile -> profile-7-link
lrwxrwxrwx 1 alice users 51 Oct 28 16:18 /nix/var/nix/profiles/per-user/alice/profile-5-link -> /nix/store/q69xad13ghpf7ir87h0b2gd28lafjj1j-profile
lrwxrwxrwx 1 alice users 51 Oct 29 13:20 /nix/var/nix/profiles/per-user/alice/profile-6-link -> /nix/store/6bvhpysd7vwz7k3b0pndn7ifi5xr32dg-profile
lrwxrwxrwx 1 alice users 51 Nov 25 14:35 /nix/var/nix/profiles/per-user/alice/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 /nix/var/nix/profiles/per-user/eelco/profile-7-link/
/nix/var/nix/profiles/per-user/eelco/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
/nix/var/nix/profiles/per-user/eelco/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
/nix/var/nix/profiles/per-user/eelco/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
…
```
The file `manifest.json` records the provenance of the packages that
are installed in this version of the profile. It looks like this:
```json
{
"version": 1,
"elements": [
{
"active": true,
"attrPath": "legacyPackages.x86_64-linux.zoom-us",
"originalUri": "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:
* `originalUri`: The [flake reference](./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 immutable flake reference to which `originalUri`
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
`defaultPackage.x86_64-linux`.
* `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.
)""