Debug Android

Debug Android

Debug Tab

By Paul F. (Intel), Michael E. (Intel), Added Wed, 09/21/2016 - 11:35

The Debug tab provides remote on-device debugging of your application without requiring a build and install step. Remote debug is provided by the Google Chrome* Developer Tools (CDT). The CDT debugger includes full JavaScript* debugging with breakpoints and profiling, which are not possible when using the weinre* debug tools and the Test tab.

Because the Debug tab uses on-device debugging, it provides the most accurate preview and debug experience you can get for your app, without having to build and install your app on a device.

When debugging on Android* devices, the Debug tab installs a custom App Preview debug module that reflects most of your app's project settings and all plugins included in your project (including all third-party plugins).

When debugging on iOS* devices you are limited to the core Cordova plugins that are found in App Preview. The Debug tab does not support third-party plugins on iOS devices, it uses a debuggable version of App Preview, which is limited to the core Cordova plugins; debugging third-party plugins on iOS is a feature we hope to add in a future release of the Intel XDK. If you wish to debug an iOS app that contains third-party plugins you can build your app and include weinre or, if you have a Mac, create a develop build of your app and use Safari and remote web inspector.

We highly recommend that you use the Debug tab as your preferred debug solution!

If you are having troubles building a custom debug module for use with the Debug tab, please read the section of this article titled Debugging on Android with a Generic Debug Module for additional help.

With this feature you can develop HTML5 code and immediately test and debug your application while it runs on a supported USB-connected device. Intel App Preview must be installed on your device(s) to use this feature. If it is not installed, the Intel XDK will attempt to install it automatically, or prompt you to install it manually. Intel App Preview is available as a free download from the respective app stores (search the stores for "Intel App Preview").

Intel App Preview facilitates remote debugging via Chrome DevTools. By using CDT remotely, you can set breakpoints in the code running on your USB-attached device, inspect variables, single step through you code, monitor DOM events, modify CSS and use the standard CDT profiling tools. (Note: for Apple iOS* devices, some features of CDT may be missing due to differences between remote CDT and remote web inspector, especially when used with devices running older versions of iOS).

The Debug tab functions only after you connect a supported mobile device to your development system with a USB cable. That device must be configured for USB debugging. You do not have to "root" or "jailbreak" your device to use this feature. Currently, only Android 4.x and above, and iOS 6.1+ devices are supported by the Debug tab. See the Test tab for a more limited remote debug feature that works with older Android and iOS devices and for use with Microsoft Windows* 8 and Windows Phone 8.1 devices.

Debug Tab Startup Summary for Android and iOS

When you first connect your Android device via USB, it will be inspected to determine if a special Intel App Preview debug module needs to be installed, or if a previously installed copy of the App Preview debug module needs to be updated. If you do not see such a prompt, follow the Android Help instructions on the Debug tab to setup your device for use with the Debug tab. An Intel App Preview debug module must be installed on your Android device to use the Debug tab.

For iOS devices, follow the iOS Help instructions on the Debug tab to create and install a special "debuggable" version of App Preview for iOS (aka Debuggable App Preview) that is signed with an Apple development [wildcard] certificate and an appropriate provisioning file created using your Apple Developer account (see these help documents regarding obtaining an Apple dev certificate and creating an Apple dev provisioning profile). This special Debuggable App Preview for iOS must be installed on your iOS device to use the Debug tab (you may also need to install Apple iTunes* on your development machine to facilitate debugging an iOS device with the Intel XDK).

When debugging on iOS* devices you are limited to the core Cordova plugins that are found in App Preview. The Debug tab does not support third-party plugins on iOS devices, it uses a debuggable version of App Preview, which is limited to the core Cordova plugins; debugging third-party plugins on iOS is a feature we hope to add in a future release of the Intel XDK. If you wish to debug an iOS app that contains third-party plugins you can build your app and include weinre or, if you have a Mac, create a develop build of your app and use Safari and remote web inspector.

Custom Debug with a USB-connected Android Device

When debugging an HTML5+Cordova project with a USB-connected Android device, the Intel XDK attempts to simulate a built app by including the plugins specified in your app's Project tab in a custom debug module. The Intel XDK uploads your project plugin selections and project settings (to the Intel XDK cloud-based build system) and builds this custom debug module an then downloads and installs it onto your USB-connected Android device. This debug module is utilized when you use the:

Debug tab

Develop tab > Run My App > Run on USB Connected Devices.

Each time you start your app on a USB-connected Android device (using the tools listed above), the Intel XDK will check for any changes in your project settings that affect Apache Cordova* plugins or Crosswalk* build settings. If changes in these settings are detected, a new custom debug module is automatically built and installed on your USB-connected Android device.

