Questions regarding debuginfod.h API

Questions regarding debuginfod.h API

[Milian Wolff]

Hey all,

now that archlinux is supporting debuginfod, I have finally tried it out. It's 
such a game changer, many thanks for everyone involved in working on this!

Now to my question: In applications using elfutils, we will now automatically 
download debug information when DEBUGINFOD_URLS is defined. But doing that can 
take a very long time. I would like to give the user feedback about this 
situation and ideally provide a means to cancel the download.

Looking at `debuginfod.h` I `debuginfod_set_progressfn` which looks ideal. But 
how do I access the default `debuginfod_client *` which seems to exist without 
me ever calling `debuginfod_begin` anywhere? Or do I need to create a new 
client here via `debuginfod_begin`?

Then, how would I cancel an ongoing download job? GDB seems to do that when I 
press `CTRL+C`, but I do not see any API I could use for that purpose?

Finally, what is the recommended way to check whether debuginfod is available? 
Should one rely on the build system to discover the `debuginfod.h` header 
file, or is some other compile time check suggested to detect it? I'm asking, 
because while I want to add the above API to get a better debuginfod 
experience, I do not necessarily want to raise the minimum elfutils version 
requirement just for that purpose.

Many thanks again!
-- 
Milian Wolff
http://milianw.de

Re: Questions regarding debuginfod.h API

[Frank Ch. Eigler]

Hi -

> now that archlinux is supporting debuginfod, I have finally tried it
> out. It's such a game changer, many thanks for everyone involved in
> working on this!

Our pleasure!

> Now to my question: In applications using elfutils, we will now
> automatically download debug information when DEBUGINFOD_URLS is
> defined. But doing that can take a very long time. 

(See also the DEBUGINFOD_MAXTIME and DEBUGINFOD_MAXSIZE env vars
that can limit this.)

> I would like to give the user feedback about this situation and
> ideally provide a means to cancel the download.

OK.

> Looking at `debuginfod.h` I `debuginfod_set_progressfn` which looks
> ideal. But how do I access the default `debuginfod_client *` which
> seems to exist without me ever calling `debuginfod_begin` anywhere?
> Or do I need to create a new client here via `debuginfod_begin`?

You do need to create a new client object.  You can reuse it.

> Then, how would I cancel an ongoing download job? GDB seems to do
> that when I press `CTRL+C`, but I do not see any API I could use for
> that purpose?

See [man debuginfod_set_progressfn].  The return code from that
progressfn callback is the ticket.


> Finally, what is the recommended way to check whether debuginfod is
> available?  Should one rely on the build system to discover the
> `debuginfod.h` header file, or is some other compile time check
> suggested to detect it?  [...]

To decide whether or not to compile in support, you'd need a
compile-time check such as for the debuginfod.h header.  (Alternately,
you could opt not to compile in support at all, and instead call out
to the debuginfod-find(1) program.)  To decide at run time whether or
not to use it, you could just use the *_find APIs and get back an
error code if things are not set up.  Or you can check the
DEBUGINFOD_URLS for being set/unset before you call in.


- FChE

Re: Questions regarding debuginfod.h API

[Milian Wolff]

