Page MenuHomeFreeBSD

Add lldb version of gdb mini-tutorial.
ClosedPublic

Authored by pauamma_gundo.com on Jun 4 2020, 10:36 PM.
Tags
None
Referenced Files
Unknown Object (File)
Feb 3 2024, 5:59 AM
Unknown Object (File)
Jan 19 2024, 6:22 AM
Unknown Object (File)
Jan 18 2024, 12:53 PM
Unknown Object (File)
Jan 4 2024, 2:23 PM
Unknown Object (File)
Dec 29 2023, 1:39 AM
Unknown Object (File)
Dec 20 2023, 6:07 AM
Unknown Object (File)
Nov 14 2023, 1:14 AM
Unknown Object (File)
Nov 13 2023, 12:38 AM

Details

Summary
  • Make sure existing gdb sections have a title ending in "with gdb".
  • Group existing gdb sections into a new "Using gdb" section, pushing them down 1 level (from sect2 to sect3). This entails a lot of whitespace change.
  • Insert new "Introduction to available debuggers" introduction section before "Using gdb" to briefly present both lldb and gdb.
  • Remove material in "Starting gdb" redundant with "Introduction to available debuggers".
  • Insert new "Using lldb" section after introduction, mirroring the organization and content of the "Using gdb" section: "Starting lldb", "Running a Program with lldb", "Examining a Core File with lldb", and "Attaching to a Running Program with lldb".
  • Change earlier reference to gdb to a generic debugger reference.
  • Pacify igor somewhat.

While there:

  • s/Did we not we set/Did we not set/
  • Add xref to the "debugging the kernel" mention.
  • Fix parenthese-period order inversions.

PR 241248

Test Plan

Tested with lynx, lldb commands tested under 12.1.

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

pauamma_gundo.com created this revision.

I wonder if it would be appropriate to ask @woodsb02 whether his instructions on https://wiki.freebsd.org/BenWoods/DebuggingPorts could be added as a section of this handbook page, or perhaps a note made about it instructing the user to look at the wiki? It seems very appropriate, as otherwise, people might not know how to get debugging symbols for third party programs supplied by ports.
Additionally, should there also be a section noting that debugging symbols for -RELEASE is included in the base-dbg and kernel-dbg distribution sets available on all installation media but -bootonly and -memdisk-mini images? People building from source might also need to be directed towards the appropriate page.

