<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer's Guide: <code>ndk-gdb</code> and <code>ndk-gdb-py</code></title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">NDK Programmer's Guide
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__debugging__n_d_k-_g_d_b.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title"><code>ndk-gdb</code> and <code>ndk-gdb-py</code> </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>IMPORTANT: IF YOU ARE DEBUGGING THREADED PROGRAMS, PLEASE READ THE SECTION BELOW TITLED 'Thread Support'.</p>
<h2>Usage</h2>
<p>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.</p>
<p>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: </p>
<pre class="fragment"> cd $PROJECT
$NDK/ndk-gdb
</pre><p>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.</p>
<p>IMPORTANT: Native debugging can only work if <em>all</em> these conditions are met:</p>
<ol type="1">
<li><p class="startli">Your application is built with the 'ndk-build' script:</p>
<p class="startli">Building with the legacy "make APP=<name>" method is not supported by ndk-gdb.</p>
</li>
<li><p class="startli">Your application is debuggable:</p>
<p class="startli">In other words, your AndroidManifest.xml has an <application> element that sets the android:debuggable attribute to "true"</p>
</li>
<li><p class="startli">You are running your application on Android 2.2 (or higher):</p>
<p class="startli">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.</p>
<p class="startli">IMPORTANT IMPORTANT IMPORTANT !!</p>
<p class="startli">If you are using the ADT Eclipse plug-in to build your application, make sure you're using version 0.9.7 or later.</p>
<p class="startli">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: </p>
<pre class="fragment"> Android 1.5 r4
Android 1.6 r3
Android 2.1 r2
Android 2.2 r1
</pre><p class="startli">These should be available through the SDK updater.</p>
<p class="startli">If these conditions are not met, the generated .apk will not contain required support files and native debugging will not be possible.</p>
</li>
</ol>
<p>'ndk-gdb' handles many error conditions and will dump an informative error message if it finds a problem. For example, it:</p>
<ul>
<li>checks that adb is in your path.</li>
<li>checks that your application is declared debuggable in its manifest.</li>
<li>checks that, on the device, the installed application with the same package name is also debuggable.</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>You can set breakpoints with 'b <location>' and resume execution with 'c' (for 'continue'). See the GDB manual for a list of commands.</p>
<p>IMPORTANT: When quitting the GDB prompt, your debugged application process will be stopped! This is a gdb limitation.</p>
<p>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...)</p>
<p>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.</p>
<h2>Options</h2>
<p>To see a list of options, type 'ndk-gdb –help'. Notable ones are:</p>
<h3><code>--verbose</code><br/>
</h3>
<p>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.</p>
<p><code>--force</code><br/>
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 <em>not</em> killed and will be stopped again.</p>
<p><code>--start</code><br/>
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.</p>
<p>NOTE: This launches the first launchable activity listed from your application manifest. Use <code>--launch=<name></code> to start another one. See <code>--launch-list</code> to dump the list of such activities.</p>
<p><code>--launch=<name></code><br/>
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.</p>
<p><code>--launch-list</code><br/>
Convenience option that prints the list of all launchable activity names found in your application manifest. The first one will be used by –start</p>
<p><code>--project=<path></code><br/>
Specify application project directory. Useful if you want to launch the script without cd-ing to the directory before that.</p>
<p><code>--port=<port></code><br/>
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.</p>
<p><code>--adb=<file></code><br/>
Specify the adb tool executable, in case it is not in your path.</p>
<p><code>-d</code>, <code>-e</code>, <code>-s <serial></code><br/>
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. </p>
<pre class="fragment"> -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.
</pre><p>Alternatively, you can define the ADB_SERIAL environment variable to list a specific device, without the need for a specific option.</p>
<p><code>--exec=<file></code><br/>
<code>-x <file></code><br/>
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.</p>
<p><code>--nowait</code><br/>
Disable pausing the Java code until GDB connects. Passing this option may cause early breakpoints to be missed.</p>
<p><code>--tui</code><br/>
<code>-t</code><br/>
Enable Text User Interface if GDB was built with it. [ndk-gdb-py only]</p>
<p><code>--gnumake-flag=<flag></code><br/>
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]</p>
<p><code>--stdcxx-py-pr={auto|none|gnustdcxx[-GCCVER]|stlport}</code><br/>
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]</p>
<h2>Requirements</h2>
<p>'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.</p>
<p>The other NDK requirements apply: e.g. GNU Make 3.81 or higher.</p>
<h2>Thread Support</h2>
<p>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.</p>
<p>The root of the problem is complex, but is essentially due to a very unfortunate bug in the platform, which was only discovered lately.</p>
<p>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).</p>
<p>In practical terms, this means:</p>
<ul>
<li>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.</li>
<li>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): <pre class="fragment"> Thread debugging is unsupported on this Android platform!
</pre></li>
</ul>
<p>If you place a breakpoint on a function executed on a non-main thread, the program will exit with the following message in GDB: </p>
<pre class="fragment"> Program terminated with signal SIGTRAP, Trace/breakpoint trap.
The program no longer exists.</pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer's Guide by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
</body>
</html>