From b07878bfe9f683b32b12e00c6106c7058548538c Mon Sep 17 00:00:00 2001 From: Qyriad Date: Tue, 21 May 2024 15:37:08 -0600 Subject: [PATCH] docs: document lookupFileArg syntax command refs Change-Id: Ib6d68594a16132805ba5d97526e16f7b3633117e --- doc/manual/src/command-ref/fileish-summary.md | 8 +++ doc/manual/src/command-ref/nix-build.md | 50 ++++++++++++++++--- doc/manual/src/command-ref/nix-instantiate.md | 9 ++-- 3 files changed, 57 insertions(+), 10 deletions(-) create mode 100644 doc/manual/src/command-ref/fileish-summary.md diff --git a/doc/manual/src/command-ref/fileish-summary.md b/doc/manual/src/command-ref/fileish-summary.md new file mode 100644 index 000000000..b74a6d075 --- /dev/null +++ b/doc/manual/src/command-ref/fileish-summary.md @@ -0,0 +1,8 @@ + +- A normal filesystem path, like `/home/meow/nixfiles/default.nix` + - Including a directory, like `/home/meow/nixfiles`, equivalent to above +- A single lookup path, like `` or `` +- A URL to a tarball, like `https://github.com/NixOS/nixpkgs/archive/refs/heads/release-23.11.tar.gz` +- A flakeref, introduced by the prefix `flake:`, like `flake:git+https://git.lix.systems/lix-project/lix` +- A channel name, introduced by the prefix `channel:`, like `channel:nixpkgs-unstable`. + - This uses a hard-coded URL pattern and is *not* related to the subscribed channels managed by the [nix-channel](./nix-channel.md) command. diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 92e642ddd..656e5f23d 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -4,7 +4,7 @@ # Synopsis -`nix-build` [*paths…*] +`nix-build` [*fileish…*] [`--arg` *name* *value*] [`--argstr` *name* *value*] [{`--attr` | `-A`} *attrPath*] @@ -20,19 +20,55 @@ For documentation on the latter, run `nix build --help` or see `man nix3-build`. # Description The `nix-build` command builds the derivations described by the Nix -expressions in *paths*. If the build succeeds, it places a symlink to +expressions in each *fileish*. If the build succeeds, it places a symlink to the result in the current directory. The symlink is called `result`. If there are multiple Nix expressions, or the Nix expressions evaluate to multiple derivations, multiple sequentially numbered symlinks are created (`result`, `result-2`, and so on). -If no *paths* are specified, then `nix-build` will use `default.nix` in +If no *fileish* is specified, then `nix-build` will use `default.nix` in the current directory, if it exists. -If an element of *paths* starts with `http://` or `https://`, it is -interpreted as the URL of a tarball that will be downloaded and unpacked -to a temporary location. The tarball must include a single top-level -directory containing at least a file named `default.nix`. +## Fileish Syntax + +A given *fileish* may take one of a few different forms, the first being a simple filesystem path, e.g. `nix-build /tmp/some-file.nix`. +This has the same semantics as the [import builtin](../language/builtins.md#builtins-import), so specifying a directory is equivalent to specifying `default.nix` within that directory. +It may also be a [search path](./env-common.html#env-NIX_PATH) (also known as a lookup path) like ``, which is convenient to use with `--attr`/`-A`: + +```console +$ nix-build '' -A firefox +``` + +(Note the quotation marks around ``, which will be necessary in most Unix shells.) + +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 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 "https://github.com/NixOS/nixpkgs/archive/refs/heads/release-23.11.tar.gz" -A firefox +``` + +If a path starts with `flake:`, the rest of the argument is interpreted as a [flakeref](./new-cli/nix3-flake.html#flake-references) (see `nix flake --help` or `man nix3-flake`), which requires the "flakes" experimental feature to be enabled. +Lix will fetch the flake, and then `import` its unpacked directory, so the flake must include a file called `default.nix`. +For example, the flake analogue to the above `nix-build` commands are: + +```console +$ nix-build flake:nixpkgs -A firefox +$ nix-build flake:github:NixOS/nixpkgs/release-23.11 -A firefox +``` + +Finally, for legacy reasons, if a path 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.xz`. +This is a **hard coded URL** pattern and is *not* related 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 path argument may be one of: + +{{#include ./fileish-summary.md}} + +## Notes `nix-build` is essentially a wrapper around [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index 479c9abcf..f9c7fcac5 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -11,7 +11,7 @@ [{`--attr`| `-A`} *attrPath*] [`--add-root` *path*] [`--expr` | `-E`] - *files…* + *fileish…* `nix-instantiate` `--find-file` *files…* @@ -25,8 +25,11 @@ of the resulting store derivations are printed on standard output. [store derivation]: ../glossary.md#gloss-store-derivation -If *files* is the character `-`, then a Nix expression will be read from -standard input. +If *fileish* is the character `-`, then a Nix expression will be read from standard input. +Otherwise, each *fileish* is interpreted the same as with [nix-build](./nix-build.md#Path_Syntax). +See that section for complete details (`nix-build --help`), but in summary, a path argument may be one of: + +{{#include ./fileish-summary.md}} # Options