I also found a little nit.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1552 ↗(On Diff #72696)

This sentence needs to start with a capitalized word, for example "The lldb command displays..."

I wonder if it would be appropriate to ask @woodsb02 whether his instructions on https://wiki.freebsd.org/BenWoods/DebuggingPorts could be added as a section of this handbook page, or perhaps a note made about it instructing the user to look at the wiki? It seems very appropriate, as otherwise, people might not know how to get debugging symbols for third party programs supplied by ports.
Additionally, should there also be a section noting that debugging symbols for -RELEASE is included in the base-dbg and kernel-dbg distribution sets available on all installation media but -bootonly and -memdisk-mini images? People building from source might also need to be directed towards the appropriate page.

Both these suggestions sound sensible to me at first glance but out of scope for this. Can you open bugs or start discussion for them in docs@ ? (If the former, feel free to cc me on them.)

I also found a little nit.

Thanks, will fix later.

I wonder if it would be appropriate to ask @woodsb02 whether his instructions on https://wiki.freebsd.org/BenWoods/DebuggingPorts could be added as a section of this handbook page, or perhaps a note made about it instructing the user to look at the wiki? It seems very appropriate, as otherwise, people might not know how to get debugging symbols for third party programs supplied by ports.

I whole-heartedly agree the ports debugging tips should be in the handbook, not buried somewhere on the wiki. I’m happy for someone to take these as they are, or improve them - I just haven’t found the time myself to do it.

Wow, this is great work and a very welcome addition to the developers handbook. Thank you for the initial writeup.
The developers-handbook has not seen many updates in recent years and many of the sections and chapters have a less formal writing style than the handbook. Perhaps this is because it was written by developers and the docs people did not get to give it a bit of formatting love yet.

Your text is great in general, however it should maybe a bit more formal. For example, the use of "you" is discouraged. Check out the Writing Style chapter in the FDP primer where this is described. I definitely want to see this added to the developers-handbook and would be willing to help you fix up the text you provided to confirm to our writing style a bit more. I just didn't want to comment on (almost) every line in your review and just mention it here.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1356 ↗(On Diff #72696)

&rel1 - typo?

1358 ↗(On Diff #72696)

we have llvm60, llvm70, llvm80, llvm90, llvm10 available, with just llvm as a meta package to pick the default - we should reference that one here.

1360 ↗(On Diff #72696)

and we'll need to clarify lldb80/lldb90 etc.

1372 ↗(On Diff #72696)

Note though that it's still GDB 6.1 there, which is obsolete/buggy; developers wishing to use GDB will still want to install the gdb package/port.

1392 ↗(On Diff #72696)

can be lldb <progname> -- <program arguments> - for example, lldb /bin/ls -- /tmp

as an aside it seems the lldb man page has an error here, using a single dash:

Passing an executable as a positional argument prepares lldb to debug
the given executable. Arguments passed after - are considered arguments
to the debugged executable.
   lldb -arch x86_64 /path/to/program - -arch arvm7
1398–1402 ↗(On Diff #72696)

(-g is also needed on any libraries the program uses, to get the most out of a debugger. Not sure it's necessary to mention in the mini tutorial though)

1420 ↗(On Diff #72696)

It might be useful to mention the shorter forms / GDB compat options before this?

1431 ↗(On Diff #72696)

i.e., wrt the comment above, move this tip before the preceding paragraphs.

1912–1915 ↗(On Diff #72696)

@bcr it would be nice if we can commit these whitespace fixes independently, first; how best to handle that?

(And, thank you very much for your submission!)

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1912–1915 ↗(On Diff #72696)

Once we have the text we want (i.e. approved), I can give it a whitespace sweep before the commit. This way, we can concentrate on the content for now.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1912–1915 ↗(On Diff #72696)

I mean, it's harder to concentrate on the content because there are these whitespace changes included also.,

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1912–1915 ↗(On Diff #72696)

Oh, now I get it. Ah well, I think it's fine if a new-ish submitter does not know (all of) our rules yet.
@pauamma_gundo.com : We usually don't mix whitespace and content changes to make it easier to review. We'll do the whitespace fixes afterwards.

Thanks all for reviewing my first draft. I'll try to submit a second draft later tonight or tomorrow.

Bah. Phabricator ate my inline replies the first time.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1356 ↗(On Diff #72696)

No, rel1.current is defined in share/xml/release.ent and used in several places, including the (users') handbook, to refer (currently) to 11.3. (Whether the "current" bit is still appropriate is more than I caan say, though.)

1392 ↗(On Diff #72696)

Manpage (at least in 12.1) says lldb wants -f before the executable if you're going to put it before the --, so I'm tempted to leave it this way. (Same manpage has -- everywhere I can see, too.)

1398–1402 ↗(On Diff #72696)

gdb section doesn't mention that, and I largely reproduced it for content that's not specific to one debugger. Should I add it in both?

1912–1915 ↗(On Diff #72696)

OK, I'll undo the whitespace and wordwrap changes, then.

Address most changes requested by debdrup, bcr, and emaste.

  • Get rid of "you"s (and of some "we"s while I was at it).
  • Make sure all sentences start with an uppercase letter.
  • Undo space changes to make content changes in the gdb section more visible.

While there, reword some of the language to make it a bit more formal.

Change requests about which I still have questions will come later.

this lgtm, thanks for all the effort here!

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1466 ↗(On Diff #72847)

heh, your garbage value changed :)

1398–1402 ↗(On Diff #72696)

It's fine to leave it as is, we can perhaps do another pass over this later on when lldb improves (specifically, gains kernel support)

I found a few minor textual things to fix, quickly done. ;-)

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1371 ↗(On Diff #72847)

Here is a leftover "you".

1420 ↗(On Diff #72847)

another "your". You can replace it with "the" here.

1571 ↗(On Diff #72847)

s/FreeBSD/&os;/

1685 ↗(On Diff #72847)

Here is a "you".

1696 ↗(On Diff #72847)

s/your/the/

Aside from these two nits, I think it would be best to do s/a\.out/progname/g as a.out is only supported via COMPAT_43 on FreeBSD, and - as far as I know - isn't used anymore. This also has the added benefit of bringing it in line with the example used just above the section where a.out is currently mentioned.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1881 ↗(On Diff #72847)

I think "the code that calls fork() on the child" is perhaps easier to read than "the code that fork()s the child", but in addition it's also more technically correct.

1897 ↗(On Diff #72847)

s/to do is/is to/

  • Address bcr's and debdrup's comments on second draft.

Thanks for these changes. I'll get them committed.

This revision is now accepted and ready to land.Jun 15 2020, 6:57 AM
This revision was automatically updated to reflect the committed changes.