【翻译】(12)NDK GDB

-----

英文文档见android-ndk-r5b的documentation.html

属于Android Native Development Kit (NDK)的一部分

见http://developer.android.com/sdk/ndk/（需要代理）

翻译仅个人见解

-----------------

'ndk-gdb' Overview

ndk-gdb概述

IMPORTANT: IF YOU ARE DEBUGGING THREADED PROGRAMS, PLEASE READ THE SECTION BELOW TITLED 'Thread Support'.

重要：如果你在调试多线程程序，请阅读下面题为“线程支持”的章节。

I. Usage:

一、用法：

---------

The Android NDK r4 introduced a helper shell script named 'ndk-gdb' to easily launch a native debugging session for your NDK-generated machine code.

Android NDK r4引入一个名为ndk-gdb的辅助shell脚本，为你用NDK生成的机器代码简单地启动原生调试会话。

The script is located at the top-level directory of the NDK, and shall be invoked from the command-line when in your application project directory, or any of its sub-directories. For example:

脚本位于NDK的顶级目录，当你位于应用程序工程目录或其子目录中，它将在命令行中执行。例如：

    cd $PROJECT

    $NDK/ndk-gdb

Where $NDK points to your NDK installation path. You can also create an alias or add $NDK to your PATH to avoid typing it every time.

这里$NDK指向你的NDK安装目录。你还可以创建一个别名或添加$NDK到你的PATH环境变量以避免每次都输入它。

IMPORTANT: Native debugging can only work if *all* these conditions are met:

重要：原生调试只可以工作在下面所有条件都满足的时候：

    1. Your application is built with the 'ndk-build' script:

1. 你的应用程序由ndk-build脚本构建：

        Building with the legacy "make APP=<name>" method is not supported by ndk-gdb.

遗留的make APP=<名称>方法构建不被ndk-gdb支持。

    2. Your application is debuggable:

    2. 你的应用程序可调试：

        In other words, your AndroidManifest.xml has an <application> element that sets the android:debuggable attribute to "true"

        换句话说，你的AndroidManifest.xml拥有<application>元素，它设置android:debuggable属性为true。

    3. You are running your application on Android 2.2 (or higher):

3. 你在Android 2.2（或更高）上运行你的应用程序：

        ndk-gdb will not work if you try to run your application on previous versions of the system. That does not mean that your application should target the Android 2.2. API level, just that the debugging session should happen on a 2.2+ device or emulator system image.

        如果你尝试运行你的应用程序在以前的系统版本，ndk-gdb将不会工作。那并不意味着你的应用程序应该把目标定为Android 2.2。只是调试会话的API级别应该发生在版本2.2以上的设备或模拟器的系统镜像上。

        IMPORTANT IMPORTANT IMPORTANT !!

        重要 重要 重要 ！！

            If you are using the ADT Eclipse plug-in to build your application, make sure you're using version 0.9.7 or later.

            如果你使用ADT Eclipse插件构建你的应用程序，请确保你正在使用0.9.7或更新。

            If you are using the 'ant' build tool, make sure that you have the latest revision of the SDK Platform components. The following minimal revisions are required:

            如果你正在使用ant构建工具，请确保你拥有最新修订版的SDK平台组件。需要以下最小修订版：

                Android 1.5      r4

                Android 1.6      r3

                Android 2.1      r2

                Android 2.2      r1

            These should be available through the SDK updater.

            这些修订版通过SDK更新器可用。

            If these conditions are not met, the generated .apk will not contain required support files and native debugging will not be possible.

            如果这些条件不满足，所生成的.apk将不包含所需支持文件，并将不可能支持原生调试。

'ndk-gdb' handles many error conditions and will dump an informative error message if it finds a problem. For example, it:

ndk-gdb处理许多错误条件，并且如果发现一个错误，它会转储错误信息消息。例如，它：

    - checks that adb is in your path.

    - 检查adb是否在你的PATH搜索路径

    - checks that your application is declared debuggable in its manifest.

- 检查你的应用程序在它的清单中被声明为可调试。（注：见上文的AndroidManifest.xml）

    - checks that, on the device, the installed application with the same package name is also debuggable.

- 检查在设备上，相同包名的已安装应用程序也是可调试的。

By default, ndk-gdb will search for an already-running application process, and will dump an error if it doesn't find one. You can however use the --start or --launch=<name> option to automatically start your activity before the

