Debugging (Android)

Elements comes with a complete debugging solution for Android projects, whether build using the Java based SDK or the native NDK.

Debugging Android SDK Apps

Android ASK based applications can be debugged right from the Fire, Water or Visual Studio IDE, either on an attached Android device, or on an Emulator.

With an Android project active, the CrossBox dropdown menu in the toolbar shows you a list of all known devices and emulators. Simply select the right item and choose "Run" (Fire/Water, ⌘R or Ctrl+R, respectively) or "Start" (Visual Studio, F5), and the IDE will build, deploy and then launch your app in the debugger.

If the selected device is an emulator that is not started yet, the IDE will automatically boot it for you.

Note: When you connect an Android device for the first time, you will need to approve it for USB debugging on the device. After approving, it might take a few seconds for the device to appear in the CrossBox menu.

Under the hood, the CrossBox menu uses the standard Android command line tools to determine available devices and emulators. If a device does not show in the menu, try running the Android SDK adb devices tool from the command line. Elements can only detect devices shown by this command; if your device does not show in adb devices, you have a more general connectivity or setup problem.

To create and configure Emulators, you can use the Virtual Device Manager, in Android Studio. Please refer to the Android Studio Documentation for details.

Also Note: Android Studio can sometimes interfere with debugging from other IDEs. If you have problems launching your Android app in the debugger, make sure Android Studio is shut down and try again.

Debugging Android NDK Extensions

Android NDK Extensions cannot run on their own, and as such, an NDK project cannot be directly launched in the debugger. However, NDK Extensions can be debugged in the context of the SDK-based android app that contains them. The easiest way to do this is to have both projects in the same solution, and use a Project Reference to add the NDK Extension to the app, as described in the Mixing SDK and NDK topic.

There are two settings to be set for mixed debugging to work:

First, there's the "Support Native Debugging" option in the NDK project. It's enabled by default for the Debug configuration in new projects, and it instructs the build chain to deploy the LLDB debugger library as part of your native library (and have it, in turn, bundled into your .apk). This is what allows the debugger to attach to the NDK portion of your app later.

Secondly, there's the "Debug Engine" option in the SDK project. It defaults to "Java", for JVM-only debugging, but as soon as a Project Reference to an NDK extension is added Fire or Water will automatically switch it to "Both" (again, only for the Debug configuration), instructing the Elements Debugger to start both JVM and native debug sessions when you launch your app.

With these set, you can debug your Android SDK application as described in the section above. You can set breakpoints or react to exceptions from both native and Java-based code.

Android Debug Hosts

Sometimes you need to debug code in the context of an Android app not created with Elements. The most common case would be an Android NDK Extension that you use in an app created with Android Studio.

By adding three settings to your project, you can enable the Fire and Water Debugger to launch an application of your choice in Mixed-Mode db debugging (i.e. with the ability to debug both Java and NDK code). This allows you to debug all parts of the launched application (whether created with Elements or not) that you have debug symbols for, but most importantly, it will allow you to debug any Java or NDK code from your current project that is running in the context of the application.

To enable this three settings (one optional) need to be provided:

  • DebugHostAPK: Optional, this setting can point to the full path of a ready-to-deploy .apk package file. If set, the debugger will install this package on your Android device or emulator as part of the debug session (instead of your current project's output). If the application you want to debug is already deployed, you can leave this empty.
  • DebugHostPackageName: The name of the application to launch. This is the reverse-domain notation name (a.k.a. Package ID).
  • DebugHostActivity: The full name of the activity to launch.

For Example:

<DebugHostAPK>/path/to/org.me.myapplication.apk</DebugHostAPK>
<DebugHostPackageName>org.me.myapplication</DebugHostPackageName>
<DebugHostActivity>org.me.myapplication.MainActivity</DebugHostActivity>

Note: It is up to you how the code you want to debug gets into the .apk file you are debugging; please refer to the documentation for the development tool you are using to create the .apk on how to embed second-party Java or NDK code.

When embedding NDK Extensions created with Elements for debugging, make sure that the "Support Native Debugging" option is turned on, and that you embed the libgdbserver.so debugger binary that is emitted as part of the NDK's output alongside the main .so file generated from your project.

See Also