[-- Attachment #1: Type: text/plain, Size: 3849 bytes --]

On Freitag, 8. April 2022 15:44:32 CEST Frank Ch. Eigler wrote:
> Hi -

<snip>

> > Now to my question: In applications using elfutils, we will now
> > automatically download debug information when DEBUGINFOD_URLS is
> > defined. But doing that can take a very long time.
> 
> (See also the DEBUGINFOD_MAXTIME and DEBUGINFOD_MAXSIZE env vars
> that can limit this.)

I did come across those, but what are suggested best practices in setting 
those? When using GDB or a profiler on larger non-trivial UI applications on 
Linux for the first time, we would start to download dozens of debug packages, 
taking hundreds of megabytes of space. This simply takes time (in total), 
whereas the two environment variables above would be per-library, no? And 
usually one does not know a priori which libraries one needs - the size is not 
really a good criterium to decide whether to download a libraries debug 
information or not...

I'm not really complaining here - just thinking out loud. I believe for novice 
users the status quo is acceptable - they'll just need to wait for the 
download to finish (potentially taking minutes). More advanced users may want 
to manually skip some (larger) libs that they know they won't use for whatever 
they are looking at...

> > I would like to give the user feedback about this situation and
> > ideally provide a means to cancel the download.
> 
> OK.
> 
> > Looking at `debuginfod.h` I `debuginfod_set_progressfn` which looks
> > ideal. But how do I access the default `debuginfod_client *` which
> > seems to exist without me ever calling `debuginfod_begin` anywhere?
> > Or do I need to create a new client here via `debuginfod_begin`?
> 
> You do need to create a new client object.  You can reuse it.

Will the default code that uses debuginfod from within dwfl then pick up my 
new client object and use that? I feel like there's a fundamental confusion 
about this on my side about this. More on that at the end of this mail below.

> > Then, how would I cancel an ongoing download job? GDB seems to do
> > that when I press `CTRL+C`, but I do not see any API I could use for
> > that purpose?
> 
> See [man debuginfod_set_progressfn].  The return code from that
> progressfn callback is the ticket.

```
$ man debuginfod_set_progressfn
No manual entry for debuginfod_set_progressfn
```

My `debuginfod.h` also does not show any (useful) inline API documentation for 
most of that file. Could this please be improved? The doxygen for dwfl is 
great and can be read directly together with the code, I never used `man` for 
that purpose in the past?

> > Finally, what is the recommended way to check whether debuginfod is
> > available?  Should one rely on the build system to discover the
> > `debuginfod.h` header file, or is some other compile time check
> > suggested to detect it?  [...]
> 
> To decide whether or not to compile in support, you'd need a
> compile-time check such as for the debuginfod.h header.  (Alternately,
> you could opt not to compile in support at all, and instead call out
> to the debuginfod-find(1) program.)  To decide at run time whether or
> not to use it, you could just use the *_find APIs and get back an
> error code if things are not set up.  Or you can check the
> DEBUGINFOD_URLS for being set/unset before you call in.

I don't see where I would use debuginfod-find or any of the 
`debuginfod_find_*` API directly. I'm using dwfl which uses debuginfod 
internally. I guess that happens via the `dwfl_*find_*` standard callbacks 
provided in `libdwfl.h`. That works perfectly fine. I simply want a bit more 
control over the debuginfod usage that happens internally in dwfl.

Is maybe a `debuginfod_client *dwfl_debuginfod(void)` function missing that 
gives access to the client used by dwfl internally?

Thanks
-- 
Milian Wolff
mail@milianw.de
http://milianw.de

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Questions regarding debuginfod.h API

[Frank Ch. Eigler]

Hi -

> > (See also the DEBUGINFOD_MAXTIME and DEBUGINFOD_MAXSIZE env vars
> > that can limit this.)

> I did come across those, but what are suggested best practices in
> setting those? When using GDB or a profiler on larger non-trivial UI
> applications on Linux for the first time, we would start to download
> dozens of debug packages, taking hundreds of megabytes of
> space. [...]

Yes, and each of those downloads can be limited by these criteria.  An
application such as gdb could adds its own throttling on top, if it is
going to do a long series of downloads.  (Alternately, gdb can try not
to download all this stuff early; we're investigating gdbindex-only
fetch operations.)


> > > Looking at `debuginfod.h` I `debuginfod_set_progressfn` which looks
> > > ideal. But how do I access the default `debuginfod_client *` which
> > > seems to exist without me ever calling `debuginfod_begin` anywhere?
> > > Or do I need to create a new client here via `debuginfod_begin`?
> > 
> > You do need to create a new client object.  You can reuse it.
> 
> Will the default code that uses debuginfod from within dwfl then pick up my 
> new client object and use that? I feel like there's a fundamental confusion 
> about this on my side about this. More on that at the end of this mail below.

Ah yes, I didn't realize you were talking about the hidden debuginfod
client usage in libdwfl.  Yes, you have not much control over that,
because it is ....  hidden & automatic.  There is a
DEBUGINFOD_PROGRESS env var with which it can activate some
notification to stderr, but that's about it.  No API to get at the
internal transient objects.

If you wish to take control of this part, you could probably still use
dwfl.  You would do all the debuginfod client API calls yourself, then
"report" the dwarf file content to dwfl via dwarf_begin_elf(),
dwarf_begin(), dwarf_setalt() etc.


> ```
> $ man debuginfod_set_progressfn
> No manual entry for debuginfod_set_progressfn
> ```

Well go complain to your distro for this packaging bug. :-)
It's an alias of [man debuginfod_find_debuginfo].


