ref-manual: Added PACKAGE_DEBUG_SPLIT_STYLE variable.

Fixes [YOCTO #6621]

This is a new variable that helps control how debug symbols and
source files are split off when creating -dbg files for use with
GDB.

(From yocto-docs rev: 506b79707f6aec7c14f1f9d7e5099d20fca45c0e)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 56 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 7ea753df71..a4dbba4a3e 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -5722,6 +5722,62 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
+            <glossdef>
+
+                <para>
+                    Determines how to split up the binary and debug information
+                    when creating <filename>*-dbg</filename> packages to be
+                    used with the GNU Project Debugger (GDB).
+                </para>
+
+                <para>
+                    With the
+                    <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
+                    you can control where debug information, which can include
+                    or exclude source files, is stored:
+                    <itemizedlist>
+                        <listitem><para>
+                            ".debug": Debug symbol files are placed next
+                            to the binary in a <filename>.debug</filename>
+                            directory on the target.
+                            For example, if a binary is installed into
+                            <filename>/bin</filename>, the corresponding debug
+                            symbol files are installed in
+                            <filename>/bin/.debug</filename>.
+                            Source files are placed in
+                            <filename>/usr/src/debug</filename>.
+                            This is the default behavior.
+                            </para></listitem>
+                        <listitem><para>
+                            "debug-file-directory": Debug symbol files are
+                            placed under <filename>/usr/lib/debug</filename>
+                            on the target, and separated by the path from where
+                            the binary is installed.
+                            For example, if a binary is installed in
+                            <filename>/bin</filename>, the corresponding debug
+                            symbols are installed in
+                            <filename>/usr/lib/debug/bin</filename>.
+                            Source files are placed in
+                            <filename>/usr/src/debug</filename>.
+                            </para></listitem>
+                        <listitem><para>
+                            "debug-without-src": The same behavior as
+                            ".debug" previously described with the exception
+                            that no source files are installed.
+                            </para></listitem>.
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    You can find out more about debugging using GDB by reading
+                    the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
             <glossdef>
                 <para>