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.