> My `debuginfod.h` also does not show any (useful) inline API
> documentation for most of that file. Could this please be improved?
> The doxygen for dwfl is great and can be read directly together with
> the code, 

As they say, patches welcome. :-) The header contains some curt
comments documenting each function.

> I never used `man` for that purpose in the past?

There is a whole section of POSIX man pages for API docs: 3.


- FChE

Re: Questions regarding debuginfod.h API

[Milian Wolff]

[-- Attachment #1: Type: text/plain, Size: 3340 bytes --]

On Freitag, 8. April 2022 21:44:32 CEST Frank Ch. Eigler wrote:
> Hi -
> 
> > > (See also the DEBUGINFOD_MAXTIME and DEBUGINFOD_MAXSIZE env vars
> > > that can limit this.)
> > 
> > I did come across those, but what are suggested best practices in
> > setting those? When using GDB or a profiler on larger non-trivial UI
> > applications on Linux for the first time, we would start to download
> > dozens of debug packages, taking hundreds of megabytes of
> > space. [...]
> 
> Yes, and each of those downloads can be limited by these criteria.  An
> application such as gdb could adds its own throttling on top, if it is
> going to do a long series of downloads.  (Alternately, gdb can try not
> to download all this stuff early; we're investigating gdbindex-only
> fetch operations.)
> 
> > > > Looking at `debuginfod.h` I `debuginfod_set_progressfn` which looks
> > > > ideal. But how do I access the default `debuginfod_client *` which
> > > > seems to exist without me ever calling `debuginfod_begin` anywhere?
> > > > Or do I need to create a new client here via `debuginfod_begin`?
> > > 
> > > You do need to create a new client object.  You can reuse it.
> > 
> > Will the default code that uses debuginfod from within dwfl then pick up
> > my
> > new client object and use that? I feel like there's a fundamental
> > confusion
> > about this on my side about this. More on that at the end of this mail
> > below.
>
> Ah yes, I didn't realize you were talking about the hidden debuginfod
> client usage in libdwfl.  Yes, you have not much control over that,
> because it is ....  hidden & automatic.  There is a
> DEBUGINFOD_PROGRESS env var with which it can activate some
> notification to stderr, but that's about it.  No API to get at the
> internal transient objects.
> 
> If you wish to take control of this part, you could probably still use
> dwfl.  You would do all the debuginfod client API calls yourself, then
> "report" the dwarf file content to dwfl via dwarf_begin_elf(),
> dwarf_begin(), dwarf_setalt() etc.

OK thank you, that is helpful. Would you say adding dwfl API to get access to 
the internal debuginfod client would be a good path forward? I guess more 
projects would potentially like to benefit from the ready made integration, 
but add a bit of control on top of it?

> > ```
> > $ man debuginfod_set_progressfn
> > No manual entry for debuginfod_set_progressfn
> > ```
> 
> Well go complain to your distro for this packaging bug. :-)
> It's an alias of [man debuginfod_find_debuginfo].

Found it now - it's packaged together with `debuginfod`, even though it should 
be part of `elfutils`.

> > My `debuginfod.h` also does not show any (useful) inline API
> > documentation for most of that file. Could this please be improved?
> > The doxygen for dwfl is great and can be read directly together with
> > the code,
> 
> As they say, patches welcome. :-) The header contains some curt
> comments documenting each function.

Would you be OK with me simply copying over the contents from the man page 
over to doxygen? Or is there a better process in place to prevent such kind of 
documentation duplication? I would have expected that the man pages for API 
documentation are generated from e.g. doxygen which does not seem to be the 
case here?

Thanks
-- 
Milian Wolff
mail@milianw.de
http://milianw.de

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Milian Wolff]

