blob: 0d2fa2adb8601d30e7a4aa236b9c463f0499aa76 [file] [log] [blame]
#!/usr/bin/env python
# Copyright 2013 The Flutter Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
import argparse
import os
import re
import shutil
import subprocess
import sys
"""Tool for starting a GDB client and server to debug a Flutter engine process on an Android device.
flutter_gdb server com.example.package_name
flutter_gdb client com.example.package_name
The Android package must be marked as debuggable in its manifest.
The "client" command will copy system libraries from the device to the host
in order to provide debug symbols. If this has already been done on a
previous run for a given device, then you can skip this step by passing
ADB_LOCAL_PATH = 'third_party/android_tools/sdk/platform-tools/adb'
def _get_flutter_root():
path = os.path.dirname(os.path.abspath(__file__))
while os.path.basename(path) != 'src':
path = os.path.dirname(path)
return path
def _find_package_pid(adb_path, package):
"""Find the pid of the Flutter application process."""
ps_output = subprocess.check_output([adb_path, 'shell', 'ps'])
ps_match ='^\S+\s+(\d+).*\s%s' % package, ps_output, re.MULTILINE)
if not ps_match:
print 'Unable to find pid for package %s on device' % package
return None
return int(
def _get_device_abi(adb_path):
abi_output = subprocess.check_output(
[adb_path, 'shell', 'getprop', 'ro.product.cpu.abi']).strip()
if abi_output.startswith('arm64'):
return 'arm64'
if abi_output.startswith('arm'):
return 'arm'
return abi_output
def _default_local_engine(abi):
"""Return the default Flutter build output directory for a given target ABI."""
if abi == 'x86':
return 'android_debug_unopt_x86'
elif abi == 'x86_64':
return 'android_debug_unopt_x64'
elif abi == 'arm64':
return 'android_debug_unopt_arm64'
return 'android_debug_unopt'
class GdbClient(object):
SYSTEM_LIBS_PATH = '/tmp/flutter_gdb_device_libs'
def _gdb_local_path(self):
GDB_LOCAL_PATH = ('third_party/android_tools/ndk/prebuilt/%s-x86_64/bin/gdb-orig')
if sys.platform.startswith('darwin'):
return GDB_LOCAL_PATH % 'darwin'
return GDB_LOCAL_PATH % 'linux'
def add_subparser(self, subparsers):
parser = subparsers.add_parser('client',
help='run a GDB client')
parser.add_argument('package', type=str)
parser.add_argument('--local-engine', type=str)
parser.add_argument('--gdb-port', type=int, default=8888)
parser.add_argument('--no-pull-libs', action="store_false",
default=True, dest="pull_libs",
help="Do not copy system libraries from the device to the host")
parser.add_argument('--old-sysroot', action="store_true", default=False,
help='Create a sysroot tree suitable for debugging on older (pre-N) versions of Android')
def _copy_system_libs(self, adb_path, package, old_sysroot):
"""Copy libraries used by the Flutter process from the device to the host."""
package_pid = _find_package_pid(adb_path, package)
if package_pid is None:
return False
# Find library files that are mapped into the process.
proc_maps = subprocess.check_output(
[adb_path, 'shell', 'run-as', package, 'cat', '/proc/%d/maps' % package_pid])
proc_libs = re.findall('(/system/.*\.(?:so|oat))\s*$', proc_maps, re.MULTILINE)
if old_sysroot:
device_libs = set((lib, os.path.basename(lib)) for lib in proc_libs)
device_libs.add(('/system/bin/linker', 'linker'))
device_libs = set((lib, lib[1:]) for lib in proc_libs)
device_libs.add(('/system/bin/linker', 'system/bin/linker'))
device_libs.add(('/system/bin/app_process32', 'system/bin/app_process32'))
device_libs.add(('/system/bin/app_process64', 'system/bin/app_process64'))
if os.path.isdir(GdbClient.SYSTEM_LIBS_PATH):
dev_null = open(os.devnull, 'w')
for lib, local_path in sorted(device_libs):
print 'Copying %s' % lib
local_path = os.path.join(GdbClient.SYSTEM_LIBS_PATH, local_path)
if not os.path.exists(os.path.dirname(local_path)):
os.makedirs(os.path.dirname(local_path))[adb_path, 'pull', lib, local_path], stderr=dev_null)
return True
def run(self, args):
flutter_root = _get_flutter_root()
if args.adb is None:
adb_path = os.path.join(flutter_root, ADB_LOCAL_PATH)
adb_path = args.adb
if args.pull_libs:
if not self._copy_system_libs(adb_path, args.package, args.old_sysroot):
return 1
[adb_path, 'forward', 'tcp:%d' % args.gdb_port, 'tcp:%d' % args.gdb_port])
if args.local_engine is None:
abi = _get_device_abi(adb_path)
local_engine = _default_local_engine(abi)
local_engine = args.local_engine
debug_out_path = os.path.join(flutter_root, 'out/%s' % local_engine)
if not os.path.exists(os.path.join(debug_out_path, '')):
print 'Unable to find Make sure you have completed a %s build' % local_engine
return 1
eval_commands = []
if not args.old_sysroot:
eval_commands.append('set sysroot %s' % GdbClient.SYSTEM_LIBS_PATH)
eval_commands.append('set solib-search-path %s:%s' %
(debug_out_path, GdbClient.SYSTEM_LIBS_PATH))
eval_commands.append('target remote localhost:%d' % args.gdb_port)
exec_command = [os.path.join(flutter_root, self._gdb_local_path())]
for command in eval_commands:
exec_command += ['--eval-command', command]
os.execv(exec_command[0], exec_command)
class GdbServer(object):
GDB_SERVER_DEVICE_TMP_PATH = '/data/local/tmp/gdbserver'
def add_subparser(self, subparsers):
parser = subparsers.add_parser('server',
help='run a GDB server on the device')
parser.add_argument('package', type=str)
parser.add_argument('--gdb-port', type=int, default=8888)
def run(self, args):
flutter_root = _get_flutter_root()
if args.adb is None:
adb_path = os.path.join(flutter_root, ADB_LOCAL_PATH)
adb_path = args.adb
package_pid = _find_package_pid(adb_path, args.package)
if package_pid is None:
return 1
abi = _get_device_abi(adb_path)
gdb_server_local_path = 'third_party/android_tools/ndk/prebuilt/android-%s/gdbserver/gdbserver' % abi
# Copy gdbserver to the package's data directory.
subprocess.check_call([adb_path, 'push',
os.path.join(flutter_root, gdb_server_local_path),
gdb_server_device_path = '/data/data/%s/gdbserver' % args.package
subprocess.check_call([adb_path, 'shell', 'run-as', args.package, 'cp', '-F',
gdb_server_device_path])[adb_path, 'shell', 'run-as', args.package,
'killall', 'gdbserver'])
# Run gdbserver.
try:[adb_path, 'shell', 'run-as', args.package,
'--attach', ':%d' % args.gdb_port, str(package_pid)])
except KeyboardInterrupt:
def main():
parser = argparse.ArgumentParser(description='Flutter debugger tool')
subparsers = parser.add_subparsers(help='sub-command help')
parser.add_argument('--adb', type=str, help='path to ADB tool')
commands = [
for command in commands:
args = parser.parse_args()
return args.func(args)
if __name__ == '__main__':