[BUG] r29: LLDB fails to locate bundled `libpython3.11.dylib` on macOS due to missing rpath

[bc-lee]

Description

Summary

The LLDB binary bundled with the Android NDK fails to launch on macOS because dyld cannot resolve @rpath/libpython3.11.dylib referenced by liblldb.dylib.
The launcher script (lldb.sh) sets PYTHONHOME and DYLD_LIBRARY_PATH to the bundled Python, but @rpath resolution does not consult DYLD_LIBRARY_PATH.
Since python3/lib is not included in any LC_RPATH entries, dyld cannot locate the bundled libpython3.11.dylib.

Environment

• macOS (15.7.1), Apple Silicon (arm64)
• Android NDK 29.0.14206865 (toolchains/llvm/prebuilt/darwin-x86_64)

Steps to Reproduce

1. Run the bundled lldb through its launcher script with tracing enabled:

$ bash -x /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb.sh
+++ dirname /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb.sh
++ cd /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin
++ pwd
+ CURDIR=/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin
+ export PYTHONHOME=/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/../python3
+ PYTHONHOME=/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/../python3
+ export DYLD_LIBRARY_PATH=/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/../python3/lib:
+ DYLD_LIBRARY_PATH=/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/../python3/lib:
+ /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb
dyld[10828]: Library not loaded: @rpath/libpython3.11.dylib
  Referenced from: <20442980-137B-3050-92EA-7E694B598235> /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/lib/liblldb.dylib
  Reason: tried: '/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/lib/../lib/libpython3.11.dylib' (no such file), '/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/../lib/libpython3.11.dylib' (no such file), '/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/../lib/libpython3.11.dylib' (no such file), '/usr/lib/libpython3.11.dylib' (no such file, not in dyld cache)
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb.sh: line 5: 10828 Abort trap: 6              "$CURDIR/lldb" "$@"

Expected Result

• lldb launches successfully and uses the bundled Python library.

Actual Result

• dyld aborts because it cannot resolve @rpath/libpython3.11.dylib.

Layout/Evidence

/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64
├── AndroidVersion.txt
├── bin
│   ├── aarch64-linux-android21-clang
...
│   ├── lldb
│   ├── lldb.sh
...
├── lib
│   ├── clang
│   │   └── 21
...
│   ├── liblldb.dylib
...
├── python3
│   ├── bin
│   │   ├── python3 -> python3.11
│   ├── lib
│   │   ├── libpython3.11.dylib
...

$ otool -L /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb (architecture x86_64):
	@rpath/liblldb.dylib (compatibility version 0.0.0, current version 21.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)
	@rpath/libc++.dylib (compatibility version 1.0.0, current version 1.0.0)
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/bin/lldb (architecture arm64):
	@rpath/liblldb.dylib (compatibility version 0.0.0, current version 21.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)
	@rpath/libc++.dylib (compatibility version 1.0.0, current version 1.0.0)

$ otool -L /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/python3/lib/libpython3.11.dylib
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/python3/lib/libpython3.11.dylib (architecture x86_64):
	@rpath/libpython3.11.dylib (compatibility version 3.11.0, current version 3.11.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1292.100.5)
	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1775.118.101)
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/python3/lib/libpython3.11.dylib (architecture arm64):
	@rpath/libpython3.11.dylib (compatibility version 3.11.0, current version 3.11.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1292.100.5)
	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1775.118.101)

$ otool -L /path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/lib/liblldb.dylib
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/lib/liblldb.dylib (architecture x86_64):
	@rpath/liblldb.dylib (compatibility version 0.0.0, current version 21.0.0)
	/usr/lib/libcompression.dylib (compatibility version 1.0.0, current version 1.0.0)
	@rpath/libpython3.11.dylib (compatibility version 3.11.0, current version 3.11.0)
	@rpath/libncurses.6.dylib (compatibility version 6.0.0, current version 6.0.0)
	@rpath/libform.6.dylib (compatibility version 6.0.0, current version 6.0.0)
	@rpath/libpanel.6.dylib (compatibility version 6.0.0, current version 6.0.0)
	@rpath/libxml2.2.dylib (compatibility version 2.0.0, current version 2.14.0)
	@rpath/libedit.0.dylib (compatibility version 1.0.0, current version 1.61.0)
	/System/Library/Frameworks/Foundation.framework/Versions/C/Foundation (compatibility version 300.0.0, current version 1856.105.0)
	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1856.105.0)
	/System/Library/Frameworks/CoreServices.framework/Versions/A/CoreServices (compatibility version 1.0.0, current version 1141.1.0)
	/System/Library/Frameworks/Security.framework/Versions/A/Security (compatibility version 1.0.0, current version 60157.60.19)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0)
	@rpath/libc++.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libobjc.A.dylib (compatibility version 1.0.0, current version 228.0.0)