[-- Attachment #1: Type: text/plain, Size: 3206 bytes --]

On Freitag, 8. April 2022 21:50:18 CEST Milian Wolff wrote:
> On Freitag, 8. April 2022 21:44:32 CEST Frank Ch. Eigler wrote:
> > > Will the default code that uses debuginfod from within dwfl then pick up
> > > my
> > > new client object and use that? I feel like there's a fundamental
> > > confusion
> > > about this on my side about this. More on that at the end of this mail
> > > below.
> > 
> > Ah yes, I didn't realize you were talking about the hidden debuginfod
> > client usage in libdwfl.  Yes, you have not much control over that,
> > because it is ....  hidden & automatic.  There is a
> > DEBUGINFOD_PROGRESS env var with which it can activate some
> > notification to stderr, but that's about it.  No API to get at the
> > internal transient objects.
> > 
> > If you wish to take control of this part, you could probably still use
> > dwfl.  You would do all the debuginfod client API calls yourself, then
> > "report" the dwarf file content to dwfl via dwarf_begin_elf(),
> > dwarf_begin(), dwarf_setalt() etc.
> 
> OK thank you, that is helpful. Would you say adding dwfl API to get access
> to the internal debuginfod client would be a good path forward? I guess
> more projects would potentially like to benefit from the ready made
> integration, but add a bit of control on top of it?

I looked into this a bit more, and would like to expand the dwfl API to give 
more control over how it uses debuginfod internally.

Without any API changes, I currently can not disable debuginfod usage in dwfl.
Well, the only option would be to unset the environment variable before any 
call into dwfl. But if I would roll my own debuginfod client code, it would 
still depend on the environment variable - thus the code would become quite 
ugly with repeated setenv/unsetenv pairs.

Additionally, the debuginfod client code in dwfl is good and well tested. 
Rolling my own just to get progress reporting and cancellation sounds like a 
waste of time to me.

Thus my proposal, and RFC: 

```
/* Let us mirror the debuginfod progressfn for dwfl and forward it to
   the internal debuginfod client, if available.
   This way, dwfl's usage of debuginfod can stay optional and we would not
   need to link to debuginfod directly from code using dwfl.
 */
typedef int (*dwfl_debuginfod_progressfn_t)(Dwfl *dwfl, long a, long b);
extern void dwfl_set_debuginfod_progressfn(Dwfl *dwfl,
			           dwfl_debuginfod_progressfn_t fn);
```

This would already greatly help me. Better yet, we would eventually also add 
some more information to the progress callback, such as the name of the 
library that has triggered the download. But that could be done in a follow up 
patch, in a fashion similar to `debuginfod_get_url` I believe.

Alternatively:

```
/* We could just give full access to the internal client
   but doing so may clash with future usages of e.g. 
   debuginfod_{set,get}_user_data in dwfl and users of dwfl.
   Otherwise, this is obviously easiest and gives most flexibility.
   We just need to forward get_client from debuginfod-client.c
 */
extern debuginfod_client *dwfl_debuginfod_client (Dwfl *);
```

What do you all think?

Cheers
-- 
Milian Wolff
mail@milianw.de
http://milianw.de

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Milian Wolff]

[-- Attachment #1: Type: text/plain, Size: 3550 bytes --]

On Samstag, 9. April 2022 15:44:34 CEST Milian Wolff wrote:
> On Freitag, 8. April 2022 21:50:18 CEST Milian Wolff wrote:
> > On Freitag, 8. April 2022 21:44:32 CEST Frank Ch. Eigler wrote:
> > > > Will the default code that uses debuginfod from within dwfl then pick
> > > > up
> > > > my
> > > > new client object and use that? I feel like there's a fundamental
> > > > confusion
> > > > about this on my side about this. More on that at the end of this mail
> > > > below.
> > > 
> > > Ah yes, I didn't realize you were talking about the hidden debuginfod
> > > client usage in libdwfl.  Yes, you have not much control over that,
> > > because it is ....  hidden & automatic.  There is a
> > > DEBUGINFOD_PROGRESS env var with which it can activate some
> > > notification to stderr, but that's about it.  No API to get at the
> > > internal transient objects.
> > > 
> > > If you wish to take control of this part, you could probably still use
> > > dwfl.  You would do all the debuginfod client API calls yourself, then
> > > "report" the dwarf file content to dwfl via dwarf_begin_elf(),
> > > dwarf_begin(), dwarf_setalt() etc.
> > 
> > OK thank you, that is helpful. Would you say adding dwfl API to get access
> > to the internal debuginfod client would be a good path forward? I guess
> > more projects would potentially like to benefit from the ready made
> > integration, but add a bit of control on top of it?
> 
> I looked into this a bit more, and would like to expand the dwfl API to give
> more control over how it uses debuginfod internally.
> 
> Without any API changes, I currently can not disable debuginfod usage in
> dwfl. Well, the only option would be to unset the environment variable
> before any call into dwfl. But if I would roll my own debuginfod client
> code, it would still depend on the environment variable - thus the code
> would become quite ugly with repeated setenv/unsetenv pairs.
> 
> Additionally, the debuginfod client code in dwfl is good and well tested.
> Rolling my own just to get progress reporting and cancellation sounds like a
> waste of time to me.
> 
> Thus my proposal, and RFC:
> 
> ```
> /* Let us mirror the debuginfod progressfn for dwfl and forward it to
>    the internal debuginfod client, if available.
>    This way, dwfl's usage of debuginfod can stay optional and we would not
>    need to link to debuginfod directly from code using dwfl.
>  */
> typedef int (*dwfl_debuginfod_progressfn_t)(Dwfl *dwfl, long a, long b);
> extern void dwfl_set_debuginfod_progressfn(Dwfl *dwfl,
> 			           dwfl_debuginfod_progressfn_t fn);
> ```
> 
> This would already greatly help me. Better yet, we would eventually also add
> some more information to the progress callback, such as the name of the
> library that has triggered the download. But that could be done in a follow
> up patch, in a fashion similar to `debuginfod_get_url` I believe.
> 
> Alternatively:
> 
> ```
> /* We could just give full access to the internal client
>    but doing so may clash with future usages of e.g.
>    debuginfod_{set,get}_user_data in dwfl and users of dwfl.
>    Otherwise, this is obviously easiest and gives most flexibility.
>    We just need to forward get_client from debuginfod-client.c
>  */
> extern debuginfod_client *dwfl_debuginfod_client (Dwfl *);
> ```
> 
> What do you all think?

Ping, could I get some feedback on the above please? I have some time the next 
days and would like to work on this. Which way would you prefer?

Thanks

-- 
Milian Wolff
mail@milianw.de
http://milianw.de

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5272 bytes --]

