Source code mapping for debugger has changed since cmake

pinheadmz commented at 2:37 pm on November 1, 2024: member

developer-notes.md says:

Configure source file mapping.

For gdb create or append to .gdbinit file:
0set substitute-path ./src /path/to/project/root/src
For lldb create or append to .lldbinit file:
0settings set target.source-map ./src /path/to/project/root/src

But I found I needed to create a .lldbinit file with these lines:

0settings append target.source-map build/src/test/ /Users/matthewzipkin/Desktop/work/bitcoin/
1settings append target.source-map build/src/src/ /Users/matthewzipkin/Desktop/work/bitcoin/src/

Here’s an example of lldb’s confused guess of source location:

0(lldb) image lookup -vn  ProcessMessages
11 match found in /Users/matthewzipkin/Desktop/work/bitcoin/build/src/bitcoind:
2...
3      LineEntry: [0x00000001003302f4-0x000000010033032c): build/src/src/net_processing.cpp:5373

Could just be fixed by updating developer-notes.md – would we ever include a .lldbinit file in the repo itself? Or am I missing something else.

bitcoin deleted a comment on Nov 3, 2024

edilmedeiros commented at 7:50 pm on January 2, 2025: contributor

After many hours, I could make it work.

Add this to ~/.lldbinit to make it load a local .lldbinit file: settings set target.load-cwd-lldbinit true. This is a convenience so that I can keep everything related to Bitcoin Core in its repo.

In the Bitcoin Core repo folder, add a .lldbinit file with (mine is located at /Users/jose.edil/2-development/bitcoin/bitcoin-core-dev, adjust to your path):

0settings set target.source-map /Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/build/src/ /Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/src/

Compiled with: $ cmake -B build -DBoost_INCLUDE_DIR=/opt/local/libexec/boost/1.87/include -DCMAKE_C_COMPILER=clang-mp-18 -DCMAKE_CXX_COMPILER=clang++-mp-18 -DCMAKE_BUILD_TYPE=Debug -DWITH_CCACHE=OFF

In particular, I suspect that -fdebug-prefix-map is not doing it’s thing:

 0(lldb) set list target.source-map
 1  target.source-map -- Source path remappings apply substitutions to the paths of source files, typically
 2                       needed to debug from a different host than the one that built the target.  The
 3                       source-map property consists of an array of pairs, the first element is a path prefix,
 4                       and the second is its replacement.  The syntax is `prefix1 replacement1 prefix2
 5                       replacement2...`.  The pairs are checked in order, the first prefix that matches is
 6                       used, and that prefix is substituted with the replacement.  A common pattern is to use
 7                       source-map in conjunction with the clang -fdebug-prefix-map flag.  In the build, use
 8                       `-fdebug-prefix-map=/path/to/build_dir=.` to rewrite the host specific build directory
 9                       to `.`.  Then for debugging, use `settings set target.source-map . /path/to/local_dir`
10                       to convert `.` to a valid local path.

0Configure summary
1=================
2…
3C++ compiler flags …................. -O0 -ftrapv -g3 -std=c++20 -fPIC -fdebug-prefix-map=/Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/src=. -fmacro-prefix-map=/Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/src=. …

