Thursday, January 29, 2015

Using Crosswalk with Visual Studio Tools for Apache Cordova


UPDATE 4/29/2015: For Visual Studio 2015 RC, please see this updated post!

UPDATE 1/30/2015: You can also see a video walkthrough of these steps.

If you've tried targeting Android devices using Hybrid app frameworks, you've probably run into issues with performance and outdated Chrome runtimes in the WebView. This is an issue with even newer devices with Android 4.4+ because the WebView does not use the same version of Chrome that the device has installed. For example, a Nexus 7 with Android 4.4.4 will use version 33 of Chrome - which is ancient in internet time! That means you are missing out on great features such as WebGL Support in Hybrid apps.

Enter the Crosswalk Project - which allows you to deploy the latest builds of Chromium with your Android app, and support all Android 4.x devices with the same featureset.


What is the downside you ask? The main downside the size of your deployed app. You can expect the Crosswalk library to add about 15 MB to your APK if you target _either_ ARM or x86. If you choose to target _both_ with a single APK, you can expect about 30 MB added to the size. This is an unfortunate amount of bloat, but for some apps it might be just fine. But there are other downsides as well... Don't expect Debugging Support when using Visual Studio Tools for Apache Cordova (at least not in CTP3). You can however use Chrome DevTools to debug Crosswalk apps. Also in my experience, Emulator support is hosed as well - you will need a physical device to test and run your apps.

But if you determine the benefits of Crosswalk outweigh the limitations, read on!

Adding Crosswalk Support to a Visual Studio Tools for Apache Cordova project

  1. Before you start:

    Download and Expand the Cordova Android (ARM) and Cordova Android (x86) packages. IMPORTANT: Make sure you get the Cordova versions!!

    If you are doing this to an existing project, be sure you are checked into source control, or at least back up your project! Just in case something goes wrong.

    Note that these instructions are for CTP3 of VS Tools for Apache Cordova. In later versions, these steps will surely change.

    You will need a physical Android device (I am using a Nexus 7)
  2. Create a new Visual Studio project using the Blank App template:

  3. Change your target to Android / Device:

  4. Run the Project so that it deploys to the device and runs.
  5. Open up Chrome and enter the url "chrome://inspect" - and note that the version of the Chrome WebView on the device is ancient history (in the case of the Nexus 7, it is 33.0.0.0).

  6. Back in Visual Studio, in the Solution Explorer select "Show All Files."
  7. NOTE: In the following steps, we will be adding a bunch of files to the \res\native\android folder of the project. The content of this folder is automatically included in your Android app by VS at build time.
  8. Make a copy of the AndroidManifest.xml file in

    \bld\Debug\platforms\Android to

    \res\native\android 
  9. Edit the copy you made of AndroidManifest.xml in \res\native\android so that it includes the following permissions just _before_ the <application> node.

    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  10. Create a new folder named CordovaLib inside the \res\native\android\ folder of your project.

  11. The Crosswalk packages you downloaded in Step 1 are needed now.

    copy the entire contents of the ARM directory

            \crosswalk-cordova-10.xx.xxx.xx-arm\framework

    to your project's

            \res\native\android\CordovaLib\
  12. Copy the VERSION file from

            \crosswalk-cordova-10.xx.xxx.xx-arm\VERSION

    to your project's

            \res\native\android\CordovaLib\VERSION
  13. If you want x86 support as well, copy the x86 folder from

            \crosswalk-cordova-10.xx.xxx.xx-arm\framework\xwalk_core_library\libs\

    to your project's

            \res\native\android\CordovaLib\xwalk_core_library\libs
    ... so that it you have both the x86 and armeabi-v7a folders in the libs directory.
  14. Go back to Solution Explorer and be sure to include all of the files we just added into your project (Show All Files, Refresh, and then right-click all files, Include in Project).
  15. Now we have to build the libs for Crosswalk.

    You only need to do this once.

    Open a command prompt at \res\native\android\CordovaLib and execute:

    android update project --subprojects --path . --target "android-19"
    ant debug

    ... you should see a BUILD SUCCESSFUL at the finish.
  16. Close any of the open cmd prompts and File Explorer Windows, as the VS build process attempts to delete some of these folders.
  17. Back in Visual Studio, select Build/Rebuild Solution.
  18. Run the project on the device using F5. You will get an ugly dialog saying "Unable to start progam .... android_sdk\platform-tools\adb.exe" - From what I gather, this is because VS cannot attach it's debugger. You can use ChromeDev tools to debug, however.
  19. To verify we are using Crosswalk, go back to Chrome and enter the URL chrome://inspect. You will see a much newer version of Chrome (in my case 39.0.2171.71):












    That's it! We now have all of the goodness of a new Chromium runtime in our Android app, including toys like WebGL Support and improved performance!