ndk-gdb revision e3cfafbda4b0b3cff9360a64c12b5af11a4ad4e0
1#!/bin/sh 2# 3# Copyright (C) 2010 The Android Open Source Project 4# 5# Licensed under the Apache License, Version 2.0 (the "License"); 6# you may not use this file except in compliance with the License. 7# You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, software 12# distributed under the License is distributed on an "AS IS" BASIS, 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14# See the License for the specific language governing permissions and 15# limitations under the License. 16# 17 18# This wrapper script is used to launch a native debugging session 19# on a given NDK application. The application must be debuggable, i.e. 20# its android:debuggable attribute must be set to 'true' in the 21# <application> element of its manifest. 22# 23# See docs/NDK-GDB.TXT for usage description. Essentially, you just 24# need to launch ndk-gdb from your application project directory 25# after doing ndk-build && ant install && <start-application-on-device> 26# 27. `dirname $0`/build/core/ndk-common.sh 28 29force_32bit_binaries 30 31find_program ADB_CMD adb 32ADB_FLAGS= 33 34AWK_CMD=awk 35 36DEBUG_PORT=5039 37 38# Delay in seconds between launching the activity and attaching gdbserver on it. 39# This is needed because there is no way to know when the activity has really 40# started, and sometimes this takes a few seconds. 41DELAY=2 42 43PARAMETERS= 44OPTION_HELP=no 45OPTION_PROJECT= 46OPTION_FORCE=no 47OPTION_ADB= 48OPTION_EXEC= 49OPTION_START=no 50OPTION_LAUNCH= 51OPTION_LAUNCH_LIST=no 52OPTION_DELAY= 53 54check_parameter () 55{ 56 if [ -z "$2" ]; then 57 echo "ERROR: Missing parameter after option '$1'" 58 exit 1 59 fi 60} 61 62check_adb_flags () 63{ 64 if [ -n "$ADB_FLAGS" ] ; then 65 echo "ERROR: Only one of -e, -d or -s <serial> can be used at the same time!" 66 exit 1 67 fi 68} 69 70get_build_var () 71{ 72 if [ -z "$GNUMAKE" ] ; then 73 GNUMAKE=make 74 fi 75 $GNUMAKE --no-print-dir -f $ANDROID_NDK_ROOT/build/core/build-local.mk -C $PROJECT DUMP_$1 76} 77 78get_build_var_for_abi () 79{ 80 if [ -z "$GNUMAKE" ] ; then 81 GNUMAKE=make 82 fi 83 $GNUMAKE --no-print-dir -f $ANDROID_NDK_ROOT/build/core/build-local.mk -C $PROJECT DUMP_$1 APP_ABI=$2 84} 85 86# Used to run an awk script on the manifest 87run_awk_manifest_script () 88{ 89 $AWK_CMD -f $AWK_SCRIPTS/$1 $PROJECT/$MANIFEST 90} 91 92if [ "$HOST_OS" = "cygwin" ] ; then 93# Return native path representation from cygwin one 94# $1: a cygwin-compatible path (e.g. /cygdrive/c/some/thing) 95# Return: path in host windows representation, e.g. C:/some/thing 96# 97# We use mixed mode (i.e. / as the directory separator) because 98# all the tools we use recognize it properly, and it avoids lots 99# of escaping nonsense associated with "\" 100# 101native_path () 102{ 103 cygpath -m $1 104} 105else # HOST_OS != windows 106native_path () 107{ 108 echo "$1" 109} 110fi # HOST_OS != windows 111 112VERBOSE=no 113while [ -n "$1" ]; do 114 opt="$1" 115 optarg=`expr "x$opt" : 'x[^=]*=\(.*\)'` 116 case "$opt" in 117 --help|-h|-\?) 118 OPTION_HELP=yes 119 ;; 120 --verbose) 121 VERBOSE=yes 122 ;; 123 -s) 124 check_parameter $1 $2 125 check_adb_flags 126 ADB_FLAGS=" -s $2" 127 shift 128 ;; 129 -s*) 130 check_adb_flags 131 optarg=`expr -- "$opt" : '-s\(.*\)'` 132 ADB_FLAGS=" -s $optarg" 133 ;; 134 -p) 135 check_parameter $1 $2 136 OPTION_PROJECT="$2" 137 shift 138 ;; 139 -p*) 140 optarg=`expr -- "$opt" : '-p\(.*\)'` 141 OPTION_PROJECT="$optarg" 142 ;; 143 --exec=*) 144 OPTION_EXEC="$optarg" 145 ;; 146 -x) 147 check_parameter $1 $2 148 OPTION_EXEC="$2" 149 shift 150 ;; 151 -x*) 152 optarg=`expr -- "$opt" : '-x\(.*\)'` 153 OPTION_EXEC="$optarg" 154 ;; 155 -e) 156 check_adb_flags 157 ADB_FLAGS=" -e" 158 ;; 159 -d) 160 check_adb_flags 161 ADB_FLAGS=" -d" 162 ;; 163 --adb=*) # specify ADB command 164 OPTION_ADB="$optarg" 165 ;; 166 --awk=*) 167 AWK_CMD="$optarg" 168 ;; 169 --project=*) 170 OPTION_PROJECT="$optarg" 171 ;; 172 --port=*) 173 DEBUG_PORT="$optarg" 174 ;; 175 --force) 176 OPTION_FORCE="yes" 177 ;; 178 --launch-list) 179 OPTION_LAUNCH_LIST="yes" 180 ;; 181 --launch=*) 182 OPTION_LAUNCH="$optarg" 183 ;; 184 --start) 185 OPTION_START=yes 186 ;; 187 --delay=*) 188 OPTION_DELAY="$optarg" 189 ;; 190 -*) # unknown options 191 echo "ERROR: Unknown option '$opt', use --help for list of valid ones." 192 exit 1 193 ;; 194 *) # Simply record parameter 195 if [ -z "$PARAMETERS" ] ; then 196 PARAMETERS="$opt" 197 else 198 PARAMETERS="$PARAMETERS $opt" 199 fi 200 ;; 201 esac 202 shift 203done 204 205if [ "$OPTION_HELP" = "yes" ] ; then 206 echo "Usage: $PROGNAME [options]" 207 echo "" 208 echo "Setup a gdb debugging session for your Android NDK application." 209 echo "Read $$NDK/docs/NDK-GDB.TXT for complete usage instructions." 210 echo "" 211 echo "Valid options:" 212 echo "" 213 echo " --help|-h|-? Print this help" 214 echo " --verbose Enable verbose mode" 215 echo " --force Kill existing debug session if it exists" 216 echo " --start Launch application instead of attaching to existing one" 217 echo " --launch=<name> Same as --start, but specify activity name (see below)" 218 echo " --launch-list List all launchable activity names from manifest" 219 echo " --delay=<secs> Delay in seconds between activity start and gdbserver attach." 220 echo " --project=<path> Specify application project path" 221 echo " -p <path> Same as --project=<path>" 222 echo " --port=<port> Use tcp:localhost:<port> to communicate with gdbserver [$DEBUG_PORT]" 223 echo " --exec=<file> Execute gdb initialization commands in <file> after connection" 224 echo " -x <file> Same as --exec=<file>" 225 echo " --adb=<file> Use specific adb command [$ADB_CMD]" 226 echo " --awk=<file> Use specific awk command [$AWK_CMD]" 227 echo " -e Connect to single emulator instance" 228 echo " -d Connect to single target device" 229 echo " -s <serial> Connect to specific emulator or device" 230 echo "" 231 exit 0 232fi 233 234log "Android NDK installation path: $ANDROID_NDK_ROOT" 235 236if [ -n "$OPTION_EXEC" ] ; then 237 if [ ! -f "$OPTION_EXEC" ]; then 238 echo "ERROR: Invalid initialization file: $OPTION_EXEC" 239 exit 1 240 fi 241fi 242 243if [ -n "$OPTION_DELAY" ] ; then 244 DELAY="$OPTION_DELAY" 245fi 246 247# Check ADB tool version 248if [ -n "$OPTION_ADB" ] ; then 249 ADB_CMD="$OPTION_ADB" 250 log "Using specific adb command: $ADB_CMD" 251else 252 if [ -z "$ADB_CMD" ] ; then 253 echo "ERROR: The 'adb' tool is not in your path." 254 echo " You can change your PATH variable, or use" 255 echo " --adb=<executable> to point to a valid one." 256 exit 1 257 fi 258 log "Using default adb command: $ADB_CMD" 259fi 260 261ADB_VERSION=`$ADB_CMD version` 262if [ $? != 0 ] ; then 263 echo "ERROR: Could not run ADB with: $ADB_CMD" 264 exit 1 265fi 266log "ADB version found: $ADB_VERSION" 267 268ADB_CMD="${ADB_CMD}${ADB_FLAGS}" 269log "Using final ADB command: '$ADB_CMD'" 270 271 272# Used internally by adb_var_shell and adb_var_shell2. This expected 273# ADB_CMD_ERRFD to be defined to a file describing where to send the 274# error output. 275_adb_var_shell () 276{ 277 # We need a temporary file to store the output of our command 278 local CMD_OUT RET OUTPUT VARNAME 279 VARNAME=$1 280 shift 281 CMD_OUT=`mktemp` 282 # Run the command, while storing the standard output to CMD_OUT 283 # and appending the exit code as the last line. 284 $ADB_CMD shell $@ ";" echo \$? | sed -e 's![[:cntrl:]]!!g' > $CMD_OUT 2>$ADB_CMD_ERRFD 285 # Get last line in log, which contains the exit code from the command 286 RET=`sed -e '$!d' $CMD_OUT` 287 # Get output, which corresponds to everything except the last line 288 OUT=`sed -e '$d' $CMD_OUT` 289 rm -f $CMD_OUT 290 eval $VARNAME=\"\$OUT\" 291 return $RET 292} 293 294# Run a command through 'adb shell' and captures its standard output 295# into a variable. The function's exit code is the same than the command's. 296# 297# This is required because there is a bug where "adb shell" always returns 298# 0 on the host, even if the command fails on the device. 299# 300# $1: Variable name (e.g. FOO) 301# On exit, $FOO is set to the command's standard output 302# 303# The return status will be 0 (success) if the command succeeded 304# or 1 (failure) otherwise. 305adb_var_shell () 306{ 307 local ADB_CMD_ERRFD="&2" 308 _adb_var_shell $@ 309} 310 311# A variant of adb_var_shell that stores both stdout and stderr in the output 312# $1: Variable name 313adb_var_shell2 () 314{ 315 local ADB_CMD_ERRFD="&1" 316 _adb_var_shell $@ 317} 318 319# Check the awk tool 320AWK_SCRIPTS=$ANDROID_NDK_ROOT/build/awk 321AWK_TEST=`$AWK_CMD -f $AWK_SCRIPTS/check-awk.awk` 322if [ $? != 0 ] ; then 323 echo "ERROR: Could not run '$AWK_CMD' command. Do you have it installed properly?" 324 exit 1 325fi 326if [ "$AWK_TEST" != "Pass" ] ; then 327 echo "ERROR: Your version of 'awk' is obsolete. Please use --awk=<file> to point to Nawk or Gawk!" 328 exit 1 329fi 330 331# Name of the manifest file 332MANIFEST=AndroidManifest.xml 333 334# Find the root of the application project. 335if [ -n "$OPTION_PROJECT" ] ; then 336 PROJECT=$OPTION_PROJECT 337 log "Using specified project path: $PROJECT" 338 if [ ! -d "$PROJECT" ] ; then 339 echo "ERROR: Your --project option does not point to a directory!" 340 exit 1 341 fi 342 if [ ! -f "$PROJECT/$MANIFEST" ] ; then 343 echo "ERROR: Your --project does not point to an Android project path!" 344 echo " It is missing a $MANIFEST file." 345 exit 1 346 fi 347else 348 # Assume we are in the project directory 349 if [ -f "$MANIFEST" ] ; then 350 PROJECT=. 351 else 352 PROJECT= 353 CURDIR=`pwd` 354 while [ "$CURDIR" != "/" ] ; do 355 if [ -f "$CURDIR/$MANIFEST" ] ; then 356 PROJECT="$CURDIR" 357 break 358 fi 359 CURDIR=`dirname $CURDIR` 360 done 361 if [ -z "$PROJECT" ] ; then 362 echo "ERROR: Launch this script from an application project directory, or use --project=<path>." 363 exit 1 364 fi 365 fi 366 log "Using auto-detected project path: $PROJECT" 367fi 368 369# Extract the package name from the manifest 370PACKAGE_NAME=`run_awk_manifest_script extract-package-name.awk` 371log "Found package name: $PACKAGE_NAME" 372if [ $? != 0 -o "$PACKAGE_NAME" = "<none>" ] ; then 373 echo "ERROR: Could not extract package name from $PROJECT/$MANIFEST." 374 echo " Please check that the file is well-formed!" 375 exit 1 376fi 377 378# If --launch-list is used, list all launchable activities, and be done with it 379if [ "$OPTION_LAUNCH_LIST" = "yes" ] ; then 380 log "Extracting list of launchable activities from manifest:" 381 run_awk_manifest_script extract-launchable.awk 382 exit 0 383fi 384 385APP_ABIS=`get_build_var APP_ABI` 386log "ABIs targetted by application: $APP_ABIS" 387 388# Check the ADB command, and that we can connect to the device/emulator 389ADB_TEST=`$ADB_CMD shell ls` 390if [ $? != 0 ] ; then 391 echo "ERROR: Could not connect to device or emulator!" 392 echo " Please check that an emulator is running or a device is connected" 393 echo " through USB to this machine. You can use -e, -d and -s <serial>" 394 echo " in case of multiple ones." 395 exit 1 396fi 397 398# Check that the device is running Froyo (API Level 8) or higher 399# 400adb_var_shell API_LEVEL getprop ro.build.version.sdk 401if [ $? != 0 -o -z "$API_LEVEL" ] ; then 402 echo "ERROR: Could not find target device's supported API level!" 403 echo "ndk-gdb will only work if your device is running Android 2.2 or higher." 404 exit 1 405fi 406log "Device API Level: $API_LEVEL" 407if [ "$API_LEVEL" -lt "8" ] ; then 408 echo "ERROR: ndk-gdb requires a target device running Android 2.2 (API level 8) or higher." 409 echo "The target device is running API level $API_LEVEL!" 410 exit 1 411fi 412 413# Get the target device's supported ABI(s) 414# And check that they are supported by the application 415# 416COMPAT_ABI=none 417adb_var_shell CPU_ABI getprop ro.product.cpu.abi 418for ABI in $APP_ABIS; do 419 if [ "$ABI" = "$CPU_ABI" ] ; then 420 COMPAT_ABI=$CPU_ABI 421 break 422 fi 423done 424 425adb_var_shell CPU_ABI2 getprop ro.product.cpu.abi2 426if [ $? != 0 -o -z "$CPU_ABI2" ] ; then 427 CPU_ABI2= 428 log "Device CPU ABI: $CPU_ABI" 429else 430 log "Device CPU ABIs: $CPU_ABI $CPU_ABI2" 431 if [ "$COMPAT_ABI" = "none" ] ; then 432 for ABI in $APP_ABIS; do 433 if [ "$ABI" = "$CPU_ABI2" ] ; then 434 COMPAT_ABI=$CPU_ABI2 435 break 436 fi 437 done 438 fi 439fi 440if [ "$COMPAT_ABI" = none ] ; then 441 echo "ERROR: The device does not support the application's targetted CPU ABIs!" 442 if [ "$CPU_ABI2" = "$CPU_ABI" ] ; then 443 CPU_ABI2= 444 fi 445 echo " Device supports: $CPU_ABI $CPU_ABI2" 446 echo " Package supports: $APP_ABIS" 447 exit 1 448fi 449log "Compatible device ABI: $COMPAT_ABI" 450 451# Check that the application is debuggable, or nothing will work 452DEBUGGABLE=`run_awk_manifest_script extract-debuggable.awk` 453log "Found debuggable flag: $DEBUGGABLE" 454if [ $? != 0 -o "$DEBUGGABLE" != "true" ] ; then 455 # If gdbserver exists, then we built with 'ndk-build NDK_DEBUG=1' and it's 456 # ok to not have android:debuggable set to true in the original manifest. 457 # However, if this is not the case, then complain!! 458 if [ -f $PROJECT/libs/$COMPAT_ABI/gdbserver ] ; then 459 log "Found gdbserver under libs/$COMPAT_ABI, assuming app was built with NDK_DEBUG=1" 460 else 461 echo "ERROR: Package $PACKAGE_NAME is not debuggable ! You can fix that in two ways:" 462 echo "" 463 echo " - Rebuilt with the NDK_DEBUG=1 option when calling 'ndk-build'." 464 echo "" 465 echo " - Modify your manifest to set android:debuggable attribute to \"true\"," 466 echo " then rebuild normally." 467 echo "" 468 echo "After one of these, re-install to the device!" 469 exit 1 470 fi 471else 472 # DEBUGGABLE is true in the manifest. Let's check that the user didn't change the 473 # debuggable flag in the manifest without calling ndk-build afterwards. 474 if [ ! -f $PROJECT/libs/$COMPAT_ABI/gdbserver ] ; then 475 echo "ERROR: Could not find gdbserver binary under $PROJECT/libs/$COMPAT_ABI" 476 echo " This usually means you modified your AndroidManifest.xml to set" 477 echo " the android:debuggable flag to 'true' but did not rebuild the" 478 echo " native binaries. Please call 'ndk-build' to do so," 479 echo " *then* re-install to the device!" 480 exit 1 481 fi 482fi 483 484# Let's check that 'gdbserver' is properly installed on the device too. If this 485# is not the case, the user didn't install the proper package after rebuilding. 486# 487adb_var_shell2 DEVICE_GDBSERVER ls /data/data/$PACKAGE_NAME/lib/gdbserver 488if [ $? != 0 ]; then 489 echo "ERROR: Non-debuggable application installed on the target device." 490 echo " Please re-install the debuggable version!" 491 exit 1 492fi 493log "Found device gdbserver: $DEVICE_GDBSERVER" 494 495# Get information from the build system 496GDBSETUP_INIT=`get_build_var_for_abi NDK_APP_GDBSETUP $COMPAT_ABI` 497log "Using gdb setup init: $GDBSETUP_INIT" 498 499TOOLCHAIN_PREFIX=`get_build_var_for_abi TOOLCHAIN_PREFIX $COMPAT_ABI` 500log "Using toolchain prefix: $TOOLCHAIN_PREFIX" 501 502APP_OUT=`get_build_var_for_abi TARGET_OUT $COMPAT_ABI` 503log "Using app out directory: $APP_OUT" 504 505# Find the <dataDir> of the package on the device 506adb_var_shell2 DATA_DIR run-as $PACKAGE_NAME /system/bin/sh -c pwd 507if [ $? != 0 -o -z "$DATA_DIR" ] ; then 508 echo "ERROR: Could not extract package's data directory. Are you sure that" 509 echo " your installed application is debuggable?" 510 exit 1 511fi 512log "Found data directory: '$DATA_DIR'" 513 514# Launch the activity if needed 515if [ "$OPTION_START" = "yes" ] ; then 516 # If --launch is used, ignore --start, otherwise extract the first 517 # launchable activity name from the manifest and use it as if --launch=<name> 518 # was used instead. 519 # 520 if [ -z "$OPTION_LAUNCH" ] ; then 521 OPTION_LAUNCH=`run_awk_manifest_script extract-launchable.awk | sed 2q` 522 if [ $? != 0 ] ; then 523 echo "ERROR: Could not extract name of launchable activity from manifest!" 524 echo " Try to use --launch=<name> directly instead as a work-around." 525 exit 1 526 fi 527 log "Found first launchable activity: $OPTION_LAUNCH" 528 if [ -z "$OPTION_LAUNCH" ] ; then 529 echo "ERROR: It seems that your Application does not have any launchable activity!" 530 echo " Please fix your manifest file and rebuild/re-install your application." 531 exit 1 532 fi 533 fi 534fi 535 536if [ -n "$OPTION_LAUNCH" ] ; then 537 log "Launching activity: $PACKAGE_NAME/$OPTION_LAUNCH" 538 run $ADB_CMD shell am start -n $PACKAGE_NAME/$OPTION_LAUNCH 539 if [ $? != 0 ] ; then 540 echo "ERROR: Could not launch specified activity: $OPTION_LAUNCH" 541 echo " Use --launch-list to dump a list of valid values." 542 exit 1 543 fi 544 # Sleep a bit, it sometimes take one second to start properly 545 # Note that we use the 'sleep' command on the device here. 546 run $ADB_CMD shell sleep $DELAY 547fi 548 549# Find the PID of the application being run 550PID=`$ADB_CMD shell ps | $AWK_CMD -f $AWK_SCRIPTS/extract-pid.awk -v PACKAGE=$PACKAGE_NAME` 551log "Found running PID: $PID" 552if [ $? != 0 -o "$PID" = "0" ] ; then 553 echo "ERROR: Could not extract PID of application on device/emulator." 554 if [ -n "$OPTION_LAUNCH" ] ; then 555 echo " Weird, this probably means one of these:" 556 echo "" 557 echo " - The installed package does not match your current manifest." 558 echo " - The application process was terminated." 559 echo "" 560 echo " Try using the --verbose option and look at its output for details." 561 else 562 echo " Are you sure the application is already started?" 563 echo " Consider using --start or --launch=<name> if not." 564 fi 565 exit 1 566fi 567 568# Check that there is no other instance of gdbserver running 569GDBSERVER_PS=`$ADB_CMD shell ps | grep lib/gdbserver` 570if [ -n "$GDBSERVER_PS" ] ; then 571 if [ "$OPTION_FORCE" = "no" ] ; then 572 echo "ERROR: Another debug session running, Use --force to kill it." 573 exit 1 574 fi 575 log "Killing existing debugging session" 576 GDBSERVER_PID=`echo $GDBSERVER_PS | $AWK_CMD -f $AWK_SCRIPTS/extract-pid.awk -v PACKAGE=lib/gdbserver` 577 if [ $GDBSERVER_PID != 0 ] ; then 578 run $ADB_CMD shell kill -9 $GDBSERVER_PID 579 fi 580fi 581 582# Launch gdbserver now 583DEBUG_SOCKET=debug-socket 584run $ADB_CMD shell run-as $PACKAGE_NAME lib/gdbserver +$DEBUG_SOCKET --attach $PID & 585if [ $? != 0 ] ; then 586 echo "ERROR: Could not launch gdbserver on the device?" 587 exit 1 588fi 589log "Launched gdbserver succesfully." 590 591# Setup network redirection 592log "Setup network redirection" 593run $ADB_CMD forward tcp:$DEBUG_PORT localfilesystem:$DATA_DIR/$DEBUG_SOCKET 594if [ $? != 0 ] ; then 595 echo "ERROR: Could not setup network redirection to gdbserver?" 596 echo " Maybe using --port=<port> to use a different TCP port might help?" 597 exit 1 598fi 599 600# Get the app_server binary from the device 601APP_PROCESS=$APP_OUT/app_process 602run $ADB_CMD pull /system/bin/app_process `native_path $APP_PROCESS` 603log "Pulled app_process from device/emulator." 604 605run $ADB_CMD pull /system/lib/libc.so `native_path $APP_OUT/libc.so` 606log "Pulled libc.so from device/emulator." 607 608# Now launch the appropriate gdb client with the right init commands 609# 610GDBCLIENT=${TOOLCHAIN_PREFIX}gdb 611GDBSETUP=$APP_OUT/gdb.setup 612cp -f $GDBSETUP_INIT $GDBSETUP 613#uncomment the following to debug the remote connection only 614#echo "set debug remote 1" >> $GDBSETUP 615echo "file `native_path $APP_PROCESS`" >> $GDBSETUP 616echo "target remote :$DEBUG_PORT" >> $GDBSETUP 617if [ -n "$OPTION_EXEC" ] ; then 618 cat $OPTION_EXEC >> $GDBSETUP 619fi 620$GDBCLIENT -x `native_path $GDBSETUP` 621