I would expect it to use paths like ./<file> for debugging symbols, but it’s not the case (note the LineEntry field below):

 0$ lldb build/src/bitcoind
 1(lldb) target create "build/src/bitcoind"
 2Current executable set to '/Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/build/src/bitcoind' (arm64).
 3
 4(lldb) image lookup -vn main
 51 match found in /Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/build/src/bitcoind:
 6        Address: bitcoind[0x00000001000050f0] (bitcoind.__TEXT.__text + 1680)
 7        Summary: bitcoind`main at bitcoind.cpp:256
 8         Module: file = "/Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/build/src/bitcoind", arch = "arm64"
 9    CompileUnit: id = {0x00000000}, file = "/Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/build/src/bitcoind.cpp", language = "c++14"
10       Function: id = {0x400000000006a2ee}, name = "main", range = [0x00000001000050f0-0x0000000100005398)
11       FuncType: id = {0x400000000006a2ee}, byte-size = 0, decl = bitcoind.cpp:255, compiler_type = "int (int, char **)"
12         Blocks: id = {0x400000000006a2ee}, range = [0x1000050f0-0x100005398)
13      LineEntry: [0x00000001000050f0-0x0000000100005128): /Users/jose.edil/2-development/bitcoin/bitcoin-core-dev/build/src/bitcoind.cpp:256
14         Symbol: id = {0x00023777}, range = [0x00000001000050f0-0x0000000100005398), name="main"
15       Variable: id = {0x400000000006a308}, name = "argc", type = "int", valid ranges = <block>, location = DW_OP_breg31 WSP+88, decl = bitcoind.cpp:255
16       Variable: id = {0x400000000006a317}, name = "argv", type = "char **", valid ranges = <block>, location = DW_OP_breg31 WSP+80, decl = bitcoind.cpp:255
17       Variable: id = {0x400000000006a326}, name = "node", type = "NodeContext", valid ranges = <block>, location = DW_OP_breg31 WSP+136, decl = bitcoind.cpp:262
18       Variable: id = {0x400000000006a336}, name = "exit_status", type = "int", valid ranges = <block>, location = DW_OP_breg31 WSP+132, decl = bitcoind.cpp:263
19       Variable: id = {0x400000000006a346}, name = "init", type = "unique_ptr<interfaces::Init, std::__1::default_delete<interfaces::Init> >", valid ranges = <block>, location = DW_OP_breg31 WSP+120, decl = bitcoind.cpp:264
20       Variable: id = {0x400000000006a356}, name = "args", type = "ArgsManager &", valid ranges = <block>, location = DW_OP_breg31 WSP+56, decl = bitcoind.cpp:277

rkrux commented at 11:36 am on February 25, 2025: contributor

But I found I needed to create a .lldbinit file with these lines: @pinheadmz Has this fixed the mapping in your system permanently? I have not tried this yet and I observe that the source file detection fails because it seems to be generated in a new location everytime I build again like in the below errors.

0Breakpoint at /Users/rkrux/projects/bitcoin/src/script/descriptor.cpp:1512 could not be resolved, but a valid location was found at /Users/rkrux/projects/bitcoin/build/src/script/descriptor.cpp:1512
1
2Breakpoint at /Users/rkrux/projects/bitcoin/src/wallet/wallet.cpp:1326 could not be resolved, but a valid location was found at /Users/rkrux/projects/bitcoin/build/src/wallet/wallet/wallet.cpp:1326

I will try this solution.

pinheadmz commented at 6:56 pm on February 25, 2025: member

I’m still tweaking the .lldbinit file actually – sometimes I’ll be debugging with lldb and end up in a new directory I hadn’t linked yet like /fuzz or something and it’ll break again. So I suspect there is a simple catch all solution I just haven’t figured it out yet

maflcko added the label Build system on Feb 25, 2025

maflcko added the label Docs on Feb 25, 2025

maflcko added the label Tests on Feb 25, 2025

fanquake commented at 11:25 am on March 5, 2025: member

It’s not clear if this is something that needs to be fixed, (is a regression), or if it’s a behaviour change that needs to be documented in some way, (in the developer notes), or something else? cc @hebasto

fanquake added this to the milestone 29.0 on Mar 5, 2025

hodlinator commented at 2:07 pm on March 5, 2025: contributor

I find it okay to have to set a mapping for the root directory, but I currently need things like:

0"/home/hodlinator/b2/build/src/test/util/test/util/": "/home/hodlinator/b2/src/test/util/"

Note how the subdirectory needs to be repeated for it to work: test/util/test/util/

Same thing happened for rkrux above:

0...valid location was found at /Users/rkrux/projects/bitcoin/build/src/wallet/wallet/wallet.cpp

hebasto commented at 2:40 pm on March 5, 2025: member

@hodlinator

Mind submitting a PR?

hodlinator commented at 2:51 pm on March 5, 2025: contributor

Any idea where to start looking for the duplicate subdirectory issue? Where do we get the virtual build/src/ paths to begin with?

willcl-ark commented at 10:36 pm on March 20, 2025: member

This seems to work for me on Linux without any .lldbinit file:

 0will@ubuntu in …/src/core/bitcoin on  master [$] via △ v3.31.6 : 🐍 (core)
 1$ just clean build-depends
 2depends build running
 3copying packages: boost libevent qt expat libxcb xcb_proto libXau xproto freetype fontconfig libxkbcommon libxcb_util libxcb_util_render libxcb_util_keysyms libxcb_util_image libxcb_util_wm qrencode bdb sqlite systemtap zeromq
 4to: /home/will/src/core/bitcoin/depends/x86_64-pc-linux-gnu
 5To build Bitcoin Core with these packages, pass '--toolchain /home/will/src/core/bitcoin/depends/x86_64-pc-linux-gnu/toolchain.cmake' to the first CMake invocation.
 6depends build complete
 7configure running
 8configure complete
 9build running
10build complete
11
12will@ubuntu in …/src/core/bitcoin on  master [$] via △ v3.31.6 : 🐍 (core) took 2m13s
13$ lldb --version
14lldb version 19.1.7
15
16will@ubuntu in …/src/core/bitcoin on  master [$] via △ v3.31.6 : 🐍 (core) took 27s
17$ lldb
18(lldb) target create build/bin/bitcoind
19Current executable set to '/home/will/src/core/bitcoin/build/bin/bitcoind' (x86_64).
20(lldb) image lookup -vn  ProcessMessages
211 match found in /home/will/src/core/bitcoin/build/bin/bitcoind:
22        Address: bitcoind[0x00000000004c7d20] (bitcoind.PT_LOAD[1]..text + 1016240)
23        Summary: bitcoind`(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&) at net_processing.cpp:4927
24         Module: file = "/home/will/src/core/bitcoin/build/bin/bitcoind", arch = "x86_64"
25    CompileUnit: id = {0x0000001d}, file = "/home/will/src/core/bitcoin/src/net_processing.cpp", language = "c++14"
26       Function: id = {0x007eedbb}, name = "(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&)", mangled = "_ZN12_GLOBAL__N_115PeerManagerImpl15ProcessMessagesEP5CNodeRSt6atomicIbE", range = [0x00000000004c7d20-0x00000000004c8b17)
27       FuncType: id = {0x007eedbb}, byte-size = 0, decl = net_processing.cpp:495, compiler_type = "_Bool (class CNode *, struct std::atomic<_Bool> &)"
28         Blocks: id = {0x007eedbb}, range = [0x004c7d20-0x004c8b17)
29      LineEntry: [0x00000000004c7d20-0x00000000004c7d4f): /home/will/src/core/bitcoin/src/net_processing.cpp:4927
30         Symbol: id = {0x00001b57}, range = [0x00000000004c7d20-0x00000000004c8b17), name="(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&)", mangled="_ZN12_GLOBAL__N_115PeerManagerImpl15ProcessMessagesEP5CNodeRSt6atomicIbE"
31       Variable: id = {0x007eedf7}, name = "peer", type = "PeerRef", valid ranges = <block>, location = DW_OP_fbreg +80, decl = net_processing.cpp:4931
32       Variable: id = {0x007eee06}, name = "poll_result", type = "optional<std::pair<CNetMessage, bool> >", valid ranges = <block>, location = DW_OP_fbreg +288, decl = net_processing.cpp:4962
33
34(lldb)