You always have the option of skipping an update to an existing custom debug module after making changes to your project build settings and, alternatively, using the existing custom module that is already installed on your device. Simply push the “cancel” button upon starting the debug session and select “skip” on the “debug module is out of date” dialog that is presented.

The following diagram summarizes the data flow of the plugin data and the project-specific debug module.

The Intel® XDK Debug tab provides full coverage of your app's selected plugins while it runs on your USB-connected Android device. Debugging with USB-connected iOS devices is also supported by the Debug tab; however, debugging third-party plugins is not supported, at this time, on iOS devices!

Requirements for Debugging with Android Devices

This feature requires that your debug device:

Uses Android versions 4.0 or later

Has version 2.4.0 (or later) of the free Intel App Preview mobile app installed

Has USB debugging enabled, an unlocked home page, and other requirements explained in Configuring Your Android USB Debug Connection .

You must install version 2.4.0 (or later) of the Intel App Preview mobile app on each device that you plan to use with the Debug tab. To view the App Preview version installed on your Android device either:

Tap Settings > Applications > Intel App Preview

Launch App Preview and simultaneously tap five fingers on the App Preview screen to view version information.

You can download the free Intel App Preview from the appropriate app store, such as the Google Play* store.

How Often is a Debug Module Generated, Downloaded, and Installed?

For a Standard HTML5 project, a debug module is usually generated just once for each project when you run your app on your USB-connected device. If you change the Crosswalk Runtime information, a debug module will again be generated, downloaded, and installed on your test device when you run your app on your USB-connected device.

For an HTML5+Cordova project, whether the Intel XDK generates a debug module depends on what changes have been made to the selected plugins or their versions (Plugin Manager) or to the Cordova Runtime settings (Build Settings) since the last debug module was generated. If changes are detected, when you run your app on your USB-connected device, a new debug module is generated, downloaded, and installed on your test device.

The time needed to generate the project-specific debug module and install it on your test device varies. Factors include the speed of your Internet connection (upload and download) and build server activity.

Minimizing How Often a Debug Module Gets Generated

Before you run your app on your USB-connected device, you might check/update the following settings in the Projects tab to minimize the how often a debug module gets generated for HTML5+Cordova projects:

In the Plugin Manager, check:

Your plugin selections.

For each selected plugin, its plugin version.

Under Build Settings in the Crosswalk-Android tab, check the Crosswalk Runtime values, which include:

Choose either an Embedded mode build (default) or a Shared mode build.

For an Embedded build, the Crosswalk version.

For a Shared build, whether a beta or stable version is chosen

You always have the option of skipping an update to an existing custom debug module after making changes to your project build settings and, alternatively, using the existing custom module that is already installed on your device. Simply push the “cancel” button upon starting the debug session and select “skip” on the “debug module is out of date” dialog that is presented.

Debugging on Android with a Generic Debug Module

If you find that you cannot build a custom debug module, a “generic” debug module can be installed onto your system. This generic debug module contains only the core Cordova and Intel XDK plugin APIs (similar to the debug module used with previous versions of the Intel XDK). To install this generic debug module:

push the “start” button (from the Debug tab) to start building a debug module

push the “cancel” button during the custom debug module build phase

push the “cancel” button when the “debug module required” warning message appears

select the “yes” button when presented with the option to install the “generic debug module” onto your device

This “generic” debug module is included with the Intel XDK during installation, so you do not need a network connection to install the generic debug module onto your device. You must, however, go through the sequence described above to debug using the generic debug module each time you start a new debug session (the install is only required once). The generic debug module has the same limitations as the Debug feature in older versions of the Intel XDK, namely:

generic debug is limited to the core Cordova and a limited set of the Intel XDK APIs

generic debug is limited to the "default" version of the Crosswalk runtime (aka webview)

generic debug does not support third-party Cordova plugins

We highly recommend that you build a custom debug module for your projects in order to optimize the accuracy of your preview and debug experience. A new debug module will only be built if you make a change to your project that results in a significant change, such as:

adding or removing a plugin

changing the version of a plugin

changing the version of Crosswalk

Troubles Starting Debug on your Android Device

There are a variety of reasons that can prevent your Debug session from starting. Usually they are caused by one of the following:

Configuring Your Android* USB Debug Connection.

Insufficient memory or storage on your Android debug device.

Problems with the adb (Android Debug Bridge) server on your development system.

Unable to "auto-start" Intel App Preview and the debug module on the Android device.

Follow the links in the list above for some recommended solutions to these problems. Additional solutions on this FAQ page may also help.

About the Debug Modules Installed on Your Device

