Build and Run using Cordova CLI

With Apache Cordova, web developers can achieve maximal code re-use by building cross-platform mobile applications using HTML, CSS, and JavaScript. For details on how Apache Cordova works, read this blog.

In order to build such a cross platform multi device application, Visual Studio uses a Cordova utility known as the Cordova command-line interface (CLI). The CLI allows Visual Studio to build projects for many platforms at once, abstracting away much of the functionality of lower-level shell scripts. The CLI copies a common set of web assets into sub-directories for each mobile platform, makes any necessary configuration changes for each, and runs build scripts to generate application binaries. The CLI also provides a common interface to apply plugins to your applications. Let us see how Visual Studio uses the Cordova CLI while building such application.

How does VS combine with Cordova CLI to build my multi device hybrid application?

Once you create a new Cordova project in Visual Studio, you see the layout as shown on the left side of the following illustration. To leverage the Cordova CLI from the Visual Studio project structure, Visual Studio uses a CLI pre-processor called vs-mda. The goal behind vs-mda is to pre-process the Visual Studio project (on the left), generate a Cordova CLI project (on the right) and then work with the Cordova project using the Cordova build commands to build a native platform application.

Visual Studio Project vs Cordova CLI project side by side comparison

Our pre-processor (vs-mda) is a node JS script that strings together a series of Cordova CLI commands as part of the build:

  1. It creates a Cordova project in bld\<config> folder. (cordova create command)

  2. Adds the target platform (for android, cordova platform add android)

  3. Prepares the target platform (copy folders like www/merges, config.xml update, update android package name, apply code signing certificates , etc)

  4. Adds/Updates plugins. There is logic here to make sure plugin add/remove command is run as needed:

    a. cordova plugin add

    <VS Solution>\<VS Project>\bld\Debug\plugins\org.apache.cordova.battery-status

    b. If config.xml has parameters for a plugin, then the parameters are also passed. For example if you were installing a Facebook plugin:

    cordova plugin add

    <VS Solution>\<VS Project>\bld\Debug\plugins\phonegap-facebook-plugin –variable APP_ID=”123456789″ –variable APP_NAME=”myApplication”

  5. Finally, if this is just a build, then the build Cordova build command is called (for android, cordova build android) to build the application for the targeted native platform.

  6. Alternatively, if the deploy command in vs was run, then the following CLI equivalent is run (for android, cordova run android).

  7. If Debugging is enabled, then VS also attaches a debugger after the run command above.

Like any other Visual Studio project, you can trigger the build command from the build menu or the run command from the debug toolbar as shown below. Running the build will generate the platform specific package ready for deployment and testing.

Build command in Build menu and Run command in Debug toolbar

One thing to mention is that for Cordova to build the native application, during its compile step, it needs the SDK’s for target platforms already installed.

So,

  • To compile applications for Android platform, you need the Android SDK installed (which is installed as part of the extension)

  • For Windows, you need Windows SDK with the associated MS-Build targets

  • For building iOS packages, you need to have a Mac that has XCode and XCode command line tools installed.

As mentioned above, to be able to build for the iOS platform, the iOS SDK must be installed on your system and hence an iOS app cannot be built on Windows. So to build for iOS, we provide a remote build agent called vs-mda-remote that runs on a remote Mac machine or locally if you are using Visual Studio inside Parallels on a Mac. For building iOS, vs-mda prepares the CLI project exactly as it would for any platform that it builds locally for and then transfers the contents over to vs-mda-remote on the Mac for compilation and packaging.

The complete build process can be illustrated as:

Build process illustration

How do I run my multi device hybrid application?

After the native application is built, Visual Studio applies different techniques to run/emulate the app on different platforms.

For example, in the case of Android, the CLI “Cordova emulate android” command uses the Android debug bridge to deploy the app to the running instance of the emulator that is configured using the AVD (Android Virtual Devices) manager. Here is how you can configure your Android device or emulator. In future releases, we intend enhance this interaction in VS to allow more flexible selection of Android emulators that you have locally configured and devices connected to your host machine.

To run apps on iOS, VS uses ios-sim to start up simulator on the remote Mac machine. If you run the app to device, VS builds and then adds the app to your iTunes for you to deploy it to your device from Windows. In the CTP3 release, we have added support to directly deploy, launch and debug the app on a device connected to your the remote Mac build agent.

We also provide you an option to launch your app in the Apache Ripple simulator before you deploy it to your device. Through Ripple, you can build your application using a traditional web developer workflow and even simulate common Cordova plugins like the camera. From there you can move on to native devices and emulators to add in more advanced features and finish and refine your app on each of your target devices.

If you’ve already installed the tools and are actively using it, thank you! If not, install the Visual Studio 2015 Preview and check the optional “Tools for Apache Cordova” option or install Visual Studio 2013 Update 4 and Visual Studio Tools for Apache Cordova CTP 3. The improvements we prioritize are based largely on your feedback, so please don’t feel shy in contacting us via UserVoice, Twitter, StackOverflow, and email.

Subhag Oak Subhag Oak, Senior Program Manager, Visual Studio Client Platform Tools Team

Subhag Oak is a Program Manager on the Visual Studio team, focusing on mobile app development technologies and Apache Cordova. Before being a PM, Subhag has worked as a developer for 12 years on a number of tooling features, all designed to make it easier for developers to build and debug applications using Visual Studio.