Perhaps #31161 affected this, or is it a macOS-specific issue? Is it still an issue on current master?

 0
 1Configuring secp256k1 subtree...
 2
 3
 4secp256k1 configure summary
 5===========================
 6Build artifacts:
 7  library type ........................ Static
 8Optional modules:
 9  ECDH ................................ OFF
10  ECDSA pubkey recovery ............... ON
11  extrakeys ........................... ON
12  schnorrsig .......................... ON
13  musig ............................... OFF
14  ElligatorSwift ...................... ON
15Parameters:
16  ecmult window size .................. 15
17  ecmult gen table size ............... 86 KiB
18Optional features:
19  assembly ............................ x86_64
20  external callbacks .................. OFF
21Optional binaries:
22  benchmark ........................... OFF
23  noverify_tests ...................... ON
24  tests ............................... ON
25  exhaustive tests .................... ON
26  ctime_tests ......................... OFF
27  examples ............................ OFF
28
29Cross compiling ....................... FALSE
30Valgrind .............................. OFF
31Preprocessor defined macros ........... ENABLE_MODULE_ELLSWIFT=1 ENABLE_MODULE_SCHNORRSIG=1 ENABLE_MODULE_EXTRAKEYS=1 ENABLE_MODULE_RECOVERY=1 ECMULT_WINDOW_SIZE=15 COMB_BLOCKS=43 COMB_TEETH=6 USE_ASM_X86_64=1
32C compiler ............................ Clang 19.1.7, /usr/lib/ccache/clang
33CFLAGS ................................ -pipe -std=c11
34Compile options ....................... -pedantic -Wall -Wcast-align -Wconditional-uninitialized -Wextra -Wnested-externs -Wno-long-long -Wno-overlength-strings -Wno-unused-function -Wreserved-identifier -Wshadow -Wstrict-prototypes -Wundef
35Build type:
36 - CMAKE_BUILD_TYPE ................... RelWithDebInfo
37 - CFLAGS ............................. -O2 -O2 -g 
38 - LDFLAGS for executables ............ 
39 - LDFLAGS for shared libraries ....... 
40
41
42
43Configure summary
44=================
45Executables:
46  bitcoind ............................ ON
47  bitcoin-node (multiprocess) ......... OFF
48  bitcoin-qt (GUI) .................... ON
49  bitcoin-gui (GUI, multiprocess) ..... OFF
50  bitcoin-cli ......................... ON
51  bitcoin-tx .......................... ON
52  bitcoin-util ........................ ON
53  bitcoin-wallet ...................... ON
54  bitcoin-chainstate (experimental) ... OFF
55  libbitcoinkernel (experimental) ..... OFF
56Optional features:
57  wallet support ...................... ON
58   - legacy wallets (Berkeley DB) ..... ON
59  external signer ..................... ON
60  ZeroMQ .............................. ON
61  USDT tracing ........................ ON
62  QR code (GUI) ....................... ON
63  DBus (GUI, Linux only) .............. ON
64Tests:
65  test_bitcoin ........................ ON
66  test_bitcoin-qt ..................... ON
67  bench_bitcoin ....................... OFF
68  fuzz binary ......................... OFF
69
70Cross compiling ....................... FALSE
71C++ compiler .......................... Clang 19.1.7, /usr/lib/ccache/clang++
72CMAKE_BUILD_TYPE ...................... RelWithDebInfo
73Preprocessor defined macros ........... 
74C++ compiler flags .................... -pipe -std=c++20 -O2 -O2 -g -std=c++20 -fPIC -fdebug-prefix-map=/home/will/src/core/bitcoin/src=. -fmacro-prefix-map=/home/will/src/core/bitcoin/src=. -Wall -Wextra -Wgnu -Wformat -Wformat-security -Wvla -Wshadow-field -Wthread-safety -Wloop-analysis -Wredundant-decls -Wunused-member-function -Wdate-time -Wconditional-uninitialized -Woverloaded-virtual -Wsuggest-override -Wimplicit-fallthrough -Wunreachable-code -Wdocumentation -Wself-assign -Wundef -Wno-unused-parameter -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3 -Wstack-protector -fstack-protector-all -fcf-protection=full -fstack-clash-protection
75Linker flags .......................... -pipe -std=c++20 -O2 -O2 -g -fuse-ld=mold -fstack-protector-all -fcf-protection=full -fstack-clash-protection -Wl,-z,relro -Wl,-z,now -Wl,-z,separate-code -fPIE -pie
76
77NOTE: The summary above may not exactly match the final applied build flags
78      if any additional CMAKE_* or environment variables have been modified.
79      To see the exact flags applied, build with the --verbose option.
80
81Attempt to harden executables ......... ON
82Treat compiler warnings as errors ..... OFF
83Use ccache for compiling .............. ON

