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

Add 'nix flake' manpages

Browse source
This commit is contained in:
Eelco Dolstra 2020-12-23 13:19:53 +01:00
parent 16e34085e8
commit c9279b831e
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
11 changed files with 1046 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
src/nix/flake-archive.md Normal file
View file

@ -0,0 +1,29 @@
R""(
# Examples
* Copy the `dwarffs` flake and its dependencies to a binary cache:
```console
# nix flake archive --to file:///tmp/my-cache dwarffs
```
* Fetch the `dwarffs` flake and its dependencies to the local Nix
store:
```console
# nix flake archive dwarffs
```
* Print the store paths of the flake sources of NixOps without
fetching them:
```console
# nix flake archive --json --dry-run nixops
```
# Description
FIXME
)""

68
src/nix/flake-check.md Normal file
View file

@ -0,0 +1,68 @@
R""(
# Examples
* Evaluate the flake in the current directory, and build its checks:
```console
# nix flake check
```
* Verify that the `patchelf` flake evaluates, but don't build its
checks:
```console
# nix flake check --no-build github:NixOS/patchelf
```
# Description
This command verifies that the flake specified by flake reference
*flake-url* can be evaluated successfully (as detailed below), and
that the derivations specified by the flake's `checks` output can be
built successfully.
# Evaluation checks
This following flake output attributes must be derivations:
* `checks.`*system*`.`*name*
* `defaultPackage.`*system*`
* `devShell.`*system*`
* `nixosConfigurations.`*name*`.config.system.build.toplevel
* `packages.`*system*`.`*name*
The following flake output attributes must be [app
definitions](./nix3-run.md):
* `apps.`*system*`.`*name*
* `defaultApp.`*system*`
The following flake output attributes must be [template
definitions](./nix3-flake-init.md):
* `defaultTemplate`
* `templates`.`*name*
The following flake output attributes must be *Nixpkgs overlays*:
* `overlay`
* `overlays`.`*name*
The following flake output attributes must be *NixOS modules*:
* `nixosModule`
* `nixosModules`.`*name*
The following flake output attributes must be
[bundlers](./nix3-bundle.md):
* `bundlers`.`*name*
* `defaultBundler`
In addition, the `hydraJobs` output is evaluated in the same way as
Hydra's `hydra-eval-jobs` (i.e. as a arbitrarily deeply nested
attribute set of derivations). Similarly, the
`legacyPackages`.*system* output is evaluated like `nix-env -qa`.
)""

18
src/nix/flake-clone.md Normal file
View file

@ -0,0 +1,18 @@
R""(
# Examples
* Check out the source code of the `dwarffs` flake and build it:
```console
# nix flake clone dwarffs --dest dwarffs
# cd dwarffs
# nix build
```
# Description
This command performs a Git or Mercurial clone of the repository
containing the source code of the flake *flake-url*.
)""

99
src/nix/flake-info.md Normal file
View file

