Debug Tab

The Debug tab provides remote on-device debugging of HTML5 code without requiring a build and install step. Remote debugging 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.

This 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. Only Android* 4.x, Android 5.x 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 Android 2.3+, all Apple iOS* devices and Microsoft Windows* 8 and Windows Phone 8 devices.

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

Debug Tab Summary

When you first connect your Android device via USB, you may be prompted to install App Preview Crosswalk (or update a previously installed copy of App Preview Crosswalk). See the Android Help instructions on the Debug tab for more information. App Preview Crosswalk 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 your Apple development [wildcard] certificate and appropriate provisioning file (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.

App Preview Crosswalk and Debuggable App Preview enable remote debugging (via a built-in copy of Chrome DevTools). Using CDT remotely, you can set breakpoints in the code running on your debug device, inspect variables, single step through you code, monitor DOM events, modify CSS and use the standard CDT profiling tools. (Note: for iOS devices, some features of CDT may be missing due to differences between remote CDT and remote web inspector, especially when used with older versions of iOS).

Debug Tab Web Runtimes

When you debug your application with this feature, the Intel XDK pushes your application to the App Preview Crosswalk or Debuggable App Preview runtime (aka WebView or container) on your attached device. On an Android device, your app runs in the Crosswalk WebView, which you will get when you use the Crosswalk for Android build tile. Running your app on an iOS device via the Debug tab is equivalent to the WebView your app sees when you build with the Cordova for iOS build tile. The Debug tab does not simulate the Legacy build tiles.

As you run your app from the Debug tab on an Android device you are running your app within the Crosswalk* portable application runtime. App Preview Crosswalk contains an Apache Cordova* container based on the Crosswalk Project. This means that your code runs within the Crosswalk for Android WebView, not the standard built-in Android WebView container, so the behavior and appearance of your app may differ when compared to running your application within Intel App Preview for Android, such as when using the Intel XDK Test tab (which relies on the built-in Android WebView). For more background regarding what a WebView is and is not, please read this blog.

The Crosswalk portable runtime (Android only) 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 Crosswalk runtime used by the Debug tab also includes an implementation of the core Apache Cordova device APIs and the Intel XDK APIs.

The runtime behavior of the Debuggable App Preview on your iOS device is a function of the version of iOS that is running on your device. It includes many of the features found in the Safari mobile browser on your device (with some limitations imposed by Apple). Debuggable App Preview includes an implementation of the core Apache Cordova device APIs and the Intel XDK APIs. For more background regarding how a WebView differs from a browser, please read this blog.

Debug Tab Requirements

Your development environment and project must meet the following requirements in order to use this debug feature:

  • Your Android device must be running version 4.0 or higher of the Android OS, USB debugging must be enabled (described below) and App Preview Crosswalk (APX) must be installed. NOTE: APX may not install on some Android 4.0 devices, due to a lack of support for the secure signing procedures used to build Android APK packages.

  • Your iOS device must be running version 6.1 or higher of iOS and a copy of Debuggable App Preview signed with a wildcard [*] development certificate and mobile provision file (that includes your device) must be installed. Debugging must be enabled on your iOS device; you do this by enabling Web Inspector on iOS in the Safari settings screen on your iOS device. Be sure to restart App Preview after enabling Web Inspector on your iOS device.

  • Debugging with an Android device on a Windows development system requires that you obtain and install the Android USB debug driver on your Windows development system.

  • You do not need to install the Android SDK or the Apple XCode* SDK; all components needed to communicate with your debug devices (other than the Windows USB debug driver mentioned above) are provided by the Intel XDK.

  • It is not necessary to “root” or "jailbreak" your device to use this feature.

  • Close any Chrome windows that are using the Chrome remote inspection and debug feature ("chrome://inspect") when you are using the Debug tab with an Android device. The Debug tab uses adb to communicate with the Android device attached to your USB port and some versions of "chrome://inspect" can cause interference with the version of adb used by the Intel XDK.

Instructions to Setup a Debug Session

Once you have verified that your project meets the above requirements, these instructions will help you setup and start a debug session.

Debug on your iOS device is enabled by the development certificate and mobile provision files that you provided to the Intel XDK to create the special Debuggable App Preview described in the previous section and by enabling Web Inspector on iOS in the Safari settings screen on your iOS device. Continue to Step 2 if you have successfully installed a copy of Debuggable App Preview on you your iOS device and have enabled your device for Web Inspector debug (and restarted App Preview after enabling Web Inspector).

1. Enabling USB debugging on your Android device.

Verify that USB debugging is enabled on your Android device. Follow the instructions below or refer to the section titled "Setting up your device" on the Remote Debugging Chrome on Android page for detailed instructions on how to enable USB debugging for your Android. In short:

  • Find the Settings > Developer options configuration screen on your Android device.

  • If Developer options is not visible, select Settings > About device and tap the Build number item seven times. Return to the previous screen and Developer options should now be visible.

  • Enable the USB Debugging option. This launches remote debug mode when a USB connection occurs.

  • If your development system is running Linux* or Apple OS X* you already have the necessary USB drivers installed to communicate with your Android device for debug and you can proceed to step 2 below.

  • If you are using a Windows development system, you may need to install the Android USB debug driver for your device. Detailed instructions are available in this article titled Configuring Your Android* USB Debug Connection for the Intel® XDK.

IMPORTANT: If the Intel XDK does not recognize your Android device over USB, change the USB connection mode of your device from Media (MTP) to Camera (PTP). This is especially important if you are running the Intel XDK on Windows, the Android USB debug driver for Windows does not always work properly when your device is configured in MTP mode.

Connect your Android device to your development system with a USB cable. When connecting your device to your development machine you may see an alert on the device requesting permission to allow USB debugging from this computer. Click Ok to grant the permissions required to debug your Android device with this computer.

 

2. Verify that your device is seen by the Intel XDK.

When a debug connection is successfully established your device will appear in the top-left corner of the Debug tab. If you have multiple devices connected, they will appear in a drop down list, where you can select the device you will use for debugging.

If the Intel XDK seems to not be communicating with your Android device over USB, try changing the USB mode of your device from a Media Device (MTP) to a Camera Device (PTP); the default is generally set to MTP. See the following images for examples of how to (typically) change the USB mode of your device.

 

3. Start a debugging session.

The icons in the toolbar (above) are referred to as: the Debug, Run and Stop buttons, respectively.

  • Select the device to use for debugging from the drop down list of devices.

  • Make sure the selected device is on, not in sleep mode and unlocked (i.e., your home screen is visible).

  • For iOS devices you must manually start App Preview on your device. Slow Android devices will benefit from also starting App Preview manually before beginning the debug session.

  • Click the Run button to preview your app running on the device.

  • You can click Debug at any time after the app has launched to start debugging with CDT.

  • Alternatively, you can skip the Run step and click the Debug button to launch your app and start a debug session directly. If this direct to debug process does not automatically start the debug session, start your app using the Run button, wait for the app to start running on your device and then push the Debug button.

  • If you have set breakpoints that would be triggered during your app's initialization, the Chrome DevTools (CDT) may not startup quickly enough to catch those breakpoints. In that case, you can click the Debug button again to restart the app and debug with the existing CDT. Using this method your early breakpoints should be triggered.

  • Click the Stop button to end the debug session.

When you select the Sources tab in the CDT window, to begin debugging JavaScript, you may be presented with an image like that shown below. This is normal. Select "Always enable" and click the "Enable Debugging" button.

 

If you change some of the files in your project and then save them to disk, you will be notified by the Debug tab that some of your project files have changed and ask if you would like to update them on your device and restart your app. Only changed files are updated and transferred to your device over the USB, providing a more efficient edit-run-debug cycle. You may need to re-establish the debug session by pushing the Debug icon, after the Debug tab restarts your app.

In some cases JavaScript debugging and breakpoints may only work AFTER the Cordova deviceready event has been issued to your application. In that case, it is not possible to debug any code that executes BEFORE the Cordova deviceready event has been issued.

If your debug session seems to be not behaving properly, it could be that the Intel XDK and App Preview are "out of sync" with each other. In that case you may need to end the debug session by clicking the Stop button and relaunch the session. This is also how you end a debug session using the Debug tab.

You can move between tabs in the Intel XDK while the Debug tab is in use (such as switching to the editor to make changes in your code) without stopping your debug session. In other words, switching away from the Debug tab will not end a debug session.

 

4. Additional notes regarding Android debugging.

On Android devices, clicking either Run or Debug automatically installs (if required) and launches the App Preview Crosswalk container app on your debug device. App Preview Crosswalk is a required component, it facilitates remote debugging and profiling of your application on your Android device.

If this is your first time using the debug feature with a specific device, or if you have recently upgraded your copy of the Intel XDK, you may see a prompt requesting permission to install App Preview Crosswalk on your device. Click on "Install It Now" to install App Preview Crosswalk onto your device.

All of the above happens automatically directly to your Android device, it is not necessary to download and install App Preview Crosswalk from an app store.

For more complete information about compiler optimizations, see our Optimization Notice.