doc: update .lldbinit configuration for cmake builds to see source code in debugger #32205

1. 
   pinheadmz commented at 6:43 pm on April 2, 2025: member

   Closes #31204

   To reproduce:

   1. build bitcoin with -DCMAKE_BUILD_TYPE=Debug
   2. run with lldb, add a breakpoint and trigger it (with a second local bitcoind peer, for example):
      • lldb buld/bin/bitcoind
      • (lldb) b ProcessMessage
      • (lldb) r -regtest Output will probably look like this:

   0Process 6764 stopped
   1* thread [#34](/bitcoin-bitcoin/34/), name = 'b-msghand', stop reason = breakpoint 1.1
   2    frame [#0](/bitcoin-bitcoin/0/): 0x00000001003380c0 bitcoind`(anonymous namespace)::PeerManagerImpl::ProcessMessages(this=0x000000013e80e400, pfrom=0x000000013c70a830, interruptMsgProc=0x000000013d009d40) at net_processing.cpp:4933:5
   

   To fix (following the doc in this PR) Create or append to ~/.lldbinit in your $HOME directory, using absolute paths. (My example)

   0settings set target.source-map /Users/matthewzipkin/Desktop/work/bitcoin/build/src /Users/matthewzipkin/Desktop/work/bitcoin/src
   

   Improved output:

   0Process 6811 stopped
   1* thread [#34](/bitcoin-bitcoin/34/), name = 'b-msghand', stop reason = breakpoint 1.1
   2    frame [#0](/bitcoin-bitcoin/0/): 0x00000001003380c0 bitcoind`(anonymous namespace)::PeerManagerImpl::ProcessMessages(this=0x000000011c808800, pfrom=0x0000000104004080, interruptMsgProc=0x000000011d009140) at net_processing.cpp:4933:5
   3   4930
   4   4931 bool PeerManagerImpl::ProcessMessages(CNode* pfrom, std::atomic<bool>& interruptMsgProc)
   5   4932 {
   6-> 4933     AssertLockNotHeld(m_tx_download_mutex);
   7   4934     AssertLockHeld(g_msgproc_mutex);
   8   4935
   9   4936     PeerRef peer = GetPeerRef(pfrom->GetId());
   

2. doc: update .lldbinit configuration for cmake builds 3a77f13992
3. 
   DrahtBot commented at 6:44 pm on April 2, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32205.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	janb84

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

4. DrahtBot added the label Docs on Apr 2, 2025
5. 
   janb84 commented at 10:08 am on April 3, 2025: contributor

   ACK 3a77f13

   Before:

   0Process 52169 stopped
   1* thread [#1](/bitcoin-bitcoin/1/), queue = 'com.apple.main-thread', stop reason = breakpoint 2.1
   2    frame [#0](/bitcoin-bitcoin/0/): 0x000000010021547c bitcoind`AddLocal(addr=0x000000012600fe00, nScore=1) at net.cpp:307:30
   

   After changes per instruction:

   0Process 52277 stopped
   1* thread [#1](/bitcoin-bitcoin/1/), queue = 'com.apple.main-thread', stop reason = breakpoint 3.1
   2   frame [#0](/bitcoin-bitcoin/0/): 0x00000001007f2d58 bitcoind`addnode() at net.cpp:307:23
   3  304 
   4  305  static RPCHelpMan addnode()
   5  306  {
   6-> 307      return RPCHelpMan{"addnode",
   7  308                  "\nAttempts to add or remove a node from the addnode list.\n"
   8  309                  "Or try a connection to a node once.\n"
   9  310                  "Nodes added using addnode (or -connect) are protected from DoS disconnection and are not required to be\n"
   

6. 
   mabu44 commented at 1:41 pm on April 8, 2025: none

   For me it works out of the box, without any lldbinit file. I am on Debian 12 with ccache installed.

   0cmake -B build_debug -DCMAKE_BUILD_TYPE=Debug
   1cmake --build build_debug -j 4 -t bitcoind
   2lldb-16 build_debug/bin/bitcoind
   

   0b ProcessInitCommands
   

   0r -regtest
   

   Output:

    0Process 91637 launched: '/home/brown/bitcoin/build_debug/bin/bitcoind' (x86_64)
    1Process 91637 stopped
    2* thread [#1](/bitcoin-bitcoin/1/), name = 'bitcoind', stop reason = breakpoint 1.1
    3    frame [#0](/bitcoin-bitcoin/0/): 0x000055555558751f bitcoind`ProcessInitCommands(args=0x0000555556a77b80) at bitcoind.cpp:138:29
    4   135 	static bool ProcessInitCommands(ArgsManager& args)
    5   136 	{
    6   137 	    // Process help and version before taking care about datadir
    7-> 138 	    if (HelpRequested(args) || args.GetBoolArg("-version", false)) {
    8   139 	        std::string strUsage = CLIENT_NAME " daemon version " + FormatFullVersion() + "\n";
    9   140 	
   10   141 	        if (args.GetBoolArg("-version", false)) {
   

7. DrahtBot added the label CI failed on Apr 29, 2025
8. DrahtBot removed the label CI failed on May 2, 2025
9. achow101 requested review from vasild on Oct 22, 2025
10. achow101 requested review from davidgumberg on Oct 22, 2025
11. achow101 requested review from ismaelsadeeq on Oct 22, 2025

Contributors
pinheadmz DrahtBot janb84 mabu44

Review Requested
vasild davidgumberg ismaelsadeeq

Labels
Docs