Unverified Commit cbd17485 authored by Alejandro Sánchez Medina's avatar Alejandro Sánchez Medina Committed by GitHub
Browse files

nixpkgs manual: add an alternative example in stdenv-separateDebugInfo (#257861) 



* nixpkgs manual: add an alternative example in stdenv-separateDebugInfo

This change gets rid of the indirect reference to `nix-env -i` usage
and shows how to achieve the same goal with a shell expression.

Co-authored-by: default avatarValentin Gagarin <valentin.gagarin@tweag.io>
parent d4df1448

doc/stdenv/stdenv.chapter.md

+47 −4
Original line number Diff line number Diff line
@@ -991,13 +991,56 @@ Hook executed at the end of the fixup phase. 


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.



For example, with GDB, you can add

:::{.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

let

  pkgs = import ./. {

    config = {};

    overlays = [

      (final: prev: {

        ncurses = prev.ncurses.overrideAttrs { separateDebugInfo = true; };

        readline = prev.readline.overrideAttrs { separateDebugInfo = true; };

      })

    ];

  };



  myDebugInfoDirs = pkgs.symlinkJoin {

    name = "myDebugInfoDirs";

    paths = with pkgs; [

      glibc.debug

      ncurses.debug

      openssl.debug

      readline.debug

    ];

  };

in

  pkgs.mkShell {



    NIX_DEBUG_INFO_DIRS = "${pkgs.lib.getLib myDebugInfoDirs}/lib/debug";



    packages = [

      pkgs.gdb

      pkgs.socat

    ];



    shellHook = ''

      ${pkgs.lib.getBin pkgs.gdb}/bin/gdb ${pkgs.lib.getBin pkgs.socat}/bin/socat

    '';

  }

```

set debug-file-directory ~/.nix-profile/lib/debug

```



to `~/.gdbinit`. GDB will then be able to find debug information installed via `nix-env -i`.

This setup works as follows:

- Add [`overlays`](#chap-overlays) to the package set, since debug symbols are disabled for `ncurses` and `readline` by default.

- Create a derivation to combine all required debug symbols under one path with [`symlinkJoin`](#trivial-builder-symlinkJoin).

- Set the environment variable `NIX_DEBUG_INFO_DIRS` in the shell. Nixpkgs patches `gdb` to use it for looking up debug symbols.

- Run `gdb` on the `socat` binary on shell startup in the [`shellHook`](#sec-pkgs-mkShell). Here we use [`lib.getBin`](#function-library-lib.attrsets.getBin) to ensure that the correct derivation output is selected rather than the default one.



:::



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