Page MenuHomeFreeBSD

Developer's Handbook: add a section on remote debugging via LLDB
ClosedPublic

Authored by mgorny_gentoo.org on Dec 9 2020, 5:25 PM.

Details

Summary

Here's a patch proposing a new section on remote debugging with LLDB. This is probably to be merge *after* LLDB 12.0.0 (or equivalent) makes it into FreeBSD, llvm-project commit a8bfee2a356a2e70f854bf6d0b364798f4183795 would be the absolute minimal for reliable remote debugging IMHO.

PR: 251709
Sponsored by: The FreeBSD Foundation
Obtained from: Moritz Systems
Submitted by: Michał Górny <mgorny@moritz.systems>

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

mgorny_gentoo.org created this revision.

Minor fix, then it is good to go.
Thanks for the patch.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1662

s/FreeBSD/&os;/

mgorny_gentoo.org edited the summary of this revision. (Show Details)
mgorny_gentoo.org marked an inline comment as done.

Updated as requested. Note that this shouldn't be probably pushed yet, as it could confuse users before LLVM 12.0.0 is released.

Updated as requested. Note that this shouldn't be probably pushed yet, as it could confuse users before LLVM 12.0.0 is released.

But it does say "... starting with LLDB 12.0.0", so the confusion would be minimal, right?

In D27524#615445, @bcr wrote:

Updated as requested. Note that this shouldn't be probably pushed yet, as it could confuse users before LLVM 12.0.0 is released.

But it does say "... starting with LLDB 12.0.0", so the confusion would be minimal, right?

I'm not sure about that. When I read stuff like this I usually think 'I am using the newest version, so that must be it'. However, IIRC there's no release schedule for 12 yet.

In D27524#615445, @bcr wrote:

Updated as requested. Note that this shouldn't be probably pushed yet, as it could confuse users before LLVM 12.0.0 is released.

But it does say "... starting with LLDB 12.0.0", so the confusion would be minimal, right?

I'm not sure about that. When I read stuff like this I usually think 'I am using the newest version, so that must be it'. However, IIRC there's no release schedule for 12 yet.

I'd err more on the side of having the information in the handbook. If it does not work, the user would get in touch with us (or figure out on their own that their local version is not the one described here). Holding things back often leads to things being forgotten, even though they are ready. These introductory sentences with version specific information should help the user. After all, why put any version information in there? If LLDB 12.0.0 is not released yet, people just have to wait.

ygy added a subscriber: ygy.

Looks good to me on the doc side, and I agree with @bcr regarding landing it sooner than later, since the required LLDB version is already included.

I will help land this change, thanks again for the submission ;)

This revision is now accepted and ready to land.Dec 10 2020, 5:08 PM
In D27524#615628, @ygy wrote:

Looks good to me on the doc side, and I agree with @bcr regarding landing it sooner than later, since the required LLDB version is already included.

Included in the document you mean, not included in FreeBSD, right? That said, I'm also on board with getting it in sooner rather than later, based on the assumption that:

  • @dim is likely to start the work on updating to Clang 12 leading up to the actual release
  • FreeBSD 13 will ship with released Clang 12
  • New LLDB is available in the llvm-devel port/package (we could reference it here if desired)
In D27524#615628, @ygy wrote:

Looks good to me on the doc side, and I agree with @bcr regarding landing it sooner than later, since the required LLDB version is already included.

Included in the document you mean, not included in FreeBSD, right? That said, I'm also on board with getting it in sooner rather than later, based on the assumption that:

  • @dim is likely to start the work on updating to Clang 12 leading up to the actual release
  • FreeBSD 13 will ship with released Clang 12

At the moment I don't see how this can work with the FreeBSD and LLVM release schedules. The FreeBSD schedule as proposed by gjb is:

head slush:              January 8, 2021
KBI freeze:              January 8, 2021
stable/13 branch:        January 22, 2021
releng/13.0 branch:      February 5, 2021
BETA1 build starts:      February 5, 2021
doc/ tree slush:         February 5, 2021 [++]
BETA2 build starts:      February 12, 2021
BETA3 build starts:      February 19, 2021 [*]
doc/ tree tag:           February 19, 2021 [++]
RC1 build starts:        February 26, 2021
RC2 build starts:        March 5, 2021
RC3 build starts:        March 12, 2021  [*]
RELEASE build starts:    March 19, 2021
RELEASE announcement:    March 23, 2021
Branch EoL:              TBD

Whereas on the LLVM mailing list, we just had a small discussion (see https://lists.llvm.org/pipermail/llvm-dev/2020-December/147063.html) about the upcoming 12.0.0 release. I mentioned there that the LLVM releases tend to happen at the end of March and the end of September (though 10.0.1 and 11.0.0 slipped by quite a lot).

Realistically, I don't think LLVM 12.0.0 will be released until well after we release FreeBSD 13.0.0. If it is up to me, I would rather merge the upcoming LLVM 11.0.1 into head, and not disrupt things too much between the git transition(s) and the slush period.

  • New LLDB is available in the llvm-devel port/package (we could reference it here if desired)

Indeed, I'd rather start pointing people to the port instead, to experiment with new features.

ygy requested changes to this revision.EditedDec 14 2020, 6:04 AM

Included in the document you mean, not included in FreeBSD, right? That said, I'm also on board with getting it in sooner rather than later, based on the assumption that:

Yes, I meant included in the document, so that there is only a minimal chance of misunderstanding.

In D27524#615666, @dim wrote:

Indeed, I'd rather start pointing people to the port instead, to experiment with new features.

I like the idea of offering users a way to experiment with new features if it is not yet available in the system. @mgorny_gentoo.org, could you please briefly mention the port in the doc (a <note> would do)?

This revision now requires changes to proceed.Dec 14 2020, 6:04 AM
en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1663

Statements like "not-yet-released" will quickly become obsolete in the documentation IMO, and we have to update it sometime again in the future. Is it possible to change it to time-irrelevant statements, that only mention the 12.0.0 version requirement as well as the available ports? ;)

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1663

Do you mean that I should basically say '[...] is available since 12.0.0 version in LLDB. ', and then mention all the available ports? To be honest, I'm not sure how to do that precisely without having users search for version that's not there yet.

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1663

@ygy how about "...is available starting with LLDB versino 12.0.0. Users of FreeBSD releases containing an earlier LLDB version can use..."

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1663

This sounds much better to me, thanks!

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1663

"...is available starting with LLDB version 12.0.0. Users of &os; releases containing an earlier LLDB version may wish to use the snapshot..."

^^ I meant this one. ;)

mgorny_gentoo.org marked 4 inline comments as done.

Updated per @ygy/@emaste's suggestions.

Apart from a minor nit that I will fix when committing, this looks good. Thanks again for the submission!

en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
1663

There is an extra "version".

This revision is now accepted and ready to land.Dec 28 2020, 4:20 PM