nix-super/src/nix/nix.md

R""(

# Examples

* Create a new flake:

  ```console
  # nix flake new hello
  # cd hello
  ```

* Build the flake in the current directory:

  ```console
  # nix build
  # ./result/bin/hello
  Hello, world!
  ```

* Run the flake in the current directory:

  ```console
  # nix run
  Hello, world!
  ```

* Start a development shell for hacking on this flake:

  ```console
  # nix develop
  # unpackPhase
  # cd hello-*
  # configurePhase
  # buildPhase
  # ./hello
  Hello, world!
  # installPhase
  # ../outputs/out/bin/hello
  Hello, world!
  ```

# Description

Nix is a tool for building software, configurations and other
artifacts in a reproducible and declarative way. For more information,
see the [Nix homepage](https://nixos.org/) or the [Nix
manual](https://nixos.org/manual/nix/stable/).

# Installables

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
    ```

  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 *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`.

* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`

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

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

  Store derivations are store paths with extension `.drv` and are a
  low-level representation of a build-time dependency graph used
  internally by Nix. By default, if you pass a store derivation to a
  `nix` subcommand, it will operate on the *output paths* of the
  derivation. For example, `nix path-info` prints information about
  the output paths:

  ```console
  # nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
  [{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
  ```

  If you want to operate on the store derivation itself, pass the
  `--derivation` flag.

* **Nix attributes**: `--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**: `--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>`).

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.

## Derivation output selection

Derivations can have multiple outputs, each corresponding to a
different store path. For instance, a package can have a `bin` output
that contains programs, and a `dev` output that provides development
artifacts like C/C++ header files. The outputs on which `nix` commands
operate are determined as follows:

* You can explicitly specify the desired outputs using the syntax
  *installable*`^`*output1*`,`*...*`,`*outputN*. For example, you can
  obtain the `dev` and `static` outputs of the `glibc` package:

  ```console
  # nix build 'nixpkgs#glibc^dev,static'
  # ls ./result-dev/include/ ./result-static/lib/
  …
  ```

* You can also specify that *all* outputs should be used using the
  syntax *installable*`^*`. For example, the following shows the size
  of all outputs of the `glibc` package in the binary cache:

  ```console
  # nix path-info -S --eval-store auto --store https://cache.nixos.org 'nixpkgs#glibc^*'
  /nix/store/g02b1lpbddhymmcjb923kf0l7s9nww58-glibc-2.33-123                 33208200
  /nix/store/851dp95qqiisjifi639r0zzg5l465ny4-glibc-2.33-123-bin             36142896
  /nix/store/kdgs3q6r7xdff1p7a9hnjr43xw2404z7-glibc-2.33-123-debug          155787312
  /nix/store/n4xa8h6pbmqmwnq0mmsz08l38abb06zc-glibc-2.33-123-static          42488328
  /nix/store/q6580lr01jpcsqs4r5arlh4ki2c1m9rv-glibc-2.33-123-dev             44200560
  ```

* If you didn't specify the desired outputs, but the derivation has an
  attribute `meta.outputsToInstall`, Nix will use those outputs. For
  example, since the package `nixpkgs#libxml2` has this attribute:

  ```console
  # nix eval 'nixpkgs#libxml2.meta.outputsToInstall'
  [ "bin" "man" ]
  ```

  a command like `nix shell nixpkgs#libxml2` will provide only those
  two outputs by default.

* Otherwise, Nix will use all outputs of the derivation.

# Nix stores

Most `nix` subcommands operate on a *Nix store*.

TODO: list store types, options

)""