From f5c13758bc0940d83f9a125b67fa59f3bbb933e3 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Wed, 22 May 2024 22:31:19 -0600 Subject: [PATCH] docs: document the cursed file syntax for new CLI This documents that all installables in the nix3 commands, in their --file/-f form accept an extended syntax for the file argument, which is the same as it is for nix-build and friends, some of which were well known in their nix-build forms (e.g. `nix-build '' -A hello) but are not well known in their nix3 forms (people rarely know that you can `nix build -f '' firefox`). Like the old CLI syntax, as documented in [1], file arguments also accept https:// tarball URLs, `flake:` prefixed flakerefs, and the cursed `channel:` prefixed hardened URLs. [1]: Ib6d68594a16132805ba5d97526e16f7b3633117e Change-Id: Ib81a5db1f60d5916f0f792d82054f3ac65717121 --- lix/nix/nix.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/lix/nix/nix.md b/lix/nix/nix.md index 06868d098..dbf070fc3 100644 --- a/lix/nix/nix.md +++ b/lix/nix/nix.md @@ -90,7 +90,7 @@ The following types of installable are supported by most commands: - This is the default - [Store path](#store-path) - This is assumed if the argument is a Nix store path or a symlink to a Nix store path -- [Nix file](#nix-file), optionally qualified by an attribute path +- [Fileish](#nix-file), optionally qualified by an attribute path - Specified with `--file`/`-f` - [Nix expression](#nix-expression), optionally qualified by an attribute path - Specified with `--expr`/`-E` @@ -182,20 +182,58 @@ All outputs can be referred to at once with the special syntax `^*`. Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^*` -### Nix file +### Fileish {#nix-file} Example: `--file /path/to/nixpkgs hello` -When the option `-f` / `--file` *path* \[*attrpath*...\] is given, installables are interpreted as the value of the expression in the Nix file at *path*. +When the option `-f` / `--file` *fileish* \[*attrpath*...\] is given, installables are interpreted as the value of the Nix file specified by *fileish*. If attribute paths are provided, commands will operate on the corresponding values accessible at these paths. The Nix expression in that file, or any selected attribute, must evaluate to a derivation. +The *fileish* itself may take one of a few different forms, the first being a simple filesystem path, e.g. `nix build -f /tmp/some-file.nix`. +Like the [import builtin](../../language/builtins.md#builtins-import), specifying a directory is equivalent to specify `default.nix` within that directory. +It may also be a [search path](../env-common.md#env-NIX_PATH) (also known as a lookup path), like ``. +Unlike using `` in a `--expr` argument, this does not require `--impure`. + To emulate the `nix-build '' -A hello` pattern, use: ```console $ nix build -f '' hello ``` +If a *fileish* starts with `http://` or `https://`, it is interpreted as the URL of a tarball which will be fetched and unpacked. +Lix will then `import` the unpacked directory, so these tarballs must include at least a single top-level directory with a file called `default.nix`. +For example, you could build from a specific version of Nixpkgs with something like: + +```console +$ nix build -f "https://github.com/NixOS/nixpkgs/archive/refs/heads/release-24.11.tar.gz" firefox +``` + +If a *fileish* starts with `flake:`, the rest of the argument is interpreted as a [flakeref](./nix3-flake.md#flake-reference) (see `nix flake --help` or `man nix3-flake`), which requires the "flakes" experimental feature to be enabled. +This is is *not quite* the same as specifying a [flake output attrpath](#flake-output-attribute). +It does *not* access the flake directly and does not even consider the existence of flake.nix, but instead fetches it as if it is not a flake at all and `import`s the unpacked directory. +In other words, it assumes that the flake has a `default.nix` file, and then interprets the attribute path relative to what `default.nix` evaluates to. + +For many flakes — including Nixpkgs — this will end up evaluating to the same thing. +These two commands build the same derivation, but one from the flake, and the other from `default.nix`: + +```console +$ nix build 'nixpkgs#firefox' # from flake.nix +$ nix build -f flake:nixpkgs firefox # from default.nix in the flake directory; ignores flake.nix altogether +``` + +Finally, for legacy reasons, if a *fileish* starts with `channel:`, the rest of the argument is interpreted as the name of a channel to fetch from `https://nixos.org/channels/$CHANNEL_NAME/nixexprs.tar.gz`. +This is a **hard coded URL** pattern and is *not* related to the subscribed channels managed by the [nix-channel](../nix-channel.md) command. + + + +> **Note**: any of the special syntaxes may always be disambiguated by prefixing the path. +> For example: a file in the current directory literally called `` can be addressed as `./`, to escape the special interpretation. + +In summary, a file path argument may be one of: + +{{#include ../fileish-summary.md}} + ### Nix expression Example: `--expr 'import {}' hello`