(12) ndk GDB

-----

For English documents, see documentation.html of android-ndk-r5b.

Part of Android Native Development Kit (ndk)

See http://developer.android.com/sdk/ndk/ (Agent required)

Translation is personal opinion only

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

'Ndk-GDB 'Overview

 

Overview of ndk-GDB

 

Important: If you are debugging threaded programs, please read the section below titled 'thread support '.

 

Important: If you are debugging MultithreadingProgram, Read the following section entitled "thread support.

 

I. Usage:

 

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 introduces an auxiliary shell script named ndk-GDB for you to use the machine generated by ndkCodeSimply start the native debugging session.

 

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:

 

The script is located in the top-level directory of ndk. When you are located in the application project directory or its subdirectory, It will be executed in the command line. For example:

 

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.

 

Here $ ndk points to your ndk installation directory. You can also create an alias or add $ ndk to your path environment variable to avoid entering it every time.

 

Important: Native debugging can only work if * All * these conditions are met:

 

Important: Native debugging can only work when all the following conditions are met:

 

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

 

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

 

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

 

The legacy make APP = <Name> method building is not supported by ndk-GDB.

 

2. Your application is debuggable:

 

2. Your application can be debugged:

 

In other words, your androidmanifest. XML has an <Application> element that sets the Android: debuggable attribute to "true"

 

In other words, your androidmanifest. XML has the <Application> element, which sets the Android: debuggable attribute to true.

 

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

 

3. You run 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 shoshould target the Android 2.2. API level, just that the debugging session shoshould happen on a 2.2 + device or emulator system image.

 

If you try to run your application in a previous system version, ndk-GDB will not work. That doesn't mean that your application should set the target to Android 2.2. Only the API level of the debugging session should occur on the system image of a device or simulator later than Version 2.2.

 

Important important 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 use the ADT Eclipse plug-in to build your application, make sure that you are using 0.9.7 or update.

 

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:

 

If you are using ant build tools, make sure you have the latest version of the SDK platform components. The following minimum revision is required:

 

Android 1.5 r4

Android 1.6 r3

Android 2.1 r2

Android 2.2 r1

 

These shoshould be available through the SDK Updater.

 

These revisions are available through the SDK Updater.

 

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

 

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

 

'Ndk-GDB 'handles handle error conditions and will dump an informative error message if it finds a problem. For example, it:

 

Ndk-GDB processes many error conditions, and if an error is found, it dumps the error message. For example, it:

 

-Checks that ADB is in your path.

 

-Check whether ADB searches for the path in your path.

 

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

 

-Check that your application is declared as debuggable in its list. (Note: See androidmanifest. xml above)

 

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

 

-Check that the installed applications with the same package name can be debugged on the device.

 

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

Debugging session.

 

By default, ndk-GDB searches for an application process that is already running. If it cannot find the process, it dumps an error. However, you can use the -- start or -- launch = <Name> Option to automatically start your activity before debugging the session.

 

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.

 

When it successfully connects to your application process, after you configure the session to find your source file and the local library of your generated symbol/debug version, ndk-GDB will give you a regular GDB prompt.

 

You can set breakpoints with 'B <location>' and resume execution with 'C' (for 'contine'). See the gdb manual for a list of commands.

 

You can use "B <position>" to set a breakpoint and use "c" to resume execution. Refer to the gdb manual to obtain the command list.

 

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

 

Important: When you exit the gdb prompt, the application process you debug will be stopped! This is the limitation of 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 ...)

 

Important: A long column of error messages will appear before the gdb prompt, where GDB explains that it cannot find various system libraries (such as 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.

 

This is normal because the libraries corresponding to the symbols/debugging versions of your target device do not exist on your development machine. You can safely ignore these messages.

 

Ii. Options:

 

Ii. Options:

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

 

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

 

To view the list of options, type ndk-GDB -- help. Note the following:

 

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

Prints detailed information about native debugging session configuration. You only need to use the error message that you cannot connect to ndk-GDB to debug the problem.

 

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

By default, if another debugging session is found to run on the same device, ndk-GDB will stop. Using -- force will kill the session and replace it with the new session. Note that the program to be debugged will not be killed and will be stopped again.

 

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

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

 

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.

 

Note: It is started in your Application List (Note: androidmanifest. xml ?) The first runnable activity listed in. Use -- launch = <Name> to start another activity. Refer to -- launch-list to dump the list of such activities.

 

-- Launch = <Name>:

This is similar to -- start, before t 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>:

Similar to -- start, the difference is that it allows you to start a specific activity of your application. It is only useful when your list defines multiple executable activities.

 

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

Convenience options: print a list of names of all activities that can be started in your application list. The first activity will be used by -- 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>:

Specifies the application project directory. This option is useful if you do not want to switch the directory before starting the script.

 

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

By default, ndk-GDB uses the local TCP port 5039 to communicate with the debugged application. By using a different port, You can native tune and run multiple programs on different devices/simulators connected to the same development machine.

 

-- ADB = <File>:

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

 

-- ADB = <File>:

If Adb is not in your path search path, use it to specify the executable file of the ADB tool.

 

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

These switches are similar to ADB switches that allow you to handle multiple devices/simulators connected to your development machine.

 

-D: connect to a single physical device

 

-D: connect to a single physical device

 

-E: connect to a single emulator Device

 

-E: connect to a single simulated device.

 

-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>: connect to a specific device or simulator. Here <serial> is the name of the device listed in 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.

 

In addition, you can define the adb_serial environment variables to list a specific device without using specific options.

 

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

After connecting to the debugging process, run the gdb initialization command in the <File> file. It is useful when you want to do something repeatedly, for example, setting a breakpoint and automatically resuming execution.

 

 

Iii. Requirements:

 

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

 

Currently, ndk-GDB requires a Unix shell to run. This means cygwin is required to run it on Windows. We hope to avoid this restriction in the future releases of ndk.

 

The other ndk requirements apply: e.g. GNU make 3.81 or higher.

 

Other ndk usage requirements: for example, GNU make 3.81 or higher.

 

Iv. Thread support:

 

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

 

If your application runs on a platform updated than Android 2.3, ndk-GDB cannot properly debug native threads. On the contrary, the debugger can only place breakpoints in the main thread, ignoring the execution of other threads completely.

 

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

 

The root cause of the problem is complex, but it is essentially a very unfortunate defect on the platform that is found late.

 

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

 

The gdbserver binary file from ndk has special code that detects this condition at runtime and automatically adapts to its behavior (in other words, when you build your code, you don't need to do anything special ).

 

What this means in practical terms are:

 

In practice, this means:

 

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

 

-If you have already corrected the platform for patches of the old version on Android 2.3 or earlier, you can automatically debug native multithreading.

 

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

 

-If you are not, you will only be able to debug the main thread (as in the previous ndk release version ). You will also see the following message when you start ndk-GDB (the value appears before the gdb prompt ):

 

Thread debugging is unsupported on this Android platform!

 

Thread debugging is not supported 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:

 

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

 

Program terminated with signal sigtrap, trace/breakpoint trap. The program no longer exists.

 

The program is sigtrap, And the tracing/breakpoint trap ends. The program no longer exists.