maflcko commented at 7:44 am on March 21, 2025: member

I find it okay to have to set a mapping for the root directory, but I currently need things like:
0"/home/hodlinator/b2/build/src/test/util/test/util/": "/home/hodlinator/b2/src/test/util/"
Note how the subdirectory needs to be repeated for it to work: test/util/test/util/

Same thing happened for rkrux above:
0...valid location was found at /Users/rkrux/projects/bitcoin/build/src/wallet/wallet/wallet.cpp

I am also seeing non-existent folders in #31957:

0  ./bld-c/src/crypto/./src/compat/byteswap.h
1  ./bld-c/src/crypto/./src/crypto/sha256.cpp
2  ./bld-c/src/crypto/./src/crypto/sha512.cpp
3  ./bld-c/src/test/./src/test/crypto_tests.cpp
4  ./bld-c/src/test/./src/test/util_tests.cpp
5  ./bld-c/src/util/./src/random.cpp
6  ./bld-c/src/util/./src/util/string.cpp

With the steps to reproduce there, it is a cmake regression. I am not sure if callgrind_annotate allows mapping, so it may be best to fix this inside the build system itself.

hebasto commented at 12:19 pm on March 26, 2025: member

#31204 (comment):

This seems to work for me on Linux without any .lldbinit file:

