puck/lix
0
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity

docs: clarify flake types and implied defaults

Browse source
This commit is contained in:
Felix Uhl 2023-10-25 14:49:30 +02:00
parent 3ca0dade5b
commit 7bc45c6136
1 changed files with 50 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

77
src/nix/flake.md
View file

@ -98,7 +98,15 @@ Here are some examples of flake references in their URL-like representation:
## Path-like syntax ## Path-like syntax
Flakes corresponding to a local path can also be referred to by a direct path reference, either `/absolute/path/to/the/flake` or `./relative/path/to/the/flake` (note that the leading `./` is mandatory for relative paths to avoid any ambiguity). Flakes corresponding to a local path can also be referred to by a direct
path reference, either `/absolute/path/to/the/flake` or`./relative/path/to/the/flake`.
Note that the leading `./` is mandatory for relative paths. If it is
omitted, the path will be interpreted as [URL-like syntax](#url-like-syntax),
which will cause error messages like this:
```console
error: cannot find flake 'flake:relative/path/to/the/flake' in the flake registries
```
The semantic of such a path is as follows: The semantic of such a path is as follows:
@ -153,18 +161,39 @@ can occur in *locked* flake references and are available to Nix code:
Currently the `type` attribute can be one of the following: Currently the `type` attribute can be one of the following:
* `path`: arbitrary local directories, or local Git trees. The * `indirect`: *The default*. Indirection through the flake registry.
required attribute `path` specifies the path of the flake. The URL These have the form
form is
``` ```
[path:]<path>(\?<params)? [flake:]<flake-id>(/<rev-or-ref>(/rev)?)?
``` ```
where *path* is an absolute path. These perform a lookup of `<flake-id>` in the flake registry. For
example, `nixpkgs` and `nixpkgs/release-20.09` are indirect flake
references. The specified `rev` and/or `ref` are merged with the
entry in the registry; see [nix registry](./nix3-registry.md) for
details.
*path* must be a directory in the file system containing a file For example, these are valid indirect flake references:
named `flake.nix`.
* `nixpkgs`
* `nixpkgs/nixos-unstable`
* `nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`
* `nixpkgs/nixos-unstable/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`
* `sub/dir` (if a flake named `sub` is in the registry)
* `path`: arbitrary local directories. The required attribute `path`
specifies the path of the flake. The URL form is
```
path:<path>(\?<params>)?
```
where *path* is an absolute path to a directory in the file system
containing a file named `flake.nix`.
If the flake at *path* is not inside a git repository, the `path:`
prefix is implied and can be omitted.
*path* generally must be an absolute path. However, on the command *path* generally must be an absolute path. However, on the command
line, it can be a relative path (e.g. `.` or `./foo`) which is line, it can be a relative path (e.g. `.` or `./foo`) which is
@ -173,20 +202,24 @@ Currently the `type` attribute can be one of the following:
(e.g. `nixpkgs` is a registry lookup; `./nixpkgs` is a relative (e.g. `nixpkgs` is a registry lookup; `./nixpkgs` is a relative
path). path).
For example, these are valid path flake references:
* `path:/home/user/sub/dir`
* `/home/user/sub/dir` (if `dir/flake.nix` is *not* in a git repository)
* `./sub/dir` (when used on the command line and `dir/flake.nix` is *not* in a git repository)
* `git`: Git repositories. The location of the repository is specified * `git`: Git repositories. The location of the repository is specified
by the attribute `url`. by the attribute `url`.
They have the URL form They have the URL form
``` ```
git(+http|+https|+ssh|+git|+file|):(//<server>)?<path>(\?<params>)? git(+http|+https|+ssh|+git|+file):(//<server>)?<path>(\?<params>)?
``` ```
or If *path* starts with `/` (or `./` when used as an argument on the
command line) and is a local path to a git repository, the leading
``` `git:` or `+file` prefixes are implied and can be omitted.
<user>@<server>:<path>
```
The `ref` attribute defaults to resolving the `HEAD` reference. The `ref` attribute defaults to resolving the `HEAD` reference.
@ -203,6 +236,9 @@ Currently the `type` attribute can be one of the following:
For example, the following are valid Git flake references: For example, the following are valid Git flake references:
* `git:/home/user/sub/dir`
* `/home/user/sub/dir` (if `dir/flake.nix` is in a git repository)
* `./sub/dir` (when used on the command line and `dir/flake.nix` is in a git repository)
* `git+https://example.org/my/repo` * `git+https://example.org/my/repo`
* `git+https://example.org/my/repo?dir=flake1` * `git+https://example.org/my/repo?dir=flake1`
* `git+ssh://git@github.com/NixOS/nix?ref=v1.2.3` * `git+ssh://git@github.com/NixOS/nix?ref=v1.2.3`
@ -324,19 +360,6 @@ Currently the `type` attribute can be one of the following:
* `sourcehut:~misterio/nix-colors/182b4b8709b8ffe4e9774a4c5d6877bf6bb9a21c` * `sourcehut:~misterio/nix-colors/182b4b8709b8ffe4e9774a4c5d6877bf6bb9a21c`
* `sourcehut:~misterio/nix-colors/21c1a380a6915d890d408e9f22203436a35bb2de?host=hg.sr.ht` * `sourcehut:~misterio/nix-colors/21c1a380a6915d890d408e9f22203436a35bb2de?host=hg.sr.ht`
* `indirect`: Indirections through the flake registry. These have the
form
```
[flake:]<flake-id>(/<rev-or-ref>(/rev)?)?
```
These perform a lookup of `<flake-id>` in the flake registry. For
example, `nixpkgs` and `nixpkgs/release-20.09` are indirect flake
references. The specified `rev` and/or `ref` are merged with the
entry in the registry; see [nix registry](./nix3-registry.md) for
details.
# Flake format # Flake format
As an example, here is a simple `flake.nix` that depends on the As an example, here is a simple `flake.nix` that depends on the