From ec5b66eb4add9d494d8fb16f6899028750d317a2 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Thu, 17 Sep 2015 15:24:32 +0200
Subject: Enable separate debug info

You can now pass

  separateDebugInfo = true;

to mkDerivation. This causes debug info to be separated from ELF
binaries and stored in the "debug" output. The advantage is that it
enables installing lean binaries, while still having the ability to
make sense of core dumps, etc.
---
 doc/stdenv.xml | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

(limited to 'doc')

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 1556ffd057f9..7ba24db2e050 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -899,6 +899,34 @@ following:
     phase.</para></listitem>
   </varlistentry>
 
+  <varlistentry>
+    <term><varname>separateDebugInfo</varname></term>
+    <listitem><para>If set to <literal>true</literal>, 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
+    <literal>debug</literal>. (This output is enabled automatically;
+    you don’t need to set the <varname>outputs</varname> attribute
+    explicitly.) To be precise, the debug information is stored in
+    <filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>,
+    where <replaceable>XXYYYY…</replaceable> is the <replaceable>build
+    ID</replaceable> 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.</para>
+
+    <para>For example, with GDB, you can add
+
+<programlisting>
+set debug-file-directory ~/.nix-profile/lib/debug
+</programlisting>
+
+    to <filename>~/.gdbinit</filename>. GDB will then be able to find
+    debug information installed via <literal>nix-env
+    -i</literal>.</para>
+
+    </listitem>
+  </varlistentry>
+
 </variablelist>
 
 </section>
-- 
cgit 1.4.1