Merge pull request #4336 from NixOS/manpages
Documentation for nix subcommands
This commit is contained in:
Eelco Dolstra
GitHub
commit
a93916b190
|
|
@ -20,11 +20,6 @@ let
|
|||
(attrNames def.commands))
|
||||
+ "\n"
|
||||
else "")
|
||||
+ (if def.examples or [] != []
|
||||
then
|
||||
"# Examples\n\n"
|
||||
+ concatStrings (map ({ description, command }: "${description}\n\n```console\n${command}\n```\n\n") def.examples)
|
||||
else "")
|
||||
+ (if def ? doc
|
||||
then def.doc + "\n\n"
|
||||
else "")
|
||||
|
|
@ -43,7 +38,7 @@ let
|
|||
if flag.category or "" != "config"
|
||||
then
|
||||
" - `--${longName}`"
|
||||
+ (if flag ? shortName then " / `${flag.shortName}`" else "")
|
||||
+ (if flag ? shortName then " / `-${flag.shortName}`" else "")
|
||||
+ (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "")
|
||||
+ " \n"
|
||||
+ " " + flag.description + "\n\n"
|
||||
|
|
|
|||
|
|
@ -254,6 +254,8 @@ nlohmann::json Args::toJSON()
|
|||
res["description"] = description();
|
||||
res["flags"] = std::move(flags);
|
||||
res["args"] = std::move(args);
|
||||
auto s = doc();
|
||||
if (s != "") res.emplace("doc", stripIndentation(s));
|
||||
return res;
|
||||
}
|
||||
|
||||
|
|
@ -351,38 +353,6 @@ void printTable(std::ostream & out, const Table2 & table)
|
|||
}
|
||||
}
|
||||
|
||||
void Command::printHelp(const string & programName, std::ostream & out)
|
||||
{
|
||||
Args::printHelp(programName, out);
|
||||
|
||||
auto exs = examples();
|
||||
if (!exs.empty()) {
|
||||
out << "\n" ANSI_BOLD "Examples:" ANSI_NORMAL "\n";
|
||||
for (auto & ex : exs)
|
||||
out << "\n"
|
||||
<< " " << ex.description << "\n" // FIXME: wrap
|
||||
<< " $ " << ex.command << "\n";
|
||||
}
|
||||
}
|
||||
|
||||
nlohmann::json Command::toJSON()
|
||||
{
|
||||
auto exs = nlohmann::json::array();
|
||||
|
||||
for (auto & example : examples()) {
|
||||
auto ex = nlohmann::json::object();
|
||||
ex["description"] = example.description;
|
||||
ex["command"] = chomp(stripIndentation(example.command));
|
||||
exs.push_back(std::move(ex));
|
||||
}
|
||||
|
||||
auto res = Args::toJSON();
|
||||
res["examples"] = std::move(exs);
|
||||
auto s = doc();
|
||||
if (s != "") res.emplace("doc", stripIndentation(s));
|
||||
return res;
|
||||
}
|
||||
|
||||
MultiCommand::MultiCommand(const Commands & commands)
|
||||
: commands(commands)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -25,6 +25,9 @@ public:
|
|||
/* Return a short one-line description of the command. */
|
||||
virtual std::string description() { return ""; }
|
||||
|
||||
/* Return documentation about this command, in Markdown format. */
|
||||
virtual std::string doc() { return ""; }
|
||||
|
||||
protected:
|
||||
|
||||
static const size_t ArityAny = std::numeric_limits<size_t>::max();
|
||||
|
|
@ -225,28 +228,11 @@ struct Command : virtual Args
|
|||
virtual void prepare() { };
|
||||
virtual void run() = 0;
|
||||
|
||||
/* Return documentation about this command, in Markdown format. */
|
||||
virtual std::string doc() { return ""; }
|
||||
|
||||
struct Example
|
||||
{
|
||||
std::string description;
|
||||
std::string command;
|
||||
};
|
||||
|
||||
typedef std::list<Example> Examples;
|
||||
|
||||
virtual Examples examples() { return Examples(); }
|
||||
|
||||
typedef int Category;
|
||||
|
||||
static constexpr Category catDefault = 0;
|
||||
|
||||
virtual Category category() { return catDefault; }
|
||||
|
||||
void printHelp(const string & programName, std::ostream & out) override;
|
||||
|
||||
nlohmann::json toJSON() override;
|
||||
};
|
||||
|
||||
typedef std::map<std::string, std::function<ref<Command>()>> Commands;
|
||||
|
|
|
|||
|
|
@ -43,22 +43,11 @@ struct CmdBuild : InstallablesCommand, MixDryRun, MixJSON, MixProfile
|
|||
return "build a derivation or fetch a store path";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To build and run GNU Hello from NixOS 17.03:",
|
||||
"nix build -f channel:nixos-17.03 hello; ./result/bin/hello"
|
||||
},
|
||||
Example{
|
||||
"To build the build.x86_64-linux attribute from release.nix:",
|
||||
"nix build -f release.nix build.x86_64-linux"
|
||||
},
|
||||
Example{
|
||||
"To make a profile point at GNU Hello:",
|
||||
"nix build --profile /tmp/profile nixpkgs#hello"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "build.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
|
|||
92
src/nix/build.md
Normal file
92
src/nix/build.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Build the default package from the flake in the current directory:
|
||||
|
||||
```console
|
||||
# nix build
|
||||
```
|
||||
|
||||
* Build and run GNU Hello from the `nixpkgs` flake:
|
||||
|
||||
```console
|
||||
# nix build nixpkgs#hello
|
||||
# ./result/bin/hello
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
* Build GNU Hello and Cowsay, leaving two result symlinks:
|
||||
|
||||
```console
|
||||
# nix build nixpkgs#hello nixpkgs#cowsay
|
||||
# ls -l result*
|
||||
lrwxrwxrwx 1 … result -> /nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10
|
||||
lrwxrwxrwx 1 … result-1 -> /nix/store/rkfrm0z6x6jmi7d3gsmma4j53h15mg33-cowsay-3.03+dfsg2
|
||||
```
|
||||
|
||||
* Build a specific output:
|
||||
|
||||
```console
|
||||
# nix build nixpkgs#glibc.dev
|
||||
# ls -ld ./result-dev
|
||||
lrwxrwxrwx 1 … ./result-dev -> /nix/store/dkm3gwl0xrx0wrw6zi5x3px3lpgjhlw4-glibc-2.32-dev
|
||||
```
|
||||
|
||||
* Build attribute `build.x86_64-linux` from (non-flake) Nix expression
|
||||
`release.nix`:
|
||||
|
||||
```console
|
||||
# nix build -f release.nix build.x86_64-linux
|
||||
```
|
||||
|
||||
* Build a NixOS system configuration from a flake, and make a profile
|
||||
point to the result:
|
||||
|
||||
```console
|
||||
# nix build --profile /nix/var/nix/profiles/system \
|
||||
~/my-configurations#nixosConfigurations.machine.config.system.build.toplevel
|
||||
```
|
||||
|
||||
(This is essentially what `nixos-rebuild` does.)
|
||||
|
||||
* Build an expression specified on the command line:
|
||||
|
||||
```console
|
||||
# nix build --impure --expr \
|
||||
'with import <nixpkgs> {};
|
||||
runCommand "foo" {
|
||||
buildInputs = [ hello ];
|
||||
}
|
||||
"hello > $out"'
|
||||
# cat ./result
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
Note that `--impure` is needed because we're using `<nixpkgs>`,
|
||||
which relies on the `$NIX_PATH` environment variable.
|
||||
|
||||
* Fetch a store path from the configured substituters, if it doesn't
|
||||
already exist:
|
||||
|
||||
```console
|
||||
# nix build /nix/store/rkfrm0z6x6jmi7d3gsmma4j53h15mg33-cowsay-3.03+dfsg2
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
`nix build` builds the specified *installables*. Installables that
|
||||
resolve to derivations are built (or substituted if possible). Store
|
||||
path installables are substituted.
|
||||
|
||||
Unless `--no-link` is specified, after a successful build, it creates
|
||||
symlinks to the store paths of the installables. These symlinks have
|
||||
the prefix `./result` by default; this can be overriden using the
|
||||
`--out-link` option. Each symlink has a suffix `-<N>-<outname>`, where
|
||||
*N* is the index of the installable (with the left-most installable
|
||||
having index 0), and *outname* is the symbolic derivation output name
|
||||
(e.g. `bin`, `dev` or `lib`). `-<N>` is omitted if *N* = 0, and
|
||||
`-<outname>` is omitted if *outname* = `out` (denoting the default
|
||||
output).
|
||||
|
||||
)""
|
||||
|
|
@ -40,14 +40,11 @@ struct CmdBundle : InstallableCommand
|
|||
return "bundle an application so that it works outside of the Nix store";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To bundle Hello:",
|
||||
"nix bundle hello"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "bundle.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
|
|
|||
36
src/nix/bundle.md
Normal file
36
src/nix/bundle.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Bundle Hello:
|
||||
|
||||
```console
|
||||
# nix bundle nixpkgs#hello
|
||||
# ./hello
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
* Bundle a specific version of Nix:
|
||||
|
||||
```console
|
||||
# nix bundle github:NixOS/nix/e3ddffb27e5fc37a209cfd843c6f7f6a9460a8ec
|
||||
# ./nix --version
|
||||
nix (Nix) 2.4pre20201215_e3ddffb
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
`nix bundle` packs the closure of the [Nix app](./nix3-run.md)
|
||||
*installable* into a single self-extracting executable. See the
|
||||
[`nix-bundle` homepage](https://github.com/matthewbauer/nix-bundle)
|
||||
for more details.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> This command only works on Linux.
|
||||
|
||||
# Bundler definitions
|
||||
|
||||
TODO
|
||||
|
||||
)""
|
||||
|
|
@ -37,6 +37,13 @@ struct CmdCatStore : StoreCommand, MixCat
|
|||
return "print the contents of a file in the Nix store on stdout";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "store-cat.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
{
|
||||
cat(store->getFSAccessor());
|
||||
|
|
@ -62,6 +69,13 @@ struct CmdCatNar : StoreCommand, MixCat
|
|||
return "print the contents of a file inside a NAR file on stdout";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "nar-cat.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
{
|
||||
cat(makeNarAccessor(make_ref<std::string>(readFile(narPath))));
|
||||
|
|
|
|||
|
|
@ -54,32 +54,11 @@ struct CmdCopy : StorePathsCommand
|
|||
return "copy paths between Nix stores";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To copy Firefox from the local store to a binary cache in file:///tmp/cache:",
|
||||
"nix copy --to file:///tmp/cache $(type -p firefox)"
|
||||
},
|
||||
Example{
|
||||
"To copy the entire current NixOS system closure to another machine via SSH:",
|
||||
"nix copy --to ssh://server /run/current-system"
|
||||
},
|
||||
Example{
|
||||
"To copy a closure from another machine via SSH:",
|
||||
"nix copy --from ssh://server /nix/store/a6cnl93nk1wxnq84brbbwr6hxw9gp2w9-blender-2.79-rc2"
|
||||
},
|
||||
#ifdef ENABLE_S3
|
||||
Example{
|
||||
"To copy Hello to an S3 binary cache:",
|
||||
"nix copy --to s3://my-bucket?region=eu-west-1 nixpkgs#hello"
|
||||
},
|
||||
Example{
|
||||
"To copy Hello to an S3-compatible binary cache:",
|
||||
"nix copy --to s3://my-bucket?region=eu-west-1&endpoint=example.com nixpkgs#hello"
|
||||
},
|
||||
#endif
|
||||
};
|
||||
return
|
||||
#include "copy.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
|
|
|||
58
src/nix/copy.md
Normal file
58
src/nix/copy.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Copy Firefox from the local store to a binary cache in `/tmp/cache`:
|
||||
|
||||
```console
|
||||
# nix copy --to file:///tmp/cache $(type -p firefox)
|
||||
```
|
||||
|
||||
Note the `file://` - without this, the destination is a chroot
|
||||
store, not a binary cache.
|
||||
|
||||
* Copy the entire current NixOS system closure to another machine via
|
||||
SSH:
|
||||
|
||||
```console
|
||||
# nix copy -s --to ssh://server /run/current-system
|
||||
```
|
||||
|
||||
The `-s` flag causes the remote machine to try to substitute missing
|
||||
store paths, which may be faster if the link between the local and
|
||||
remote machines is slower than the link between the remote machine
|
||||
and its substituters (e.g. `https://cache.nixos.org`).
|
||||
|
||||
* Copy a closure from another machine via SSH:
|
||||
|
||||
```console
|
||||
# nix copy --from ssh://server /nix/store/a6cnl93nk1wxnq84brbbwr6hxw9gp2w9-blender-2.79-rc2
|
||||
```
|
||||
|
||||
* Copy Hello to a binary cache in an Amazon S3 bucket:
|
||||
|
||||
```console
|
||||
# nix copy --to s3://my-bucket?region=eu-west-1 nixpkgs#hello
|
||||
```
|
||||
|
||||
or to an S3-compatible storage system:
|
||||
|
||||
```console
|
||||
# nix copy --to s3://my-bucket?region=eu-west-1&endpoint=example.com nixpkgs#hello
|
||||
```
|
||||
|
||||
Note that this only works if Nix is built with AWS support.
|
||||
|
||||
* Copy a closure from `/nix/store` to the chroot store `/tmp/nix/nix/store`:
|
||||
|
||||
```console
|
||||
# nix copy --to /tmp/nix nixpkgs#hello --no-check-sigs
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
`nix copy` copies store path closures between two Nix stores. The
|
||||
source store is specified using `--from` and the destination using
|
||||
`--to`. If one of these is omitted, it defaults to the local store.
|
||||
|
||||
)""
|
||||
|
|
@ -385,30 +385,11 @@ struct CmdDevelop : Common, MixEnvironment
|
|||
return "run a bash shell that provides the build environment of a derivation";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To get the build environment of GNU hello:",
|
||||
"nix develop nixpkgs#hello"
|
||||
},
|
||||
Example{
|
||||
"To get the build environment of the default package of flake in the current directory:",
|
||||
"nix develop"
|
||||
},
|
||||
Example{
|
||||
"To store the build environment in a profile:",
|
||||
"nix develop --profile /tmp/my-shell nixpkgs#hello"
|
||||
},
|
||||
Example{
|
||||
"To use a build environment previously recorded in a profile:",
|
||||
"nix develop /tmp/my-shell"
|
||||
},
|
||||
Example{
|
||||
"To replace all occurences of a store path with a writable directory:",
|
||||
"nix develop --redirect nixpkgs#glibc.dev ~/my-glibc/outputs/dev"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "develop.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
@ -495,14 +476,11 @@ struct CmdPrintDevEnv : Common
|
|||
return "print shell code that can be sourced by bash to reproduce the build environment of a derivation";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To apply the build environment of GNU hello to the current shell:",
|
||||
". <(nix print-dev-env nixpkgs#hello)"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "print-dev-env.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catUtility; }
|
||||
|
|
|
|||
94
src/nix/develop.md
Normal file
94
src/nix/develop.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Start a shell with the build environment of the default package of
|
||||
the flake in the current directory:
|
||||
|
||||
```console
|
||||
# nix develop
|
||||
```
|
||||
|
||||
Typical commands to run inside this shell are:
|
||||
|
||||
```console
|
||||
# configurePhase
|
||||
# buildPhase
|
||||
# installPhase
|
||||
```
|
||||
|
||||
Alternatively, you can run whatever build tools your project uses
|
||||
directly, e.g. for a typical Unix project:
|
||||
|
||||
```console
|
||||
# ./configure --prefix=$out
|
||||
# make
|
||||
# make install
|
||||
```
|
||||
|
||||
* Run a particular build phase directly:
|
||||
|
||||
```console
|
||||
# nix develop --configure
|
||||
# nix develop --build
|
||||
# nix develop --check
|
||||
# nix develop --install
|
||||
# nix develop --installcheck
|
||||
```
|
||||
|
||||
* Start a shell with the build environment of GNU Hello:
|
||||
|
||||
```console
|
||||
# nix develop nixpkgs#hello
|
||||
```
|
||||
|
||||
* Record a build environment in a profile:
|
||||
|
||||
```console
|
||||
# nix develop --profile /tmp/my-build-env nixpkgs#hello
|
||||
```
|
||||
|
||||
* Use a build environment previously recorded in a profile:
|
||||
|
||||
```console
|
||||
# nix develop /tmp/my-build-env
|
||||
```
|
||||
|
||||
* Replace all occurences of the store path corresponding to
|
||||
`glibc.dev` with a writable directory:
|
||||
|
||||
```console
|
||||
# nix develop --redirect nixpkgs#glibc.dev ~/my-glibc/outputs/dev
|
||||
```
|
||||
|
||||
Note that this is useful if you're running a `nix develop` shell for
|
||||
`nixpkgs#glibc` in `~/my-glibc` and want to compile another package
|
||||
against it.
|
||||
|
||||
# Description
|
||||
|
||||
`nix develop` starts a `bash` shell that provides an interactive build
|
||||
environment nearly identical to what Nix would use to build
|
||||
*installable*. Inside this shell, environment variables and shell
|
||||
functions are set up so that you can interactively and incrementally
|
||||
build your package.
|
||||
|
||||
Nix determines the build environment by building a modified version of
|
||||
the derivation *installable* that just records the environment
|
||||
initialised by `stdenv` and exits. This build environment can be
|
||||
recorded into a profile using `--profile`.
|
||||
|
||||
The prompt used by the `bash` shell can be customised by setting the
|
||||
`bash-prompt` and `bash-prompt-suffix` settings in `nix.conf` or in
|
||||
the flake's `nixConfig` attribute.
|
||||
|
||||
# Flake output attributes
|
||||
|
||||
If no flake output attribute is given, `nix run` tries the following
|
||||
flake output attributes:
|
||||
|
||||
* `devShell.<system>`
|
||||
|
||||
* `defaultPackage.<system>`
|
||||
|
||||
)""
|
||||
|
|
@ -121,14 +121,11 @@ struct CmdDiffClosures : SourceExprCommand
|
|||
return "show what packages and versions were added and removed between two closures";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
{
|
||||
"To show what got added and removed between two versions of the NixOS system profile:",
|
||||
"nix store diff-closures /nix/var/nix/profiles/system-655-link /nix/var/nix/profiles/system-658-link",
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "diff-closures.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
|
|||
51
src/nix/diff-closures.md
Normal file
51
src/nix/diff-closures.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show what got added and removed between two versions of the NixOS
|
||||
system profile:
|
||||
|
||||
```console
|
||||
# nix store diff-closures /nix/var/nix/profiles/system-655-link /nix/var/nix/profiles/system-658-link
|
||||
acpi-call: 2020-04-07-5.8.16 → 2020-04-07-5.8.18
|
||||
baloo-widgets: 20.08.1 → 20.08.2
|
||||
bluez-qt: +12.6 KiB
|
||||
dolphin: 20.08.1 → 20.08.2, +13.9 KiB
|
||||
kdeconnect: 20.08.2 → ∅, -6597.8 KiB
|
||||
kdeconnect-kde: ∅ → 20.08.2, +6599.7 KiB
|
||||
…
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows the differences between the two closures *before*
|
||||
and *after* with respect to the addition, removal, or version change
|
||||
of packages, as well as changes in store path sizes.
|
||||
|
||||
For each package name in the two closures (where a package name is
|
||||
defined as the name component of a store path excluding the version),
|
||||
if there is a change in the set of versions of the package, or a
|
||||
change in the size of the store paths of more than 8 KiB, it prints a
|
||||
line like this:
|
||||
|
||||
```console
|
||||
dolphin: 20.08.1 → 20.08.2, +13.9 KiB
|
||||
```
|
||||
|
||||
No size change is shown if it's below the threshold. If the package
|
||||
does not exist in either the *before* or *after* closures, it is
|
||||
represented using `∅` (empty set) on the appropriate side of the
|
||||
arrow. If a package has an empty version string, the version is
|
||||
rendered as `ε` (epsilon).
|
||||
|
||||
There may be multiple versions of a package in each closure. In that
|
||||
case, only the changed versions are shown. Thus,
|
||||
|
||||
```console
|
||||
libfoo: 1.2, 1.3 → 1.4
|
||||
```
|
||||
|
||||
leaves open the possibility that there are other versions (e.g. `1.1`)
|
||||
that exist in both closures.
|
||||
|
||||
)""
|
||||
|
|
@ -11,14 +11,11 @@ struct CmdDumpPath : StorePathCommand
|
|||
return "serialise a store path to stdout in NAR format";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To get a NAR from the binary cache https://cache.nixos.org/:",
|
||||
"nix store dump-path --store https://cache.nixos.org/ /nix/store/7crrmih8c52r8fbnqb933dxrsp44md93-glibc-2.25"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "store-dump-path.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store, const StorePath & storePath) override
|
||||
|
|
@ -49,14 +46,11 @@ struct CmdDumpPath2 : Command
|
|||
return "serialise a path to stdout in NAR format";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To serialise directory 'foo' as a NAR:",
|
||||
"nix nar dump-path ./foo"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "nar-dump-path.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run() override
|
||||
|
|
|
|||
|
|
@ -15,14 +15,11 @@ struct CmdEdit : InstallableCommand
|
|||
return "open the Nix expression of a Nix package in $EDITOR";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To open the Nix expression of the GNU Hello package:",
|
||||
"nix edit nixpkgs#hello"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "edit.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
|
|
|||
31
src/nix/edit.md
Normal file
31
src/nix/edit.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Open the Nix expression of the GNU Hello package:
|
||||
|
||||
```console
|
||||
# nix edit nixpkgs#hello
|
||||
```
|
||||
|
||||
* Get the filename and line number used by `nix edit`:
|
||||
|
||||
```console
|
||||
# nix eval --raw nixpkgs#hello.meta.position
|
||||
/nix/store/fvafw0gvwayzdan642wrv84pzm5bgpmy-source/pkgs/applications/misc/hello/default.nix:15
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command opens the Nix expression of a derivation in an
|
||||
editor. The filename and line number of the derivation are taken from
|
||||
its `meta.position` attribute. Nixpkgs' `stdenv.mkDerivation` sets
|
||||
this attribute to the location of the definition of the
|
||||
`meta.description`, `version` or `name` derivation attributes.
|
||||
|
||||
The editor to invoke is specified by the `EDITOR` environment
|
||||
variable. It defaults to `cat`. If the editor is `emacs`, `nano` or
|
||||
`vim`, it is passed the line number of the derivation using the
|
||||
argument `+<lineno>`.
|
||||
|
||||
)""
|
||||
|
|
@ -40,30 +40,11 @@ struct CmdEval : MixJSON, InstallableCommand
|
|||
return "evaluate a Nix expression";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
{
|
||||
"To evaluate a Nix expression given on the command line:",
|
||||
"nix eval --expr '1 + 2'"
|
||||
},
|
||||
{
|
||||
"To evaluate a Nix expression from a file or URI:",
|
||||
"nix eval -f ./my-nixpkgs hello.name"
|
||||
},
|
||||
{
|
||||
"To get the current version of Nixpkgs:",
|
||||
"nix eval --raw nixpkgs#lib.version"
|
||||
},
|
||||
{
|
||||
"To print the store path of the Hello package:",
|
||||
"nix eval --raw nixpkgs#hello"
|
||||
},
|
||||
{
|
||||
"To get a list of checks in the 'nix' flake:",
|
||||
"nix eval nix#checks.x86_64-linux --apply builtins.attrNames"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "eval.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
|
|
|||
74
src/nix/eval.md
Normal file
74
src/nix/eval.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Evaluate a Nix expression given on the command line:
|
||||
|
||||
```console
|
||||
# nix eval --expr '1 + 2'
|
||||
```
|
||||
|
||||
* Evaluate a Nix expression to JSON:
|
||||
|
||||
```console
|
||||
# nix eval --json --expr '{ x = 1; }'
|
||||
{"x":1}
|
||||
```
|
||||
|
||||
* Evaluate a Nix expression from a file:
|
||||
|
||||
```console
|
||||
# nix eval -f ./my-nixpkgs hello.name
|
||||
```
|
||||
|
||||
* Get the current version of the `nixpkgs` flake:
|
||||
|
||||
```console
|
||||
# nix eval --raw nixpkgs#lib.version
|
||||
```
|
||||
|
||||
* Print the store path of the Hello package:
|
||||
|
||||
```console
|
||||
# nix eval --raw nixpkgs#hello
|
||||
```
|
||||
|
||||
* Get a list of checks in the `nix` flake:
|
||||
|
||||
```console
|
||||
# nix eval nix#checks.x86_64-linux --apply builtins.attrNames
|
||||
```
|
||||
|
||||
* Generate a directory with the specified contents:
|
||||
|
||||
```console
|
||||
# nix eval --write-to ./out --expr '{ foo = "bar"; subdir.bla = "123"; }'
|
||||
# cat ./out/foo
|
||||
bar
|
||||
# cat ./out/subdir/bla
|
||||
123
|
||||
|
||||
# Description
|
||||
|
||||
This command evaluates the Nix expression *installable* and prints the
|
||||
result on standard output.
|
||||
|
||||
# Output format
|
||||
|
||||
`nix eval` can produce output in several formats:
|
||||
|
||||
* By default, the evaluation result is printed as a Nix expression.
|
||||
|
||||
* With `--json`, the evaluation result is printed in JSON format. Note
|
||||
that this fails if the result contains values that are not
|
||||
representable as JSON, such as functions.
|
||||
|
||||
* With `--raw`, the evaluation result must be a string, which is
|
||||
printed verbatim, without any quoting.
|
||||
|
||||
* With `--write-to` *path*, the evaluation result must be a string or
|
||||
a nested attribute set whose leaf values are strings. These strings
|
||||
are written to files named *path*/*attrpath*. *path* must not
|
||||
already exist.
|
||||
|
||||
)""
|
||||
29
src/nix/flake-archive.md
Normal file
29
src/nix/flake-archive.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Copy the `dwarffs` flake and its dependencies to a binary cache:
|
||||
|
||||
```console
|
||||
# nix flake archive --to file:///tmp/my-cache dwarffs
|
||||
```
|
||||
|
||||
* Fetch the `dwarffs` flake and its dependencies to the local Nix
|
||||
store:
|
||||
|
||||
```console
|
||||
# nix flake archive dwarffs
|
||||
```
|
||||
|
||||
* Print the store paths of the flake sources of NixOps without
|
||||
fetching them:
|
||||
|
||||
```console
|
||||
# nix flake archive --json --dry-run nixops
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
FIXME
|
||||
|
||||
)""
|
||||
68
src/nix/flake-check.md
Normal file
68
src/nix/flake-check.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Evaluate the flake in the current directory, and build its checks:
|
||||
|
||||
```console
|
||||
# nix flake check
|
||||
```
|
||||
|
||||
* Verify that the `patchelf` flake evaluates, but don't build its
|
||||
checks:
|
||||
|
||||
```console
|
||||
# nix flake check --no-build github:NixOS/patchelf
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command verifies that the flake specified by flake reference
|
||||
*flake-url* can be evaluated successfully (as detailed below), and
|
||||
that the derivations specified by the flake's `checks` output can be
|
||||
built successfully.
|
||||
|
||||
# Evaluation checks
|
||||
|
||||
This following flake output attributes must be derivations:
|
||||
|
||||
* `checks.`*system*`.`*name*
|
||||
* `defaultPackage.`*system*`
|
||||
* `devShell.`*system*`
|
||||
* `nixosConfigurations.`*name*`.config.system.build.toplevel
|
||||
* `packages.`*system*`.`*name*
|
||||
|
||||
The following flake output attributes must be [app
|
||||
definitions](./nix3-run.md):
|
||||
|
||||
* `apps.`*system*`.`*name*
|
||||
* `defaultApp.`*system*`
|
||||
|
||||
The following flake output attributes must be [template
|
||||
definitions](./nix3-flake-init.md):
|
||||
|
||||
* `defaultTemplate`
|
||||
* `templates`.`*name*
|
||||
|
||||
The following flake output attributes must be *Nixpkgs overlays*:
|
||||
|
||||
* `overlay`
|
||||
* `overlays`.`*name*
|
||||
|
||||
The following flake output attributes must be *NixOS modules*:
|
||||
|
||||
* `nixosModule`
|
||||
* `nixosModules`.`*name*
|
||||
|
||||
The following flake output attributes must be
|
||||
[bundlers](./nix3-bundle.md):
|
||||
|
||||
* `bundlers`.`*name*
|
||||
* `defaultBundler`
|
||||
|
||||
In addition, the `hydraJobs` output is evaluated in the same way as
|
||||
Hydra's `hydra-eval-jobs` (i.e. as a arbitrarily deeply nested
|
||||
attribute set of derivations). Similarly, the
|
||||
`legacyPackages`.*system* output is evaluated like `nix-env -qa`.
|
||||
|
||||
)""
|
||||
18
src/nix/flake-clone.md
Normal file
18
src/nix/flake-clone.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Check out the source code of the `dwarffs` flake and build it:
|
||||
|
||||
```console
|
||||
# nix flake clone dwarffs --dest dwarffs
|
||||
# cd dwarffs
|
||||
# nix build
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command performs a Git or Mercurial clone of the repository
|
||||
containing the source code of the flake *flake-url*.
|
||||
|
||||
)""
|
||||
99
src/nix/flake-info.md
Normal file
99
src/nix/flake-info.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show what `nixpkgs` resolves to:
|
||||
|
||||
```console
|
||||
# nix flake info nixpkgs
|
||||
Resolved URL: github:NixOS/nixpkgs
|
||||
Locked URL: github:NixOS/nixpkgs/b67ba0bfcc714453cdeb8d713e35751eb8b4c8f4
|
||||
Description: A collection of packages for the Nix package manager
|
||||
Path: /nix/store/23qapccs6cfmwwrlq8kr41vz5vdmns3r-source
|
||||
Revision: b67ba0bfcc714453cdeb8d713e35751eb8b4c8f4
|
||||
Last modified: 2020-12-23 12:36:12
|
||||
```
|
||||
|
||||
* Show information about `dwarffs` in JSON format:
|
||||
|
||||
```console
|
||||
# nix flake info dwarffs --json | jq .
|
||||
{
|
||||
"description": "A filesystem that fetches DWARF debug info from the Internet on demand",
|
||||
"lastModified": 1597153508,
|
||||
"locked": {
|
||||
"lastModified": 1597153508,
|
||||
"narHash": "sha256-VHg3MYVgQ12LeRSU2PSoDeKlSPD8PYYEFxxwkVVDRd0=",
|
||||
"owner": "edolstra",
|
||||
"repo": "dwarffs",
|
||||
"rev": "d181d714fd36eb06f4992a1997cd5601e26db8f5",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"id": "dwarffs",
|
||||
"type": "indirect"
|
||||
},
|
||||
"originalUrl": "flake:dwarffs",
|
||||
"path": "/nix/store/hang3792qwdmm2n0d9nsrs5n6bsws6kv-source",
|
||||
"resolved": {
|
||||
"owner": "edolstra",
|
||||
"repo": "dwarffs",
|
||||
"type": "github"
|
||||
},
|
||||
"resolvedUrl": "github:edolstra/dwarffs",
|
||||
"revision": "d181d714fd36eb06f4992a1997cd5601e26db8f5",
|
||||
"url": "github:edolstra/dwarffs/d181d714fd36eb06f4992a1997cd5601e26db8f5"
|
||||
}
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows information about the flake specified by the flake
|
||||
reference *flake-url*. It resolves the flake reference using the
|
||||
[flake registry](./nix3-registry.md), fetches it, and prints some meta
|
||||
data. This includes:
|
||||
|
||||
* `Resolved URL`: If *flake-url* is a flake identifier, then this is
|
||||
the flake reference that specifies its actual location, looked up in
|
||||
the flake registry.
|
||||
|
||||
* `Locked URL`: A flake reference that contains a commit or content
|
||||
hash and thus uniquely identifies a specific flake version.
|
||||
|
||||
* `Description`: A one-line description of the flake, taken from the
|
||||
`description` field in `flake.nix`.
|
||||
|
||||
* `Path`: The store path containing the source code of the flake.
|
||||
|
||||
* `Revision`: The Git or Mercurial commit hash of the locked flake.
|
||||
|
||||
* `Revisions`: The number of ancestors of the Git or Mercurial commit
|
||||
of the locked flake. Note that this is not available for `github`
|
||||
flakes.
|
||||
|
||||
* `Last modified`: For Git or Mercurial flakes, this is the commit
|
||||
time of the commit of the locked flake; for tarball flakes, it's the
|
||||
most recent timestamp of any file inside the tarball.
|
||||
|
||||
With `--json`, the output is a JSON object with the following fields:
|
||||
|
||||
* `original` and `originalUrl`: The flake reference specified by the
|
||||
user (*flake-url*) in attribute set and URL representation.
|
||||
|
||||
* `resolved` and `resolvedUrl`: The resolved flake reference (see
|
||||
above) in attribute set and URL representation.
|
||||
|
||||
* `locked` and `lockedUrl`: The locked flake reference (see above) in
|
||||
attribute set and URL representation.
|
||||
|
||||
* `description`: See `Description` above.
|
||||
|
||||
* `path`: See `Path` above.
|
||||
|
||||
* `revision`: See `Revision` above.
|
||||
|
||||
* `revCount`: See `Revisions` above.
|
||||
|
||||
* `lastModified`: See `Last modified` above.
|
||||
|
||||
)""
|
||||
54
src/nix/flake-init.md
Normal file
54
src/nix/flake-init.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Create a flake using the default template:
|
||||
|
||||
```console
|
||||
# nix flake init
|
||||
```
|
||||
|
||||
* List available templates:
|
||||
|
||||
```console
|
||||
# nix flake show templates
|
||||
```
|
||||
|
||||
* Create a flake from a specific template:
|
||||
|
||||
```console
|
||||
# nix flake init -t templates#simpleContainer
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command creates a flake in the current directory by copying the
|
||||
files of a template. It will not overwrite existing files. The default
|
||||
template is `templates#defaultTemplate`, but this can be overriden
|
||||
using `-t`.
|
||||
|
||||
# Template definitions
|
||||
|
||||
A flake can declare templates through its `templates` and
|
||||
`defaultTemplate` output attributes. A template has two attributes:
|
||||
|
||||
* `description`: A one-line description of the template, in CommonMark
|
||||
syntax.
|
||||
|
||||
* `path`: The path of the directory to be copied.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```
|
||||
outputs = { self }: {
|
||||
|
||||
templates.rust = {
|
||||
path = ./rust;
|
||||
description = "A simple Rust/Cargo project";
|
||||
};
|
||||
|
||||
templates.defaultTemplate = self.templates.rust;
|
||||
}
|
||||
```
|
||||
|
||||
)""
|
||||
23
src/nix/flake-list-inputs.md
Normal file
23
src/nix/flake-list-inputs.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show the inputs of the `hydra` flake:
|
||||
|
||||
```console
|
||||
# nix flake list-inputs github:NixOS/hydra
|
||||
github:NixOS/hydra/bde8d81876dfc02143e5070e42c78d8f0d83d6f7
|
||||
├───nix: github:NixOS/nix/79aa7d95183cbe6c0d786965f0dbff414fd1aa67
|
||||
│ ├───lowdown-src: github:kristapsdz/lowdown/1705b4a26fbf065d9574dce47a94e8c7c79e052f
|
||||
│ └───nixpkgs: github:NixOS/nixpkgs/ad0d20345219790533ebe06571f82ed6b034db31
|
||||
└───nixpkgs follows input 'nix/nixpkgs'
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows the inputs of the flake specified by the flake
|
||||
referenced *flake-url*. Since it prints the locked inputs that result
|
||||
from generating or updating the lock file, this command essentially
|
||||
displays the contents of the flake's lock file in human-readable form.
|
||||
|
||||
)""
|
||||
34
src/nix/flake-new.md
Normal file
34
src/nix/flake-new.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Create a flake using the default template in the directory `hello`:
|
||||
|
||||
```console
|
||||
# nix flake new hello
|
||||
```
|
||||
|
||||
* List available templates:
|
||||
|
||||
```console
|
||||
# nix flake show templates
|
||||
```
|
||||
|
||||
* Create a flake from a specific template in the directory `hello`:
|
||||
|
||||
```console
|
||||
# nix flake new hello -t templates#trivial
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command creates a flake in the directory `dest-dir`, which must
|
||||
not already exist. It's equivalent to:
|
||||
|
||||
```console
|
||||
# mkdir dest-dir
|
||||
# cd dest-dir
|
||||
# nix flake init
|
||||
```
|
||||
|
||||
)""
|
||||
38
src/nix/flake-show.md
Normal file
38
src/nix/flake-show.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show the output attributes provided by the `patchelf` flake:
|
||||
|
||||
```console
|
||||
github:NixOS/patchelf/f34751b88bd07d7f44f5cd3200fb4122bf916c7e
|
||||
├───checks
|
||||
│ ├───aarch64-linux
|
||||
│ │ └───build: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
│ ├───i686-linux
|
||||
│ │ └───build: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
│ └───x86_64-linux
|
||||
│ └───build: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
├───defaultPackage
|
||||
│ ├───aarch64-linux: package 'patchelf-0.12.20201207.f34751b'
|
||||
│ ├───i686-linux: package 'patchelf-0.12.20201207.f34751b'
|
||||
│ └───x86_64-linux: package 'patchelf-0.12.20201207.f34751b'
|
||||
├───hydraJobs
|
||||
│ ├───build
|
||||
│ │ ├───aarch64-linux: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
│ │ ├───i686-linux: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
│ │ └───x86_64-linux: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
│ ├───coverage: derivation 'patchelf-coverage-0.12.20201207.f34751b'
|
||||
│ ├───release: derivation 'patchelf-0.12.20201207.f34751b'
|
||||
│ └───tarball: derivation 'patchelf-tarball-0.12.20201207.f34751b'
|
||||
└───overlay: Nixpkgs overlay
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows the output attributes provided by the flake
|
||||
specified by flake reference *flake-url*. These are the top-level
|
||||
attributes in the `outputs` of the flake, as well as lower-level
|
||||
attributes for some standard outputs (e.g. `packages` or `checks`).
|
||||
|
||||
)""
|
||||
53
src/nix/flake-update.md
Normal file
53
src/nix/flake-update.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Update the `nixpkgs` and `nix` inputs of the flake in the current
|
||||
directory:
|
||||
|
||||
```console
|
||||
# nix flake update --update-input nixpkgs --update-input nix
|
||||
* Updated 'nix': 'github:NixOS/nix/9fab14adbc3810d5cc1f88672fde1eee4358405c' -> 'github:NixOS/nix/8927cba62f5afb33b01016d5c4f7f8b7d0adde3c'
|
||||
* Updated 'nixpkgs': 'github:NixOS/nixpkgs/3d2d8f281a27d466fa54b469b5993f7dde198375' -> 'github:NixOS/nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293'
|
||||
```
|
||||
|
||||
* Recreate the lock file (i.e. update all inputs) and commit the new
|
||||
lock file:
|
||||
|
||||
```console
|
||||
# nix flake update --recreate-lock-file --commit-lock-file
|
||||
…
|
||||
warning: committed new revision '158bcbd9d6cc08ab859c0810186c1beebc982aad'
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command updates the lock file of a flake (`flake.lock`) so that
|
||||
it contains a lock for every flake input specified in
|
||||
`flake.nix`. Note that every command that operates on a flake will
|
||||
also update the lock file if needed, and supports the same
|
||||
flags. Therefore,
|
||||
|
||||
```console
|
||||
# nix flake update --update-input nixpkgs
|
||||
# nix build
|
||||
```
|
||||
|
||||
is equivalent to:
|
||||
|
||||
```console
|
||||
# nix build --update-input nixpkgs
|
||||
```
|
||||
|
||||
Thus, this command is only useful if you want to update the lock file
|
||||
separately from any other action such as building.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> This command does *not* update locks that are already present unless
|
||||
> you explicitly ask for it using `--update-input` or
|
||||
> `--recreate-lock-file`. Thus, if the lock file already has locks for
|
||||
> every input, then `nix flake update` (without arguments) does
|
||||
> nothing.
|
||||
|
||||
)""
|
||||
|
|
@ -104,6 +104,13 @@ struct CmdFlakeUpdate : FlakeCommand
|
|||
return "update flake lock file";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-update.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
{
|
||||
/* Use --refresh by default for 'nix flake update'. */
|
||||
|
|
@ -134,6 +141,13 @@ struct CmdFlakeInfo : FlakeCommand, MixJSON
|
|||
return "list info about a given flake";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-info.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
{
|
||||
auto flake = getFlake();
|
||||
|
|
@ -153,6 +167,13 @@ struct CmdFlakeListInputs : FlakeCommand, MixJSON
|
|||
return "list flake inputs";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-list-inputs.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
{
|
||||
auto flake = lockFlake();
|
||||
|
|
@ -211,6 +232,13 @@ struct CmdFlakeCheck : FlakeCommand
|
|||
return "check whether the flake evaluates and run its tests";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-check.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
{
|
||||
settings.readOnlyMode = !build;
|
||||
|
|
@ -631,22 +659,11 @@ struct CmdFlakeInit : CmdFlakeInitCommon
|
|||
return "create a flake in the current directory from a template";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To create a flake using the default template:",
|
||||
"nix flake init"
|
||||
},
|
||||
Example{
|
||||
"To see available templates:",
|
||||
"nix flake show templates"
|
||||
},
|
||||
Example{
|
||||
"To create a flake from a specific template:",
|
||||
"nix flake init -t templates#nixos-container"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "flake-init.md"
|
||||
;
|
||||
}
|
||||
|
||||
CmdFlakeInit()
|
||||
|
|
@ -662,6 +679,13 @@ struct CmdFlakeNew : CmdFlakeInitCommon
|
|||
return "create a flake in the specified directory from a template";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-new.md"
|
||||
;
|
||||
}
|
||||
|
||||
CmdFlakeNew()
|
||||
{
|
||||
expectArgs({
|
||||
|
|
@ -681,6 +705,13 @@ struct CmdFlakeClone : FlakeCommand
|
|||
return "clone flake repository";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-clone.md"
|
||||
;
|
||||
}
|
||||
|
||||
CmdFlakeClone()
|
||||
{
|
||||
addFlag({
|
||||
|
|
@ -720,22 +751,11 @@ struct CmdFlakeArchive : FlakeCommand, MixJSON, MixDryRun
|
|||
return "copy a flake and all its inputs to a store";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To copy the dwarffs flake and its dependencies to a binary cache:",
|
||||
"nix flake archive --to file:///tmp/my-cache dwarffs"
|
||||
},
|
||||
Example{
|
||||
"To fetch the dwarffs flake and its dependencies to the local Nix store:",
|
||||
"nix flake archive dwarffs"
|
||||
},
|
||||
Example{
|
||||
"To print the store paths of the flake sources of NixOps without fetching them:",
|
||||
"nix flake archive --json --dry-run nixops"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "flake-archive.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
|
|
@ -797,6 +817,13 @@ struct CmdFlakeShow : FlakeCommand
|
|||
return "show the outputs provided by a flake";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake-show.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
{
|
||||
auto state = getEvalState();
|
||||
|
|
@ -955,6 +982,13 @@ struct CmdFlake : NixMultiCommand
|
|||
return "manage Nix flakes";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "flake.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run() override
|
||||
{
|
||||
if (!command)
|
||||
|
|
|
|||
566
src/nix/flake.md
Normal file
566
src/nix/flake.md
Normal file
|
|
@ -0,0 +1,566 @@
|
|||
R""(
|
||||
|
||||
# Description
|
||||
|
||||
`nix flake` provides subcommands for creating, modifying and querying
|
||||
*Nix flakes*. Flakes are the unit for packaging Nix code in a
|
||||
reproducible and discoverable way. They can have dependencies on other
|
||||
flakes, making it possible to have multi-repository Nix projects.
|
||||
|
||||
A flake is a filesystem tree (typically fetched from a Git repository
|
||||
or a tarball) that contains a file named `flake.nix` in the root
|
||||
directory. `flake.nix` specifies some metadata about the flake such as
|
||||
dependencies (called *inputs*), as well as its *outputs* (the Nix
|
||||
values such as packages or NixOS modules provided by the flake).
|
||||
|
||||
# Flake references
|
||||
|
||||
Flake references (*flakerefs*) are a way to specify the location of a
|
||||
flake. These have two different forms:
|
||||
|
||||
* An attribute set representation, e.g.
|
||||
|
||||
```nix
|
||||
{
|
||||
type = "github";
|
||||
owner = "NixOS";
|
||||
repo = "nixpkgs";
|
||||
}
|
||||
```
|
||||
|
||||
The only required attribute is `type`. The supported types are
|
||||
listed below.
|
||||
|
||||
* A URL-like syntax, e.g.
|
||||
|
||||
```
|
||||
github:NixOS/nixpkgs
|
||||
```
|
||||
|
||||
These are used on the command line as a more convenient alternative
|
||||
to the attribute set representation. For instance, in the command
|
||||
|
||||
```console
|
||||
# nix build github:NixOS/nixpkgs#hello
|
||||
```
|
||||
|
||||
`github:NixOS/nixpkgs` is a flake reference (while `hello` is an
|
||||
output attribute). They are also allowed in the `inputs` attribute
|
||||
of a flake, e.g.
|
||||
|
||||
```nix
|
||||
inputs.nixpkgs.url = github:NixOS/nixpkgs;
|
||||
```
|
||||
|
||||
is equivalent to
|
||||
|
||||
```nix
|
||||
inputs.nixpkgs = {
|
||||
type = "github";
|
||||
owner = "NixOS";
|
||||
repo = "nixpkgs";
|
||||
};
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Here are some examples of flake references in their URL-like representation:
|
||||
|
||||
* `.`: The flake in the current directory.
|
||||
* `/home/alice/src/patchelf`: A flake in some other directory.
|
||||
* `nixpkgs`: The `nixpkgs` entry in the flake registry.
|
||||
* `nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`: The `nixpkgs`
|
||||
entry in the flake registry, with its Git revision overriden to a
|
||||
specific value.
|
||||
* `github:NixOS/nixpkgs`: The `master` branch of the `NixOS/nixpkgs`
|
||||
repository on GitHub.
|
||||
* `github:NixOS/nixpkgs/nixos-20.09`: The `nixos-20.09` branch of the
|
||||
`nixpkgs` repository.
|
||||
* `github:NixOS/nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`: A
|
||||
specific revision of the `nixpkgs` repository.
|
||||
* `github:edolstra/nix-warez?dir=blender`: A flake in a subdirectory
|
||||
of a GitHub repository.
|
||||
* `git+https://github.com/NixOS/patchelf`: A Git repository.
|
||||
* `git+https://github.com/NixOS/patchelf?ref=master`: A specific
|
||||
branch of a Git repository.
|
||||
* `git+https://github.com/NixOS/patchelf?ref=master&rev=f34751b88bd07d7f44f5cd3200fb4122bf916c7e`:
|
||||
A specific branch *and* revision of a Git repository.
|
||||
* `https://github.com/NixOS/patchelf/archive/master.tar.gz`: A tarball
|
||||
flake.
|
||||
|
||||
## Flake reference attributes
|
||||
|
||||
The following generic flake reference attributes are supported:
|
||||
|
||||
* `dir`: The subdirectory of the flake in which `flake.nix` is
|
||||
located. This parameter enables having multiple flakes in a
|
||||
repository or tarball. The default is the root directory of the
|
||||
flake.
|
||||
|
||||
* `narHash`: The hash of the NAR serialisation (in SRI format) of the
|
||||
contents of the flake. This is useful for flake types such as
|
||||
tarballs that lack a unique content identifier such as a Git commit
|
||||
hash.
|
||||
|
||||
In addition, the following attributes are common to several flake
|
||||
reference types:
|
||||
|
||||
* `rev`: A Git or Mercurial commit hash.
|
||||
|
||||
* `ref`: A Git or Mercurial branch or tag name.
|
||||
|
||||
Finally, some attribute are typically not specified by the user, but
|
||||
can occur in *locked* flake references and are available to Nix code:
|
||||
|
||||
* `revCount`: The number of ancestors of the commit `rev`.
|
||||
|
||||
* `lastModified`: The timestamp (in seconds since the Unix epoch) of
|
||||
the last modification of this version of the flake. For
|
||||
Git/Mercurial flakes, this is the commit time of commit *rev*, while
|
||||
for tarball flakes, it's the most recent timestamp of any file
|
||||
inside the tarball.
|
||||
|
||||
## Types
|
||||
|
||||
Currently the `type` attribute can be one of the following:
|
||||
|
||||
* `path`: arbitrary local directories, or local Git trees. The
|
||||
required attribute `path` specifies the path of the flake. The URL
|
||||
form is
|
||||
|
||||
```
|
||||
[path:]<path>(\?<params)?
|
||||
```
|
||||
|
||||
where *path* is an absolute path.
|
||||
|
||||
*path* must be a directory in the file system containing a file
|
||||
named `flake.nix`.
|
||||
|
||||
If the directory or any of its parents is a Git repository, then
|
||||
this is essentially equivalent to `git+file://<path>` (see below),
|
||||
except that the `dir` parameter is derived automatically. For
|
||||
example, if `/foo/bar` is a Git repository, then the flake reference
|
||||
`/foo/bar/flake` is equivalent to `/foo/bar?dir=flake`.
|
||||
|
||||
If the directory is not inside a Git repository, then the flake
|
||||
contents is the entire contents of *path*.
|
||||
|
||||
*path* generally must be an absolute path. However, on the command
|
||||
line, it can be a relative path (e.g. `.` or `./foo`) which is
|
||||
interpreted as relative to the current directory. In this case, it
|
||||
must start with `.` to avoid ambiguity with registry lookups
|
||||
(e.g. `nixpkgs` is a registry lookup; `./nixpkgs` is a relative
|
||||
path).
|
||||
|
||||
* `git`: Git repositories. The location of the repository is specified
|
||||
by the attribute `url`.
|
||||
|
||||
They have the URL form
|
||||
|
||||
```
|
||||
git(+http|+https|+ssh|+git|+file|):(//<server>)?<path>(\?<params>)?
|
||||
```
|
||||
|
||||
The `ref` attribute defaults to `master`.
|
||||
|
||||
The `rev` attribute must denote a commit that exists in the branch
|
||||
or tag specified by the `ref` attribute, since Nix doesn't do a full
|
||||
clone of the remote repository by default (and the Git protocol
|
||||
doesn't allow fetching a `rev` without a known `ref`). The default
|
||||
is the commit currently pointed to by `ref`.
|
||||
|
||||
For example, the following are valid Git flake references:
|
||||
|
||||
* `git+https://example.org/my/repo`
|
||||
* `git+https://example.org/my/repo?dir=flake1`
|
||||
* `git+ssh://git@github.com/NixOS/nix?ref=v1.2.3`
|
||||
* `git://github.com/edolstra/dwarffs?ref=unstable&rev=e486d8d40e626a20e06d792db8cc5ac5aba9a5b4`
|
||||
* `git+file:///home/my-user/some-repo/some-repo`
|
||||
|
||||
* `mercurial`: Mercurial repositories. The URL form is similar to the
|
||||
`git` type, except that the URL schema must be one of `hg+http`,
|
||||
`hg+https`, `hg+ssh` or `hg+file`.
|
||||
|
||||
* `tarball`: Tarballs. The location of the tarball is specified by the
|
||||
attribute `url`.
|
||||
|
||||
In URL form, the schema must be `http://`, `https://` or `file://`
|
||||
URLs and the extension must be `.zip`, `.tar`, `.tar.gz`, `.tar.xz`
|
||||
or `.tar.bz2`.
|
||||
|
||||
* `github`: A more efficient way to fetch repositories from
|
||||
GitHub. The following attributes are required:
|
||||
|
||||
* `owner`: The owner of the repository.
|
||||
|
||||
* `repo`: The name of the repository.
|
||||
|
||||
These are downloaded as tarball archives, rather than
|
||||
through Git. This is often much faster and uses less disk space
|
||||
since it doesn't require fetching the entire history of the
|
||||
repository. On the other hand, it doesn't allow incremental fetching
|
||||
(but full downloads are often faster than incremental fetches!).
|
||||
|
||||
The URL syntax for `github` flakes is:
|
||||
|
||||
```
|
||||
github:<owner>/<repo>(/<rev-or-ref>)?(\?<params>)?
|
||||
```
|
||||
|
||||
`<rev-or-ref>` specifies the name of a branch or tag (`ref`), or a
|
||||
commit hash (`rev`). Note that unlike Git, GitHub allows fetching by
|
||||
commit hash without specifying a branch or tag.
|
||||
|
||||
Some examples:
|
||||
|
||||
* `github:edolstra/dwarffs`
|
||||
* `github:edolstra/dwarffs/unstable`
|
||||
* `github:edolstra/dwarffs/d3f2baba8f425779026c6ec04021b2e927f61e31`
|
||||
|
||||
* `indirect`: Indirections through the flake registry. These have the
|
||||
form
|
||||
|
||||
```
|
||||
[flake:]<flake-id>(/<rev-or-ref>(/rev)?)?
|
||||
```
|
||||
|
||||
These perform a lookup of `<flake-id>` in the flake registry. or
|
||||
example, `nixpkgs` and `nixpkgs/release-20.09` are indirect flake
|
||||
references. The specified `rev` and/or `ref` are merged with the
|
||||
entry in the registry; see [nix registry](./nix3-registry.md) for
|
||||
details.
|
||||
|
||||
# Flake format
|
||||
|
||||
As an example, here is a simple `flake.nix` that depends on the
|
||||
Nixpkgs flake and provides a single package (i.e. an installable
|
||||
derivation):
|
||||
|
||||
```nix
|
||||
{
|
||||
description = "A flake for building Hello World";
|
||||
|
||||
inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-20.03;
|
||||
|
||||
outputs = { self, nixpkgs }: {
|
||||
|
||||
defaultPackage.x86_64-linux =
|
||||
# Notice the reference to nixpkgs here.
|
||||
with import nixpkgs { system = "x86_64-linux"; };
|
||||
stdenv.mkDerivation {
|
||||
name = "hello";
|
||||
src = self;
|
||||
buildPhase = "gcc -o hello ./hello.c";
|
||||
installPhase = "mkdir -p $out/bin; install -t $out/bin hello";
|
||||
};
|
||||
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
The following attributes are supported in `flake.nix`:
|
||||
|
||||
* `description`: A short, one-line description of the flake.
|
||||
|
||||
* `inputs`: An attrset specifying the dependencies of the flake
|
||||
(described below).
|
||||
|
||||
* `outputs`: A function that, given an attribute set containing the
|
||||
outputs of each of the input flakes keyed by their identifier,
|
||||
yields the Nix values provided by this flake. Thus, in the example
|
||||
above, `inputs.nixpkgs` contains the result of the call to the
|
||||
`outputs` function of the `nixpkgs` flake.
|
||||
|
||||
In addition to the outputs of each input, each input in `inputs`
|
||||
also contains some metadata about the inputs. These are:
|
||||
|
||||
* `outPath`: The path in the Nix store of the flake's source tree.
|
||||
|
||||
* `rev`: The commit hash of the flake's repository, if applicable.
|
||||
|
||||
* `revCount`: The number of ancestors of the revision `rev`. This is
|
||||
not available for `github` repositories, since they're fetched as
|
||||
tarballs rather than as Git repositories.
|
||||
|
||||
* `lastModifiedDate`: The commit time of the revision `rev`, in the
|
||||
format `%Y%m%d%H%M%S` (e.g. `20181231100934`). Unlike `revCount`,
|
||||
this is available for both Git and GitHub repositories, so it's
|
||||
useful for generating (hopefully) monotonically increasing version
|
||||
strings.
|
||||
|
||||
* `lastModified`: The commit time of the revision `rev` as an integer
|
||||
denoting the number of seconds since 1970.
|
||||
|
||||
* `narHash`: The SHA-256 (in SRI format) of the NAR serialization of
|
||||
the flake's source tree.
|
||||
|
||||
The value returned by the `outputs` function must be an attribute
|
||||
set. The attributes can have arbitrary values; however, various
|
||||
`nix` subcommands require specific attributes to have a specific
|
||||
value (e.g. `packages.x86_64-linux` must be an attribute set of
|
||||
derivations built for the `x86_64-linux` platform).
|
||||
|
||||
## Flake inputs
|
||||
|
||||
The attribute `inputs` specifies the dependencies of a flake, as an
|
||||
attrset mapping input names to flake references. For example, the
|
||||
following specifies a dependency on the `nixpkgs` and `import-cargo`
|
||||
repositories:
|
||||
|
||||
```nix
|
||||
# A GitHub repository.
|
||||
inputs.import-cargo = {
|
||||
type = "github";
|
||||
owner = "edolstra";
|
||||
repo = "import-cargo";
|
||||
};
|
||||
|
||||
# An indirection through the flake registry.
|
||||
inputs.nixpkgs = {
|
||||
type = "indirect";
|
||||
id = "nixpkgs";
|
||||
};
|
||||
```
|
||||
|
||||
Alternatively, you can use the URL-like syntax:
|
||||
|
||||
```nix
|
||||
inputs.import-cargo.url = github:edolstra/import-cargo;
|
||||
inputs.nixpkgs.url = "nixpkgs";
|
||||
```
|
||||
|
||||
Each input is fetched, evaluated and passed to the `outputs` function
|
||||
as a set of attributes with the same name as the corresponding
|
||||
input. The special input named `self` refers to the outputs and source
|
||||
tree of *this* flake. Thus, a typical `outputs` function looks like
|
||||
this:
|
||||
|
||||
```nix
|
||||
outputs = { self, nixpkgs, import-cargo }: {
|
||||
... outputs ...
|
||||
};
|
||||
```
|
||||
|
||||
It is also possible to omit an input entirely and *only* list it as
|
||||
expected function argument to `outputs`. Thus,
|
||||
|
||||
```nix
|
||||
outputs = { self, nixpkgs }: ...;
|
||||
```
|
||||
|
||||
without an `inputs.nixpkgs` attribute is equivalent to
|
||||
|
||||
```nix
|
||||
inputs.nixpkgs = {
|
||||
type = "indirect";
|
||||
id = "nixpkgs";
|
||||
};
|
||||
```
|
||||
|
||||
Repositories that don't contain a `flake.nix` can also be used as
|
||||
inputs, by setting the input's `flake` attribute to `false`:
|
||||
|
||||
```nix
|
||||
inputs.grcov = {
|
||||
type = "github";
|
||||
owner = "mozilla";
|
||||
repo = "grcov";
|
||||
flake = false;
|
||||
};
|
||||
|
||||
outputs = { self, nixpkgs, grcov }: {
|
||||
packages.x86_64-linux.grcov = stdenv.mkDerivation {
|
||||
src = grcov;
|
||||
...
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Transitive inputs can be overriden from a `flake.nix` file. For
|
||||
example, the following overrides the `nixpkgs` input of the `nixops`
|
||||
input:
|
||||
|
||||
```nix
|
||||
inputs.nixops.inputs.nixpkgs = {
|
||||
type = "github";
|
||||
owner = "my-org";
|
||||
repo = "nixpkgs";
|
||||
};
|
||||
```
|
||||
|
||||
It is also possible to "inherit" an input from another input. This is
|
||||
useful to minimize flake dependencies. For example, the following sets
|
||||
the `nixpkgs` input of the top-level flake to be equal to the
|
||||
`nixpkgs` input of the `dwarffs` input of the top-level flake:
|
||||
|
||||
```nix
|
||||
inputs.nixops.follows = "dwarffs/nixpkgs";
|
||||
```
|
||||
|
||||
The value of the `follows` attribute is a `/`-separated sequence of
|
||||
input names denoting the path of inputs to be followed from the root
|
||||
flake.
|
||||
|
||||
Overrides and `follows` can be combined, e.g.
|
||||
|
||||
```nix
|
||||
inputs.nixops.inputs.nixpkgs.follows = "dwarffs/nixpkgs";
|
||||
```
|
||||
|
||||
sets the `nixpkgs` input of `nixops` to be the same as the `nixpkgs`
|
||||
input of `dwarffs`. It is worth noting, however, that it is generally
|
||||
not useful to eliminate transitive `nixpkgs` flake inputs in this
|
||||
way. Most flakes provide their functionality through Nixpkgs overlays
|
||||
or NixOS modules, which are composed into the top-level flake's
|
||||
`nixpkgs` input; so their own `nixpkgs` input is usually irrelevant.
|
||||
|
||||
# Lock files
|
||||
|
||||
Inputs specified in `flake.nix` are typically "unlocked" in the sense
|
||||
that they don't specify an exact revision. To ensure reproducibility,
|
||||
Nix will automatically generate and use a *lock file* called
|
||||
`flake.lock` in the flake's directory. The lock file contains a graph
|
||||
structure isomorphic to the graph of dependencies of the root
|
||||
flake. Each node in the graph (except the root node) maps the
|
||||
(usually) unlocked input specifications in `flake.nix` to locked input
|
||||
specifications. Each node also contains some metadata, such as the
|
||||
dependencies (outgoing edges) of the node.
|
||||
|
||||
For example, if `flake.nix` has the inputs in the example above, then
|
||||
the resulting lock file might be:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 7,
|
||||
"root": "n1",
|
||||
"nodes": {
|
||||
"n1": {
|
||||
"inputs": {
|
||||
"nixpkgs": "n2",
|
||||
"import-cargo": "n3",
|
||||
"grcov": "n4"
|
||||
}
|
||||
},
|
||||
"n2": {
|
||||
"inputs": {},
|
||||
"locked": {
|
||||
"owner": "edolstra",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "7f8d4b088e2df7fdb6b513bc2d6941f1d422a013",
|
||||
"type": "github",
|
||||
"lastModified": 1580555482,
|
||||
"narHash": "sha256-OnpEWzNxF/AU4KlqBXM2s5PWvfI5/BS6xQrPvkF5tO8="
|
||||
},
|
||||
"original": {
|
||||
"id": "nixpkgs",
|
||||
"type": "indirect"
|
||||
}
|
||||
},
|
||||
"n3": {
|
||||
"inputs": {},
|
||||
"locked": {
|
||||
"owner": "edolstra",
|
||||
"repo": "import-cargo",
|
||||
"rev": "8abf7b3a8cbe1c8a885391f826357a74d382a422",
|
||||
"type": "github",
|
||||
"lastModified": 1567183309,
|
||||
"narHash": "sha256-wIXWOpX9rRjK5NDsL6WzuuBJl2R0kUCnlpZUrASykSc="
|
||||
},
|
||||
"original": {
|
||||
"owner": "edolstra",
|
||||
"repo": "import-cargo",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"n4": {
|
||||
"inputs": {},
|
||||
"locked": {
|
||||
"owner": "mozilla",
|
||||
"repo": "grcov",
|
||||
"rev": "989a84bb29e95e392589c4e73c29189fd69a1d4e",
|
||||
"type": "github",
|
||||
"lastModified": 1580729070,
|
||||
"narHash": "sha256-235uMxYlHxJ5y92EXZWAYEsEb6mm+b069GAd+BOIOxI="
|
||||
},
|
||||
"original": {
|
||||
"owner": "mozilla",
|
||||
"repo": "grcov",
|
||||
"type": "github"
|
||||
},
|
||||
"flake": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This graph has 4 nodes: the root flake, and its 3 dependencies. The
|
||||
nodes have arbitrary labels (e.g. `n1`). The label of the root node of
|
||||
the graph is specified by the `root` attribute. Nodes contain the
|
||||
following fields:
|
||||
|
||||
* `inputs`: The dependencies of this node, as a mapping from input
|
||||
names (e.g. `nixpkgs`) to node labels (e.g. `n2`).
|
||||
|
||||
* `original`: The original input specification from `flake.lock`, as a
|
||||
set of `builtins.fetchTree` arguments.
|
||||
|
||||
* `locked`: The locked input specification, as a set of
|
||||
`builtins.fetchTree` arguments. Thus, in the example above, when we
|
||||
build this flake, the input `nixpkgs` is mapped to revision
|
||||
`7f8d4b088e2df7fdb6b513bc2d6941f1d422a013` of the `edolstra/nixpkgs`
|
||||
repository on GitHub.
|
||||
|
||||
It also includes the attribute `narHash`, specifying the expected
|
||||
contents of the tree in the Nix store (as computed by `nix
|
||||
hash-path`), and may include input-type-specific attributes such as
|
||||
the `lastModified` or `revCount`. The main reason for these
|
||||
attributes is to allow flake inputs to be substituted from a binary
|
||||
cache: `narHash` allows the store path to be computed, while the
|
||||
other attributes are necessary because they provide information not
|
||||
stored in the store path.
|
||||
|
||||
* `flake`: A Boolean denoting whether this is a flake or non-flake
|
||||
dependency. Corresponds to the `flake` attribute in the `inputs`
|
||||
attribute in `flake.nix`.
|
||||
|
||||
The `original` and `locked` attributes are omitted for the root
|
||||
node. This is because we cannot record the commit hash or content hash
|
||||
of the root flake, since modifying `flake.lock` will invalidate these.
|
||||
|
||||
The graph representation of lock files allows circular dependencies
|
||||
between flakes. For example, here are two flakes that reference each
|
||||
other:
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs.b = ... location of flake B ...;
|
||||
# Tell the 'b' flake not to fetch 'a' again, to ensure its 'a' is
|
||||
# *this* 'a'.
|
||||
inputs.b.inputs.a.follows = "";
|
||||
outputs = { self, b }: {
|
||||
foo = 123 + b.bar;
|
||||
xyzzy = 1000;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs.a = ... location of flake A ...;
|
||||
inputs.a.inputs.b.follows = "";
|
||||
outputs = { self, a }: {
|
||||
bar = 456 + a.xyzzy;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Lock files transitively lock direct as well as indirect
|
||||
dependencies. That is, if a lock file exists and is up to date, Nix
|
||||
will not look at the lock files of dependencies. However, lock file
|
||||
generation itself *does* use the lock files of dependencies by
|
||||
default.
|
||||
|
||||
)""
|
||||
17
src/nix/help.md
Normal file
17
src/nix/help.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show help about `nix` in general:
|
||||
|
||||
```console
|
||||
# nix help
|
||||
```
|
||||
|
||||
* Show help about a particular subcommand:
|
||||
|
||||
```console
|
||||
# nix help flake info
|
||||
```
|
||||
|
||||
)""
|
||||
|
|
@ -13,22 +13,11 @@ struct CmdLog : InstallableCommand
|
|||
return "show the build log of the specified packages or paths, if available";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To get the build log of GNU Hello:",
|
||||
"nix log nixpkgs#hello"
|
||||
},
|
||||
Example{
|
||||
"To get the build log of a specific path:",
|
||||
"nix log /nix/store/lmngj4wcm9rkv3w4dfhzhcyij3195hiq-thunderbird-52.2.1"
|
||||
},
|
||||
Example{
|
||||
"To get a build log from a specific binary cache:",
|
||||
"nix log --store https://cache.nixos.org nixpkgs#hello"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "log.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
|
|
|||
40
src/nix/log.md
Normal file
40
src/nix/log.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Get the build log of GNU Hello:
|
||||
|
||||
```console
|
||||
# nix log nixpkgs#hello
|
||||
```
|
||||
|
||||
* Get the build log of a specific store path:
|
||||
|
||||
```console
|
||||
# nix log /nix/store/lmngj4wcm9rkv3w4dfhzhcyij3195hiq-thunderbird-52.2.1
|
||||
```
|
||||
|
||||
* Get a build log from a specific binary cache:
|
||||
|
||||
```console
|
||||
# nix log --store https://cache.nixos.org nixpkgs#hello
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command prints the log of a previous build of the derivation
|
||||
*installable* on standard output.
|
||||
|
||||
Nix looks for build logs in two places:
|
||||
|
||||
* In the directory `/nix/var/log/nix/drvs`, which contains logs for
|
||||
locally built derivations.
|
||||
|
||||
* In the binary caches listed in the `substituters` setting. Logs
|
||||
should be named `<cache>/log/<base-name-of-store-path>`, where
|
||||
`store-path` is a derivation,
|
||||
e.g. `https://cache.nixos.org/log/dvmig8jgrdapvbyxb1rprckdmdqx08kv-hello-2.10.drv`.
|
||||
For non-derivation store paths, Nix will first try to determine the
|
||||
deriver by fetching the `.narinfo` file for this store path.
|
||||
|
||||
)""
|
||||
|
|
@ -75,6 +75,8 @@ struct MixLs : virtual Args, MixJSON
|
|||
|
||||
if (json) {
|
||||
JSONPlaceholder jsonRoot(std::cout);
|
||||
if (showDirectory)
|
||||
throw UsageError("'--directory' is useless with '--json'");
|
||||
listNar(jsonRoot, accessor, path, recursive);
|
||||
} else
|
||||
listText(accessor);
|
||||
|
|
@ -92,21 +94,18 @@ struct CmdLsStore : StoreCommand, MixLs
|
|||
});
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To list the contents of a store path in a binary cache:",
|
||||
"nix store ls --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10"
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
std::string description() override
|
||||
{
|
||||
return "show information about a path in the Nix store";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "store-ls.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
{
|
||||
list(store->getFSAccessor());
|
||||
|
|
@ -127,14 +126,11 @@ struct CmdLsNar : Command, MixLs
|
|||
expectArg("path", &path);
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To list a specific file in a NAR:",
|
||||
"nix nar ls -l hello.nar /bin/hello"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "nar-ls.md"
|
||||
;
|
||||
}
|
||||
|
||||
std::string description() override
|
||||
|
|
|
|||
|
|
@ -184,6 +184,13 @@ struct NixArgs : virtual MultiCommand, virtual MixCommonArgs
|
|||
{
|
||||
return "a tool for reproducible and declarative configuration management";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "nix.md"
|
||||
;
|
||||
}
|
||||
};
|
||||
|
||||
static void showHelp(std::vector<std::string> subcommand)
|
||||
|
|
@ -205,21 +212,14 @@ struct CmdHelp : Command
|
|||
|
||||
std::string description() override
|
||||
{
|
||||
return "show help about 'nix' or a particular subcommand";
|
||||
return "show help about `nix` or a particular subcommand";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To show help about 'nix' in general:",
|
||||
"nix help"
|
||||
},
|
||||
Example{
|
||||
"To show help about a particular subcommand:",
|
||||
"nix help run"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "help.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run() override
|
||||
|
|
|
|||
|
|
@ -15,21 +15,14 @@ struct CmdMakeContentAddressable : StorePathsCommand, MixJSON
|
|||
|
||||
std::string description() override
|
||||
{
|
||||
return "rewrite a path or closure to content-addressable form";
|
||||
return "rewrite a path or closure to content-addressed form";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To create a content-addressable representation of GNU Hello (but not its dependencies):",
|
||||
"nix store make-content-addressable nixpkgs#hello"
|
||||
},
|
||||
Example{
|
||||
"To compute a content-addressable representation of the current NixOS system closure:",
|
||||
"nix store make-content-addressable -r /run/current-system"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "make-content-addressable.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store, StorePaths storePaths) override
|
||||
|
|
|
|||
59
src/nix/make-content-addressable.md
Normal file
59
src/nix/make-content-addressable.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Create a content-addressed representation of the closure of GNU Hello:
|
||||
|
||||
```console
|
||||
# nix store make-content-addressable -r nixpkgs#hello
|
||||
…
|
||||
rewrote '/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10' to '/nix/store/5skmmcb9svys5lj3kbsrjg7vf2irid63-hello-2.10'
|
||||
```
|
||||
|
||||
Since the resulting paths are content-addressed, they are always
|
||||
trusted and don't need signatures to copied to another store:
|
||||
|
||||
```console
|
||||
# nix copy --to /tmp/nix --trusted-public-keys '' /nix/store/5skmmcb9svys5lj3kbsrjg7vf2irid63-hello-2.10
|
||||
```
|
||||
|
||||
By contrast, the original closure is input-addressed, so it does
|
||||
need signatures to be trusted:
|
||||
|
||||
```console
|
||||
# nix copy --to /tmp/nix --trusted-public-keys '' nixpkgs#hello
|
||||
cannot add path '/nix/store/zy9wbxwcygrwnh8n2w9qbbcr6zk87m26-libunistring-0.9.10' because it lacks a valid signature
|
||||
```
|
||||
|
||||
* Create a content-addressed representation of the current NixOS
|
||||
system closure:
|
||||
|
||||
```console
|
||||
# nix store make-content-addressable -r /run/current-system
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command converts the closure of the store paths specified by
|
||||
*installables* to content-addressed form. Nix store paths are usually
|
||||
*input-addressed*, meaning that the hash part of the store path is
|
||||
computed from the contents of the derivation (i.e., the build-time
|
||||
dependency graph). Input-addressed paths need to be signed by a
|
||||
trusted key if you want to import them into a store, because we need
|
||||
to trust that the contents of the path were actually built by the
|
||||
derivation.
|
||||
|
||||
By contrast, in a *content-addressed* path, the hash part is computed
|
||||
from the contents of the path. This allows the contents of the path to
|
||||
be verified without any additional information such as
|
||||
signatures. This means that a command like
|
||||
|
||||
```console
|
||||
# nix store build /nix/store/5skmmcb9svys5lj3kbsrjg7vf2irid63-hello-2.10 \
|
||||
--substituters https://my-cache.example.org
|
||||
```
|
||||
|
||||
will succeed even if the binary cache `https://my-cache.example.org`
|
||||
doesn't present any signatures.
|
||||
|
||||
)""
|
||||
19
src/nix/nar-cat.md
Normal file
19
src/nix/nar-cat.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* List a file in a NAR and pipe it through `gunzip`:
|
||||
|
||||
```console
|
||||
# nix nar cat ./hello.nar /share/man/man1/hello.1.gz | gunzip
|
||||
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4.
|
||||
.TH HELLO "1" "November 2014" "hello 2.10" "User Commands"
|
||||
…
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command prints on standard output the contents of the regular
|
||||
file *path* inside the NAR file *nar*.
|
||||
|
||||
)""
|
||||
17
src/nix/nar-dump-path.md
Normal file
17
src/nix/nar-dump-path.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* To serialise directory `foo` as a NAR:
|
||||
|
||||
```console
|
||||
# nix nar dump-path ./foo > foo.nar
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command generates a NAR file containing the serialisation of
|
||||
*path*, which must contain only regular files, directories and
|
||||
symbolic links. The NAR is written to standard output.
|
||||
|
||||
)""
|
||||
24
src/nix/nar-ls.md
Normal file
24
src/nix/nar-ls.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* To list a specific file in a NAR:
|
||||
|
||||
```console
|
||||
# nix nar ls -l ./hello.nar /bin/hello
|
||||
-r-xr-xr-x 38184 hello
|
||||
```
|
||||
|
||||
* To recursively list the contents of a directory inside a NAR, in JSON
|
||||
format:
|
||||
|
||||
```console
|
||||
# nix nar ls --json -R ./hello.nar /bin
|
||||
{"type":"directory","entries":{"hello":{"type":"regular","size":38184,"executable":true,"narOffset":400}}}
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows information about a *path* inside NAR file *nar*.
|
||||
|
||||
)""
|
||||
|
|
@ -9,7 +9,14 @@ struct CmdNar : NixMultiCommand
|
|||
|
||||
std::string description() override
|
||||
{
|
||||
return "query the contents of NAR files";
|
||||
return "create or inspect NAR files";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "nar.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catUtility; }
|
||||
|
|
|
|||
13
src/nix/nar.md
Normal file
13
src/nix/nar.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
R""(
|
||||
|
||||
# Description
|
||||
|
||||
`nix nar` provides several subcommands for creating and inspecting
|
||||
*Nix Archives* (NARs).
|
||||
|
||||
# File format
|
||||
|
||||
For the definition of the NAR file format, see Figure 5.2 in
|
||||
https://edolstra.github.io/pubs/phd-thesis.pdf.
|
||||
|
||||
)""
|
||||
119
src/nix/nix.md
Normal file
119
src/nix/nix.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Create a new flake:
|
||||
|
||||
```console
|
||||
# nix flake new hello
|
||||
# cd hello
|
||||
```
|
||||
|
||||
* Build the flake in the current directory:
|
||||
|
||||
```console
|
||||
# nix build
|
||||
# ./result/bin/hello
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
* Run the flake in the current directory:
|
||||
|
||||
```console
|
||||
# nix run
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
* Start a development shell for hacking on this flake:
|
||||
|
||||
```console
|
||||
# nix develop
|
||||
# unpackPhase
|
||||
# cd hello-*
|
||||
# configurePhase
|
||||
# buildPhase
|
||||
# ./hello
|
||||
Hello, world!
|
||||
# installPhase
|
||||
# ../outputs/out/bin/hello
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
Nix is a tool for building software, configurations and other
|
||||
artifacts in a reproducible and declarative way. For more information,
|
||||
see the [Nix homepage](https://nixos.org/) or the [Nix
|
||||
manual](https://nixos.org/manual/nix/stable/).
|
||||
|
||||
# Installables
|
||||
|
||||
Many `nix` subcommands operate on one or more *installables*. These are
|
||||
command line arguments that represent something that can be built in
|
||||
the Nix store. Here are the recognised types of installables:
|
||||
|
||||
* **Flake output attributes**: `nixpkgs#hello`
|
||||
|
||||
These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
|
||||
flake reference and *attrpath* is an optional attribute path. For
|
||||
more information on flakes, see [the `nix flake` manual
|
||||
page](./nix3-flake.md). Flake references are most commonly a flake
|
||||
identifier in the flake registry (e.g. `nixpkgs`) or a path
|
||||
(e.g. `/path/to/my-flake` or `.`).
|
||||
|
||||
If *attrpath* is omitted, Nix tries some default values; for most
|
||||
subcommands, the default is `defaultPackage.`*system*
|
||||
(e.g. `defaultPackage.x86_64-linux`), but some subcommands have
|
||||
other defaults. If *attrpath* *is* specified, *attrpath* is
|
||||
interpreted as relative to one or more prefixes; for most
|
||||
subcommands, these are `packages.`*system*,
|
||||
`legacyPackages.*system*` and the empty prefix. Thus, on
|
||||
`x86_64-linux` `nix build nixpkgs#hello` will try to build the
|
||||
attributes `packages.x86_64-linux.hello`,
|
||||
`legacyPackages.x86_64-linux.hello` and `hello`.
|
||||
|
||||
* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
|
||||
|
||||
These are paths inside the Nix store, or symlinks that resolve to a
|
||||
path in the Nix store.
|
||||
|
||||
* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
|
||||
|
||||
Store derivations are store paths with extension `.drv` and are a
|
||||
low-level representation of a build-time dependency graph used
|
||||
internally by Nix. By default, if you pass a store derivation to a
|
||||
`nix` subcommand, it will operate on the *output paths* of the
|
||||
derivation. For example, `nix path-info` prints information about
|
||||
the output paths:
|
||||
|
||||
```console
|
||||
# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
|
||||
[{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
|
||||
```
|
||||
|
||||
If you want to operate on the store derivation itself, pass the
|
||||
`--derivation` flag.
|
||||
|
||||
* **Nix attributes**: `--file /path/to/nixpkgs hello`
|
||||
|
||||
When the `-f` / `--file` *path* option is given, installables are
|
||||
interpreted as attribute paths referencing a value returned by
|
||||
evaluating the Nix file *path*.
|
||||
|
||||
* **Nix expressions**: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
|
||||
|
||||
When the `--expr` option is given, all installables are interpreted
|
||||
as Nix expressions. You may need to specify `--impure` if the
|
||||
expression references impure inputs (such as `<nixpkgs>`).
|
||||
|
||||
For most commands, if no installable is specified, the default is `.`,
|
||||
i.e. Nix will operate on the default flake output attribute of the
|
||||
flake in the current directory.
|
||||
|
||||
# Nix stores
|
||||
|
||||
Most `nix` subcommands operate on a *Nix store*.
|
||||
|
||||
TODO: list store types, options
|
||||
|
||||
)""
|
||||
|
|
@ -13,14 +13,11 @@ struct CmdOptimiseStore : StoreCommand
|
|||
return "replace identical files in the store by hard links";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To optimise the Nix store:",
|
||||
"nix store optimise"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "optimise-store.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
|
|||
23
src/nix/optimise-store.md
Normal file
23
src/nix/optimise-store.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Optimise the Nix store:
|
||||
|
||||
```console
|
||||
nix store optimise
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command deduplicates the Nix store: it scans the store for
|
||||
regular files with identical contents, and replaces them with hard
|
||||
links to a single instance.
|
||||
|
||||
Note that you can also set `auto-optimise-store` to `true` in
|
||||
`nix.conf` to perform this optimisation incrementally whenever a new
|
||||
path is added to the Nix store. To make this efficient, Nix maintains
|
||||
a content-addressed index of all the files in the Nix store in the
|
||||
directory `/nix/store/.links/`.
|
||||
|
||||
)""
|
||||
|
|
@ -29,38 +29,15 @@ struct CmdPathInfo : StorePathsCommand, MixJSON
|
|||
return "query information about store paths";
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To show the closure sizes of every path in the current NixOS system closure, sorted by size:",
|
||||
"nix path-info -rS /run/current-system | sort -nk2"
|
||||
},
|
||||
Example{
|
||||
"To show a package's closure size and all its dependencies with human readable sizes:",
|
||||
"nix path-info -rsSh nixpkgs#rust"
|
||||
},
|
||||
Example{
|
||||
"To check the existence of a path in a binary cache:",
|
||||
"nix path-info -r /nix/store/7qvk5c91...-geeqie-1.1 --store https://cache.nixos.org/"
|
||||
},
|
||||
Example{
|
||||
"To print the 10 most recently added paths (using --json and the jq(1) command):",
|
||||
"nix path-info --json --all | jq -r 'sort_by(.registrationTime)[-11:-1][].path'"
|
||||
},
|
||||
Example{
|
||||
"To show the size of the entire Nix store:",
|
||||
"nix path-info --json --all | jq 'map(.narSize) | add'"
|
||||
},
|
||||
Example{
|
||||
"To show every path whose closure is bigger than 1 GB, sorted by closure size:",
|
||||
"nix path-info --json --all -S | jq 'map(select(.closureSize > 1e9)) | sort_by(.closureSize) | map([.path, .closureSize])'"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "path-info.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
||||
void printSize(uint64_t value)
|
||||
{
|
||||
if (!humanReadable) {
|
||||
|
|
|
|||
94
src/nix/path-info.md
Normal file
94
src/nix/path-info.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Print the store path produced by `nixpkgs#hello`:
|
||||
|
||||
```console
|
||||
# nix path-info nixpkgs#hello
|
||||
/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10
|
||||
```
|
||||
|
||||
* Show the closure sizes of every path in the current NixOS system
|
||||
closure, sorted by size:
|
||||
|
||||
```console
|
||||
# nix path-info -rS /run/current-system | sort -nk2
|
||||
/nix/store/hl5xwp9kdrd1zkm0idm3kkby9q66z404-empty 96
|
||||
/nix/store/27324qvqhnxj3rncazmxc4mwy79kz8ha-nameservers 112
|
||||
…
|
||||
/nix/store/539jkw9a8dyry7clcv60gk6na816j7y8-etc 5783255504
|
||||
/nix/store/zqamz3cz4dbzfihki2mk7a63mbkxz9xq-nixos-system-machine-20.09.20201112.3090c65 5887562256
|
||||
```
|
||||
|
||||
* Show a package's closure size and all its dependencies with human
|
||||
readable sizes:
|
||||
|
||||
```console
|
||||
# nix path-info -rsSh nixpkgs#rustc
|
||||
/nix/store/01rrgsg5zk3cds0xgdsq40zpk6g51dz9-ncurses-6.2-dev 386.7K 69.1M
|
||||
/nix/store/0q783wnvixpqz6dxjp16nw296avgczam-libpfm-4.11.0 5.9M 37.4M
|
||||
…
|
||||
```
|
||||
|
||||
* Check the existence of a path in a binary cache:
|
||||
|
||||
```console
|
||||
# nix path-info -r /nix/store/blzxgyvrk32ki6xga10phr4sby2xf25q-geeqie-1.5.1 --store https://cache.nixos.org/
|
||||
path '/nix/store/blzxgyvrk32ki6xga10phr4sby2xf25q-geeqie-1.5.1' is not valid
|
||||
|
||||
```
|
||||
|
||||
* Print the 10 most recently added paths (using --json and the jq(1)
|
||||
command):
|
||||
|
||||
```console
|
||||
# nix path-info --json --all | jq -r 'sort_by(.registrationTime)[-11:-1][].path'
|
||||
```
|
||||
|
||||
* Show the size of the entire Nix store:
|
||||
|
||||
```console
|
||||
# nix path-info --json --all | jq 'map(.narSize) | add'
|
||||
49812020936
|
||||
```
|
||||
|
||||
* Show every path whose closure is bigger than 1 GB, sorted by closure
|
||||
size:
|
||||
|
||||
```console
|
||||
# nix path-info --json --all -S \
|
||||
| jq 'map(select(.closureSize > 1e9)) | sort_by(.closureSize) | map([.path, .closureSize])'
|
||||
[
|
||||
…,
|
||||
[
|
||||
"/nix/store/zqamz3cz4dbzfihki2mk7a63mbkxz9xq-nixos-system-machine-20.09.20201112.3090c65",
|
||||
5887562256
|
||||
]
|
||||
]
|
||||
```
|
||||
|
||||
* Print the path of the store derivation produced by `nixpkgs#hello`:
|
||||
|
||||
```console
|
||||
# nix path-info --derivation nixpkgs#hello
|
||||
/nix/store/s6rn4jz1sin56rf4qj5b5v8jxjm32hlk-hello-2.10.drv
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows information about the store paths produced by
|
||||
*installables*, or about all paths in the store if you pass `--all`.
|
||||
|
||||
By default, this command only prints the store paths. You can get
|
||||
additional information by passing flags such as `--closure-size`,
|
||||
--size`, `--sigs` or `--json`.
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> Note that `nix path-info` does not build or substitute the
|
||||
> *installables* you specify. Thus, if the corresponding store paths
|
||||
> don't already exist, this command will fail. You can use `nix build`
|
||||
> to ensure that they exist.
|
||||
|
||||
)""
|
||||
|
|
@ -8,17 +8,14 @@ struct CmdPingStore : StoreCommand
|
|||
{
|
||||
std::string description() override
|
||||
{
|
||||
return "test whether a store can be opened";
|
||||
return "test whether a store can be accessed";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To test whether connecting to a remote Nix store via SSH works:",
|
||||
"nix store ping --store ssh://mac1"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "ping-store.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
|
|||
30
src/nix/ping-store.md
Normal file
30
src/nix/ping-store.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Test whether connecting to a remote Nix store via SSH works:
|
||||
|
||||
```console
|
||||
# nix store ping --store ssh://mac1
|
||||
```
|
||||
|
||||
* Test whether a URL is a valid binary cache:
|
||||
|
||||
```console
|
||||
# nix store ping --store https://cache.nixos.org
|
||||
```
|
||||
|
||||
* Test whether the Nix daemon is up and running:
|
||||
|
||||
```console
|
||||
# nix store ping --store daemon
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command tests whether a particular Nix store (specified by the
|
||||
argument `--store` *url*) can be accessed. What this means is
|
||||
dependent on the type of the store. For instance, for an SSH store it
|
||||
means that Nix can connect to the specified machine.
|
||||
|
||||
)""
|
||||
19
src/nix/print-dev-env.md
Normal file
19
src/nix/print-dev-env.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Apply the build environment of GNU hello to the current shell:
|
||||
|
||||
```console
|
||||
# . <(nix print-dev-env nixpkgs#hello)
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command prints a shell script that can be sourced by `b`ash and
|
||||
that sets the environment variables and shell functions defined by the
|
||||
build process of *installable*. This allows you to get a similar build
|
||||
environment in your current shell rather than in a subshell (as with
|
||||
`nix develop`).
|
||||
|
||||
)""
|
||||
28
src/nix/profile-diff-closures.md
Normal file
28
src/nix/profile-diff-closures.md
Normal 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
31
src/nix/profile-info.md
Normal 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
27
src/nix/profile-install.md
Normal 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
32
src/nix/profile-remove.md
Normal 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
41
src/nix/profile-upgrade.md
Normal 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.
|
||||
|
||||
)""
|
||||
|
|
@ -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
107
src/nix/profile.md
Normal 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.
|
||||
|
||||
)""
|
||||
33
src/nix/registry-add.md
Normal file
33
src/nix/registry-add.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Set the `nixpkgs` flake identifier to a specific branch of Nixpkgs:
|
||||
|
||||
```console
|
||||
# nix registry add nixpkgs github:NixOS/nixpkgs/nixos-20.03
|
||||
```
|
||||
|
||||
* Pin `nixpkgs` to a specific revision:
|
||||
|
||||
```console
|
||||
# nix registry add nixpkgs github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
|
||||
```
|
||||
|
||||
* Add an entry that redirects a specific branch of `nixpkgs` to
|
||||
another fork:
|
||||
|
||||
```console
|
||||
# nix registry add nixpkgs/nixos-20.03 ~/Dev/nixpkgs
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command adds an entry to the user registry that maps flake
|
||||
reference *from-url* to flake reference *to-url*. If an entry for
|
||||
*from-url* already exists, it is overwritten.
|
||||
|
||||
Entries can be removed using [`nix registry
|
||||
remove`](./nix3-registry-remove.md).
|
||||
|
||||
)""
|
||||
29
src/nix/registry-list.md
Normal file
29
src/nix/registry-list.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show the contents of all registries:
|
||||
|
||||
```console
|
||||
# nix registry list
|
||||
user flake:dwarffs github:edolstra/dwarffs/d181d714fd36eb06f4992a1997cd5601e26db8f5
|
||||
system flake:nixpkgs path:/nix/store/fxl9mrm5xvzam0lxi9ygdmksskx4qq8s-source?lastModified=1605220118&narHash=sha256-Und10ixH1WuW0XHYMxxuHRohKYb45R%2fT8CwZuLd2D2Q=&rev=3090c65041104931adda7625d37fa874b2b5c124
|
||||
global flake:blender-bin github:edolstra/nix-warez?dir=blender
|
||||
global flake:dwarffs github:edolstra/dwarffs
|
||||
…
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command displays the contents of all registries on standard
|
||||
output. Each line represents one registry entry in the format *type*
|
||||
*from* *to*, where *type* denotes the registry containing the entry:
|
||||
|
||||
* `flags`: entries specified on the command line using `--override-flake`.
|
||||
* `user`: the user registry.
|
||||
* `system`: the system registry.
|
||||
* `global`: the global registry.
|
||||
|
||||
See the [`nix registry` manual page](./nix3-registry.md) for more details.
|
||||
|
||||
)""
|
||||
38
src/nix/registry-pin.md
Normal file
38
src/nix/registry-pin.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Pin `nixpkgs` to its most recent Git revision:
|
||||
|
||||
```console
|
||||
# nix registry pin nixpkgs
|
||||
```
|
||||
|
||||
Afterwards the user registry will have an entry like this:
|
||||
|
||||
```console
|
||||
nix registry list | grep '^user '
|
||||
user flake:nixpkgs github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
|
||||
```
|
||||
|
||||
and `nix flake info` will say:
|
||||
|
||||
```console
|
||||
# nix flake info nixpkgs
|
||||
Resolved URL: github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
|
||||
Locked URL: github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
|
||||
…
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command adds an entry to the user registry that maps flake
|
||||
reference *url* to the corresponding *locked* flake reference, that
|
||||
is, a flake reference that specifies an exact revision or content
|
||||
hash. This ensures that until this registry entry is removed, all uses
|
||||
of *url* will resolve to exactly the same flake.
|
||||
|
||||
Entries can be removed using [`nix registry
|
||||
remove`](./nix3-registry-remove.md).
|
||||
|
||||
)""
|
||||
16
src/nix/registry-remove.md
Normal file
16
src/nix/registry-remove.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Remove the entry `nixpkgs` from the user registry:
|
||||
|
||||
```console
|
||||
# nix registry remove nixpkgs
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command removes from the user registry any entry for flake
|
||||
reference *url*.
|
||||
|
||||
)""
|
||||
|
|
@ -17,6 +17,13 @@ struct CmdRegistryList : StoreCommand
|
|||
return "list available Nix flakes";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "registry-list.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(nix::ref<nix::Store> store) override
|
||||
{
|
||||
using namespace fetchers;
|
||||
|
|
@ -47,6 +54,13 @@ struct CmdRegistryAdd : MixEvalArgs, Command
|
|||
return "add/replace flake in user flake registry";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "registry-add.md"
|
||||
;
|
||||
}
|
||||
|
||||
CmdRegistryAdd()
|
||||
{
|
||||
expectArg("from-url", &fromUrl);
|
||||
|
|
@ -75,6 +89,13 @@ struct CmdRegistryRemove : virtual Args, MixEvalArgs, Command
|
|||
return "remove flake from user flake registry";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "registry-remove.md"
|
||||
;
|
||||
}
|
||||
|
||||
CmdRegistryRemove()
|
||||
{
|
||||
expectArg("url", &url);
|
||||
|
|
@ -97,6 +118,13 @@ struct CmdRegistryPin : virtual Args, EvalCommand
|
|||
return "pin a flake to its current version in user flake registry";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "registry-pin.md"
|
||||
;
|
||||
}
|
||||
|
||||
CmdRegistryPin()
|
||||
{
|
||||
expectArg("url", &url);
|
||||
|
|
@ -132,6 +160,13 @@ struct CmdRegistry : virtual NixMultiCommand
|
|||
return "manage the flake registry";
|
||||
}
|
||||
|
||||
std::string doc() override
|
||||
{
|
||||
return
|
||||
#include "registry.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
||||
void run() override
|
||||
|
|
|
|||
98
src/nix/registry.md
Normal file
98
src/nix/registry.md
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
R""(
|
||||
|
||||
# Description
|
||||
|
||||
`nix flake` provides subcommands for managing *flake
|
||||
registries*. Flake registries are a convenience feature that allows
|
||||
you to refer to flakes using symbolic identifiers such as `nixpkgs`,
|
||||
rather than full URLs such as `git://github.com/NixOS/nixpkgs`. You
|
||||
can use these identifiers on the command line (e.g. when you do `nix
|
||||
run nixpkgs#hello`) or in flake input specifications in `flake.nix`
|
||||
files. The latter are automatically resolved to full URLs and recorded
|
||||
in the flake's `flake.lock` file.
|
||||
|
||||
In addition, the flake registry allows you to redirect arbitrary flake
|
||||
references (e.g. `github:NixOS/patchelf`) to another location, such as
|
||||
a local fork.
|
||||
|
||||
There are multiple registries. These are, in order from lowest to
|
||||
highest precedence:
|
||||
|
||||
* The global registry, which is a file downloaded from the URL
|
||||
specified by the setting `flake-registry`. It is cached locally and
|
||||
updated automatically when it's older than `tarball-ttl`
|
||||
seconds. The default global registry is kept in [a GitHub
|
||||
repository](https://github.com/NixOS/flake-registry).
|
||||
|
||||
* The system registry, which is shared by all users. The default
|
||||
location is `/etc/nix/registry.json`. On NixOS, the system registry
|
||||
can be specified using the NixOS option `nix.registry`.
|
||||
|
||||
* The user registry `~/.config/nix/registry.json`. This registry can
|
||||
be modified by commands such as `nix flake pin`.
|
||||
|
||||
* Overrides specified on the command line using the option
|
||||
`--override-flake`.
|
||||
|
||||
# Registry format
|
||||
|
||||
A registry is a JSON file with the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
[
|
||||
{
|
||||
"from": {
|
||||
"type": "indirect",
|
||||
"id": "nixpkgs"
|
||||
},
|
||||
"to": {
|
||||
"type": "github",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs"
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
That is, it contains a list of objects with attributes `from` and
|
||||
`to`, both of which contain a flake reference in attribute
|
||||
representation. (For example, `{"type": "indirect", "id": "nixpkgs"}`
|
||||
is the attribute representation of `nixpkgs`, while `{"type":
|
||||
"github", "owner": "NixOS", "repo": "nixpkgs"}` is the attribute
|
||||
representation of `github:NixOS/nixpkgs`.)
|
||||
|
||||
Given some flake reference *R*, a registry entry is used if its
|
||||
`from` flake reference *matches* *R*. *R* is then replaced by the
|
||||
*unification* of the `to` flake reference with *R*.
|
||||
|
||||
# Matching
|
||||
|
||||
The `from` flake reference in a registry entry *matches* some flake
|
||||
reference *R* if the attributes in `from` are the same as the
|
||||
attributes in `R`. For example:
|
||||
|
||||
* `nixpkgs` matches with `nixpkgs`.
|
||||
|
||||
* `nixpkgs` matches with `nixpkgs/nixos-20.09`.
|
||||
|
||||
* `nixpkgs/nixos-20.09` does not match with `nixpkgs`.
|
||||
|
||||
* `nixpkgs` does not match with `git://github.com/NixOS/patchelf`.
|
||||
|
||||
# Unification
|
||||
|
||||
The `to` flake reference in a registry entry is *unified* with some flake
|
||||
reference *R* by taking `to` and applying the `rev` and `ref`
|
||||
attributes from *R*, if specified. For example:
|
||||
|
||||
* `github:NixOS/nixpkgs` unified with `nixpkgs` produces `github:NixOS/nixpkgs`.
|
||||
|
||||
* `github:NixOS/nixpkgs` unified with `nixpkgs/nixos-20.09` produces `github:NixOS/nixpkgs/nixos-20.09`.
|
||||
|
||||
* `github:NixOS/nixpkgs/master` unified with `nixpkgs/nixos-20.09` produces `github:NixOS/nixpkgs/nixos-20.09`.
|
||||
|
||||
)""
|
||||
|
|
@ -405,6 +405,7 @@ bool NixRepl::processLine(string line)
|
|||
}
|
||||
|
||||
if (command == ":?" || command == ":help") {
|
||||
// FIXME: convert to Markdown, include in the 'nix repl' manpage.
|
||||
std::cout
|
||||
<< "The following commands are available:\n"
|
||||
<< "\n"
|
||||
|
|
@ -801,14 +802,11 @@ struct CmdRepl : StoreCommand, MixEvalArgs
|
|||
return "start an interactive environment for evaluating Nix expressions";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"Display all special commands within the REPL:",
|
||||
"nix repl\nnix-repl> :?"
|
||||
}
|
||||
};
|
||||
return
|
||||
#include "repl.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
|
|||
57
src/nix/repl.md
Normal file
57
src/nix/repl.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Display all special commands within the REPL:
|
||||
|
||||
```console
|
||||
# nix repl
|
||||
nix-repl> :?
|
||||
```
|
||||
|
||||
* Evaluate some simple Nix expressions:
|
||||
|
||||
```console
|
||||
# nix repl
|
||||
|
||||
nix-repl> 1 + 2
|
||||
3
|
||||
|
||||
nix-repl> map (x: x * 2) [1 2 3]
|
||||
[ 2 4 6 ]
|
||||
```
|
||||
|
||||
* Interact with Nixpkgs in the REPL:
|
||||
|
||||
```console
|
||||
# nix repl '<nixpkgs>'
|
||||
|
||||
Loading '<nixpkgs>'...
|
||||
Added 12428 variables.
|
||||
|
||||
nix-repl> emacs.name
|
||||
"emacs-27.1"
|
||||
|
||||
nix-repl> emacs.drvPath
|
||||
"/nix/store/lp0sjrhgg03y2n0l10n70rg0k7hhyz0l-emacs-27.1.drv"
|
||||
|
||||
nix-repl> drv = runCommand "hello" { buildInputs = [ hello ]; } "hello > $out"
|
||||
|
||||
nix-repl> :b x
|
||||
this derivation produced the following outputs:
|
||||
out -> /nix/store/0njwbgwmkwls0w5dv9mpc1pq5fj39q0l-hello
|
||||
|
||||
nix-repl> builtins.readFile drv
|
||||
"Hello, world!\n"
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command provides an interactive environment for evaluating Nix
|
||||
expressions. (REPL stands for 'read–eval–print loop'.)
|
||||
|
||||
On startup, it loads the Nix expressions named *files* and adds them
|
||||
into the lexical scope. You can load addition files using the `:l
|
||||
<filename>` command, or reload all files using `:r`.
|
||||
|
||||
)""
|
||||
|
|
@ -86,26 +86,11 @@ struct CmdShell : InstallablesCommand, RunCommon, MixEnvironment
|
|||
return "run a shell in which the specified packages are available";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To start a shell providing GNU Hello from NixOS 20.03:",
|
||||
"nix shell nixpkgs/nixos-20.03#hello"
|
||||
},
|
||||
Example{
|
||||
"To start a shell providing youtube-dl from your 'nixpkgs' channel:",
|
||||
"nix shell nixpkgs#youtube-dl"
|
||||
},
|
||||
Example{
|
||||
"To run GNU Hello:",
|
||||
"nix shell nixpkgs#hello -c hello --greeting 'Hi everybody!'"
|
||||
},
|
||||
Example{
|
||||
"To run GNU Hello in a chroot store:",
|
||||
"nix shell --store ~/my-nix nixpkgs#hello -c hello"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "shell.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store) override
|
||||
|
|
@ -168,22 +153,11 @@ struct CmdRun : InstallableCommand, RunCommon
|
|||
return "run a Nix application";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To run Blender:",
|
||||
"nix run blender-bin"
|
||||
},
|
||||
Example{
|
||||
"To run vim from nixpkgs:",
|
||||
"nix run nixpkgs#vim"
|
||||
},
|
||||
Example{
|
||||
"To run vim from nixpkgs with arguments:",
|
||||
"nix run nixpkgs#vim -- --help"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "run.md"
|
||||
;
|
||||
}
|
||||
|
||||
Strings getDefaultFlakeAttrPaths() override
|
||||
|
|
|
|||
87
src/nix/run.md
Normal file
87
src/nix/run.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Run the default app from the `blender-bin` flake:
|
||||
|
||||
```console
|
||||
# nix run blender-bin
|
||||
```
|
||||
|
||||
* Run a non-default app from the `blender-bin` flake:
|
||||
|
||||
```console
|
||||
# nix run blender-bin#blender_2_83
|
||||
```
|
||||
|
||||
Tip: you can find apps provided by this flake by running `nix flake
|
||||
show blender-bin`.
|
||||
|
||||
* Run `vim` from the `nixpkgs` flake:
|
||||
|
||||
```console
|
||||
# nix run nixpkgs#vim
|
||||
```
|
||||
|
||||
Note that `vim` (as of the time of writing of this page) is not an
|
||||
app but a package. Thus, Nix runs the eponymous file from the `vim`
|
||||
package.
|
||||
|
||||
* Run `vim` with arguments:
|
||||
|
||||
```console
|
||||
# nix run nixpkgs#vim -- --help
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
`nix run` builds and runs *installable*, which must evaluate to an
|
||||
*app* or a regular Nix derivation.
|
||||
|
||||
If *installable* evaluates to an *app* (see below), it executes the
|
||||
program specified by the app definition.
|
||||
|
||||
If *installable* evaluates to a derivation, it will try to execute the
|
||||
program `<out>/bin/<name>`, where *out* is the primary output store
|
||||
path of the derivation and *name* is the name part of the value of the
|
||||
`name` attribute of the derivation (e.g. if `name` is set to
|
||||
`hello-1.10`, it will run `$out/bin/hello`).
|
||||
|
||||
# Flake output attributes
|
||||
|
||||
If no flake output attribute is given, `nix run` tries the following
|
||||
flake output attributes:
|
||||
|
||||
* `defaultApp.<system>`
|
||||
|
||||
* `defaultPackage.<system>`
|
||||
|
||||
If an attribute *name* is given, `nix run` tries the following flake
|
||||
output attributes:
|
||||
|
||||
* `apps.<system>.<name>`
|
||||
|
||||
* `packages.<system>.<name>`
|
||||
|
||||
* `legacyPackages.<system>.<name>`
|
||||
|
||||
# Apps
|
||||
|
||||
An app is specified by a flake output attribute named
|
||||
`apps.<system>.<name>` or `defaultApp.<system>`. It looks like this:
|
||||
|
||||
```nix
|
||||
apps.x86_64-linux.blender_2_79 = {
|
||||
type = "app";
|
||||
program = "${self.packages.x86_64-linux.blender_2_79}/bin/blender";
|
||||
};
|
||||
```
|
||||
|
||||
The only supported attributes are:
|
||||
|
||||
* `type` (required): Must be set to `app`.
|
||||
|
||||
* `program` (required): The full path of the executable to run. It
|
||||
must reside in the Nix store.
|
||||
|
||||
)""
|
||||
|
|
@ -41,29 +41,14 @@ struct CmdSearch : InstallableCommand, MixJSON
|
|||
|
||||
std::string description() override
|
||||
{
|
||||
return "query available packages";
|
||||
return "search for packages";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To show all packages in the flake in the current directory:",
|
||||
"nix search"
|
||||
},
|
||||
Example{
|
||||
"To show packages in the 'nixpkgs' flake containing 'blender' in its name or description:",
|
||||
"nix search nixpkgs blender"
|
||||
},
|
||||
Example{
|
||||
"To search for Firefox or Chromium:",
|
||||
"nix search nixpkgs 'firefox|chromium'"
|
||||
},
|
||||
Example{
|
||||
"To search for packages containing 'git' and either 'frontend' or 'gui':",
|
||||
"nix search nixpkgs git 'frontend|gui'"
|
||||
}
|
||||
};
|
||||
return
|
||||
#include "search.md"
|
||||
;
|
||||
}
|
||||
|
||||
Strings getDefaultFlakeAttrPaths() override
|
||||
|
|
|
|||
72
src/nix/search.md
Normal file
72
src/nix/search.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show all packages in the `nixpkgs` flake:
|
||||
|
||||
```console
|
||||
# nix search nixpkgs
|
||||
* legacyPackages.x86_64-linux.AMB-plugins (0.8.1)
|
||||
A set of ambisonics ladspa plugins
|
||||
|
||||
* legacyPackages.x86_64-linux.ArchiSteamFarm (4.3.1.0)
|
||||
Application with primary purpose of idling Steam cards from multiple accounts simultaneously
|
||||
…
|
||||
```
|
||||
|
||||
* Show packages in the `nixpkgs` flake containing `blender` in its
|
||||
name or description:
|
||||
|
||||
```console
|
||||
# nix search nixpkgs blender
|
||||
* legacyPackages.x86_64-linux.blender (2.91.0)
|
||||
3D Creation/Animation/Publishing System
|
||||
```
|
||||
|
||||
* Search for packages underneath the attribute `gnome3` in Nixpkgs:
|
||||
|
||||
```console
|
||||
# nix search nixpkgs#gnome3 vala
|
||||
* legacyPackages.x86_64-linux.gnome3.vala (0.48.9)
|
||||
Compiler for GObject type system
|
||||
```
|
||||
|
||||
* Show all packages in the flake in the current directory:
|
||||
|
||||
```console
|
||||
# nix search
|
||||
```
|
||||
|
||||
* Search for Firefox or Chromium:
|
||||
|
||||
```console
|
||||
# nix search nixpkgs 'firefox|chromium'
|
||||
```
|
||||
|
||||
* Search for packages containing `git'`and either `frontend` or `gui`:
|
||||
|
||||
```console
|
||||
# nix search nixpkgs git 'frontend|gui'
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
`nix search` searches *installable* (which must be evaluatable, e.g. a
|
||||
flake) for packages whose name or description matches all of the
|
||||
regular expressions *regex*. For each matching package, It prints the
|
||||
full attribute name (from the root of the installable), the version
|
||||
and the `meta.description` field, highlighting the substrings that
|
||||
were matched by the regular expressions. If no regular expressions are
|
||||
specified, all packages are shown.
|
||||
|
||||
# Flake output attributes
|
||||
|
||||
If no flake output attribute is given, `nix search` searches for
|
||||
packages:
|
||||
|
||||
* Directly underneath `packages.<system>`.
|
||||
|
||||
* Underneath `legacyPackages.<system>`, recursing into attribute sets
|
||||
that contain an attribute `recurseForDerivations = true`.
|
||||
|
||||
)""
|
||||
48
src/nix/shell.md
Normal file
48
src/nix/shell.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Start a shell providing `youtube-dl` from the `nixpkgs` flake:
|
||||
|
||||
```console
|
||||
# nix shell nixpkgs#youtube-dl
|
||||
# youtube-dl --version
|
||||
2020.11.01.1
|
||||
```
|
||||
|
||||
* Start a shell providing GNU Hello from NixOS 20.03:
|
||||
|
||||
```console
|
||||
# nix shell nixpkgs/nixos-20.03#hello
|
||||
```
|
||||
|
||||
* Run GNU Hello:
|
||||
|
||||
```console
|
||||
# nix shell nixpkgs#hello -c hello --greeting 'Hi everybody!'
|
||||
Hi everybody!
|
||||
```
|
||||
|
||||
* Run GNU Hello in a chroot store:
|
||||
|
||||
```console
|
||||
# nix shell --store ~/my-nix nixpkgs#hello -c hello
|
||||
```
|
||||
|
||||
* Start a shell providing GNU Hello in a chroot store:
|
||||
|
||||
```console
|
||||
# nix shell --store ~/my-nix nixpkgs#hello nixpkgs#bashInteractive -c bash
|
||||
```
|
||||
|
||||
Note that it's necessary to specify `bash` explicitly because your
|
||||
default shell (e.g. `/bin/bash`) generally will not exist in the
|
||||
chroot.
|
||||
|
||||
# Description
|
||||
|
||||
`nix shell` runs a command in an environment in which the `$PATH`
|
||||
variable provides the specified *installables*. If not command is
|
||||
specified, it starts the default shell of your user account.
|
||||
|
||||
)""
|
||||
|
|
@ -29,18 +29,11 @@ struct CmdShowDerivation : InstallablesCommand
|
|||
return "show the contents of a store derivation";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To show the store derivation that results from evaluating the Hello package:",
|
||||
"nix show-derivation nixpkgs#hello"
|
||||
},
|
||||
Example{
|
||||
"To show the full derivation graph (if available) that produced your NixOS system:",
|
||||
"nix show-derivation -r /run/current-system"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "show-derivation.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catUtility; }
|
||||
|
|
@ -103,7 +96,7 @@ struct CmdShowDerivation : InstallablesCommand
|
|||
}
|
||||
}
|
||||
|
||||
drvObj.attr("platform", drv.platform);
|
||||
drvObj.attr("system", drv.platform);
|
||||
drvObj.attr("builder", drv.builder);
|
||||
|
||||
{
|
||||
|
|
|
|||
103
src/nix/show-derivation.md
Normal file
103
src/nix/show-derivation.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show the store derivation that results from evaluating the Hello
|
||||
package:
|
||||
|
||||
```console
|
||||
# nix show-derivation nixpkgs#hello
|
||||
{
|
||||
"/nix/store/s6rn4jz1sin56rf4qj5b5v8jxjm32hlk-hello-2.10.drv": {
|
||||
…
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* Show the full derivation graph (if available) that produced your
|
||||
NixOS system:
|
||||
|
||||
```console
|
||||
# nix show-derivation -r /run/current-system
|
||||
```
|
||||
|
||||
* Print all files fetched using `fetchurl` by Firefox's dependency
|
||||
graph:
|
||||
|
||||
```console
|
||||
# nix show-derivation -r nixpkgs#firefox \
|
||||
| jq -r '.[] | select(.outputs.out.hash and .env.urls) | .env.urls' \
|
||||
| uniq | sort
|
||||
```
|
||||
|
||||
Note that `.outputs.out.hash` selects *fixed-output derivations*
|
||||
(derivations that produce output with a specified content hash),
|
||||
while `.env.urls` selects derivations with a `urls` attribute.
|
||||
|
||||
# Description
|
||||
|
||||
This command prints on standard output a JSON representation of the
|
||||
store derivations to which *installables* evaluate. Store derivations
|
||||
are used internally by Nix. They are store paths with extension `.drv`
|
||||
that represent the build-time dependency graph to which a Nix
|
||||
expression evaluates.
|
||||
|
||||
By default, this command only shows top-level derivations, but with
|
||||
`--recursive`, it also shows their dependencies.
|
||||
|
||||
The JSON output is a JSON object whose keys are the store paths of the
|
||||
derivations, and whose values are a JSON object with the following
|
||||
fields:
|
||||
|
||||
* `outputs`: Information about the output paths of the
|
||||
derivation. This is a JSON object with one member per output, where
|
||||
the key is the output name and the value is a JSON object with these
|
||||
fields:
|
||||
|
||||
* `path`: The output path.
|
||||
* `hashAlgo`: For fixed-output derivations, the hashing algorithm
|
||||
(e.g. `sha256`), optionally prefixed by `r:` if `hash` denotes a
|
||||
NAR hash rather than a flat file hash.
|
||||
* `hash`: For fixed-output derivations, the expected content hash in
|
||||
base-16.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"outputs": {
|
||||
"out": {
|
||||
"path": "/nix/store/2543j7c6jn75blc3drf4g5vhb1rhdq29-source",
|
||||
"hashAlgo": "r:sha256",
|
||||
"hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* `inputSrcs`: A list of store paths on which this derivation depends.
|
||||
|
||||
* `inputDrvs`: A JSON object specifying the derivations on which this
|
||||
derivation depends, and what outputs of those derivations. For
|
||||
example,
|
||||
|
||||
```json
|
||||
"inputDrvs": {
|
||||
"/nix/store/6lkh5yi7nlb7l6dr8fljlli5zfd9hq58-curl-7.73.0.drv": ["dev"],
|
||||
"/nix/store/fn3kgnfzl5dzym26j8g907gq3kbm8bfh-unzip-6.0.drv": ["out"]
|
||||
}
|
||||
```
|
||||
|
||||
specifies that this derivation depends on the `dev` output of
|
||||
`curl`, and the `out` output of `unzip`.
|
||||
|
||||
* `system`: The system type on which this derivation is to be built
|
||||
(e.g. `x86_64-linux`).
|
||||
|
||||
* `builder`: The absolute path of the program to be executed to run
|
||||
the build. Typically this is the `bash` shell
|
||||
(e.g. `/nix/store/r3j288vpmczbl500w6zz89gyfa4nr0b1-bash-4.4-p23/bin/bash`).
|
||||
|
||||
* `args`: The command-line arguments passed to the `builder`.
|
||||
|
||||
* `env`: The environment passed to the `builder`.
|
||||
|
||||
)""
|
||||
19
src/nix/store-cat.md
Normal file
19
src/nix/store-cat.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show the contents of a file in a binary cache:
|
||||
|
||||
```console
|
||||
# nix store cat --store https://cache.nixos.org/ \
|
||||
/nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10/bin/hello | hexdump -C | head -n1
|
||||
00000000 7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 |.ELF............|
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command prints on standard output the contents of the regular
|
||||
file *path* in a Nix store. *path* can be a top-level store path or
|
||||
any file inside a store path.
|
||||
|
||||
)""
|
||||
23
src/nix/store-dump-path.md
Normal file
23
src/nix/store-dump-path.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* To get a NAR containing the GNU Hello package:
|
||||
|
||||
```console
|
||||
# nix store dump-path nixpkgs#hello > hello.nar
|
||||
```
|
||||
|
||||
* To get a NAR from the binary cache https://cache.nixos.org/:
|
||||
|
||||
```console
|
||||
# nix store dump-path --store https://cache.nixos.org/ \
|
||||
/nix/store/7crrmih8c52r8fbnqb933dxrsp44md93-glibc-2.25 > glibc.nar
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command generates a NAR file containing the serialisation of the
|
||||
store path *installable*. The NAR is written to standard output.
|
||||
|
||||
)""
|
||||
27
src/nix/store-ls.md
Normal file
27
src/nix/store-ls.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* To list the contents of a store path in a binary cache:
|
||||
|
||||
```console
|
||||
# nix store ls --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
|
||||
dr-xr-xr-x 0 ./bin
|
||||
-r-xr-xr-x 38184 ./bin/hello
|
||||
dr-xr-xr-x 0 ./share
|
||||
…
|
||||
```
|
||||
|
||||
* To show information about a specific file in a binary cache:
|
||||
|
||||
```console
|
||||
# nix store ls --store https://cache.nixos.org/ -l /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10/bin/hello
|
||||
-r-xr-xr-x 38184 hello
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command shows information about *path* in a Nix store. *path* can
|
||||
be a top-level store path or any file inside a store path.
|
||||
|
||||
)""
|
||||
|
|
@ -37,18 +37,11 @@ struct CmdUpgradeNix : MixDryRun, StoreCommand
|
|||
return "upgrade Nix to the latest stable version";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To upgrade Nix to the latest stable version:",
|
||||
"nix upgrade-nix"
|
||||
},
|
||||
Example{
|
||||
"To upgrade Nix in a specific profile:",
|
||||
"nix upgrade-nix -p /nix/var/nix/profiles/per-user/alice/profile"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "upgrade-nix.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catNixInstallation; }
|
||||
|
|
|
|||
28
src/nix/upgrade-nix.md
Normal file
28
src/nix/upgrade-nix.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Upgrade Nix to the latest stable version:
|
||||
|
||||
```console
|
||||
# nix upgrade-nix
|
||||
```
|
||||
|
||||
* Upgrade Nix in a specific profile:
|
||||
|
||||
```console
|
||||
# nix upgrade-nix -p /nix/var/nix/profiles/per-user/alice/profile
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command upgrades Nix to the latest version. By default, it
|
||||
locates the directory containing the `nix` binary in the `$PATH`
|
||||
environment variable. If that directory is a Nix profile, it will
|
||||
upgrade the `nix` package in that profile to the latest stable binary
|
||||
release.
|
||||
|
||||
You cannot use this command to upgrade Nix in the system profile of a
|
||||
NixOS system (that is, if `nix` is found in `/run/current-system`).
|
||||
|
||||
)""
|
||||
|
|
@ -35,18 +35,11 @@ struct CmdVerify : StorePathsCommand
|
|||
return "verify the integrity of store paths";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To verify the entire Nix store:",
|
||||
"nix store verify --all"
|
||||
},
|
||||
Example{
|
||||
"To check whether each path in the closure of Firefox has at least 2 signatures:",
|
||||
"nix store verify -r -n2 --no-contents $(type -p firefox)"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "verify.md"
|
||||
;
|
||||
}
|
||||
|
||||
void run(ref<Store> store, StorePaths storePaths) override
|
||||
|
|
|
|||
49
src/nix/verify.md
Normal file
49
src/nix/verify.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Verify the entire Nix store:
|
||||
|
||||
```console
|
||||
# nix store verify --all
|
||||
```
|
||||
|
||||
* Check whether each path in the closure of Firefox has at least 2
|
||||
signatures:
|
||||
|
||||
```console
|
||||
# nix store verify -r -n2 --no-contents $(type -p firefox)
|
||||
```
|
||||
|
||||
* Verify a store path in the binary cache `https://cache.nixos.org/`:
|
||||
|
||||
```console
|
||||
# nix store verify --store https://cache.nixos.org/ \
|
||||
/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
This command verifies the integrity of the store paths *installables*,
|
||||
or, if `--all` is given, the entire Nix store. For each path, it
|
||||
checks that
|
||||
|
||||
* its contents match the NAR hash recorded in the Nix database; and
|
||||
|
||||
* it is *trusted*, that is, it is signed by at least one trusted
|
||||
signing key, is content-addressed, or is built locally ("ultimately
|
||||
trusted").
|
||||
|
||||
# Exit status
|
||||
|
||||
The exit status of this command is the sum of the following values:
|
||||
|
||||
* **1** if any path is corrupted (i.e. its contents don't match the
|
||||
recorded NAR hash).
|
||||
|
||||
* **2** if any path is untrusted.
|
||||
|
||||
* **4** if any path couldn't be verified for any other reason (such as
|
||||
an I/O error).
|
||||
|
||||
)""
|
||||
|
|
@ -50,22 +50,11 @@ struct CmdWhyDepends : SourceExprCommand
|
|||
return "show why a package has another package in its closure";
|
||||
}
|
||||
|
||||
Examples examples() override
|
||||
std::string doc() override
|
||||
{
|
||||
return {
|
||||
Example{
|
||||
"To show one path through the dependency graph leading from Hello to Glibc:",
|
||||
"nix why-depends nixpkgs#hello nixpkgs#glibc"
|
||||
},
|
||||
Example{
|
||||
"To show all files and paths in the dependency graph leading from Thunderbird to libX11:",
|
||||
"nix why-depends --all nixpkgs#thunderbird nixpkgs#xorg.libX11"
|
||||
},
|
||||
Example{
|
||||
"To show why Glibc depends on itself:",
|
||||
"nix why-depends nixpkgs#glibc nixpkgs#glibc"
|
||||
},
|
||||
};
|
||||
return
|
||||
#include "why-depends.md"
|
||||
;
|
||||
}
|
||||
|
||||
Category category() override { return catSecondary; }
|
||||
|
|
|
|||
80
src/nix/why-depends.md
Normal file
80
src/nix/why-depends.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
R""(
|
||||
|
||||
# Examples
|
||||
|
||||
* Show one path through the dependency graph leading from Hello to
|
||||
Glibc:
|
||||
|
||||
```console
|
||||
# nix why-depends nixpkgs#hello nixpkgs#glibc
|
||||
/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10
|
||||
└───bin/hello: …...................../nix/store/9l06v7fc38c1x3r2iydl15ksgz0ysb82-glibc-2.32/lib/ld-linux-x86-64.…
|
||||
→ /nix/store/9l06v7fc38c1x3r2iydl15ksgz0ysb82-glibc-2.32
|
||||
```
|
||||
|
||||
* Show all files and paths in the dependency graph leading from
|
||||
Thunderbird to libX11:
|
||||
|
||||
```console
|
||||
# nix why-depends --all nixpkgs#thunderbird nixpkgs#xorg.libX11
|
||||
/nix/store/qfc8729nzpdln1h0hvi1ziclsl3m84sr-thunderbird-78.5.1
|
||||
├───lib/thunderbird/libxul.so: …6wrw-libxcb-1.14/lib:/nix/store/adzfjjh8w25vdr0xdx9x16ah4f5rqrw5-libX11-1.7.0/lib:/nix/store/ssf…
|
||||
│ → /nix/store/adzfjjh8w25vdr0xdx9x16ah4f5rqrw5-libX11-1.7.0
|
||||
├───lib/thunderbird/libxul.so: …pxyc-libXt-1.2.0/lib:/nix/store/1qj29ipxl2fyi2b13l39hdircq17gnk0-libXdamage-1.1.5/lib:/nix/store…
|
||||
│ → /nix/store/1qj29ipxl2fyi2b13l39hdircq17gnk0-libXdamage-1.1.5
|
||||
│ ├───lib/libXdamage.so.1.1.0: …-libXfixes-5.0.3/lib:/nix/store/adzfjjh8w25vdr0xdx9x16ah4f5rqrw5-libX11-1.7.0/lib:/nix/store/9l0…
|
||||
│ │ → /nix/store/adzfjjh8w25vdr0xdx9x16ah4f5rqrw5-libX11-1.7.0
|
||||
…
|
||||
```
|
||||
|
||||
* Show why Glibc depends on itself:
|
||||
|
||||
```console
|
||||
# nix why-depends nixpkgs#glibc nixpkgs#glibc
|
||||
/nix/store/9df65igwjmf2wbw0gbrrgair6piqjgmi-glibc-2.31
|
||||
└───lib/ld-2.31.so: …che Do not use /nix/store/9df65igwjmf2wbw0gbrrgair6piqjgmi-glibc-2.31/etc/ld.so.cache. --…
|
||||
→ /nix/store/9df65igwjmf2wbw0gbrrgair6piqjgmi-glibc-2.31
|
||||
```
|
||||
|
||||
* Show why Geeqie has a build-time dependency on `systemd`:
|
||||
|
||||
```console
|
||||
# nix why-depends --derivation nixpkgs#geeqie nixpkgs#systemd
|
||||
/nix/store/drrpq2fqlrbj98bmazrnww7hm1in3wgj-geeqie-1.4.drv
|
||||
└───/: …atch.drv",["out"]),("/nix/store/qzh8dyq3lfbk3i1acbp7x9wh3il2imiv-gtk+3-3.24.21.drv",["dev"]),("/…
|
||||
→ /nix/store/qzh8dyq3lfbk3i1acbp7x9wh3il2imiv-gtk+3-3.24.21.drv
|
||||
└───/: …16.0.drv",["dev"]),("/nix/store/8kp79fyslf3z4m3dpvlh6w46iaadz5c2-cups-2.3.3.drv",["dev"]),("/nix…
|
||||
→ /nix/store/8kp79fyslf3z4m3dpvlh6w46iaadz5c2-cups-2.3.3.drv
|
||||
└───/: ….3.1.drv",["out"]),("/nix/store/yd3ihapyi5wbz1kjacq9dbkaq5v5hqjg-systemd-246.4.drv",["dev"]),("/…
|
||||
→ /nix/store/yd3ihapyi5wbz1kjacq9dbkaq5v5hqjg-systemd-246.4.drv
|
||||
```
|
||||
|
||||
# Description
|
||||
|
||||
Nix automatically determines potential runtime dependencies between
|
||||
store paths by scanning for the *hash parts* of store paths. For
|
||||
instance, if there exists a store path
|
||||
`/nix/store/9df65igwjmf2wbw0gbrrgair6piqjgmi-glibc-2.31`, and a file
|
||||
inside another store path contains the string `9df65igw…`, then the
|
||||
latter store path *refers* to the former, and thus might need it at
|
||||
runtime. Nix always maintains the existence of the transitive closure
|
||||
of a store path under the references relationship; it is therefore not
|
||||
possible to install a store path without having all of its references
|
||||
present.
|
||||
|
||||
Sometimes Nix packages end up with unexpected runtime dependencies;
|
||||
for instance, a reference to a compiler might accidentally end up in a
|
||||
binary, causing the former to be in the latter's closure. This kind of
|
||||
*closure size bloat* is undesirable.
|
||||
|
||||
`nix why-depends` allows you to diagnose the cause of such issues. It
|
||||
shows why the store path *package* depends on the store path
|
||||
*dependency*, by showing a shortest sequence in the references graph
|
||||
from the former to the latter. Also, for each node along this path, it
|
||||
shows a file fragment containing a reference to the next store path in
|
||||
the sequence.
|
||||
|
||||
To show why derivation *package* has a build-time rather than runtime
|
||||
dependency on derivation *dependency*, use `--derivation`.
|
||||
|
||||
)""
|
||||
Loading…
Reference in a new issue