Re: Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Frank Ch. Eigler]

Hi -

> > Thus my proposal, and RFC:
> > 
> > ```
> > /* Let us mirror the debuginfod progressfn for dwfl and forward it to
> >    the internal debuginfod client, if available.
> >    This way, dwfl's usage of debuginfod can stay optional and we would not
> >    need to link to debuginfod directly from code using dwfl.
> >  */
> > typedef int (*dwfl_debuginfod_progressfn_t)(Dwfl *dwfl, long a, long b);
> > extern void dwfl_set_debuginfod_progressfn(Dwfl *dwfl,
> > 			           dwfl_debuginfod_progressfn_t fn);
> > ```

(Don't quite see how this extension would let you disable or enable
debuginfod support on a given dwfl.  By the time a progressfn is
called, some debuginfod traffic would be attempted.)n


> Alternately:
> [...]
> > /* We could just give full access to the internal client
> >    but doing so may clash with future usages of e.g.
> >    debuginfod_{set,get}_user_data in dwfl and users of dwfl.
> >    Otherwise, this is obviously easiest and gives most flexibility.
> >    We just need to forward get_client from debuginfod-client.c
> >  */
> > extern debuginfod_client *dwfl_debuginfod_client (Dwfl *);
> > ```
> > What do you all think?

In order to -influence- things, would you not need to -change- the
client somehow?  We don't have debuginfod-client apis to disable or
reconfigure any particular client object.  Such an API wouldn't let
you replace it with a hook object of your own either.


So, dunno, could you perhaps remind us what your current usage
interests are?

To enable/disable it on a per-dwfl basis?  If yes, and if statically,
maybe a new Dwfl_Callbacks option for .find_debuginfo() could be your
ticket: a dwfl_standard_find_debuginfo variant sans debuginfod at the
end.


- FChE

Re: Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Milian Wolff]

On Mittwoch, 6. Juli 2022 20:40:09 CEST Frank Ch. Eigler wrote:
> Hi -
> 
> > > Thus my proposal, and RFC:
> > > 
> > > ```
> > > /* Let us mirror the debuginfod progressfn for dwfl and forward it to
> > > 
> > >    the internal debuginfod client, if available.
> > >    This way, dwfl's usage of debuginfod can stay optional and we would
> > >    not
> > >    need to link to debuginfod directly from code using dwfl.
> > >  
> > >  */
> > > 
> > > typedef int (*dwfl_debuginfod_progressfn_t)(Dwfl *dwfl, long a, long b);
> > > extern void dwfl_set_debuginfod_progressfn(Dwfl *dwfl,
> > > 
> > > 			           dwfl_debuginfod_progressfn_t fn);
> > > 
> > > ```
> 
> (Don't quite see how this extension would let you disable or enable
> debuginfod support on a given dwfl.  By the time a progressfn is
> called, some debuginfod traffic would be attempted.)n
> 
> > Alternately:
> > [...]
> > 
> > > /* We could just give full access to the internal client
> > > 
> > >    but doing so may clash with future usages of e.g.
> > >    debuginfod_{set,get}_user_data in dwfl and users of dwfl.
> > >    Otherwise, this is obviously easiest and gives most flexibility.
> > >    We just need to forward get_client from debuginfod-client.c
> > >  
> > >  */
> > > 
> > > extern debuginfod_client *dwfl_debuginfod_client (Dwfl *);
> > > ```
> > > What do you all think?
> 
> In order to -influence- things, would you not need to -change- the
> client somehow?  We don't have debuginfod-client apis to disable or
> reconfigure any particular client object.  Such an API wouldn't let
> you replace it with a hook object of your own either.
> 
> 
> So, dunno, could you perhaps remind us what your current usage
> interests are?
> 
> To enable/disable it on a per-dwfl basis?  If yes, and if statically,
> maybe a new Dwfl_Callbacks option for .find_debuginfo() could be your
> ticket: a dwfl_standard_find_debuginfo variant sans debuginfod at the
> end.

