[PATCH] ref-manual: extend explanation of PACKAGE_DEBUG_SPLIT_STYLE

[PATCH] ref-manual: extend explanation of PACKAGE_DEBUG_SPLIT_STYLE

[Robert P. J. Day]

The current explanation of this variable seems incomplete, so be a
bit more verbose to make sure the reader understands the packaging
possibilities.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 5caada626..a46ea186e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5064,33 +5064,39 @@ system and gives an overview of their function and contents.
       ":ref:`package.bbclass <ref-classes-package>`" section.

    :term:`PACKAGE_DEBUG_SPLIT_STYLE`
-      Determines how to split up the binary and debug information when
-      creating ``*-dbg`` packages to be used with the GNU Project Debugger
-      (GDB).
-
-      With the :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable, you can control
-      where debug information, which can include or exclude source files,
-      is stored:
-
-      -  ".debug": Debug symbol files are placed next to the binary in a
-         ``.debug`` directory on the target. For example, if a binary is
-         installed into ``/bin``, the corresponding debug symbol files are
-         installed in ``/bin/.debug``. Source files are placed in
-         ``/usr/src/debug``.
-
-      -  "debug-file-directory": Debug symbol files are placed under
-         ``/usr/lib/debug`` on the target, and separated by the path from
-         where the binary is installed. For example, if a binary is
-         installed in ``/bin``, the corresponding debug symbols are
-         installed in ``/usr/lib/debug/bin``. Source files are placed in
-         ``/usr/src/debug``.
-
-      -  "debug-without-src": The same behavior as ".debug" previously
-         described with the exception that no source files are installed.
-
-      -  "debug-with-srcpkg": The same behavior as ".debug" previously
-         described with the exception that all source files are placed in a
-         separate ``*-src`` pkg. This is the default behavior.
+      Determines how to split up and package debug and source information
+      when creating debugging packages to be used with the GNU Project
+      Debugger (GDB). In general, based on the value of this variable,
+      you can combine the source and debug info in a single package,
+      you can break out the source into a separate package that can be
+      installed independently, or you can choose to not have the source
+      packaged at all.
+
+      The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
+
+      -  "``.debug``": All debugging and source info is placed in a single
+         ``*-dbg`` package; debug symbol files are placed next to the
+         binary in a ``.debug`` directory so that, if a binary is installed
+         into ``/bin``, the corresponding debug symbol file is installed
+         in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
+         package under ``/usr/src/debug``.
+
+      -  "``debug-file-directory``": As above, all debugging and source info
+         is placed in a single ``*-dbg`` package; debug symbol files are
+         placed entirely under the directory ``/usr/lib/debug`` and separated
+         by the path from where the binary is installed, so that if a binary
+         is installed in ``/bin``, the corresponding debug symbols are installed
+         in ``/usr/lib/debug/bin``, and so on. As above, source is installed
+         in the same package under ``/usr/src/debug``.
+
+      -  "``debug-with-srcpkg``": Debugging info is placed in the standard
+         ``*-dbg`` package as with the ``.debug`` value, while source is
+         placed in a separate ``*-src`` package, which can be installed
+         independently.  This is the default setting for this variable,
+         as defined in Poky's ``bitbake.conf`` file.
+
+      -  "``debug-without-src``": The same behavior as with the ``.debug``
+         setting, but no source is packaged at all.

       You can find out more about debugging using GDB by reading the
       ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                         http://crashcourse.ca

LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [docs] [PATCH] ref-manual: extend explanation of PACKAGE_DEBUG_SPLIT_STYLE

[Michael Opdenacker]

Hi Robert,

On 9/18/21 1:57 PM, Robert P. J. Day wrote:
> The current explanation of this variable seems incomplete, so be a
> bit more verbose to make sure the reader understands the packaging
> possibilities.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 5caada626..a46ea186e 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -5064,33 +5064,39 @@ system and gives an overview of their function and contents.
>        ":ref:`package.bbclass <ref-classes-package>`" section.
>
>     :term:`PACKAGE_DEBUG_SPLIT_STYLE`
> -      Determines how to split up the binary and debug information when
> -      creating ``*-dbg`` packages to be used with the GNU Project Debugger
> -      (GDB).
> -
> -      With the :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable, you can control
> -      where debug information, which can include or exclude source files,
> -      is stored:
> -
> -      -  ".debug": Debug symbol files are placed next to the binary in a
> -         ``.debug`` directory on the target. For example, if a binary is
> -         installed into ``/bin``, the corresponding debug symbol files are
> -         installed in ``/bin/.debug``. Source files are placed in
> -         ``/usr/src/debug``.
> -
> -      -  "debug-file-directory": Debug symbol files are placed under
> -         ``/usr/lib/debug`` on the target, and separated by the path from
> -         where the binary is installed. For example, if a binary is
> -         installed in ``/bin``, the corresponding debug symbols are
> -         installed in ``/usr/lib/debug/bin``. Source files are placed in
> -         ``/usr/src/debug``.
> -
> -      -  "debug-without-src": The same behavior as ".debug" previously
> -         described with the exception that no source files are installed.
> -
> -      -  "debug-with-srcpkg": The same behavior as ".debug" previously
> -         described with the exception that all source files are placed in a
> -         separate ``*-src`` pkg. This is the default behavior.
> +      Determines how to split up and package debug and source information
> +      when creating debugging packages to be used with the GNU Project
> +      Debugger (GDB). In general, based on the value of this variable,
> +      you can combine the source and debug info in a single package,
> +      you can break out the source into a separate package that can be
> +      installed independently, or you can choose to not have the source
> +      packaged at all.
> +
> +      The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
> +
> +      -  "``.debug``": All debugging and source info is placed in a single
> +         ``*-dbg`` package; debug symbol files are placed next to the
> +         binary in a ``.debug`` directory so that, if a binary is installed
> +         into ``/bin``, the corresponding debug symbol file is installed
> +         in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
> +         package under ``/usr/src/debug``.
> +
> +      -  "``debug-file-directory``": As above, all debugging and source info
> +         is placed in a single ``*-dbg`` package; debug symbol files are
> +         placed entirely under the directory ``/usr/lib/debug`` and separated
> +         by the path from where the binary is installed, so that if a binary
> +         is installed in ``/bin``, the corresponding debug symbols are installed
> +         in ``/usr/lib/debug/bin``, and so on. As above, source is installed
> +         in the same package under ``/usr/src/debug``.
> +
> +      -  "``debug-with-srcpkg``": Debugging info is placed in the standard
> +         ``*-dbg`` package as with the ``.debug`` value, while source is
> +         placed in a separate ``*-src`` package, which can be installed
> +         independently.  This is the default setting for this variable,
> +         as defined in Poky's ``bitbake.conf`` file.
> +
> +      -  "``debug-without-src``": The same behavior as with the ``.debug``
> +         setting, but no source is packaged at all.
>
>        You can find out more about debugging using GDB by reading the
>        ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section


