This article refers to the Visual Studio Tools for Apache Cordova, which is pre-release software. The features described are in preview and are subject to change. You can download the preview from the Microsoft Download Center.
This article describes how to install the tools and third-party dependencies required for creating cross-platform Cordova apps using Visual Studio Tools for Apache Cordova:
Requirements
Getting the tools
Installing the tools
Installing the dependencies manually
Installing tools for iOS
Overriding system environment variables
-
One of the following operating systems: Windows 7, Windows 8, Windows 8.1, or Windows Server 2012 R2.
ImportantIf you are using Windows 7, you can develop apps for Android and iOS, but not for Windows or Windows Phone.
-
Visual Studio 2013 Update 4 (Professional, Ultimate, Premium, or Community Edition) with the following features installed:
-
Tools for Maintaining Store apps for Windows 8
-
Windows Phone 8.0 SDK
You can add these features to an existing installation of Visual Studio 2013 Update 4. In Control Panel, choose Programs and Features. Select Visual Studio 2013 from the list, and then choose Change. In the Visual Studio setup window, chooseModify. In the features list, select the two options, as shown in the illustration.
-
-
If you are using Visual Studio 2015 Preview instead of Visual Studio 2013, see the installation procedure in this topic.
To build apps for specific device platforms, there are a few additional requirements:
-
Android emulator works best on computers that can run the Intel HAXM driver. See Run Your Apache Cordova App on Android.
-
Windows Phone emulators require a computer that can run Hyper-V. For more information, see the emulator‘s system requirements.
-
iOS and the iOS Simulator require a Mac computer capable of running Xcode 6 (Xcode 6 is recommended). For additional steps, see Install Tools to Build for iOS.
TipIf you want to build iOS on a cloud service instead of Mac hardware, see Build and Simulate iOS in the Cloud.
To get the Visual Studio Tools for Apache Cordova extension, go to the Microsoft Download Center. Follow the steps in the next section to install the extension.
| Important |
|---|
|
If you previously installed a CTP of the Visual Studio Tools for Apache Cordova (Multi-Device Hybrid Apps), you must first uninstall the CTP using Control Panel, Programs and Features before installing the Visual Studio 2013 Update 4 and the current CTP. |
In Visual Studio 2015 Preview, Visual Studio Tools for Apache Cordova can be installed as an optional feature during installation. For the installation procedure, see Get started with Visual Studio Tools for Apache Cordova.
The installer first installs a patch to Visual Studio to support Cordova app development. Then it gives you the option to install the following third-party software. Most of these are open-source software required by specific platforms or by Apache Cordova.
-
Joyent Node.js enables Visual Studio to integrate with the Apache Cordova Command Line Interface (CLI) and Apache Ripple Emulator.
-
Git CLI is required only if you need to manually add Git URIs for specific Cordova plug-ins.
-
Google Chrome is required to run the Apache Ripple emulator for iOS and Android.
-
Apache Ant 1.8.0 or later is required for the Android build process.
-
Oracle Java JDK 7 is required for the Android build process.
-
Android SDK is required for the Android build process and Ripple.
-
SQLite for Windows Runtime is required to add SQL connectivity to Windows apps (for the WebSQL Polyfill plugin).
-
Apple iTunes is required for deploying an app to an iOS device connected to your Windows PC.
To install the Visual Studio extension and dependencies
-
Run the installer that you found in Get the tools.
-
Follow the instructions to install the Visual Studio extension.
-
When prompted, allow the installer to install third-party software dependencies, or you can clear the software selections and manually install the dependencies you need later.
ImportantIf the third-party dependencies are already on your system or you choose to install them manually, you might have to update your system path. See Installing dependencies manually.
-
Reboot your computer.
ImportantYou must reboot to make sure everything is installed correctly.
-
Open Visual Studio, choose Tools, then Extensions and Updates, and then Updates. If there is a Visual Studio update available for Visual Studio Tools for Apache Cordova, install it.
NoteThe first time you build an app after installing the tools, Visual Studio will download and install the Cordova tools. As a result, the first build takes extra time to complete. Check the Output window to see progress.
-
Before you run your app on the iOS Simulator or an iOS device, you must install the remote agent on a Mac computer. See Install Tools to Build for iOS.
If you choose not to install one or more dependencies with the extension, you can install them later manually.
| Caution |
|---|
|
You can install the dependencies in any order, except for Java. You must install and configure Java before you install the Android SDK. |
Read the following information and use these links to install dependencies manually.
-
We recommend installing the x86 version of Node.js.
-
When you install Git command line tools, select the option that adds Git to your command prompt path.
CautionGit command line tools 1.9.3 are installed by default. Unexpected failures may occur if you install a version prior to 1.9.0.
-
-
Download and extract Ant to a location like C:/ant-1.x.x
-
Set the ANT_HOME environment variable to point to the preceding location.
-
Add %ANT_HOME%\bin to the system path.
NoteIf you need to set this environment variable manually, see Override system environment variables.
-
-
-
Set the JAVA_HOME environment variable to C:/Program Files/Java/jdk1.7.0_55
-
Add this to the system path: %JAVA_HOME%\bin
NoteIf you need to set this environment variable manually, see Override system environment variables.
-
-
Android SDK with the following SDK packages:
-
Android SDK Tools (latest version)
-
Android SDK Platform-tools (latest version)
-
Android SDK Build-tools (latest version)
-
Android 4.4.x (API level 19) with the following packages:
-
SDK Platform
-
ARM EABI v7a System Image
-
Intel x86 Atom System Image
-
Google APIs (x86 System Image)
-
Google APIs (ARM System Image)
-
The following illustration shows the required packages in the Android SDK Manager.
Set the ADT_HOME environment variable to the SDK installation location.
Add this to the system path: %ADT_HOME%\tools;%ADT_HOME%\platform-tools
If you need to set this environment variable manually, see Override system environment variables.
TipIf you install the Android SDK to its default location on Windows, it gets installed to C:\Program Files (x86)\Android\android-sdk.
-
-
WebSocket4Net (required if you’re developing your app on Windows 7)
-
Download WebSocket4Net(0.9).Binaries.zip from CodePlex.
-
From the downloaded zip file, copy net45\Release\WebSocket4Net.dll into the %ProgramFiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\WebClient\Diagnostics\ToolWindows folder on your computer.
-
A few extra steps are required to build and run apps for iOS from Visual Studio. See Install Tools to Build for iOS.
Visual Studio detects the configurations for the third-party software you’ve installed, and maintains the installation paths in the following environment variables:
-
ADT_HOME points to the Android installation path.
-
ANT_HOME points to the Ant folder on your computer.
-
GIT_HOME points to the Git installation path.
-
JAVA_HOME points to the Java installation path.
Visual Studio uses these environment variables when building and running your app. You can view the environment variables and revise their values through the Visual Studio Options dialog box. You might want to override the default settings for one of the following reasons:
-
Visual Studio was unable to verify the path. In this case, a warning is displayed next to the environment variable.
-
You have multiple versions of the software installed, and you’d like to use a specific version.
-
You want your global environment path to be different from the local Visual Studio environment.
To override the variables
-
On the Visual Studio menu bar, choose Tools, Options.
-
In the Options dialog box, choose Tools for Apache Cordova, and then choose Environment Variable Overrides.
-
Make your changes:
-
To override a value, select its check box, and then revise the value.
If the path information is invalid or missing, Visual Studio displays a warning next to that variable.
-
To reset an environment variable to its default value, clear its check box or choose Reset to Default.
-
-
Choose OK to save your changes and close the dialog box.
Visual Studio has been test against a specific version of Apache Cordova. We intend to support selecting a Cordova version at a per-project level, but even now it is possible to apply a patch to use a different version of Cordova across all projects on your system.
| Caution |
|---|
|
Patching Visual Studio is not officially supported. You may run into unexpected behaviors and we recommend that only advanced users take these steps. The patch makes system-wide changes to your machine. |
To update Visual Studio to use a different version of Cordova
-
After you install Visual Studio Tools for Cordova, create and build a blank project to install Cordova.
-
Open a command line and type this command:
cd %appdata%\npm\node_modules\vs-mda
If you installed Node.js yourself, vs-mda may be installed in a different location. The preceding command shows the default installation location.
-
On the command line, type this command:
npm install cordova@version --save
where version is the version of the Cordova CLI that you want to use. For example, you might use 4.1.0.
If you‘ve installed Cordova somewhere else, you can type cordova --version to find out the Cordova version.
ImportantBe sure to omit the -g global switch when you run the preceding install command.
-
Run a "clean" operation such as Clean Solution on the project you are editing in Visual Studio to make the version change take effect.
To revert to the supported version of Cordova
-
Open a command prompt and type:
npm uninstall -g vs-mda
Visual Studio will automatically reinstall vs-mda the next time you build.
Alternatively, you can search for the vs-mda file under C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions and modify package.json to refer to the version you would like to use. When you are finished modifying package.json, run the following command from same folder:
npm install -g vs-mda
For iOS build support on your Mac, the version of Cordova that vs-mda-remote uses must match the version that you installed for Visual Studio. The following steps describe how to update vs-mda-remote to use a specific version of Cordova. For complete information on installing iOS build tools, see Install Tools to Build for iOS.
To update vs-mda-remote on your Mac to a different version of Cordova
-
Open the Terminal app on your Mac and type the following command:
cd /usr/local/lib/node_modules/vs-mda-remote
If you did not install vs-mda-remote globally (-g) the location of vs-mda-remote may be different on your Mac.
-
Type this command:
sudo npm install cordova@version --save
where version is the same version of the Cordova CLI you installed previously. For example, this might be 4.1.0.
ImportantBe sure to omit the -g global switch when you run the preceding install command.
If you installed Cordova somewhere else, you can type cordova --version to find out the Cordova version.
Run a "clean" operation such as Clean Solution on the project you are editing in Visual Studio to make the version change take effect.
To revert vs-mda-remote on your Mac to the supported version
-
Open the Terminal app on your Mac and type:
sudo npm uninstall -g vs-mda-remote
-
Type the following command:
sudo npm install -g vs-mda-remote --save
