ndk-gdb使用简介

文档摘自android-ndk-r9c-linux-x86_64.tar.bz2中的docs/ndk-gdb.html

下面是渣渣版翻译，禁止围观，禁止吐槽

'ndk-gdb' and 'ndk-gdb-py' Overview

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

 注意：若是你须要调试多线程程序，请阅读下面的 “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.

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 r4引入了一个ndk-gdb的协助脚本，用来简单地运行NDK产生的机器代码的本地调试会话。脚本位于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安装路径。你一样能够建立一个alias或者增长$NDK到PATH环境变量来避免每次输入前面那一长串...

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

注意：只有当下列条件所有知足的时候，本地调试才能够正常工做

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

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

2. Your application is debuggable:

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

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

   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.

   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.

   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:

         Android 1.5      r4
         Android 1.6      r3
         Android 2.1      r2
         Android 2.2      r1

   These should be available through the SDK updater.

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

   
   

1.你的应用是用ndk-build脚本创建的。

        用早期的"make APP=<name>"方法创建的应用不被ndk-gdb支持。

2.你的应用是可调试的。

        换句话说，你的AndroidManifest.xml里面有一个<application>对象，而且设置了android:debuggable 属性为"ture".

3.应用运行在安卓2.2(或者更高)的版本上。

        ndk-gdb不能在这以前的系统版本上工做。这并不意味着你的应用须要使用target为Android2.2 的API，仅仅是调试会话须要在一个2.2+的设备或者仿真器上而已。

        注意！！！注意！！！注意！！！若是你用安卓开发工具ADT Eclipse来创建应用，请确保版本为 0.9.7或更高.若是你用ant,确保你已经有最新版本的的SDK 组件。须要的最小的版本为：

                Android 1.5     r4 

                Android 1.6     r3 

                Android 2.1     r2 

                Android 2.2     r1。 

        这些均可以经过SDK updater 工具来下载。

        若是这些条件没有达成，产生的.apk文件将不包含用于支持本地调试的一些文件，致使不能调试。

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

• checks that adb is in your path.

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

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

  
  

‘ndk-gdb’处理不少的错误条件，而且会dump一些它找到的有用的错误消息。举个栗子：

    -检查adb是否在PATH环境变量中，

    -检查应用是否在manifest里声明了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= option to automatically start your activity before the debugging session.

默认状况下，ndk-gdb会搜索已经在运行的应用进程，若是没找到，会dump一条错误信息。你也能够用 --start 或者 --launch=<name>选项,它将在调试会话以前自动启动activity。

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.

当它成功地attach 到你的应用进程，而后搜索你产生本地库的的源文件和符号/调试版本以适当地设置调试会话后，ndk-gdb将会给出一个正常的GDB提示符。

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

你能够用b <location>来设置断点，而后用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...)

       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.

注意：GDB提示符开始会产生一长串的错误消息，抱怨它找不到各类各样的系统库(libc.so,libstdc++.so,libcutils.so,等等...)

这是正常的，由于你的开发机器上没有与你目标机上一致的 带符号表/调试信息 的版本的这些库。

你能够安全的忽略这些信息。

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.

打印调试会话的详细的信息。只有当你没法链接，而且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.

若是ndk-gdb发现同一台设备上正运行着另外一个调试会话，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.

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.

默认状况下，ndk-gdb会尝试attach到目标设备上一个已经在运行的应用实例。你能够用 --start直接地在调试会话启动前运行应用。

注意：这样实际上是运行在你的manifest中列出的第一个可运行的activity。用--lauch=<name>来启动其余的。用--lauch-list来列出全部这些activity

--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.

与 --start相似，除了它容许你启动应用中指定的activity以外。这只在你的应用中定义了多个可运行的activity时候才有用。

--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

快速地打印全部在你的应用manifest中找到的可运行的activity名字。其中第一个会被--start使用

--project=<path>:

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

指定应用的工做目录，若是你想不cd到对应的目录下就运行对应的脚本，这个选项会很是有用

--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.

默认状况下，ndk-gdb会使用本地的TCP 5039端口来与被调试的应用通讯。经过改变端口号，可让不一样设备/仿真器上的调试程序同时链接到同一台开发机器。

--adb=<file>:

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

指定adb工具的路径，假如adb没有在你的环境变量PATH中的时候。

-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:          Connect to a single physical device
    -e:          Connect to a single emulator device
    -s <serial>: Connect to a specific device or emulator
                 where <serial> is the device's name as listed
                 by the "adb devices" command.

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

这些标志位跟ADB的同样，它容许你处理如下状况，当你有多个设备/仿真器链接到你的开发机器的时候。

    -d:          链接到单个物理设备。
    -e:          链接到单个仿真器设备。
    -s <serial>: 链接到指定串号的设备，能够用adb devices先查看设备串号列表

 或者，你能够定义ADB_SERIAL环境变量为指定的设备，从而不须要使用上面这些选项。

--exec=<file>: -x <file>:

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

链接到调试进程以后，立刻运行该文件中的GDB命令。当你老是要作一些重复的事情的时候，这是很是有用的。举个栗子:设置一系列的断点，而后自动恢复执行

--nowait:

Disable pausing the Java code until GDB connects. Passing this option may cause early breakpoints to be missed.

GDB链接上前不暂停Java代码，启用该选项将致使前面设置的一些断点被忽略。

--tui: -t:

Enable Text User Interface if GDB was built with it. [ndk-gdb-py only]

启用文本用户接口，若是GDB在build的时候带了该功能。[只对ndk-gdb-py有效]

--gnumake-flag=<flag>:

Extra flag(s) to pass to the ndk-build system when querying it for project information. Multiple instances can be used. [ndk-gdb-py only]

--stdcxx-py-pr={auto|none|gnustdcxx[-GCCVER]|stlport}:

Use specified Python pretty-printers for displaying types in the Standard C++ Library. 'auto' mode works by looking at the .so files for a libstdc++ library, and as such only works in the shared scenario. When linking statically to a libstdc++ library, the required printers must be specified. The default is 'none'. [ndk-gdb-py only]

III. Requirements:

'ndk-gdb' requires a Unix shell to run. This means that Cygwin is required to run it on Windows. An experimental Python re-implementation called 'ndk-gdb-py' is also provided, removing this restriction and providing some new features.

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

ndk-gdb 须要unix shell来运行，这意味着window下须要借助Cygwin.一个实验性的从新实现的版本ndk-gdb-py，去除了该限制，而且提供了一些新的特性。

其余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.

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).

What this means in practical terms are:

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

• 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):

      Thread debugging is unsupported on this Android platform!

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

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

若是在比Android 2.3更早的平台上运行，ndk-gdb将不能很好地调试本地线程.此时，调试器只能在主线程中放置断点，其余位置的将彻底被忽略。

这个问题的根本缘由很复杂，不过它本质上归结于android平台一个很是不幸的BUG，一个不久前才被发现的BUG

gdbserver文件是NDK指定的代码，用来检测运行时条件而且自适应其行为。(换句话说，你不须要作任何指定的事情，当你build你的代码的时候）

实际上这意味着：

• 若是你在android 2.3，或者先前已经修复这个bug的平台，你自动就能够多线程调试。
  
  

• 若是不是,你将只能调试主线程(就像之前发行的NDK版本同样). 而且，当你运行ndk-gdb的时候你会看见下面的消息:(在gdb提示符以前):

      Thread debugging is unsupported on this Android platform!

        若是你放置一个断点在非主线程调用的函数中，程序将会退出而且GDB会发出以下信息

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