Many thanks for the patch. I agree this clarifies the explanations.
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> ... and
merged in "master-next".

By the way, what about submitting a patch to
https://git.openembedded.org/openembedded-core/tree/meta/conf/local.conf.sample.extended
too, to mention "debug-with-srcpkg" and "debug-without-src" too?

Thanks again,

Cheers,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] ref-manual: extend explanation of PACKAGE_DEBUG_SPLIT_STYLE

[Robert P. J. Day]

On Tue, 21 Sep 2021, Michael Opdenacker wrote:

> Hi Robert,
>
> On 9/18/21 1:57 PM, Robert P. J. Day wrote:
> > The current explanation of this variable seems incomplete, so be a
> > bit more verbose to make sure the reader understands the packaging
> > possibilities.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index 5caada626..a46ea186e 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -5064,33 +5064,39 @@ system and gives an overview of their function and contents.
> >        ":ref:`package.bbclass <ref-classes-package>`" section.
> >
> >     :term:`PACKAGE_DEBUG_SPLIT_STYLE`
> > -      Determines how to split up the binary and debug information when
> > -      creating ``*-dbg`` packages to be used with the GNU Project Debugger
> > -      (GDB).
> > -
> > -      With the :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable, you can control
> > -      where debug information, which can include or exclude source files,
> > -      is stored:
> > -
> > -      -  ".debug": Debug symbol files are placed next to the binary in a
> > -         ``.debug`` directory on the target. For example, if a binary is
> > -         installed into ``/bin``, the corresponding debug symbol files are
> > -         installed in ``/bin/.debug``. Source files are placed in
> > -         ``/usr/src/debug``.
> > -
> > -      -  "debug-file-directory": Debug symbol files are placed under
> > -         ``/usr/lib/debug`` on the target, and separated by the path from
> > -         where the binary is installed. For example, if a binary is
> > -         installed in ``/bin``, the corresponding debug symbols are
> > -         installed in ``/usr/lib/debug/bin``. Source files are placed in
> > -         ``/usr/src/debug``.
> > -
> > -      -  "debug-without-src": The same behavior as ".debug" previously
> > -         described with the exception that no source files are installed.
> > -
> > -      -  "debug-with-srcpkg": The same behavior as ".debug" previously
> > -         described with the exception that all source files are placed in a
> > -         separate ``*-src`` pkg. This is the default behavior.
> > +      Determines how to split up and package debug and source information
> > +      when creating debugging packages to be used with the GNU Project
> > +      Debugger (GDB). In general, based on the value of this variable,
> > +      you can combine the source and debug info in a single package,
> > +      you can break out the source into a separate package that can be
> > +      installed independently, or you can choose to not have the source
> > +      packaged at all.
> > +
> > +      The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
> > +
> > +      -  "``.debug``": All debugging and source info is placed in a single
> > +         ``*-dbg`` package; debug symbol files are placed next to the
> > +         binary in a ``.debug`` directory so that, if a binary is installed
> > +         into ``/bin``, the corresponding debug symbol file is installed
> > +         in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
> > +         package under ``/usr/src/debug``.
> > +
> > +      -  "``debug-file-directory``": As above, all debugging and source info
> > +         is placed in a single ``*-dbg`` package; debug symbol files are
> > +         placed entirely under the directory ``/usr/lib/debug`` and separated
> > +         by the path from where the binary is installed, so that if a binary
> > +         is installed in ``/bin``, the corresponding debug symbols are installed
> > +         in ``/usr/lib/debug/bin``, and so on. As above, source is installed
> > +         in the same package under ``/usr/src/debug``.
> > +
> > +      -  "``debug-with-srcpkg``": Debugging info is placed in the standard
> > +         ``*-dbg`` package as with the ``.debug`` value, while source is
> > +         placed in a separate ``*-src`` package, which can be installed
> > +         independently.  This is the default setting for this variable,
> > +         as defined in Poky's ``bitbake.conf`` file.
> > +
> > +      -  "``debug-without-src``": The same behavior as with the ``.debug``
> > +         setting, but no source is packaged at all.
> >
> >        You can find out more about debugging using GDB by reading the
> >        ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section
>
>
> Many thanks for the patch. I agree this clarifies the explanations.
> Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> ... and
> merged in "master-next".
>
> By the way, what about submitting a patch to
> https://git.openembedded.org/openembedded-core/tree/meta/conf/local.conf.sample.extended
> too, to mention "debug-with-srcpkg" and "debug-without-src" too?

  can i get some consensus that the above explanation actually matches
what happens?

rday