@ -0,0 +1,99 @@
R""(
# Examples
* Show what `nixpkgs` resolves to:
```console
# nix flake info nixpkgs
Resolved URL: github:NixOS/nixpkgs
Locked URL: github:NixOS/nixpkgs/b67ba0bfcc714453cdeb8d713e35751eb8b4c8f4
Description: A collection of packages for the Nix package manager
Path: /nix/store/23qapccs6cfmwwrlq8kr41vz5vdmns3r-source
Revision: b67ba0bfcc714453cdeb8d713e35751eb8b4c8f4
Last modified: 2020-12-23 12:36:12
```
* Show information about `dwarffs` in JSON format:
```console
# nix flake info dwarffs --json | jq .
{
"description": "A filesystem that fetches DWARF debug info from the Internet on demand",
"lastModified": 1597153508,
"locked": {
"lastModified": 1597153508,
"narHash": "sha256-VHg3MYVgQ12LeRSU2PSoDeKlSPD8PYYEFxxwkVVDRd0=",
"owner": "edolstra",
"repo": "dwarffs",
"rev": "d181d714fd36eb06f4992a1997cd5601e26db8f5",
"type": "github"
},
"original": {
"id": "dwarffs",
"type": "indirect"
},
"originalUrl": "flake:dwarffs",
"path": "/nix/store/hang3792qwdmm2n0d9nsrs5n6bsws6kv-source",
"resolved": {
"owner": "edolstra",
"repo": "dwarffs",
"type": "github"
},
"resolvedUrl": "github:edolstra/dwarffs",
"revision": "d181d714fd36eb06f4992a1997cd5601e26db8f5",
"url": "github:edolstra/dwarffs/d181d714fd36eb06f4992a1997cd5601e26db8f5"
}
```
# Description
This command shows information about the flake specified by the flake
reference *flake-url*. It resolves the flake reference using the
[flake registry](./nix3-registry.md), fetches it, and prints some meta
data. This includes:
* `Resolved URL`: If *flake-url* is a flake identifier, then this is
the flake reference that specifies its actual location, looked up in
the flake registry.
* `Locked URL`: A flake reference that contains a commit or content
hash and thus uniquely identifies a specific flake version.
* `Description`: A one-line description of the flake, taken from the
`description` field in `flake.nix`.
* `Path`: The store path containing the source code of the flake.
* `Revision`: The Git or Mercurial commit hash of the locked flake.
* `Revisions`: The number of ancestors of the Git or Mercurial commit
of the locked flake. Note that this is not available for `github`
flakes.
* `Last modified`: For Git or Mercurial flakes, this is the commit
time of the commit of the locked flake; for tarball flakes, it's the
most recent timestamp of any file inside the tarball.
With `--json`, the output is a JSON object with the following fields:
* `original` and `originalUrl`: The flake reference specified by the
user (*flake-url*) in attribute set and URL representation.
* `resolved` and `resolvedUrl`: The resolved flake reference (see
above) in attribute set and URL representation.
* `locked` and `lockedUrl`: The locked flake reference (see above) in
attribute set and URL representation.
* `description`: See `Description` above.
* `path`: See `Path` above.
* `revision`: See `Revision` above.
* `revCount`: See `Revisions` above.
* `lastModified`: See `Last modified` above.
)""

54
src/nix/flake-init.md Normal file
View file

@ -0,0 +1,54 @@
R""(
# Examples
* Create a flake using the default template:
```console
# nix flake init
```
* List available templates:
```console
# nix flake show templates
```
* Create a flake from a specific template:
```console
# nix flake init -t templates#simpleContainer
```
# Description
This command creates a flake in the current directory by copying the
files of a template. It will not overwrite existing files. The default
template is `templates#defaultTemplate`, but this can be overriden
using `-t`.
# Template definitions
A flake can declare templates through its `templates` and
`defaultTemplate` output attributes. A template has two attributes:
* `description`: A one-line description of the template, in CommonMark
syntax.
* `path`: The path of the directory to be copied.
Here is an example:
```
outputs = { self }: {
templates.rust = {
path = ./rust;
description = "A simple Rust/Cargo project";
};
templates.defaultTemplate = self.templates.rust;
}
```
)""

23
src/nix/flake-list-inputs.md Normal file
View file

@ -0,0 +1,23 @@
R""(
# Examples
* Show the inputs of the `hydra` flake:
```console
# nix flake list-inputs github:NixOS/hydra
github:NixOS/hydra/bde8d81876dfc02143e5070e42c78d8f0d83d6f7
├───nix: github:NixOS/nix/79aa7d95183cbe6c0d786965f0dbff414fd1aa67
│ ├───lowdown-src: github:kristapsdz/lowdown/1705b4a26fbf065d9574dce47a94e8c7c79e052f
│ └───nixpkgs: github:NixOS/nixpkgs/ad0d20345219790533ebe06571f82ed6b034db31
└───nixpkgs follows input 'nix/nixpkgs'
```
# Description
This command shows the inputs of the flake specified by the flake
referenced *flake-url*. Since it prints the locked inputs that result
from generating or updating the lock file, this command essentially
displays the contents of the flake's lock file in human-readable form.
)""

34
src/nix/flake-new.md Normal file
View file

