[OE-core,4/4] dev-manual/common-tasks.rst: correct the documentation for debuginfod

Submitted by Richard Purdie on April 19, 2021, 10:11 a.m. | Patch ID: 179664

Details

Message ID 8b2212544d8f565c7343a88d837c8c6f390e82e8.camel@linuxfoundation.org
State New
Headers show

Commit Message

Richard Purdie April 19, 2021, 10:11 a.m.
Forwarded from OE-Core to ensure docs people see it.

Cheers,

Richard
Particularly,
- correctly describe the use of DEBUGINFOD_URLS; drop it from bitbake variables
- all necessary component tweaks are enabled by default via DISTRO_FEATURES
- provide on-target examples of what to look for when things work properly

Signed-off-by: Alexander Kanavin <alex.kanavin@gmail.com>
---
 documentation/dev-manual/common-tasks.rst | 34 +++++++++++++++--------
 documentation/ref-manual/variables.rst    |  6 ----
 2 files changed, 22 insertions(+), 18 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 176025f9e8..9f33b6b2c8 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -10005,34 +10005,44 @@  debug symbols from the server.
 
 To run a debuginfod server, you need to do the following:
 
--  Ensure that this variable is set in your ``local.conf`` file:
+-  Ensure that "debuginfod" is present in :term:`DISTRO_FEATURES
+   (it already is in oe-core defaults and poky reference distribution).
+   If not, set:
    ::
 
-      PACKAGECONFIG_pn-elfutils-native = "debuginfod libdebuginfod"
+      DISTRO_FEATURES_append = " debuginfod"
 
-   This :term:`PACKAGECONFIG` option enables debuginfod and libdebuginfod for
-   "elfutils-native".
+   This distro feature enables the server and client library in elfutils,
+   and enables debuginfod support in clients (at the moment, gdb and binutils).
 
--  Run the following commands to set up the "debuginfod" server:
+-  Run the following commands to launch the "debuginfod" server on the host:
    ::
 
       $ oe-debuginfod
 
+-  To use debuginfod on the target, you need to know the ip:port where
+   debuginfod is listening on the host (port defaults to 8002), and export
+   that into the shell environment, for example in qemu:
+   ::
 
-To use debuginfod on the target, you need the following:
+      root@qemux86-64:~# export DEBUGINFOD_URLS="http://192.168.7.1:8002/"
 
--  Ensure that this variable is set in your ``local.conf`` file:
+-  Then debug info fetching should simply work when running the target gdb,
+   readelf or objdump, for example:
    ::
 
-      DEBUGINFOD_URLS = "http://localhost:8002/"
-
-   This :term:`DEBUGINFOD_URLS` option does the client configuration.
+      root@qemux86-64:~# gdb /bin/cat
+      ...
+      Reading symbols from /bin/cat...
+      Downloading separate debug info for /bin/cat...
+      Reading symbols from /home/root/.cache/debuginfod_client/923dc4780cfbc545850c616bffa884b6b5eaf322/debuginfo...
 
+-  It's also possible to use "debuginfod-find" to just query the server:
    ::
 
-        PACKAGECONFIG_pn-gdb = "debuginfod"
+      root@qemux86-64:~# debuginfod-find debuginfo /bin/ls
+      /home/root/.cache/debuginfod_client/356edc585f7f82d46f94fcb87a86a3fe2d2e60bd/debuginfo
 
-   This :term:`PACKAGECONFIG` option enables "debuginfod" for "gdb".
 
 Using the gdbserver method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 74ac12bf98..8a35b0960e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1563,12 +1563,6 @@  system and gives an overview of their function and contents.
 
          DEBIANNAME_${PN} = "dbus-1"
 
-   :term:`DEBUGINFOD_URLS`
-      Points to the URL of the "debuginfod" server. Such that for every
-      debugging information lookup, the debuginfod client will query the
-      server and return the requested information. You set this variable
-      in your ``local.conf`` file.
-
    :term:`DEBUG_BUILD`
       Specifies to build packages with debugging information. This
       influences the value of the ``SELECTED_OPTIMIZATION`` variable.

Comments

Quentin Schulz April 19, 2021, 10:33 a.m.
Hi all,

On Mon, Apr 19, 2021 at 11:11:21AM +0100, Richard Purdie wrote:
> Forwarded from OE-Core to ensure docs people see it.
> 
> Cheers,
> 
> Richard

> Date: Mon, 19 Apr 2021 11:00:44 +0200
> From: Alexander Kanavin <alex.kanavin@gmail.com>
> To: openembedded-core@lists.openembedded.org
> Cc: Alexander Kanavin <alex.kanavin@gmail.com>
> Subject: [OE-core] [PATCH 4/4] dev-manual/common-tasks.rst: correct the
>  documentation for debuginfod
> 
> Particularly,
> - correctly describe the use of DEBUGINFOD_URLS; drop it from bitbake variables
> - all necessary component tweaks are enabled by default via DISTRO_FEATURES
> - provide on-target examples of what to look for when things work properly
> 
> Signed-off-by: Alexander Kanavin <alex.kanavin@gmail.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 34 +++++++++++++++--------
>  documentation/ref-manual/variables.rst    |  6 ----
>  2 files changed, 22 insertions(+), 18 deletions(-)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 176025f9e8..9f33b6b2c8 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -10005,34 +10005,44 @@ debug symbols from the server.
>  
>  To run a debuginfod server, you need to do the following:
>  
> --  Ensure that this variable is set in your ``local.conf`` file:
> +-  Ensure that "debuginfod" is present in :term:`DISTRO_FEATURES

