How to Debug Cocos2d-x C++ Native Code on Android in Eclipse

Android NDK debugging with an IDE can be a challenge. It would be great if Google would create an IDE like Visual Studio or Xcode that supports C++ and Java. It looks like Android Studio might be that solution, but it needs to mature more before it could be considered a robust C++ development and debugging solution.

This article is all about how to use Tegra and GDB to debug Android C++ games using Eclipse.

Also check out this important post that includes some very useful tips about debugging Android C++ games using the Android Developer Tools and the Android NDK.

Tegra Android Development Pack

I have used the Tegra Android Development Pack, an Eclipse based solution from NVDIA, for about 18 months now. It has breakpoint debugging and Logcat logging to debug cocos2d-x Android C++ and Java code simultaneously. Works great to isolate those Android specific issues that cannot be caught when developing/testing in Xcode for iOS/Mac or Visual Studio WP8.

Tegra Android and the NVIDIA Debug Manager for Android NDK (breakpoints and all) is free, you just have to sign up for their Gameworks free membership:

You can get just the NVIDIA Debug Manager for Android NDK eclipse plugin or their entire NDK Eclipse Android IDE. If you use their NDK, be sure to double check the NDK version compatibility.

Steps to Setup The Tegra Android Development Pack for NDK Android Debugging (Mac Setup)

1) Register for NVIDIA Registered Developer Program:

2) Register for the NVDIA GameWorks so that you can download the Android Tegra Developer Tools. This is done in the NVIDIA portal after your are approved for the NVIDIA Registered Developer Program. The approval took a few hours for me.

3) Download and Install the Android Tegra Developer Tools.

4) Download Cocos2d-x 3.4 This process does not work in 3.5+, likely due to some changes in cocos2d-x.

5) Unzip Cocos2d-x 3.4 into the location where you installed NVIDIA’s tools (or any other desired location and note the location). Default location for the NVPACK is your home directory in the folder titled NVPACK. So in that case, unzip the Cocos2d-x 3.4 zip file inside of the NVPACK folder; the result will be the new folder cocos2d-x-3.4 inside of the NVPACK folder.

6) Run the python script by executing the cocos script on a command line in the cocos2d-x folder: ./

7) Read the output of the script. It is important that all variables are set properly. If any are not set, you will need to set these manually. If you followed the steps above, using the versions described above, then you should not need to set any variables manually. The key here is to ensure that your environment variables point to the desired Ant, cocos2d-x root, NDK root, Android SDK, etc. Note that the NVPACK adds environment and path variables too, so review this carefully to make sure the NDK_ROOT, NDKROOT, ANT_ROOT, ANT_HOME, NVPACK_NDK_VERSION, COCOS_CONSOLE_ROOT, COCOS_TEMPLATES_ROOT, and ANDROID_SDK_ROOT are set to point to the correct versions you intend to use. Note that in step 19 below I download ndk-r9d since there were cocos2d-x build issues with ndk-r10d that came with the Tegra Android Developer Pack.

8) Execute cocos new SampleOne -p com.heyalda.sampleOne -d /Your/Project/Path -l cpp.

9) Open Eclipse and enter a desired working directory.

10) Right-click in the left panel and select Import. Then select the General folder and select Existing Projects into Workspace. Select Browse and then navigate to the newly created game titled SampleOne and in the folder cocos/platform/android/java and then select open.

11) You might see errors after importing regarding the missing Android Library API 10. Disregard those errors for now.

12) From the top title bar navigation menu in eclipse, select Window -> Android SDK Manager.
Deselect Installed in the SDK Manager window and ensure that Updates/New is selected.
Select the Android 3.2 (API 13), or whichever Android version levels you want.

13) Install the API 13 (or whichever android levels you want).

14) After installation completes, close Eclipse.

15) Change directories into the newly created game and type cocos run -p android. This will build the cocos2d-x library and the newly created android project. If you connect and Android device to your computer, after the build succeeds the app will be installed not he Android device and launched. Depending on the power of your computer, this build may take anywhere from a few minutes or longer.

16) Define the Android SDK Root for your project by right clicking on your project, select properties and then C/C++ Build -> Environment and then add the Variable ANDROID_SDK_ROOT that points to your SDK root. Click the Apply to All Configurations to apply it to Release and Debug configurations.

17) Download and install ndk-r9d since there are issue with r10d and cocos2d-x compatibility. Be sure to update your .bash_profile and eclipse NDK_ROOT settings to point to ndk-r9d. If you get a bunch of srand and rand build errors, then you are probably not pointing your environment at ndk-r9d.

18) If you get the error similar to this:
Android NDK: WARNING: APP_PLATFORM android-21 is larger than android:minSdkVersion 13 in ./AndroidManifest.xml
Then open the file NVPACK/android-ndk-r10d/build/core/

Search for the text $(call __ndk_info,WARNING: APP_PLATFORM $(APP_PLATFORM) is larger than android:minS
Or if you are using ndk-r9d, then search for the same string in the /build/core/ file.
Then comment out that line by adding a # to the first character of the line.
This is a hack to get the app to launch. Probably should not leave this setting permanently.

19) If you get the “Dex Loader – Unable to execute dex: Multiple dex files” if I remember correctly, you may need to comment out the cocos2d-x reference in temporarily. An alternative is that you could remove the cocos2d-x source code from your java build path, but that has implications to that may not be desired.

20) Right-Click on the project name and then in the context menu select Debug As -> Android Native Application. The Eclipse perspective should switch to the debug perspective. You can then change back and forth between the C++ and Debug perspectives in Eclipse using Window->Open Perspective

21) In the C++ perspective, you can open C++ files in the Classes folder and then double-click on the left side of a source line to set a breakpoint.

I tested this process, but if you find issues with it please let me know and I will update these steps.

Here are some screenshots of the result.

Here you can see a C++ NDK breakpoint being hit in a Cocos2d-x game running on a Nexus 7 tablet. The blue line where the breakpoint was hit is highlighted.



This image shows the app stopping due to an assertion. The red text in the Logcat log shows the exact C++ class and line number that caused the assertion.



Alternative Solutions for C++ NDK Android Debugging

The following are solutions that enable debugging C++ code on Android devices that I have not tested.

NVIDIA Nsight for Visual Studio

The post in the following link talks about a similar NVIDIA Visual Studio breakpoint enabled NDK debugging solution for Android called Nsight. But it looks like you need to buy Visual Studio Professional 2013 to use Nsight. Edit: You might be able to use the Visual Studio Community Edition with Nsight, but there might be licensing issues.

Visual GDB from Sysprogs

This looks like an interesting:

Info About GDB and GDB Server

Interesting Discussion About using gdb (I think all of the above solutions use gdb and gdb server):

ARM DS5 C++ Debugging

This looks interesting, but I have not tried to use it yet:

About the author

Jim Range

Jim Range has over a decade of experience architecting and implementing software based solutions for numerous fortune 500 companies in industries such as financial services, retail, and insurance, as well as small businesses. Jim has an excellent understanding of the software development lifecycle, agile development, and how to manage the development of an app. Over the past ten years Jim has been focused on mobile software development. He has created over 138 apps that have been downloaded more than 10 million times from the Apple App Store, Google Play, and Windows Phone Store. Jim also has experience as an information security consultant where he has provided numerous network and web application security assessments for Fortune 500 companies in the financial services, retail and insurance industries.