debugging session.

默认，ndk-gdb将搜索一个已经在运行的应用程序进程，如果它找不到进程它将转储错误。然而你可以使用--start或--launch=<名称>选项以在调试会话前自动开始你的活动。

When it successfully attaches to your application process, ndk-gdb will give you a normal GDB prompt, after setting up the session to properly look for your source files and symbol/debug versions of your generated native

libraries.

当它成功地连接到你的应用程序进程，在把会话配置为可以合适地找到你的源文件和你生成的符号/调试版本的本地库之后，ndk-gdb将给你一个常规的GDB提示符。

You can set breakpoints with 'b <location>' and resume execution with 'c' (for 'continue'). See the GDB manual for a list of commands.

你可以用“b <位置>”设置断点并且用c（继续的缩写）恢复执行。参考GDB手册以获得命令列表。

IMPORTANT: When quitting the GDB prompt, your debugged application process will be stopped! This is a gdb limitation.

重要：当退出GDB提示符，你调试的应用程序进程将被停止！这是gdb的限制。

IMPORTANT: The GDB prompt will be preceded by a long list of error messages, where gdb complains that it cannot find various system libraries (e.g. libc.so, libstdc++.so, liblog.so, libcutils.so, etc...)

重要：GDB提示符之前将出现一长列错误消息，那里gdb解释它不能找到各种系统库（例如：libc.so，libstdc++.so，liblog.so，libcutils.so，等等）

           This is normal, because there are no symbol/debug versions of these libraries corresponding to your target device on your development machine. You can safely ignore these messages.

           这是正常的，因为在你的开发机器上这些对应你目标设备的符号/调试版本的库不存在。你可以安全地忽略这些消息。

II. Options:

二、选项：

------------

To see a list of options, type 'ndk-gdb --help'. Notable ones are:

要查看选项列表，请键入ndk-gdb --help。值得注意的有：

  --verbose:

    Print verbose information about the native debugging session setup. Only needed to debug problems when you can't connect and that the error messages printed by ndk-gdb are not enough.

  --verbose:

    打印出关于原生调试会话配置的详细信息。只在你不能连接和ndk-gdb打印的错误消息不足时才需要用它来调试问题。

  --force:

    By default, ndk-gdb aborts if it finds that another native debugging session is running on the same device. Using --force will kill the session, and replace it with a new one. Note that the debugged program is *not* killed and will be stopped again.

  --force:

    默认，如果发现另一个调试会话运行在相同设备，ndk-gdb会中止。使用--force将杀死那个会话，并且把新的会话替换它。注意调试的程序不会被杀死并且将再次被停止。

  --start:

    By default, ndk-gdb will try to attach to an existing running instance of your application on the target device. You can use --start to explicitly launch your application before the debugging session.

  --start:

    默认，ndk-gdb将尝试连接到在目标设备上现存运行的你的应用程序实例。你可以使用--start显式地在调试会话前启动你的应用程序。

    NOTE: This launches the first launchable activity listed from your application manifest. Use --launch=<name> to start another one. See --launch-list to dump the list of such activities.

