Using Crosswalk with Visual Studio Tools for Apache Cordova

4/29/2015 - Updated instructions for Visual Studio 2015 RC

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 is 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

1. Before you start:
   
   Download and Expand the Crosswalk 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 Visual Studio 2015 RC. In later versions, these steps might 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. Go to the \platforms\android\CordovaLib subfolder of the project, and delete the contents of \platforms\android\CordovaLib.
8. Copy AndroidManifest.xml from \platforms\android\ to \res\native\android\
9. Edit 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. Add a directory named CordovaLib in your \res\native\android\ folder.
11. The Crosswalk packages you downloaded in Step 1 are needed now.
    
    copy the entire contents of the ARM directory
    
            \crosswalk-cordova-11.xx.xxx.xx-arm\framework
    
    to your project's
    
            \res\native\android\CordovaLib\
12. Copy the VERSION file from
    
            \crosswalk-cordova-11.xx.xxx.xx-arm\VERSION
    
    to your project's
    
            \res\native\android\VERSION
13. If you want x86 support as well, copy the x86 folder from
    
            \crosswalk-cordova-11.xx.xxx.xx-x86\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. Execute a Build in VS (Ctrl+Shift+B), so that the files in \res\native\android\ are copied to \platforms\android\.  NOTE: At this point, the build will succeed but Crosswalk is NOT yet enabled!
15. Now we have to build the libs for Crosswalk.
    
    You only need to do this once.
    
    Open a command prompt at \platforms\android\CordovaLib and execute:
    
    
    android update project --subprojects --path . --target "android-21"
    
    Next, type in:
    ant debug
    
    ... you should see a BUILD SUCCESSFUL at the finish.
16. In the command prompt, go up one directory to \platforms\android\ and once again update the version and run ant:
    
    android update project --subprojects --path . --target "android-21"
    ant debug
    
    ... you should see a BUILD SUCCESSFUL at the finish.
17. Close any of the open cmd prompts and File Explorer Windows, as the VS build process attempts to delete some of these folders.
18. Back in Visual Studio, select Build/Rebuild Solution. This time your build will take a bit longer because it's packaging up the Chromium runtime with the APK.
19. Run the project on the device using F5. Note that Visual Studio currently does not support debugging with Crosswalk, because it cannot attach it's debugger. You can use ChromeDev tools to debug, however.
20. 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 40.0.2214.91, but it depends on the release of the Crosswalk libraries you downloaded in Step 1):
    
    
    
    
    
    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!