Skip to content

Commit

Permalink
make descriptions of each installable type an own subsection
Browse files Browse the repository at this point in the history 
this is easier to edit, provides anchors for free, and renders correctly
on the terminal without additional effort.
  • Loading branch information
@fricklerhandwerk
fricklerhandwerk committed Jan 19, 2023
1 parent 4e41fe9 commit c1afdf0
Showing 1 changed file with 89 additions and 77 deletions.
166 changes: 89 additions & 77 deletions src/nix/nix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,100 +50,112 @@ manual](https://nixos.org/manual/nix/stable/).

Many `nix` subcommands operate on one or more *installables*. These are
command line arguments that represent something that can be built in
the Nix store. Here are the recognised types of installables:

* **Flake output attributes**: `nixpkgs#hello`

These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
flake reference and *attrpath* is an optional attribute path. For
more information on flakes, see [the `nix flake` manual
page](./nix3-flake.md). Flake references are most commonly a flake
identifier in the flake registry (e.g. `nixpkgs`), or a raw path
(e.g. `/path/to/my-flake` or `.` or `../foo`), or a full URL
(e.g. `github:nixos/nixpkgs` or `path:.`)

When the flake reference is a raw path (a path without any URL
scheme), it is interpreted as a `path:` or `git+file:` url in the following
way:
- If the path is within a Git repository, then the url will be of the form
`git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
where `GIT_REPO_ROOT` is the path to the root of the git repository,
and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
root) of the closest parent of the given path that contains a `flake.nix` within
the git repository.
If no such directory exists, then Nix will error-out.
Note that the search will only include files indexed by git. In particular, files
which are matched by `.gitignore` or have never been `git add`-ed will not be
available in the flake. If this is undesirable, specify `path:<directory>` explicitly;
For example, if `/foo/bar` is a git repository with the following structure:
```
.
└── baz
├── blah
│  └── file.txt
└── flake.nix
```
the Nix store.

For most commands, if no installable is specified, the default is `.`,
i.e. Nix will operate on the default flake output attribute of the
flake in the current directory.

Here are the recognised types of installables:

## Flake output attributes

Example: `nixpkgs#hello`

These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
flake reference and *attrpath* is an optional attribute path. For
more information on flakes, see [the `nix flake` manual
page](./nix3-flake.md). Flake references are most commonly a flake
identifier in the flake registry (e.g. `nixpkgs`), or a raw path
(e.g. `/path/to/my-flake` or `.` or `../foo`), or a full URL
(e.g. `github:nixos/nixpkgs` or `path:.`)

When the flake reference is a raw path (a path without any URL
scheme), it is interpreted as a `path:` or `git+file:` url in the following
way:

- If the path is within a Git repository, then the url will be of the form
`git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
where `GIT_REPO_ROOT` is the path to the root of the git repository,
and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
root) of the closest parent of the given path that contains a `flake.nix` within
the git repository.
If no such directory exists, then Nix will error-out.

Note that the search will only include files indexed by git. In particular, files
which are matched by `.gitignore` or have never been `git add`-ed will not be
available in the flake. If this is undesirable, specify `path:<directory>` explicitly;

For example, if `/foo/bar` is a git repository with the following structure:
```
.
└── baz
├── blah
│  └── file.txt
└── flake.nix
```

Then `/foo/bar/baz/blah` will resolve to `git+file:///foo/bar?dir=baz`

- If the supplied path is not a git repository, then the url will have the form
`path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
of the supplied path that contains a `flake.nix` file (within the same file-system).
If no such directory exists, then Nix will error-out.
For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
`path:/foo/bar`
- If the supplied path is not a git repository, then the url will have the form
`path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
of the supplied path that contains a `flake.nix` file (within the same file-system).
If no such directory exists, then Nix will error-out.

If *attrpath* is omitted, Nix tries some default values; for most
subcommands, the default is `packages.`*system*`.default`
(e.g. `packages.x86_64-linux.default`), but some subcommands have
other defaults. If *attrpath* *is* specified, *attrpath* is
interpreted as relative to one or more prefixes; for most
subcommands, these are `packages.`*system*,
`legacyPackages.*system*` and the empty prefix. Thus, on
`x86_64-linux` `nix build nixpkgs#hello` will try to build the
attributes `packages.x86_64-linux.hello`,
`legacyPackages.x86_64-linux.hello` and `hello`.
For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
`path:/foo/bar`

* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
If *attrpath* is omitted, Nix tries some default values; for most
subcommands, the default is `packages.`*system*`.default`
(e.g. `packages.x86_64-linux.default`), but some subcommands have
other defaults. If *attrpath* *is* specified, *attrpath* is
interpreted as relative to one or more prefixes; for most
subcommands, these are `packages.`*system*,
`legacyPackages.*system*` and the empty prefix. Thus, on
`x86_64-linux` `nix build nixpkgs#hello` will try to build the
attributes `packages.x86_64-linux.hello`,
`legacyPackages.x86_64-linux.hello` and `hello`.

These are paths inside the Nix store, or symlinks that resolve to a
path in the Nix store.
## Store paths

* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
Example: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`

By default, if you pass a [store derivation] path to a `nix` subcommand, the command will operate on the [output path]s of the derivation.
These are paths inside the Nix store, or symlinks that resolve to a
path in the Nix store.

[output path]: ../../glossary.md#gloss-output-path
## Store derivations

For example, `nix path-info` prints information about the output paths:
Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`

```console
# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
[{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
```
By default, if you pass a [store derivation] path to a `nix` subcommand, the command will operate on the [output path]s of the derivation.

If you want to operate on the store derivation itself, pass the
`--derivation` flag.
[output path]: ../../glossary.md#gloss-output-path

* **Nix attributes**: `--file /path/to/nixpkgs hello`
For example, `nix path-info` prints information about the output paths:

When the `-f` / `--file` *path* option is given, installables are
interpreted as attribute paths referencing a value returned by
evaluating the Nix file *path*.
```console
# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
[{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
```

* **Nix expressions**: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
If you want to operate on the store derivation itself, pass the
`--derivation` flag.

When the `--expr` option is given, all installables are interpreted
as Nix expressions. You may need to specify `--impure` if the
expression references impure inputs (such as `<nixpkgs>`).
## Nix attributes

For most commands, if no installable is specified, the default is `.`,
i.e. Nix will operate on the default flake output attribute of the
flake in the current directory.
Example: `--file /path/to/nixpkgs hello`

When the `-f` / `--file` *path* option is given, installables are
interpreted as attribute paths referencing a value returned by
evaluating the Nix file *path*.

## Nix expressions

Example: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.

When the `--expr` option is given, all installables are interpreted
as Nix expressions. You may need to specify `--impure` if the
expression references impure inputs (such as `<nixpkgs>`).

## Derivation output selection

Expand Down

0 comments on commit c1afdf0

Please sign in to comment.