注意：它启动在你的应用程序清单（注：指AndroidManifest.xml？）中列出的第一个可运行活动。使用--launch=<名称>以开始另一个活动。参考--launch-list以转储这类活动的列表。

  --launch=<name>:

    This is similar to --start, except that it allows you to start a specific activity from your application. This is only useful if your manifest defines several launchable activities.

  --launch=<name>:

    类似于--start，不同的是它允许启动你的应用程序的一个特定活动。它只在你的清单定义多个可运行活动时才有用。

  --launch-list:

    Convenience option that prints the list of all launchable activity names found in your application manifest. The first one will be used by --start

  --launch-list:

    方便选项，打印所有在你的应用程序清单中可启动活动的名称列表。第一个活动将被--start使用。

  --project=<path>:

    Specify application project directory. Useful if you want to launch the script without cd-ing to the directory before that.

  --project=<path>:

    指定应用程序工程目录。如果你想在启动脚本前不切换目录，这个选项会有用。

  --port=<port>:

    By default, ndk-gdb will use local TCP port 5039 to communicate with the debugged application. By using a different port, it is possible to natively debug programs running on different devices/emulators connected to the same development machine.

  --port=<port>:

    默认，ndk-gdb将使用本地TCP端口5039和调试的应用程序通信。通过使用一个不同的端口，可以原生地调试运行在连接到相同开发机器的不同设备/模拟器上的多个程序。

  --adb=<file>:

    Specify the adb tool executable, in case it is not in your path.

  --adb=<file>:

    如果adb不在你的PATH搜索路径中，用它指定adb工具的可执行文件。

  -d, -e, -s <serial>:

    These flags are similar to the ADB ones and allow you to handle the case where you have several devices/emulators connected to your development machine.

  -d, -e, -s <serial>:

    这些开关类似于ADB的开关，允许你处理拥有几个连接到你的开发机器的多个设备/模拟器的情况。

        -d:          Connect to a single physical device

        -d:          连接到单个物理设备

        -e:          Connect to a single emulator device

        -e:          连接到单个模拟设备

        -s <serial>: Connect to a specific device or emulator where <serial> is the device's name as listed by the "adb devices" command.

        -s <serial>: 连接到特定设备或模拟器，这里<serial>是adb devices命令中列出的设备名称。

    Alternatively, you can define the ADB_SERIAL environment variable to list a specific device, without the need for a specific option.

    另外，你可以定义ADB_SERIAL环境变量以列出一个特定设备，而不需要使用特定的选项。

  --exec=<file>:

  -x <file>:

    After connecting to the debugged process, run the GDB initialization commands found in <file>. This is useful if you want to do something repeatedly, e.g. setting up a list of breakpoints then resuming execution automatically.

  --exec=<file>:

  -x <file>:

    在能连接到调试进程后，运行在<file>文件中的GDB初始化命令。如果你想重复地做一些事情时有用，例如设置一列断点然后自动地恢复执行。

III. Requirements:

三、配置要求：

------------------

At the moment 'ndk-gdb' requires a Unix shell to run. This means that Cygwin is required to run it on Windows. We hope to get rid of this limitation in a future NDK release.

目前ndk-gdb需要一个Unix外壳来运行。这意味着在Windows上需要Cygwin来运行它。我们希望在未来NDK发布版中避免这个限制。

The other NDK requirements apply: e.g. GNU Make 3.81 or higher.

其它NDK使用要求：例如GNU Make 3.81或更高。

IV. Thread Support:

四、线程支持：

-------------------

If your application runs on a platform older than Android 2.3, ndk-gdb will not be able to debug native threads properly. Instead, the debugger will only be able to put breakpoints on the main thread, completely ignoring the execution of other ones.

如果你的应用程序运行在一个比Android 2.3更新的平台上，ndk-gdb将不能合理地调试原生线程。相反，调试器将只能在主线程放置断点，完全忽略其它线程的执行。

The root of the problem is complex, but is essentially due to a very unfortunate bug in the platform, which was only discovered lately.

问题的根源很复杂，但本质上是因为平台上的一个非常不幸的缺陷，它较迟被发现。

The gdbserver binary that comes with this NDK has special code to detect this condition at runtime and adapt its behaviour automatically (in other words, you don't have anything special to do when building your code).

来自NDK的gdbserver二进制文件拥有特殊代码在运行期检测这个条件并自动地适配它的行为（换句话说，当你构建你的代码时，你不需要做任何特殊的事情）。

What this means in practical terms are:

用实际的话来说这意味着：

- If you are on Android 2.3, or a prior platform release which has had the platform bugfix back-ported to it, you will be able to debug native threads automatically.

- 如果你在Android 2.3或之前的平台发布版上，它已经被针对老版本的补丁作出平台修正，那么你将可以自动地可以调试原生多线程。

- If you are not, you will only be able to debug the main thread (as in previous NDK releases). You will also see the following message when launching ndk-gdb (just before the gdb prompt):

- 如果你不是，你将只能调试主线程（正如以前的NDK发布版那样）。你还将在启动ndk-gdb时看到以下消息（值出现在gdb提示符前）：

     Thread debugging is unsupported on this Android platform!

     在这个Android平台上不支持线程调试！

  If you place a breakpoint on a function executed on a non-main thread, the program will exit with the following message in GDB:

  如果你在非主线程上执行的函数放置一个断点，GDB将用以下消息退出程序：

        Program terminated with signal SIGTRAP, Trace/breakpoint trap. The program no longer exists.

        程序被信号SIGTRAP，跟踪/断点陷阱终止。程序不再存在。