Missing trailing `.

> +   (it already is in oe-core defaults and poky reference distribution).

s/oe-core/``OpenEmbedded-core/ ?
s/poky/``poky``/ ?

> +   If not, set:
>     ::
>  
> -      PACKAGECONFIG_pn-elfutils-native = "debuginfod libdebuginfod"
> +      DISTRO_FEATURES_append = " debuginfod"
>  
> -   This :term:`PACKAGECONFIG` option enables debuginfod and libdebuginfod for
> -   "elfutils-native".
> +   This distro feature enables the server and client library in elfutils,

s/elfutils/``elfutils``/ ?

> +   and enables debuginfod support in clients (at the moment, gdb and binutils).
>  

s/debuginfod/``debuginfod``/ ?
s/gdb/``gdb``/ ?
s/binutils/``binutils``/ ?

> --  Run the following commands to set up the "debuginfod" server:
> +-  Run the following commands to launch the "debuginfod" server on the host:

s/"debuginfod"/``debuginfod``/ ?

>     ::
>  
>        $ oe-debuginfod
>  
> +-  To use debuginfod on the target, you need to know the ip:port where
> +   debuginfod is listening on the host (port defaults to 8002), and export

s/debuginfod/``debuginfod``/ for both debuginfod?

> +   that into the shell environment, for example in qemu:

s/qemu/``qemu``/ ?

> +   ::
>  

It should be:

that into the shell environment, for example in qemu::

instead.

> -To use debuginfod on the target, you need the following:
> +      root@qemux86-64:~# export DEBUGINFOD_URLS="http://192.168.7.1:8002/"
>  
> --  Ensure that this variable is set in your ``local.conf`` file:
> +-  Then debug info fetching should simply work when running the target gdb,

s/gdb/``gdb``/ ?

> +   readelf or objdump, for example:

s/readelf/``readelf``/ ?
s/objdump/``objdump``/ ?

>     ::
>  

It should be:

readelf or objdump, for example::

instead.

> -      DEBUGINFOD_URLS = "http://localhost:8002/"
> -
> -   This :term:`DEBUGINFOD_URLS` option does the client configuration.
> +      root@qemux86-64:~# gdb /bin/cat
> +      ...
> +      Reading symbols from /bin/cat...
> +      Downloading separate debug info for /bin/cat...
> +      Reading symbols from /home/root/.cache/debuginfod_client/923dc4780cfbc545850c616bffa884b6b5eaf322/debuginfo...
>  
> +-  It's also possible to use "debuginfod-find" to just query the server:

s/"debuginfod-find"/``debuginfod-find``/ ?

>     ::
>  

It should be:

It's also possible to use "debuginfod-find" to just query the server::

instead.

Cheers,
Quentin
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1127): https://lists.yoctoproject.org/g/docs/message/1127
Mute This Topic: https://lists.yoctoproject.org/mt/82204968/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Alexander Kanavin April 19, 2021, 12:39 p.m.
Thank you, I will fix these up and resend. Is docs@ the right destination
for patches to documentation/ ?

Alex

On Mon, 19 Apr 2021 at 12:33, Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> Hi all,
>
> On Mon, Apr 19, 2021 at 11:11:21AM +0100, Richard Purdie wrote:
> > Forwarded from OE-Core to ensure docs people see it.
> >
> > Cheers,
> >
> > Richard
>
> > Date: Mon, 19 Apr 2021 11:00:44 +0200
> > From: Alexander Kanavin <alex.kanavin@gmail.com>
> > To: openembedded-core@lists.openembedded.org
> > Cc: Alexander Kanavin <alex.kanavin@gmail.com>
> > Subject: [OE-core] [PATCH 4/4] dev-manual/common-tasks.rst: correct the
> >  documentation for debuginfod
> >
> > Particularly,
> > - correctly describe the use of DEBUGINFOD_URLS; drop it from bitbake
> variables
> > - all necessary component tweaks are enabled by default via
> DISTRO_FEATURES
> > - provide on-target examples of what to look for when things work
> properly
> >
> > Signed-off-by: Alexander Kanavin <alex.kanavin@gmail.com>
> > ---
> >  documentation/dev-manual/common-tasks.rst | 34 +++++++++++++++--------
> >  documentation/ref-manual/variables.rst    |  6 ----
> >  2 files changed, 22 insertions(+), 18 deletions(-)
> >
> > diff --git a/documentation/dev-manual/common-tasks.rst
> b/documentation/dev-manual/common-tasks.rst
> > index 176025f9e8..9f33b6b2c8 100644
> > --- a/documentation/dev-manual/common-tasks.rst
> > +++ b/documentation/dev-manual/common-tasks.rst
> > @@ -10005,34 +10005,44 @@ debug symbols from the server.
> >
> >  To run a debuginfod server, you need to do the following:
> >
> > --  Ensure that this variable is set in your ``local.conf`` file:
> > +-  Ensure that "debuginfod" is present in :term:`DISTRO_FEATURES
>
> Missing trailing `.
>
> > +   (it already is in oe-core defaults and poky reference distribution).
>
> s/oe-core/``OpenEmbedded-core/ ?
> s/poky/``poky``/ ?
>
> > +   If not, set:
> >     ::
> >
> > -      PACKAGECONFIG_pn-elfutils-native = "debuginfod libdebuginfod"
> > +      DISTRO_FEATURES_append = " debuginfod"
> >
> > -   This :term:`PACKAGECONFIG` option enables debuginfod and
> libdebuginfod for
> > -   "elfutils-native".
> > +   This distro feature enables the server and client library in
> elfutils,
>
> s/elfutils/``elfutils``/ ?
>
> > +   and enables debuginfod support in clients (at the moment, gdb and
> binutils).
> >
>
> s/debuginfod/``debuginfod``/ ?
> s/gdb/``gdb``/ ?
> s/binutils/``binutils``/ ?
>
> > --  Run the following commands to set up the "debuginfod" server:
> > +-  Run the following commands to launch the "debuginfod" server on the
> host:
>
> s/"debuginfod"/``debuginfod``/ ?
>
> >     ::
> >
> >        $ oe-debuginfod
> >
> > +-  To use debuginfod on the target, you need to know the ip:port where
> > +   debuginfod is listening on the host (port defaults to 8002), and
> export
>
> s/debuginfod/``debuginfod``/ for both debuginfod?
>
> > +   that into the shell environment, for example in qemu:
>
> s/qemu/``qemu``/ ?
>
> > +   ::
> >
>
> It should be:
>
> that into the shell environment, for example in qemu::
>
> instead.
>
> > -To use debuginfod on the target, you need the following:
> > +      root@qemux86-64:~# export DEBUGINFOD_URLS="
> http://192.168.7.1:8002/"
> >
> > --  Ensure that this variable is set in your ``local.conf`` file:
> > +-  Then debug info fetching should simply work when running the target
> gdb,
>
> s/gdb/``gdb``/ ?
>
> > +   readelf or objdump, for example:
>
> s/readelf/``readelf``/ ?
> s/objdump/``objdump``/ ?
>
> >     ::
> >
>
> It should be:
>
> readelf or objdump, for example::
>
> instead.
>
> > -      DEBUGINFOD_URLS = "http://localhost:8002/"
> > -
> > -   This :term:`DEBUGINFOD_URLS` option does the client configuration.
> > +      root@qemux86-64:~# gdb /bin/cat
> > +      ...
> > +      Reading symbols from /bin/cat...
> > +      Downloading separate debug info for /bin/cat...
> > +      Reading symbols from
> /home/root/.cache/debuginfod_client/923dc4780cfbc545850c616bffa884b6b5eaf322/debuginfo...
> >
> > +-  It's also possible to use "debuginfod-find" to just query the server:
>
> s/"debuginfod-find"/``debuginfod-find``/ ?
>
> >     ::
> >
>
> It should be:
>
> It's also possible to use "debuginfod-find" to just query the server::
>
> instead.
>
> Cheers,
> Quentin
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1128): https://lists.yoctoproject.org/g/docs/message/1128
Mute This Topic: https://lists.yoctoproject.org/mt/82204968/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Quentin Schulz April 19, 2021, 12:52 p.m.
Hi Alex,

On Mon, Apr 19, 2021 at 02:39:00PM +0200, Alexander Kanavin wrote:
> Thank you, I will fix these up and resend. Is docs@ the right destination
> for patches to documentation/ ?
> 

Yes, as far as my understanding goes, documentation/ in poky is handled
the same way as e.g. meta layer (which comes from openembedded-core).
So, the actual git repo/branch to base your patch against is:
https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs branch master
or master-next if there are conflicts not straightforward to fix.

There, you can read
https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/README to
know how to contribute and
https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/documentation/README
to know a bit more about what's what and the rules (until we get a
CONTRIBUTING or GUIDELINES or whatever file to explain the implicit
rules).

Let us know if there's anything that needs clarification or if you need
help!

Cheers,
Quentin

> Alex
> 
> On Mon, 19 Apr 2021 at 12:33, Quentin Schulz <
> quentin.schulz@streamunlimited.com> wrote:
> 
> > Hi all,
> >
> > On Mon, Apr 19, 2021 at 11:11:21AM +0100, Richard Purdie wrote:
> > > Forwarded from OE-Core to ensure docs people see it.
> > >
> > > Cheers,
> > >
> > > Richard
> >
> > > Date: Mon, 19 Apr 2021 11:00:44 +0200
> > > From: Alexander Kanavin <alex.kanavin@gmail.com>
> > > To: openembedded-core@lists.openembedded.org
> > > Cc: Alexander Kanavin <alex.kanavin@gmail.com>
> > > Subject: [OE-core] [PATCH 4/4] dev-manual/common-tasks.rst: correct the
> > >  documentation for debuginfod
> > >
> > > Particularly,
> > > - correctly describe the use of DEBUGINFOD_URLS; drop it from bitbake
> > variables
> > > - all necessary component tweaks are enabled by default via
> > DISTRO_FEATURES
> > > - provide on-target examples of what to look for when things work
> > properly
> > >
> > > Signed-off-by: Alexander Kanavin <alex.kanavin@gmail.com>
> > > ---
> > >  documentation/dev-manual/common-tasks.rst | 34 +++++++++++++++--------
> > >  documentation/ref-manual/variables.rst    |  6 ----
> > >  2 files changed, 22 insertions(+), 18 deletions(-)
> > >
> > > diff --git a/documentation/dev-manual/common-tasks.rst
> > b/documentation/dev-manual/common-tasks.rst
> > > index 176025f9e8..9f33b6b2c8 100644
> > > --- a/documentation/dev-manual/common-tasks.rst
> > > +++ b/documentation/dev-manual/common-tasks.rst
> > > @@ -10005,34 +10005,44 @@ debug symbols from the server.
> > >
> > >  To run a debuginfod server, you need to do the following:
> > >
> > > --  Ensure that this variable is set in your ``local.conf`` file:
> > > +-  Ensure that "debuginfod" is present in :term:`DISTRO_FEATURES
> >
> > Missing trailing `.
> >
> > > +   (it already is in oe-core defaults and poky reference distribution).
> >
> > s/oe-core/``OpenEmbedded-core/ ?
> > s/poky/``poky``/ ?
> >
> > > +   If not, set:
> > >     ::
> > >
> > > -      PACKAGECONFIG_pn-elfutils-native = "debuginfod libdebuginfod"
> > > +      DISTRO_FEATURES_append = " debuginfod"
> > >
> > > -   This :term:`PACKAGECONFIG` option enables debuginfod and
> > libdebuginfod for
> > > -   "elfutils-native".
> > > +   This distro feature enables the server and client library in
> > elfutils,
> >
> > s/elfutils/``elfutils``/ ?
> >
> > > +   and enables debuginfod support in clients (at the moment, gdb and
> > binutils).
> > >
> >
> > s/debuginfod/``debuginfod``/ ?
> > s/gdb/``gdb``/ ?
> > s/binutils/``binutils``/ ?
> >
> > > --  Run the following commands to set up the "debuginfod" server:
> > > +-  Run the following commands to launch the "debuginfod" server on the
> > host:
> >
> > s/"debuginfod"/``debuginfod``/ ?
> >
> > >     ::
> > >
> > >        $ oe-debuginfod
> > >
> > > +-  To use debuginfod on the target, you need to know the ip:port where
> > > +   debuginfod is listening on the host (port defaults to 8002), and
> > export
> >
> > s/debuginfod/``debuginfod``/ for both debuginfod?
> >
> > > +   that into the shell environment, for example in qemu:
> >
> > s/qemu/``qemu``/ ?
> >
> > > +   ::
> > >
> >
> > It should be:
> >
> > that into the shell environment, for example in qemu::
> >
> > instead.
> >
> > > -To use debuginfod on the target, you need the following:
> > > +      root@qemux86-64:~# export DEBUGINFOD_URLS="
> > http://192.168.7.1:8002/"
> > >
> > > --  Ensure that this variable is set in your ``local.conf`` file:
> > > +-  Then debug info fetching should simply work when running the target
> > gdb,
> >
> > s/gdb/``gdb``/ ?
> >
> > > +   readelf or objdump, for example:
> >
> > s/readelf/``readelf``/ ?
> > s/objdump/``objdump``/ ?
> >
> > >     ::
> > >
> >
> > It should be:
> >
> > readelf or objdump, for example::
> >
> > instead.
> >
> > > -      DEBUGINFOD_URLS = "http://localhost:8002/"
> > > -
> > > -   This :term:`DEBUGINFOD_URLS` option does the client configuration.
> > > +      root@qemux86-64:~# gdb /bin/cat
> > > +      ...
> > > +      Reading symbols from /bin/cat...
> > > +      Downloading separate debug info for /bin/cat...
> > > +      Reading symbols from
> > /home/root/.cache/debuginfod_client/923dc4780cfbc545850c616bffa884b6b5eaf322/debuginfo...
> > >
> > > +-  It's also possible to use "debuginfod-find" to just query the server:
> >
> > s/"debuginfod-find"/``debuginfod-find``/ ?
> >
> > >     ::
> > >
> >
> > It should be:
> >
> > It's also possible to use "debuginfod-find" to just query the server::
> >
> > instead.
> >
> > Cheers,
> > Quentin
> >

> 
> 
>