From 02f3d191f9ea320d890db94939a273584eefa4af Mon Sep 17 00:00:00 2001 From: Qyriad Date: Tue, 21 May 2024 15:37:08 -0600 Subject: [PATCH 1/4] 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 ``, 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 --- doc/manual/src/command-ref/fileish-summary.md | 14 ++++++ doc/manual/src/command-ref/nix-build.md | 50 ++++++++++++++++--- doc/manual/src/command-ref/nix-env.md | 2 +- .../src/command-ref/nix-env/opt-common.md | 20 ++++++-- doc/manual/src/command-ref/nix-instantiate.md | 9 ++-- doc/manual/src/command-ref/nix-shell.md | 5 +- 6 files changed, 80 insertions(+), 20 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..c5db366de --- /dev/null +++ b/doc/manual/src/command-ref/fileish-summary.md @@ -0,0 +1,14 @@ + +- A normal filesystem path, like `/home/meow/nixfiles/default.nix` + - Or 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](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references), 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. diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 24714b2b4..b4c3a4697 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`. +Like the [import builtin](../language/builtins.md#builtins-import) specifying a directory is equivalent to specifying `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 ``, 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 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 "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.md#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 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 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-env.md b/doc/manual/src/command-ref/nix-env.md index 5a9e05fed..b3940aeaa 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -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`] diff --git a/doc/manual/src/command-ref/nix-env/opt-common.md b/doc/manual/src/command-ref/nix-env/opt-common.md index 636281b6d..fcf7e16db 100644 --- a/doc/manual/src/command-ref/nix-env/opt-common.md +++ b/doc/manual/src/command-ref/nix-env/opt-common.md @@ -2,16 +2,26 @@ 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` + - Or 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](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references), 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 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 diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md index 1eaf3c36a..ce33b264f 100644 --- a/doc/manual/src/command-ref/nix-shell.md +++ b/doc/manual/src/command-ref/nix-shell.md @@ -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 From 5a59ad9ecc110f2e89c68eb426e3af94e1ce6c46 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Wed, 22 May 2024 17:15:45 -0600 Subject: [PATCH 2/4] docstrings: NixRepl::getDerivationPath: exceptions directly thrown getDerivationPath() directly throws nix::Error for invalid derivations Change-Id: I81ead950060b789794fa683b61c6349fece1690d --- src/libcmd/repl.cc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/libcmd/repl.cc b/src/libcmd/repl.cc index 46b6d57ed..02aa5a272 100644 --- a/src/libcmd/repl.cc +++ b/src/libcmd/repl.cc @@ -107,6 +107,11 @@ struct NixRepl void initEnv() override; virtual StringSet completePrefix(const std::string & prefix) override; + + /** + * @exception nix::Error thrown directly if the expression does not evaluate + * to a derivation, or evaluates to an invalid derivation. + */ StorePath getDerivationPath(Value & v); ProcessLineResult processLine(std::string line); From e1a26a99a54f36775de9190dbe13bac1cd45fbc8 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Wed, 22 May 2024 22:31:19 -0600 Subject: [PATCH 3/4] 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 --- doc/manual/src/command-ref/fileish-summary.md | 1 + src/nix/nix.md | 47 ++++++++++++++++++- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/fileish-summary.md b/doc/manual/src/command-ref/fileish-summary.md index c5db366de..6200dfcc8 100644 --- a/doc/manual/src/command-ref/fileish-summary.md +++ b/doc/manual/src/command-ref/fileish-summary.md @@ -4,6 +4,7 @@ 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. + It is also manually duplicated in src/nix/nix.md, because those files don't support include?? busted. --> - A normal filesystem path, like `/home/meow/nixfiles/default.nix` - Or a directory, like `/home/meow/nixfiles`, equivalent to above diff --git a/src/nix/nix.md b/src/nix/nix.md index 0d588cd01..c33c85dd8 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -158,16 +158,61 @@ Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^*` 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-23.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, but instead fetches it 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 +``` + +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: + +- A normal filesystem path, like `/home/meow/nixfiles/default.nix` + - Or 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](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references), 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. + ### Nix expression Example: `--expr 'import {}' hello` From a369e70bffbf9672bf4edff9a9080eff9a13f373 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Wed, 22 May 2024 22:38:38 -0600 Subject: [PATCH 4/4] add editorconfig for markdown Change-Id: I493fc37fde425fc5c5c24f9b077bdc235271233c --- .editorconfig | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.editorconfig b/.editorconfig index 887ecadba..bcee9cfce 100644 --- a/.editorconfig +++ b/.editorconfig @@ -24,3 +24,8 @@ indent_size = 4 # Match diffs, avoid to trim trailing whitespace [*.{diff,patch}] trim_trailing_whitespace = false + +[*.md] +indent_style = space +indent_size = 2 +max_line_length = 0