/path/to/android/sdk/ndk/29.0.14206865/toolchains/llvm/prebuilt/darwin-x86_64/lib/liblldb.dylib (architecture arm64):
	@rpath/liblldb.dylib (compatibility version 0.0.0, current version 21.0.0)
	/usr/lib/libcompression.dylib (compatibility version 1.0.0, current version 1.0.0)
	@rpath/libpython3.11.dylib (compatibility version 3.11.0, current version 3.11.0)
	@rpath/libncurses.6.dylib (compatibility version 6.0.0, current version 6.0.0)
	@rpath/libform.6.dylib (compatibility version 6.0.0, current version 6.0.0)
	@rpath/libpanel.6.dylib (compatibility version 6.0.0, current version 6.0.0)
	@rpath/libxml2.2.dylib (compatibility version 2.0.0, current version 2.14.0)
	@rpath/libedit.0.dylib (compatibility version 1.0.0, current version 1.61.0)
	/System/Library/Frameworks/Foundation.framework/Versions/C/Foundation (compatibility version 300.0.0, current version 1856.105.0)
	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1856.105.0)
	/System/Library/Frameworks/CoreServices.framework/Versions/A/CoreServices (compatibility version 1.0.0, current version 1141.1.0)
	/System/Library/Frameworks/Security.framework/Versions/A/Security (compatibility version 1.0.0, current version 60157.60.19)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.11)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1311.0.0)
	@rpath/libc++.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libobjc.A.dylib (compatibility version 1.0.0, current version 228.0.0)

Analysis

• liblldb.dylib depends on @rpath/libpython3.11.dylib.
• The current LC_RPATH entries only include relative paths to ../lib, excluding ../python3/lib.
• On macOS, @rpath resolution is driven solely by LC_RPATH entries—DYLD_LIBRARY_PATH is not considered when resolving @rpath-prefixed install names.
• As a result, setting DYLD_LIBRARY_PATH in lldb.sh does not affect this lookup.

Workarounds

To make LLDB functional locally, manually add an rpath to point at the bundled Python library:

# Option 1: Modify liblldb.dylib
install_name_tool -add_rpath "@loader_path/../python3/lib" \
  /path/to/.../lib/liblldb.dylib

# Option 2: Modify the lldb executable
install_name_tool -add_rpath "@executable_path/../python3/lib" \
  /path/to/.../bin/lldb

Validate the change:

otool -l /path/to/.../lib/liblldb.dylib | awk '/LC_RPATH/,/path/'
otool -l /path/to/.../bin/lldb | awk '/LC_RPATH/,/path/'

After modification, re-sign or strip and re-sign the binaries to restore valid signatures:

codesign --force --sign - --timestamp=none /path/to/.../lib/liblldb.dylib
codesign --force --sign - --timestamp=none /path/to/.../bin/lldb

This workaround is suitable for local development only.
Re-signing modified binaries is not appropriate for distributed SDKs.

Proposed Fix (for NDK maintainers)

• Include @loader_path/../python3/lib as an additional LC_RPATH in liblldb.dylib and/or @executable_path/../python3/lib in bin/lldb.
• Avoid relying on DYLD_LIBRARY_PATH for resolving @rpath dependencies.
• The lldb.sh script may still set PYTHONHOME, but DYLD_LIBRARY_PATH becomes unnecessary for this issue.

I am using a supported NDK

• I have checked and the NDK I'm using is currently supported

Affected versions

r29

[DanAlbert]

Hmm, we fixed this before: #2143. The fix for that was https://android.googlesource.com/platform/ndk/+/a89d08d393e59f038eef705ba79868551e9f114a. I'll dig into why that's not working soon and we can pick that up for an r29b.

[DanAlbert]

Actually, looking at the timing I bet the fix just wasn't included in r29. I'd tested r29 by hand at one point, but that was before we'd figured out that unsigned binaries worked but signed ones didn't, and I'd tested an unsigned binary because that's what I have in my dev environment.