Merge changes Ib81a5db1,Ib6d68594,Id91e1fd4 into main
* changes: docs: document the cursed file syntax for new CLI docs: document the cursed file syntax for old cli doc preprocessor: support indent directives
This commit is contained in:
jade
@@ -0,0 +1,12 @@
|
||||
<!--
|
||||
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.
|
||||
-->
|
||||
- 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 `<nixpkgs>` or `<nixos>`
|
||||
- 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 *nixpkgs* channel tarball name, introduced by the prefix `channel:`, like `channel:nixos-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.
|
||||
@@ -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 `<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 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 *nixpkgs* channel tarball 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 `<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
|
||||
|
||||
@@ -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`]
|
||||
|
||||
@@ -2,16 +2,16 @@
|
||||
|
||||
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#fileish-syntax).
|
||||
See that section for complete details (`nix-build --help`), but in summary, a path argument may be one of:
|
||||
|
||||
{{#include ../fileish-summary.md}}
|
||||
|
||||
- `--profile` / `-p` *path*\
|
||||
Specifies the profile to be used by those operations that operate on
|
||||
|
||||
@@ -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#fileish-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
|
||||
|
||||
|
||||
@@ -33,10 +33,9 @@ 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`.
|
||||
If *path* is given it is interpreted like a [*fileish* argument to nix-build](./nix-build.md#fileish-syntax):
|
||||
|
||||
{{#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
|
||||
|
||||
@@ -1,9 +1,21 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Preprocesses mdbook markdown, primarily for include directives.
|
||||
|
||||
The include directive format is as follows:
|
||||
{{#include foo/bar/baz.md}}
|
||||
|
||||
The content of includes will be indented as much as the directive itself.
|
||||
|
||||
Including a generated file (from building Lix; generally for the 'new' CLI):
|
||||
{{#include @generated@/foo/bar/baz.md}}
|
||||
"""
|
||||
|
||||
from pathlib import Path
|
||||
import json
|
||||
import os, os.path
|
||||
import sys
|
||||
import textwrap
|
||||
|
||||
name = 'substitute.py'
|
||||
|
||||
@@ -11,6 +23,12 @@ def log(*args, **kwargs):
|
||||
kwargs['file'] = sys.stderr
|
||||
return print(f'{name}:', *args, **kwargs)
|
||||
|
||||
def remove_prefix_if_present(s: str, prefix: str) -> str | None:
|
||||
if s.startswith(prefix):
|
||||
return s.removeprefix(prefix)
|
||||
else:
|
||||
return None
|
||||
|
||||
def do_include(content: str, relative_md_path: Path, source_root: Path, search_path: Path):
|
||||
assert not relative_md_path.is_absolute(), f'{relative_md_path=} from mdbook should be relative'
|
||||
|
||||
@@ -20,16 +38,32 @@ def do_include(content: str, relative_md_path: Path, source_root: Path, search_p
|
||||
|
||||
lines = []
|
||||
for l in content.splitlines(keepends=True):
|
||||
if l.strip().startswith("{{#include "):
|
||||
requested = l.strip()[11:][:-2]
|
||||
if requested.startswith("@generated@/"):
|
||||
included = search_path / Path(requested[12:])
|
||||
if remain := remove_prefix_if_present(l.strip(), "{{#include"):
|
||||
requested = remain[1:-2]
|
||||
# We indent bodies of indent directives by the indent of the
|
||||
# directive itself.
|
||||
num_leading_indent = len(l) - len(l.lstrip())
|
||||
|
||||
if subpath := remove_prefix_if_present(requested, "@generated@/"):
|
||||
included = search_path / Path(subpath)
|
||||
requested = included.relative_to(search_path)
|
||||
else:
|
||||
included = source_root / relative_md_path.parent / requested
|
||||
requested = included.resolve().relative_to(source_root)
|
||||
assert included.exists(), f"{requested} not found at {included}"
|
||||
lines.append(do_include(included.read_text(), requested, source_root, search_path) + "\n")
|
||||
|
||||
lines.append(
|
||||
textwrap.indent(
|
||||
do_include(
|
||||
included.read_text(),
|
||||
requested,
|
||||
source_root,
|
||||
search_path,
|
||||
),
|
||||
" " * num_leading_indent
|
||||
)
|
||||
+ "\n"
|
||||
)
|
||||
else:
|
||||
lines.append(l)
|
||||
return "".join(lines)
|
||||
|
||||
+41
-3
@@ -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 `<nixpkgs>`.
|
||||
Unlike using `<nixpkgs>` in a `--expr` argument, this does not require `--impure`.
|
||||
|
||||
To emulate the `nix-build '<nixpkgs>' -A hello` pattern, use:
|
||||
|
||||
```console
|
||||
$ nix build -f '<nixpkgs>' 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.
|
||||
|
||||
<!-- XXX(jade): it is my understanding that although a lot of content here is duplicated from nix-build.md, THESE ARE NOT THE SAME BAD PARSER AAAAAAAAAAAA -->
|
||||
|
||||
> **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 file path argument may be one of:
|
||||
|
||||
{{#include ../fileish-summary.md}}
|
||||
|
||||
### Nix expression
|
||||
|
||||
Example: `--expr 'import <nixpkgs> {}' hello`
|
||||
|
||||
Reference in New Issue
Block a user