I tested v28.1 on Ubuntu 24.04 with GCC 13.3:

 0$ ./configure --enable-ccache
 1$ make -j $(nproc) src/bitcoind
 2$ lldb
 3(lldb) version
 4lldb version 18.1.3
 5(lldb) target create src/bitcoind
 6Current executable set to '/home/hebasto/dev/bitcoin/src/bitcoind' (x86_64).
 7(lldb) settings show target.source-map
 8target.source-map (path-map) =
 9(lldb) image lookup -vn ProcessMessages
101 match found in /home/hebasto/dev/bitcoin/src/bitcoind:
11        Address: bitcoind[0x00000000001e31e0] (bitcoind.PT_LOAD[1]..text + 1776496)
12        Summary: bitcoind`(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&)
13         Module: file = "/home/hebasto/dev/bitcoin/src/bitcoind", arch = "x86_64"
14    CompileUnit: id = {0x00000008}, file = "src/net_processing.cpp", language = "c++14"
15      LineEntry: [0x00000000001e31e0-0x00000000001e31f1): src/net_processing.cpp:5380:1
16         Symbol: id = {0x000003ed}, range = [0x00000000001e31e0-0x00000000001e3cf0), name="(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&)", mangled="_ZN12_GLOBAL__N_115PeerManagerImpl15ProcessMessagesEP5CNodeRSt6atomicIbE"
17
18(lldb) settings set target.source-map ./src /home/hebasto/dev/bitcoin/src
19(lldb) settings show target.source-map
20target.source-map (path-map) =
21[0] "src" -> "/home/hebasto/dev/bitcoin/src"
22
23(lldb) image lookup -vn ProcessMessages
241 match found in /home/hebasto/dev/bitcoin/src/bitcoind:
25        Address: bitcoind[0x00000000001e31e0] (bitcoind.PT_LOAD[1]..text + 1776496)
26        Summary: bitcoind`(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&)
27         Module: file = "/home/hebasto/dev/bitcoin/src/bitcoind", arch = "x86_64"
28    CompileUnit: id = {0x00000008}, file = "src/net_processing.cpp", language = "c++14"
29      LineEntry: [0x00000000001e31e0-0x00000000001e31f1): src/net_processing.cpp:5380:1
30         Symbol: id = {0x000003ed}, range = [0x00000000001e31e0-0x00000000001e3cf0), name="(anonymous namespace)::PeerManagerImpl::ProcessMessages(CNode*, std::atomic<bool>&)", mangled="_ZN12_GLOBAL__N_115PeerManagerImpl15ProcessMessagesEP5CNodeRSt6atomicIbE"

So the guideline for lldb does not work in my build environment, even for the pre-CMake branch.

Source code mapping for debugger has changed since cmake #31204