From 1ca4896e3be349eca6865e54a00e53f5710350e1 Mon Sep 17 00:00:00 2001 From: Alexander Bantyev Date: Wed, 26 Apr 2023 12:45:00 +0400 Subject: [PATCH] Nix: update and add documentation for nix subcommands (#9959) * Nix: update and add documentation for nix subcommands Updates the documentation on the new unstable Nix command & subcommands, and adds a separate page for the Classic Nix commands. --------- Co-authored-by: K.B.Dharun Krishna Co-authored-by: axtloss Co-authored-by: CleanMachine1 <78213164+CleanMachine1@users.noreply.github.com> --- pages/common/nix-build.md | 3 ++- pages/common/nix-classic.md | 29 +++++++++++++++++++++++++++ pages/common/nix-shell.md | 3 ++- pages/common/nix-store.md | 29 +++++++++++++++++++++++++++ pages/common/nix.md | 34 +++++++++++++++++++++----------- pages/common/nix3-build.md | 21 ++++++++++++++++++++ pages/common/nix3-develop.md | 16 +++++++++++++++ pages/common/nix3-edit.md | 12 +++++++++++ pages/common/nix3-flake.md | 24 ++++++++++++++++++++++ pages/common/nix3-profile.md | 28 ++++++++++++++++++++++++++ pages/common/nix3-registry.md | 25 +++++++++++++++++++++++ pages/common/nix3-repl.md | 25 +++++++++++++++++++++++ pages/common/nix3-run.md | 13 ++++++++++++ pages/common/nix3-search.md | 17 ++++++++++++++++ pages/common/nix3-shell.md | 25 +++++++++++++++++++++++ pages/common/nix3-store.md | 25 +++++++++++++++++++++++ pages/common/nix3-why-depends.md | 12 +++++++++++ 17 files changed, 327 insertions(+), 14 deletions(-) create mode 100644 pages/common/nix-classic.md create mode 100644 pages/common/nix-store.md create mode 100644 pages/common/nix3-build.md create mode 100644 pages/common/nix3-develop.md create mode 100644 pages/common/nix3-edit.md create mode 100644 pages/common/nix3-flake.md create mode 100644 pages/common/nix3-profile.md create mode 100644 pages/common/nix3-registry.md create mode 100644 pages/common/nix3-repl.md create mode 100644 pages/common/nix3-run.md create mode 100644 pages/common/nix3-search.md create mode 100644 pages/common/nix3-shell.md create mode 100644 pages/common/nix3-store.md create mode 100644 pages/common/nix3-why-depends.md diff --git a/pages/common/nix-build.md b/pages/common/nix-build.md index 2258acba7c..760061f442 100644 --- a/pages/common/nix-build.md +++ b/pages/common/nix-build.md @@ -1,7 +1,8 @@ # nix-build > Build a Nix expression. -> More information: . +> See also: `tldr nix3 build`. +> More information: . - Build a Nix expression: diff --git a/pages/common/nix-classic.md b/pages/common/nix-classic.md new file mode 100644 index 0000000000..e3d3fcc89c --- /dev/null +++ b/pages/common/nix-classic.md @@ -0,0 +1,29 @@ +# Nix classic interface + +> A classic, stable interface to a powerful package manager that makes package management reliable, reproducible, and declarative. +> Some Nix commands such as `nix-build`, `nix-shell`, `nix-env`, and `nix-store` have their own pages. See also: `tldr nix`. +> More information: . + +- Search for a package in nixpkgs via its name: + +`nix-env -qaP {{search_term_regexp}}` + +- Start a shell with the specified packages available: + +`nix-shell -p {{pkg1 pkg2 pkg3...}}` + +- Install some packages permanently: + +`nix-env -iA {{nixpkgs.pkg1 nixpkgs.pkg2...}}` + +- Show all dependencies of a store path (package), in a tree format: + +`nix-store --query --tree {{/nix/store/...}}` + +- Update the channels (repositories): + +`nix-channel --update` + +- Remove unused paths from Nix store: + +`nix-collect-garbage` diff --git a/pages/common/nix-shell.md b/pages/common/nix-shell.md index 706ae59a05..46ce588479 100644 --- a/pages/common/nix-shell.md +++ b/pages/common/nix-shell.md @@ -1,7 +1,8 @@ # nix-shell > Start an interactive shell based on a Nix expression. -> More information: . +> See also: `tldr nix3 shell`. +> More information: . - Start with nix expression in `shell.nix` or `default.nix` in the current directory: diff --git a/pages/common/nix-store.md b/pages/common/nix-store.md new file mode 100644 index 0000000000..9bc8bbb5d9 --- /dev/null +++ b/pages/common/nix-store.md @@ -0,0 +1,29 @@ +# nix-store + +> Manipulate or query the Nix store. +> See also: `tldr nix3 store`. +> More information: . + +- Collect garbage, such as removing unused paths: + +`nix-store --gc` + +- Hard-link identical files together to reduce space usage: + +`nix-store --optimise` + +- Delete a specific store path (must be unused): + +`nix-store --delete {{/nix/store/...}}` + +- Show all dependencies of a store path (package), in a tree format: + +`nix-store --query --tree {{/nix/store/...}}` + +- Calculate the total size of a certain store path with all the dependencies: + +`du -cLsh $(nix-store --query --references {{/nix/store/...}})` + +- Show all dependents of a particular store path: + +`nix-store --query --referrers {{/nix/store/...}}` diff --git a/pages/common/nix.md b/pages/common/nix.md index f792a2906f..8f6115b9b2 100644 --- a/pages/common/nix.md +++ b/pages/common/nix.md @@ -1,24 +1,34 @@ # nix -> Utilities for the Nix language and store. -> More information: . +> Powerful package manager that makes package management reliable, reproducible, and declarative. +> The `nix` command-line utility is experimental and requires enabling experimental features. For a classic, stable interface, see `tldr nix classic`. +> Some `nix` subcommands such as `build`, `develop`, `flake`, `registry`, `profile`, `search`, `repl`, `store`, `edit`, `why-depends` etc. have their own usage documentation, accessible via `tldr nix3 subcommand`. +> More information: . -- Search for a package via its name or description: +- Enable the `nix` command: -`nix search {{search_term}}` +`mkdir -p ~/.config/nix; echo 'experimental-features = nix-command flakes' > ~/.config/nix/nix.conf` -- Start a Nix shell with the specified packages available: +- Display help for the `nix` subcommand: -`nix run {{nixpkgs.pkg1 nixpkgs.pkg2 nixpkgs.pkg3...}}` +`nix help {{subcommand}}` -- Optimise Nix store disk usage by combining duplicate files: +- Search for a package in nixpkgs via its name or description: -`nix store optimise` +`nix search nixpkgs {{search_term}}` + +- Start a shell with the specified packages from nixpkgs available: + +`nix shell {{nixpkgs#pkg1 nixpkgs#pkg2 nixpkgs#pkg3 ...}}` + +- Install some packages from nixpkgs permanently: + +`nix profile install {{nixpkgs#pkg1 nixpkgs#pkg2 nixpkgs#pkg3 ...}}` + +- Remove unused paths from Nix store to free up space: + +`nix store gc` - Start an interactive environment for evaluating Nix expressions: `nix repl` - -- Upgrade Nix to the latest stable version: - -`nix upgrade-nix` diff --git a/pages/common/nix3-build.md b/pages/common/nix3-build.md new file mode 100644 index 0000000000..63e4db636d --- /dev/null +++ b/pages/common/nix3-build.md @@ -0,0 +1,21 @@ +# nix build + +> Build a Nix expression (downloading from the cache when possible). +> See also: `tldr nix-build`. See `tldr nix3 flake` for information about flakes. +> More information: . + +- Build a package from nixpkgs, symlinking the result to `./result`: + +`nix build {{nixpkgs#pkg}}` + +- Build a package from a flake in the current directory, showing the build logs in the process: + +`nix build -L {{.#pkg}}` + +- Build the default package from a flake in some directory: + +`nix build {{./path/to/directory}}` + +- Build a package without making the `result` symlink, instead printing the store path to the stdout: + +`nix build --no-link --print-out-paths` diff --git a/pages/common/nix3-develop.md b/pages/common/nix3-develop.md new file mode 100644 index 0000000000..16a2b7baf9 --- /dev/null +++ b/pages/common/nix3-develop.md @@ -0,0 +1,16 @@ +# nix develop + +> Run a bash shell that provides the build environment of a derivation. +> More information: . + +- Start a shell with all dependencies of a package from nixpkgs available: + +`nix develop {{nixpkgs#pkg}}` + +- Start a development shell for the default package in a flake in the current directory: + +`nix develop` + +- In that shell, configure and build the sources: + +`configurePhase; buildPhase` diff --git a/pages/common/nix3-edit.md b/pages/common/nix3-edit.md new file mode 100644 index 0000000000..d060cdbb61 --- /dev/null +++ b/pages/common/nix3-edit.md @@ -0,0 +1,12 @@ +# nix edit + +> Open the Nix expression of a Nix package in $EDITOR. +> More information: . + +- Open the source of the Nix expression of a package from nixpkgs in your `$EDITOR`: + +`nix edit {{nixpkgs#pkg}}` + +- Dump the source of a package to stdout: + +`EDITOR=cat nix edit {{nixpkgs#pkg}}` diff --git a/pages/common/nix3-flake.md b/pages/common/nix3-flake.md new file mode 100644 index 0000000000..9ed8992cd4 --- /dev/null +++ b/pages/common/nix3-flake.md @@ -0,0 +1,24 @@ +# nix flake + +> Manage Nix flakes. +> More information: . + +- See documentation about what Nix flakes are: + +`nix flake --help` + +- Create a new flake (just the `flake.nix` file) from the default template, in the current directory: + +`nix flake init` + +- Update all inputs (dependencies) of the flake in the current directory: + +`nix flake update` + +- Update a specific input (dependency) of the flake in the current directory: + +`nix flake lock --update-input {{input}}` + +- Show all the outputs of a flake on github: + +`nix flake show {{github:owner/repo}}` diff --git a/pages/common/nix3-profile.md b/pages/common/nix3-profile.md new file mode 100644 index 0000000000..5ce247843c --- /dev/null +++ b/pages/common/nix3-profile.md @@ -0,0 +1,28 @@ +# nix profile + +> Install, update and remove packages from Nix profiles. +> More information: . + +- Install some packages from nixpkgs into the default profile: + +`nix profile install {{nixpkgs#pkg1 nixpkgs#pkg2 ...}}` + +- Install a package from a flake on GitHub into a custom profile: + +`nix profile install {{github:owner/repo/pkg}} --profile {{./path/to/directory}}` + +- List packages currently installed in the default profile: + +`nix profile list` + +- Remove a package installed from nixpkgs from the default profile, by name: + +`nix profile remove {{legacyPackages.x86_64-linux.pkg}}` + +- Upgrade packages in the default to the latest available versions: + +`nix profile upgrade` + +- Rollback (cancel) the latest action on the default profile: + +`nix profile rollback` diff --git a/pages/common/nix3-registry.md b/pages/common/nix3-registry.md new file mode 100644 index 0000000000..d516b02827 --- /dev/null +++ b/pages/common/nix3-registry.md @@ -0,0 +1,25 @@ +# nix registry + +> Manage a Nix flake registry. +> See `tldr nix3 flake` for information about flakes. +> More information: . + +- Pin the `nixpkgs` revision to the current version of the upstream repository: + +`nix registry pin {{nixpkgs}}` + +- Pin an entry to the latest version of the branch, or a particular reivision of a github repository: + +`nix registry pin {{entry}} {{github:owner/repo/branch_or_revision}}` + +- Add a new entry that always points to the latest version of a github repository, updating automatically: + +`nix registry add {{entry}} {{github:owner/repo}}` + +- Remove a registry entry: + +`nix registry remove {{entry}}` + +- See documentation about what Nix flake registries are: + +`nix registry --help` diff --git a/pages/common/nix3-repl.md b/pages/common/nix3-repl.md new file mode 100644 index 0000000000..d05cbb70e7 --- /dev/null +++ b/pages/common/nix3-repl.md @@ -0,0 +1,25 @@ +# nix repl + +> Start an interactive environment for evaluating Nix expressions. +> See for a description of the Nix expression language. +> More information: . + +- Start an interactive environment for evaluating Nix expressions: + +`nix repl` + +- Load all packages from a flake (e.g. `nixpkgs`) into scope: + +`:lf {{nixpkgs}}` + +- Build a package from an expression: + +`:b {{expression}}` + +- Start a shell with package from the expression available: + +`:u {{expression}}` + +- Start a shell with dependencies of the package from the expression available: + +`:s {{expression}}` diff --git a/pages/common/nix3-run.md b/pages/common/nix3-run.md new file mode 100644 index 0000000000..5fad773dc1 --- /dev/null +++ b/pages/common/nix3-run.md @@ -0,0 +1,13 @@ +# nix run + +> Run an application from a Nix flake. +> See `tldr nix3 flake` for information about flakes. +> More information: . + +- Run a command whose name matches the package name from nixpkgs (if you want a different command from that package, see `tldr nix3 shell`): + +`nix run nixpkgs#{{pkg}}` + +- Run the default application in the flake in the current directory: + +`nix run` diff --git a/pages/common/nix3-search.md b/pages/common/nix3-search.md new file mode 100644 index 0000000000..ecbe44152a --- /dev/null +++ b/pages/common/nix3-search.md @@ -0,0 +1,17 @@ +# nix search + +> Search for packages in a Nix flake. +> See `tldr nix3 flake` for information about flakes. +> More information: . + +- Search `nixpkgs` for a package based on its name or description: + +`nix search {{nixpkgs}} {{search_term...}}` + +- Show description of a package from nixpkgs: + +`nix search {{nixpkgs#pkg}}` + +- Show all packages available from a flake on github: + +`nix search {{github:owner/repo}}` diff --git a/pages/common/nix3-shell.md b/pages/common/nix3-shell.md new file mode 100644 index 0000000000..c82753f601 --- /dev/null +++ b/pages/common/nix3-shell.md @@ -0,0 +1,25 @@ +# nix shell + +> Start a shell in which the specified packages are available. +> See also: `tldr nix-shell`. See `tldr nix3 flake` for information about flakes. +> More information: . + +- Start an interactive shell with some packages from `nixpkgs`: + +`nix shell {{nixpkgs#pkg1 nixpkgs#packageSet.pkg2 ...}}` + +- Start a shell providing a package from an older version of `nixpkgs` (21.05): + +`nix shell {{nixpkgs/nixos-21.05#pkg}}` + +- Start a shell with the "default package" from a flake in the current directory, printing build logs if any builds happen: + +`nix shell -L` + +- Start a shell with a package from a flake on GitHub: + +`nix shell {{github:owner/repo#pkg}}` + +- Run a command in a shell with a package: + +`nix shell {{nixpkgs#pkg}} -c {{some-cmd --someflag 'Some other arguments'}}` diff --git a/pages/common/nix3-store.md b/pages/common/nix3-store.md new file mode 100644 index 0000000000..1cff469d29 --- /dev/null +++ b/pages/common/nix3-store.md @@ -0,0 +1,25 @@ +# nix store + +> Manipulate the Nix store. +> See also: `tldr nix-store`. +> More information: . + +- Collect garbage, i.e. remove unused paths to reduce space usage: + +`nix store gc` + +- Hard-link identical files together to reduce space usage: + +`nix store optimise` + +- Delete a specific store path (most be unused): + +`nix store delete {{/nix/store/...}}` + +- List a contents of the store path, on a remote store: + +`nix store --store {{https://cache.nixos.org}} ls {{/nix/store/...}}` + +- Show the differences in versions between two store paths, with their respective dependencies: + +`nix store diff-closures {{/nix/store/...}} {{/nix/store/...}}` diff --git a/pages/common/nix3-why-depends.md b/pages/common/nix3-why-depends.md new file mode 100644 index 0000000000..5dfd26ca59 --- /dev/null +++ b/pages/common/nix3-why-depends.md @@ -0,0 +1,12 @@ +# nix why-depends + +> Show why a package depends on another package. +> More information: . + +- Show why the currently running NixOS system requires a certain store path: + +`nix why-depends {{/run/current-system}} {{/nix/store/...}}` + +- Show why a package from nixpkgs requires another package as a _build-time_ dependency: + +`nix why-depends --derivation {{nixpkgs#dependent}} {{nixpkgs#dependency}}`