docs: document the cursed file syntax for old cli

This documents the fact that nix-build, nix-env, nix-instantiate, and
nix-shell accept an extended syntax for their file arguments, including
some well-known (but not well documented) aspects, like being able to
specify `<nixpkgs>`, but also https:// tarball URLs, `flake:` prefixed
flakerefs, and the cursed `channel:` prefixed hardcoded URLs

Same thing for the new CLI incoming :)

Change-Id: Ib6d68594a16132805ba5d97526e16f7b3633117e
This commit is contained in:
Qyriad 2024-05-21 15:37:08 -06:00
parent 12c0cc7b0e
commit ec0f49ec43
6 changed files with 76 additions and 20 deletions

View file

@ -0,0 +1,14 @@
<!--
File-ish argument syntax summary.
This file gets included into pages like nix-build.md and nix-instantiate.md, and each individual page that includes
this also links to nix-build.md for the full explanation.
This include file is manually duplicated in nix-env/opt-common.md because list indentation sadness.
-->
- 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 `<nixpkgs>` or `<nixos>`
- 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](@docroot@/command-ref/nix-channel.md) command.

View file

@ -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 `<nixpkgs>`, which is convenient to use with `--attr`/`-A`:
```console
$ nix-build '<nixpkgs>' -A firefox
```
(Note the quotation marks around `<nixpkgs>`, 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 analogues 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 `<nixpkgs>` can be addressed as `./<nixpkgs>`, 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

View file

@ -8,7 +8,7 @@
[`--option` *name* *value*]
[`--arg` *name* *value*]
[`--argstr` *name* *value*]
[{`--file` | `-f`} *path*]
[{`--file` | `-f`} *fileish*]
[{`--profile` | `-p`} *path*]
[`--system-filter` *system*]
[`--dry-run`]

View file

@ -2,16 +2,22 @@
The following options are allowed for all `nix-env` operations, but may not always have an effect.
- `--file` / `-f` *path*\
- `--file` / `-f` *fileish*\
Specifies the Nix expression (designated below as the *active Nix
expression*) used by the `--install`, `--upgrade`, and `--query
--available` operations to obtain derivations. The default is
`~/.nix-defexpr`.
If the argument 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* 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:
- 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 `<nixpkgs>` or `<nixos>`
- 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](@docroot@/command-ref/nix-channel.md) command.
- `--profile` / `-p` *path*\
Specifies the profile to be used by those operations that operate on

View file

@ -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

View file

@ -33,10 +33,7 @@ the environment of a derivation for development.
If *path* is not given, `nix-shell` defaults to `shell.nix` if it
exists, and `default.nix` otherwise.
If *path* 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`.
{{#include ./fileish-summary.md}}
If the derivation defines the variable `shellHook`, it will be run
after `$stdenv/setup` has been sourced. Since this hook is not executed