I have two goals:

a) Notifying the user that a download is ongoing. Right now, it feels like the 
tool is frozen as no feedback is given to the user.

b) Allow to disable debuginfod. But that is already doable by unsetting the 
DEBUGINFOD_URLS env var, and as such I don't necessarily need any additional 
API for that?

As such, only a) is something that needs immediate attention imo, and what my 
API proposal is covering.

Thanks

-- 
Milian Wolff
http://milianw.de

Re: Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Frank Ch. Eigler]

Hi -

> a) Notifying the user that a download is ongoing. Right now, it feels like the 
> tool is frozen as no feedback is given to the user.

Right, can you explain how DEBUGINFOD_PROGRESS=1 is not a good fit in your case?

- FChE

Re: Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Milian Wolff]

On Mittwoch, 6. Juli 2022 21:41:33 CEST Frank Ch. Eigler wrote:
> Hi -
> 
> > a) Notifying the user that a download is ongoing. Right now, it feels like
> > the tool is frozen as no feedback is given to the user.
> 
> Right, can you explain how DEBUGINFOD_PROGRESS=1 is not a good fit in your
> case?

As you said yourself:

> There is a
> DEBUGINFOD_PROGRESS env var with which it can activate some
> notification to stderr, but that's about it.

I'm working on GUI applications (hotspot [1], gammaray [2]), people do not 
look at the command line output. I want to show the download progress and 
status graphically instead.

[1]: https://github.com/KDAB/hotspot/
[2]: https://github.com/KDAB/gammaray

-- 
Milian Wolff
http://milianw.de

Re: Expanding control over debuginfod usage from dwfl [was: Re: Questions regarding debuginfod.h API]

[Frank Ch. Eigler]

Hi -

> I'm working on GUI applications (hotspot [1], gammaray [2]), people do not 
> look at the command line output. I want to show the download progress and 
> status graphically instead. [...]

Aha, got it.  I'd say a

    extern debuginfod_client *dwfl_get_debuginfod_client (Dwfl *);

type function would probably be your bet.  That could also be built
upon later, to provide finer grained control (to override environment
variable settings e.g.).


The other approach of a custom Dwfl_Callbacks .find_debuginfo hook is
also available, wherein your own app can take charge of finding /
downloading debuginfo, with its own bespoke debuginfod_client object.
This would have the benefit of working with existing elfutils.


- FChE

Re: Questions regarding debuginfod.h API

[Frank Ch. Eigler]

Hi -

> > > My `debuginfod.h` also does not show any (useful) inline API
> > > documentation for most of that file. Could this please be improved?
> > > The doxygen for dwfl is great and can be read directly together with
> > > the code,
> > 
> > As they say, patches welcome. :-) The header contains some curt
> > comments documenting each function.
> 
> Would you be OK with me simply copying over the contents from the man page 
> over to doxygen? Or is there a better process in place to prevent such kind of 
> documentation duplication? I would have expected that the man pages for API 
> documentation are generated from e.g. doxygen which does not seem to be the 
> case here?

Correct, elfutils does not have much API documentation generally.  The
debuginfod parts are a recent addition that buck that trend. :-) I
don't have a strong opinion about doxygen syntax markup or tooling
dependence, per se.  OTOH I would not want to see documentation
duplication or loss of man pages.

- FChE