@ -0,0 +1,34 @@
R""(
# Examples
* Create a flake using the default template in the directory `hello`:
```console
# nix flake new hello
```
* List available templates:
```console
# nix flake show templates
```
* Create a flake from a specific template in the directory `hello`:
```console
# nix flake new hello -t templates#trivial
```
# Description
This command creates a flake in the directory `dest-dir`, which must
not already exist. It's equivalent to:
```console
# mkdir dest-dir
# cd dest-dir
# nix flake init
```
)""

38
src/nix/flake-show.md Normal file
View file

@ -0,0 +1,38 @@
R""(
# Examples
* Show the output attributes provided by the `patchelf` flake:
```console
github:NixOS/patchelf/f34751b88bd07d7f44f5cd3200fb4122bf916c7e
├───checks
│ ├───aarch64-linux
│ │ └───build: derivation 'patchelf-0.12.20201207.f34751b'
│ ├───i686-linux
│ │ └───build: derivation 'patchelf-0.12.20201207.f34751b'
│ └───x86_64-linux
│ └───build: derivation 'patchelf-0.12.20201207.f34751b'
├───defaultPackage
│ ├───aarch64-linux: package 'patchelf-0.12.20201207.f34751b'
│ ├───i686-linux: package 'patchelf-0.12.20201207.f34751b'
│ └───x86_64-linux: package 'patchelf-0.12.20201207.f34751b'
├───hydraJobs
│ ├───build
│ │ ├───aarch64-linux: derivation 'patchelf-0.12.20201207.f34751b'
│ │ ├───i686-linux: derivation 'patchelf-0.12.20201207.f34751b'
│ │ └───x86_64-linux: derivation 'patchelf-0.12.20201207.f34751b'
│ ├───coverage: derivation 'patchelf-coverage-0.12.20201207.f34751b'
│ ├───release: derivation 'patchelf-0.12.20201207.f34751b'
│ └───tarball: derivation 'patchelf-tarball-0.12.20201207.f34751b'
└───overlay: Nixpkgs overlay
```
# Description
This command shows the output attributes provided by the flake
specified by flake reference *flake-url*. These are the top-level
attributes in the `outputs` of the flake, as well as lower-level
attributes for some standard outputs (e.g. `packages` or `checks`).
)""

53
src/nix/flake-update.md Normal file
View file

@ -0,0 +1,53 @@
R""(
# Examples
* Update the `nixpkgs` and `nix` inputs of the flake in the current
directory:
```console
# nix flake update --update-input nixpkgs --update-input nix
* Updated 'nix': 'github:NixOS/nix/9fab14adbc3810d5cc1f88672fde1eee4358405c' -> 'github:NixOS/nix/8927cba62f5afb33b01016d5c4f7f8b7d0adde3c'
* Updated 'nixpkgs': 'github:NixOS/nixpkgs/3d2d8f281a27d466fa54b469b5993f7dde198375' -> 'github:NixOS/nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293'
```
* Recreate the lock file (i.e. update all inputs) and commit the new
lock file:
```console
# nix flake update --recreate-lock-file --commit-lock-file
…
warning: committed new revision '158bcbd9d6cc08ab859c0810186c1beebc982aad'
```
# Description
This command updates the lock file of a flake (`flake.lock`) so that
it contains a lock for every flake input specified in
`flake.nix`. Note that every command that operates on a flake will
also update the lock file if needed, and supports the same
flags. Therefore,
```console
# nix flake update --update-input nixpkgs
# nix build
```
is equivalent to:
```console
# nix build --update-input nixpkgs
```
Thus, this command is only useful if you want to update the lock file
separately from any other action such as building.
> **Note**
>
> This command does *not* update locks that are already present unless
> you explicitly ask for it using `--update-input` or
> `--recreate-lock-file`. Thus, if the lock file already has locks for
> every input, then `nix flake update` (without arguments) does
> nothing.
)""

94
src/nix/flake.cc
View file

