If set to `true`, the standard environment will enable debug information in C/C++ builds. After installation, the debug information will be separated from the executables and stored in the output named `debug`. (This output is enabled automatically; you don’t need to set the `outputs` attribute explicitly.) To be precise, the debug information is stored in `debug/lib/debug/.build-id/XX/YYYY…`, where \<XXYYYY…\> is the \<build ID\> of the binary — a SHA-1 hash of the contents of the binary. Debuggers like GDB use the build ID to look up the separated debug information.

:::{.example #ex-gdb-debug-symbols-socat}

# Enable debug symbols for use with GDB

To make GDB find debug information for the `socat` package and its dependencies, you can use the following `shell.nix`:

```nix
{
  pkgs ? import <nixpkgs> {
    config = { };
    overlays = [
      (final: prev: {
        ncurses = prev.ncurses.overrideAttrs { separateDebugInfo = true; };
        readline = prev.readline.overrideAttrs { separateDebugInfo = true; };
      })
    ];
  },
}:
pkgs.mkShell {
  NIX_DEBUG_INFO_DIRS = pkgs.lib.makeSearchPathOutput "debug" "lib/debug" [
    pkgs.glibc
    pkgs.ncurses
    pkgs.openssl
    pkgs.readline
  ];

  packages = [
    pkgs.gdb
    pkgs.socat
  ];

  shellHook = ''
    gdb socat
  '';
}
```

This setup works as follows:
- Add [`overlays`](#chap-overlays) to the package set, since debug symbols are disabled for `ncurses` and `readline` by default.
- Set the environment variable `NIX_DEBUG_INFO_DIRS` in the shell. Nixpkgs patches `gdb` to use this variable for looking up debug symbols.
  [`lib.makeSearchPathOutput`](#function-library-lib.strings.makeSearchPathOutput) constructs a colon-separated search path, pointing to the directories containing the debug symbols of the listed packages.
- Run `gdb` on the `socat` binary on shell startup in the [`shellHook`](#sec-pkgs-mkShell).

:::

### The installCheck phase {#ssec-installCheck-phase}

The installCheck phase checks whether the package was installed correctly by running its test suite against the installed directories. The default `installCheck` calls `make installcheck`.

It is often better to add tests that are not part of the source distribution to `passthru.tests` (see
[](#var-passthru-tests)). This avoids adding overhead to every build and enables us to run them independently.

#### Variables controlling the installCheck phase {#variables-controlling-the-installcheck-phase}

##### `doInstallCheck` {#var-stdenv-doInstallCheck}

Controls whether the installCheck phase is executed. By default it is skipped, but if `doInstallCheck` is set to true, the installCheck phase is usually executed. Thus you should set

```nix
{ doInstallCheck = true; }
```

in the derivation to enable install checks. The exception is cross compilation. Cross compiled builds never run tests, no matter how `doInstallCheck` is set, as the newly-built program won’t run on the platform used to build it.

##### `installCheckTarget` {#var-stdenv-installCheckTarget}

The make target that runs the install tests. Defaults to `installcheck`.

##### `installCheckFlags` / `installCheckFlagsArray` {#var-stdenv-installCheckFlags}

A list of strings passed as additional flags to `make`. Like `makeFlags` and `makeFlagsArray`, but only used by the installCheck phase.

##### `installCheckInputs` {#var-stdenv-installCheckInputs}

A list of host dependencies used by the phase, usually libraries linked into executables built during tests. This gets included in `buildInputs` when `doInstallCheck` is set.

##### `nativeInstallCheckInputs` {#var-stdenv-nativeInstallCheckInputs}

A list of native dependencies used by the phase, notably tools needed on `$PATH`. This gets included in `nativeBuildInputs` when `doInstallCheck` is set.

##### `preInstallCheck` {#var-stdenv-preInstallCheck}

Hook executed at the start of the installCheck phase.

##### `postInstallCheck` {#var-stdenv-postInstallCheck}

Hook executed at the end of the installCheck phase.