Previous versions of the Intel XDK always installed generic debug modules called App Preview Crosswalk when using the Debug tab with your USB-connected device. These debug apps were shared by all of your Intel XDK projects for use with the Debug tab (multiple copies were necessary to support different versions of Crosswalk). The Intel XDK now creates a custom App Preview debug module that is unique to each project.

For each custom debug module that is generated, the Intel XDK installs an app named AP Debug xnn project-name. There is one debug module app generated and installed on your device for each project. For example, if you add or remove plugins or change their versions, a new project-specific debug module is generated and installed. This new debug module replaces the previous debug module app installed on that device for that project. This ensures that the debug module contains the most recently selected plugins when you run your app on your USB-connected test device.

If you change the Crosswalk version settings in the Build Settings section of the Project tab, the Intel XDK generates and installs a new debug module, but it does not replace a previous debug module for that project built for a different version of Crosswalk. For example, if you have recently tested your app with a different version of Crosswalk, that previous debug module will still be present on the device.

If you test a new app on the same device, you will find two debug module apps on your device (one per project). As you increase the number of apps you test and/or versions of Crosswalk, you will add to the list of installed custom debug modules on your test device.

When a project is no longer in active development or testing, you should consider uninstalling that project's associated debug module apps from your test device(s). You can use the Intel XDK to remove debug modules from your USB-connected Android device:

On your development system, open the Debug tab.

Click the  button on the toolbar.

After the Intel XDK scans your device, view each debug module package ID, its creation date, its Crosswalk version,and its associated project name.

Select each debug module you want to remove.

Click the Remove button to remove the selected debug modules.

Either Close the dialog or click Rescan to display the remaining debug modules.

Alternatively, you can do this manually on your Android device: tap Settings > Application manager and scroll to see a list of the installed debug modules. Tap to uninstall the ones no longer needed.

Debug Tab Web Runtimes

When debugging your application via the Debug tab, the Intel XDK pushes your application to a special App Preview debug module. On Android devices your app runs in a Crosswalk WebView (the App Preview debug module is built with Crosswalk). The performance and behavior you see using the Debug tab with an Android device is what you will see when you build your app using the Android-Crosswalk build tile. On iOS devices the Debug tab performance and behavior is equivalent to what you will see when you build your app using the Cordova for iOS build tile (precise performance and behavior is dependent on the version of iOS that is running on the device). The Debug tab cannot be used to debug the behavior of your app if you build with the Windows build tiles. See Debug and Test Overview for additional debug options.

When using the Debug tab with an Android device you are running your app in the Crosswalk* portable application runtime. The special Intel App Preview debug module used by the Debug tab is an Apache Cordova* container built using the Crosswalk Project WebView for Android. This means that your code runs in an Android-Crosswalk WebView, not in the built-in Android device WebView, so the behavior and appearance of your app will differ compared to what you will see if you build for Android, versus building for Android-Crosswalk. For more background regarding what a WebView is, please read this blog.

The Crosswalk portable runtime for Android is built on top of the Chromium* content module and Blink* rendering and layout engine. This means it shares many of the features found in the Google Chrome* browser on your desktop. In addition to the standard Crosswalk APIs the App Preview debug module for Android used by the Debug tab also includes an implementation of the Apache Cordova framework for Android and exactly those Cordova plugins that you have specified as part of your project.

Choosing the "shared model" Crosswalk build option for your Android-Crosswalk application requires installation of the Crosswalk shared model runtime library onto your test device. When you start a Debug session for a project that is configured to use the Crosswalk shared model library, the Intel XDK may update or replace the shared Crosswalk library on your device. This can result in the Crosswalk shared library no longer updating automatically via the Android store. If you want the runtime to automatically update via the store, remove the Crosswalk shared library from your device and re-install it directly from the Android store, after you are finished debugging.

When properly configured, the App Preview debug module for Android contains a customized runtime environment that represents the runtime environment, plugins and build settings your app will see if you build it with the Android-Crosswalk build option.

The runtime behavior of the App Preview debug module on your iOS device is a function of the version of iOS that is running on your device. The built-in iOS WebView includes many of the features found in the Safari mobile browser on your device (with a few limitations imposed by Apple). Unlike the debug module used for debugging on Android devices, the iOS debug module (aka Debuggable App Preview) includes a fixed implementation of the core Apache Cordova device APIs and the Intel XDK APIs.

The App Preview debug module used for debugging on iOS devices is not customized to match the plugins and build settings of your project. A future version of the Intel XDK will support customization of the App Preview debug module used on iOS. For that reason, it is not possible at this time to debug features of your iOS app that require the use of third-party plugins using the Debug tab. See Debug and Test Overview for additional debug options.

Next