@ -104,6 +104,13 @@ struct CmdFlakeUpdate : FlakeCommand
return "update flake lock file"; return "update flake lock file";
} }
std::string doc() override
{
return
#include "flake-update.md"
;
}
void run(nix::ref<nix::Store> store) override void run(nix::ref<nix::Store> store) override
{ {
/* Use --refresh by default for 'nix flake update'. */ /* Use --refresh by default for 'nix flake update'. */
@ -134,6 +141,13 @@ struct CmdFlakeInfo : FlakeCommand, MixJSON
return "list info about a given flake"; return "list info about a given flake";
} }
std::string doc() override
{
return
#include "flake-info.md"
;
}
void run(nix::ref<nix::Store> store) override void run(nix::ref<nix::Store> store) override
{ {
auto flake = getFlake(); auto flake = getFlake();
@ -153,6 +167,13 @@ struct CmdFlakeListInputs : FlakeCommand, MixJSON
return "list flake inputs"; return "list flake inputs";
} }
std::string doc() override
{
return
#include "flake-list-inputs.md"
;
}
void run(nix::ref<nix::Store> store) override void run(nix::ref<nix::Store> store) override
{ {
auto flake = lockFlake(); auto flake = lockFlake();
@ -211,6 +232,13 @@ struct CmdFlakeCheck : FlakeCommand
return "check whether the flake evaluates and run its tests"; return "check whether the flake evaluates and run its tests";
} }
std::string doc() override
{
return
#include "flake-check.md"
;
}
void run(nix::ref<nix::Store> store) override void run(nix::ref<nix::Store> store) override
{ {
settings.readOnlyMode = !build; settings.readOnlyMode = !build;
@ -631,22 +659,11 @@ struct CmdFlakeInit : CmdFlakeInitCommon
return "create a flake in the current directory from a template"; return "create a flake in the current directory from a template";
} }
Examples examples() override std::string doc() override
{ {
return { return
Example{ #include "flake-init.md"
"To create a flake using the default template:", ;
"nix flake init"
},
Example{
"To see available templates:",
"nix flake show templates"
},
Example{
"To create a flake from a specific template:",
"nix flake init -t templates#nixos-container"
},
};
} }
CmdFlakeInit() CmdFlakeInit()
@ -662,6 +679,13 @@ struct CmdFlakeNew : CmdFlakeInitCommon
return "create a flake in the specified directory from a template"; return "create a flake in the specified directory from a template";
} }
std::string doc() override
{
return
#include "flake-new.md"
;
}
CmdFlakeNew() CmdFlakeNew()
{ {
expectArgs({ expectArgs({
@ -681,6 +705,13 @@ struct CmdFlakeClone : FlakeCommand
return "clone flake repository"; return "clone flake repository";
} }
std::string doc() override
{
return
#include "flake-clone.md"
;
}
CmdFlakeClone() CmdFlakeClone()
{ {
addFlag({ addFlag({
@ -720,22 +751,11 @@ struct CmdFlakeArchive : FlakeCommand, MixJSON, MixDryRun
return "copy a flake and all its inputs to a store"; return "copy a flake and all its inputs to a store";
} }
Examples examples() override std::string doc() override
{ {
return { return
Example{ #include "flake-archive.md"
"To copy the dwarffs flake and its dependencies to a binary cache:", ;
"nix flake archive --to file:///tmp/my-cache dwarffs"
},
Example{
"To fetch the dwarffs flake and its dependencies to the local Nix store:",
"nix flake archive dwarffs"
},
Example{
"To print the store paths of the flake sources of NixOps without fetching them:",
"nix flake archive --json --dry-run nixops"
},
};
} }
void run(nix::ref<nix::Store> store) override void run(nix::ref<nix::Store> store) override
@ -797,6 +817,13 @@ struct CmdFlakeShow : FlakeCommand
return "show the outputs provided by a flake"; return "show the outputs provided by a flake";
} }
std::string doc() override
{
return
#include "flake-show.md"
;
}
void run(nix::ref<nix::Store> store) override void run(nix::ref<nix::Store> store) override
{ {
auto state = getEvalState(); auto state = getEvalState();
@ -955,6 +982,13 @@ struct CmdFlake : NixMultiCommand
return "manage Nix flakes"; return "manage Nix flakes";
} }
std::string doc() override
{
return
#include "flake.md"
;
}
void run() override void run() override
{ {
if (!command) if (!command)

566
src/nix/flake.md Normal file
View file

@ -0,0 +1,566 @@
R""(
# Description
`nix flake` provides subcommands for creating, modifying and querying
*Nix flakes*. Flakes are the unit for packaging Nix code in a
reproducible and discoverable way. They can have dependencies on other
flakes, making it possible to have multi-repository Nix projects.
A flake is a filesystem tree (typically fetched from a Git repository
or a tarball) that contains a file named `flake.nix` in the root
directory. `flake.nix` specifies some metadata about the flake such as
dependencies (called *inputs*), as well as its *outputs* (the Nix
values such as packages or NixOS modules provided by the flake).
# Flake references
Flake references (*flakerefs*) are a way to specify the location of a
flake. These have two different forms:
* An attribute set representation, e.g.
```nix
{
type = "github";
owner = "NixOS";
repo = "nixpkgs";
}
```
The only required attribute is `type`. The supported types are
listed below.
* A URL-like syntax, e.g.
```
github:NixOS/nixpkgs
```
These are used on the command line as a more convenient alternative
to the attribute set representation. For instance, in the command
```console
# nix build github:NixOS/nixpkgs#hello
```
`github:NixOS/nixpkgs` is a flake reference (while `hello` is an
output attribute). They are also allowed in the `inputs` attribute
of a flake, e.g.
```nix
inputs.nixpkgs.url = github:NixOS/nixpkgs;
```
is equivalent to
```nix
inputs.nixpkgs = {
type = "github";
owner = "NixOS";
repo = "nixpkgs";
};
```
## Examples
Here are some examples of flake references in their URL-like representation:
* `.`: The flake in the current directory.
* `/home/alice/src/patchelf`: A flake in some other directory.
* `nixpkgs`: The `nixpkgs` entry in the flake registry.
* `nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`: The `nixpkgs`
entry in the flake registry, with its Git revision overriden to a
specific value.
* `github:NixOS/nixpkgs`: The `master` branch of the `NixOS/nixpkgs`
repository on GitHub.
* `github:NixOS/nixpkgs/nixos-20.09`: The `nixos-20.09` branch of the
`nixpkgs` repository.
* `github:NixOS/nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293`: A
specific revision of the `nixpkgs` repository.
* `github:edolstra/nix-warez?dir=blender`: A flake in a subdirectory
of a GitHub repository.
* `git+https://github.com/NixOS/patchelf`: A Git repository.
* `git+https://github.com/NixOS/patchelf?ref=master`: A specific
branch of a Git repository.
* `git+https://github.com/NixOS/patchelf?ref=master&rev=f34751b88bd07d7f44f5cd3200fb4122bf916c7e`:
A specific branch *and* revision of a Git repository.
* `https://github.com/NixOS/patchelf/archive/master.tar.gz`: A tarball
flake.
## Flake reference attributes
The following generic flake reference attributes are supported:
* `dir`: The subdirectory of the flake in which `flake.nix` is
located. This parameter enables having multiple flakes in a
repository or tarball. The default is the root directory of the
flake.
* `narHash`: The hash of the NAR serialisation (in SRI format) of the
contents of the flake. This is useful for flake types such as
tarballs that lack a unique content identifier such as a Git commit
hash.
In addition, the following attributes are common to several flake
reference types:
* `rev`: A Git or Mercurial commit hash.
* `ref`: A Git or Mercurial branch or tag name.
Finally, some attribute are typically not specified by the user, but
can occur in *locked* flake references and are available to Nix code:
* `revCount`: The number of ancestors of the commit `rev`.
* `lastModified`: The timestamp (in seconds since the Unix epoch) of
the last modification of this version of the flake. For
Git/Mercurial flakes, this is the commit time of commit *rev*, while
for tarball flakes, it's the most recent timestamp of any file
inside the tarball.
## Types
Currently the `type` attribute can be one of the following:
* `path`: arbitrary local directories, or local Git trees. The
required attribute `path` specifies the path of the flake. The URL
form is
```
[path:]<path>(\?<params)?
```
where *path* is an absolute path.
*path* must be a directory in the file system containing a file
named `flake.nix`.
If the directory or any of its parents is a Git repository, then
this is essentially equivalent to `git+file://<path>` (see below),
except that the `dir` parameter is derived automatically. For
example, if `/foo/bar` is a Git repository, then the flake reference
`/foo/bar/flake` is equivalent to `/foo/bar?dir=flake`.
If the directory is not inside a Git repository, then the flake
contents is the entire contents of *path*.
*path* generally must be an absolute path. However, on the command
line, it can be a relative path (e.g. `.` or `./foo`) which is
interpreted as relative to the current directory. In this case, it
must start with `.` to avoid ambiguity with registry lookups
(e.g. `nixpkgs` is a registry lookup; `./nixpkgs` is a relative
path).
* `git`: Git repositories. The location of the repository is specified
by the attribute `url`.
They have the URL form
```
git(+http|+https|+ssh|+git|+file|):(//<server>)?<path>(\?<params>)?
```
The `ref` attribute defaults to `master`.
The `rev` attribute must denote a commit that exists in the branch
or tag specified by the `ref` attribute, since Nix doesn't do a full
clone of the remote repository by default (and the Git protocol
doesn't allow fetching a `rev` without a known `ref`). The default
is the commit currently pointed to by `ref`.
For example, the following are valid Git flake references:
* `git+https://example.org/my/repo`
* `git+https://example.org/my/repo?dir=flake1`
* `git+ssh://git@github.com/NixOS/nix?ref=v1.2.3`
* `git://github.com/edolstra/dwarffs?ref=unstable&rev=e486d8d40e626a20e06d792db8cc5ac5aba9a5b4`
* `git+file:///home/my-user/some-repo/some-repo`
* `mercurial`: Mercurial repositories. The URL form is similar to the
`git` type, except that the URL schema must be one of `hg+http`,
`hg+https`, `hg+ssh` or `hg+file`.
* `tarball`: Tarballs. The location of the tarball is specified by the
attribute `url`.
In URL form, the schema must be `http://`, `https://` or `file://`
URLs and the extension must be `.zip`, `.tar`, `.tar.gz`, `.tar.xz`
or `.tar.bz2`.
* `github`: A more efficient way to fetch repositories from
GitHub. The following attributes are required:
* `owner`: The owner of the repository.
* `repo`: The name of the repository.
These are downloaded as tarball archives, rather than
through Git. This is often much faster and uses less disk space
since it doesn't require fetching the entire history of the
repository. On the other hand, it doesn't allow incremental fetching
(but full downloads are often faster than incremental fetches!).
The URL syntax for `github` flakes is:
```
github:<owner>/<repo>(/<rev-or-ref>)?(\?<params>)?
```
`<rev-or-ref>` specifies the name of a branch or tag (`ref`), or a
commit hash (`rev`). Note that unlike Git, GitHub allows fetching by
commit hash without specifying a branch or tag.
Some examples:
* `github:edolstra/dwarffs`
* `github:edolstra/dwarffs/unstable`
* `github:edolstra/dwarffs/d3f2baba8f425779026c6ec04021b2e927f61e31`
* `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. or
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
As an example, here is a simple `flake.nix` that depends on the
Nixpkgs flake and provides a single package (i.e. an installable
derivation):
```nix
{
description = "A flake for building Hello World";
inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-20.03;
outputs = { self, nixpkgs }: {
defaultPackage.x86_64-linux =
# Notice the reference to nixpkgs here.
with import nixpkgs { system = "x86_64-linux"; };
stdenv.mkDerivation {
name = "hello";
src = self;
buildPhase = "gcc -o hello ./hello.c";
installPhase = "mkdir -p $out/bin; install -t $out/bin hello";
};
};
}
```
The following attributes are supported in `flake.nix`:
* `description`: A short, one-line description of the flake.
* `inputs`: An attrset specifying the dependencies of the flake
(described below).
* `outputs`: A function that, given an attribute set containing the
outputs of each of the input flakes keyed by their identifier,
yields the Nix values provided by this flake. Thus, in the example
above, `inputs.nixpkgs` contains the result of the call to the
`outputs` function of the `nixpkgs` flake.
In addition to the outputs of each input, each input in `inputs`
also contains some metadata about the inputs. These are:
* `outPath`: The path in the Nix store of the flake's source tree.
* `rev`: The commit hash of the flake's repository, if applicable.
* `revCount`: The number of ancestors of the revision `rev`. This is
not available for `github` repositories, since they're fetched as
tarballs rather than as Git repositories.
* `lastModifiedDate`: The commit time of the revision `rev`, in the
format `%Y%m%d%H%M%S` (e.g. `20181231100934`). Unlike `revCount`,
this is available for both Git and GitHub repositories, so it's
useful for generating (hopefully) monotonically increasing version
strings.
* `lastModified`: The commit time of the revision `rev` as an integer
denoting the number of seconds since 1970.
* `narHash`: The SHA-256 (in SRI format) of the NAR serialization of
the flake's source tree.
The value returned by the `outputs` function must be an attribute
set. The attributes can have arbitrary values; however, various
`nix` subcommands require specific attributes to have a specific
value (e.g. `packages.x86_64-linux` must be an attribute set of
derivations built for the `x86_64-linux` platform).
## Flake inputs
The attribute `inputs` specifies the dependencies of a flake, as an
attrset mapping input names to flake references. For example, the
following specifies a dependency on the `nixpkgs` and `import-cargo`
repositories:
```nix
# A GitHub repository.
inputs.import-cargo = {
type = "github";
owner = "edolstra";
repo = "import-cargo";
};
# An indirection through the flake registry.
inputs.nixpkgs = {
type = "indirect";
id = "nixpkgs";
};
```
Alternatively, you can use the URL-like syntax:
```nix
inputs.import-cargo.url = github:edolstra/import-cargo;
inputs.nixpkgs.url = "nixpkgs";
```
Each input is fetched, evaluated and passed to the `outputs` function
as a set of attributes with the same name as the corresponding
input. The special input named `self` refers to the outputs and source
tree of *this* flake. Thus, a typical `outputs` function looks like
this:
```nix
outputs = { self, nixpkgs, import-cargo }: {
... outputs ...
};
```
It is also possible to omit an input entirely and *only* list it as
expected function argument to `outputs`. Thus,
```nix
outputs = { self, nixpkgs }: ...;
```
without an `inputs.nixpkgs` attribute is equivalent to
```nix
inputs.nixpkgs = {
type = "indirect";
id = "nixpkgs";
};
```
Repositories that don't contain a `flake.nix` can also be used as
inputs, by setting the input's `flake` attribute to `false`:
```nix
inputs.grcov = {
type = "github";
owner = "mozilla";
repo = "grcov";
flake = false;
};
outputs = { self, nixpkgs, grcov }: {
packages.x86_64-linux.grcov = stdenv.mkDerivation {
src = grcov;
...
};
};
```
Transitive inputs can be overriden from a `flake.nix` file. For
example, the following overrides the `nixpkgs` input of the `nixops`
input:
```nix
inputs.nixops.inputs.nixpkgs = {
type = "github";
owner = "my-org";
repo = "nixpkgs";
};
```
It is also possible to "inherit" an input from another input. This is
useful to minimize flake dependencies. For example, the following sets
the `nixpkgs` input of the top-level flake to be equal to the
`nixpkgs` input of the `dwarffs` input of the top-level flake:
```nix
inputs.nixops.follows = "dwarffs/nixpkgs";
```
The value of the `follows` attribute is a `/`-separated sequence of
input names denoting the path of inputs to be followed from the root
flake.
Overrides and `follows` can be combined, e.g.
```nix
inputs.nixops.inputs.nixpkgs.follows = "dwarffs/nixpkgs";
```
sets the `nixpkgs` input of `nixops` to be the same as the `nixpkgs`
input of `dwarffs`. It is worth noting, however, that it is generally
not useful to eliminate transitive `nixpkgs` flake inputs in this
way. Most flakes provide their functionality through Nixpkgs overlays
or NixOS modules, which are composed into the top-level flake's
`nixpkgs` input; so their own `nixpkgs` input is usually irrelevant.
# Lock files
Inputs specified in `flake.nix` are typically "unlocked" in the sense
that they don't specify an exact revision. To ensure reproducibility,
Nix will automatically generate and use a *lock file* called
`flake.lock` in the flake's directory. The lock file contains a graph
structure isomorphic to the graph of dependencies of the root
flake. Each node in the graph (except the root node) maps the
(usually) unlocked input specifications in `flake.nix` to locked input
specifications. Each node also contains some metadata, such as the
dependencies (outgoing edges) of the node.
For example, if `flake.nix` has the inputs in the example above, then
the resulting lock file might be:
```json
{
"version": 7,
"root": "n1",
"nodes": {
"n1": {
"inputs": {
"nixpkgs": "n2",
"import-cargo": "n3",
"grcov": "n4"
}
},
"n2": {
"inputs": {},
"locked": {
"owner": "edolstra",
"repo": "nixpkgs",
"rev": "7f8d4b088e2df7fdb6b513bc2d6941f1d422a013",
"type": "github",
"lastModified": 1580555482,
"narHash": "sha256-OnpEWzNxF/AU4KlqBXM2s5PWvfI5/BS6xQrPvkF5tO8="
},
"original": {
"id": "nixpkgs",
"type": "indirect"
}
},
"n3": {
"inputs": {},
"locked": {
"owner": "edolstra",
"repo": "import-cargo",
"rev": "8abf7b3a8cbe1c8a885391f826357a74d382a422",
"type": "github",
"lastModified": 1567183309,
"narHash": "sha256-wIXWOpX9rRjK5NDsL6WzuuBJl2R0kUCnlpZUrASykSc="
},
"original": {
"owner": "edolstra",
"repo": "import-cargo",
"type": "github"
}
},
"n4": {
"inputs": {},
"locked": {
"owner": "mozilla",
"repo": "grcov",
"rev": "989a84bb29e95e392589c4e73c29189fd69a1d4e",
"type": "github",
"lastModified": 1580729070,
"narHash": "sha256-235uMxYlHxJ5y92EXZWAYEsEb6mm+b069GAd+BOIOxI="
},
"original": {
"owner": "mozilla",
"repo": "grcov",
"type": "github"
},
"flake": false
}
}
}
```
This graph has 4 nodes: the root flake, and its 3 dependencies. The
nodes have arbitrary labels (e.g. `n1`). The label of the root node of
the graph is specified by the `root` attribute. Nodes contain the
following fields:
* `inputs`: The dependencies of this node, as a mapping from input
names (e.g. `nixpkgs`) to node labels (e.g. `n2`).
* `original`: The original input specification from `flake.lock`, as a
set of `builtins.fetchTree` arguments.
* `locked`: The locked input specification, as a set of
`builtins.fetchTree` arguments. Thus, in the example above, when we
build this flake, the input `nixpkgs` is mapped to revision
`7f8d4b088e2df7fdb6b513bc2d6941f1d422a013` of the `edolstra/nixpkgs`
repository on GitHub.
It also includes the attribute `narHash`, specifying the expected
contents of the tree in the Nix store (as computed by `nix
hash-path`), and may include input-type-specific attributes such as
the `lastModified` or `revCount`. The main reason for these
attributes is to allow flake inputs to be substituted from a binary
cache: `narHash` allows the store path to be computed, while the
other attributes are necessary because they provide information not
stored in the store path.
* `flake`: A Boolean denoting whether this is a flake or non-flake
dependency. Corresponds to the `flake` attribute in the `inputs`
attribute in `flake.nix`.
The `original` and `locked` attributes are omitted for the root
node. This is because we cannot record the commit hash or content hash
of the root flake, since modifying `flake.lock` will invalidate these.
The graph representation of lock files allows circular dependencies
between flakes. For example, here are two flakes that reference each
other:
```nix
{
inputs.b = ... location of flake B ...;
# Tell the 'b' flake not to fetch 'a' again, to ensure its 'a' is
# *this* 'a'.
inputs.b.inputs.a.follows = "";
outputs = { self, b }: {
foo = 123 + b.bar;
xyzzy = 1000;
};
}
```
and
```nix
{
inputs.a = ... location of flake A ...;
inputs.a.inputs.b.follows = "";
outputs = { self, a }: {
bar = 456 + a.xyzzy;
};
}
```
Lock files transitively lock direct as well as indirect
dependencies. That is, if a lock file exists and is up to date, Nix
will not look at the lock files of dependencies. However, lock file
generation itself *does* use the lock files of dependencies by
default.
)""