diff --git a/Readme.md b/Readme.md index b587e706..0a85f256 100644 --- a/Readme.md +++ b/Readme.md @@ -1,12 +1,20 @@ # Visual Studio Tools for Apache Cordova -This repository contains a set of documents and tutorials for the **Visual Studio 2015 RC** release of **[Tools for Apache Cordova](http://aka.ms/cordova).** +This repository contains a set of documents and tutorials for the **Visual Studio 2015** release of **[Tools for Apache Cordova](http://aka.ms/cordova).** -**Note that this documentation does not apply to Visual Studio 2013 CTPs.** +**Note that, with the exception of known issues, this documentation does not apply to Visual Studio 2013 CTPs.** ## Tutorials +1. [Using Apache Cordova 5](./tutorial-cordova-5) + 1. [An Introduction to Cordova 5 Security](./tutorial-cordova-5/cordova-5-security.md) 1. [Using Gulp with your Cordova projects](./tutorial-gulp) + 1. [Using Gulp to Build Cordova Projects](./tutorial-gulp/gulp-ci.md) + 1. [Invoking Gulp Tasks During a Cordova Build and the VS Task Runner Explorer](./tutorial-gulp/gulp-task-runner-explorer.md) + 1. [Compiling TypeScript wit Gulp](./tutorial-gulp/gulp-typescript.md) 1. [Building Cordova Apps in a Team / Continuous Integration Environment](./tutorial-team-build) + 1. [Getting Start with Cordova & TFS 2015 or Visual Studio Online](./tutorial-team-build/TFS2015.md) + 1. [Getting Start with Cordova & TFS 2013](./tutorial-team-build/TFS2013.md) + 1. [Getting Start with Cordova & Jenkins CI](./tutorial-team-build/Jenkins.md) 1. [Package & Publish your Cordova Applications](./tutorial-package-publish) @@ -30,7 +38,6 @@ This repository contains a set of documents and tutorials for the **Visual Studi 1. [Visual Studio 2015](./known-issues/known-issues-vs2015.md) 1. [CTP 3.1 / Visual Studio 2013](./known-issues/known-issues-vs2013.md) - ## Help us improve our documentation Help us improve out docuementaiton by sending us a pull-request or opening a [GitHub Issue](https://github.com/Microsoft/cordova-docs/issues/new) diff --git a/known-issues/known-issues-general.md b/known-issues/known-issues-general.md index c04ee2c4..72a66117 100644 --- a/known-issues/known-issues-general.md +++ b/known-issues/known-issues-general.md @@ -11,6 +11,7 @@ This article covers general [known issues](../Readme.md#knownissues) related to **Building a Cordova project from source control results in Cordova plugin APIs not returning results:** The following four json files can cause this to occur if added to source control. - plugins/android.json +- plugins/ios.json - plugins/windows.json - plugins/remote_ios.json - plugins/wp8.json. @@ -18,22 +19,14 @@ This article covers general [known issues](../Readme.md#knownissues) related to Remove these files from source control if you are not checking in the "platforms" folder (reccomended). For local copies, you can either fetch a fresh copy from source control or remove the above files along with platforms found in the "platforms" folder to resolve the issue. See [tips and workarounds](../tips-and-workarounds/general/README.md#l#missingexclude) for additional details. ---------- -**Plugin with variables not working:** Due to a Cordova issue with Cordova 4.3.0, you can run into problems with plugin variables in Cordova < 5.0.0. Plugin variable information is lost if you install the "plugin" before the "platform" which can happen depending on your workflow. They do, however, function in Cordova 5.1.1 which you can use with VS 2015. To update to 5.1.1 and use plugin variables, you will need to update your VS project and use the command line. +**Plugin with variables not working:** Due to a Cordova issue with Cordova 4.3.0 and 4.3.1, you can run into problems with plugin variables in Cordova < 5.0.0. Plugin variable information is lost if you install the "plugin" before the "platform" which can happen depending on your workflow. They do, however, function in Cordova 5.1.1 which you can use with VS 2015. Follow these steps to use a plugin with variables: 1. Remove the plugins with the variables via the config designer. 2. Update to Cordova 5.1.1 via the config designer (Platforms > Cordova CLI) - 3. From the command line: - 1. Go to your project directory. - 2. Type the following from substituting project path, plugin name, and variables for those that apply to you: - - ~~~~~~~~~~~~~~ - cd - npm install -g cordova@5.1.1 - cordova plugin add nl.x-services.plugins.launchmyapp --variable URL_SCHEME=myscheme - ~~~~~~~~~~~~~~ - + 3. Re-add your plugin via "Plugins" tab in the config.xml designer + ---------- **Slow first build or first plugin add:** The first build or plugin add for a given version of Cordova will be slower than subsequent builds as VS must first dynamically acquire Cordova. See the Output Window for more detail on progress. Further, the first remote iOS build will exhibit the same behavior as the agent downloads Cordova on your OSX machine. If you encounter a CordovaModuleLoadError with the first iOS build for a given Cordova version you can follow [these instructions](../tips-and-workarounds/ios/README.md#npm-cache) to resolve the problem. diff --git a/known-issues/known-issues-ios.md b/known-issues/known-issues-ios.md index 7a9cee6f..51173957 100644 --- a/known-issues/known-issues-ios.md +++ b/known-issues/known-issues-ios.md @@ -1,6 +1,18 @@ #**Known Issues - iOS** This article covers [known issues](../Readme.md#knownissues) related to Visual Studio Tools for Apache Cordova 2015 when building or deploying to iOS devices or simulators. +---------- +**vs-ms-remote reports a 404 error when using VS 2015 RTM or later:** VS 2015 RTM and up uses a new "remotebuild" agent instead of vs-mda-remote. See [remotebuild installation instructions](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +---------- +**iOS Simulator does not work when using the remotebuild agent and VS 2015 RTM:** You need to install version 3.1.1 of the ios-sim node module. Run "npm install -g ios-sim@3.1.1" from the Terminal app in OSX to install. See [remotebuild installation instructions](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +---------- +**iPhone 4S Simulator appears when selecting iPad or other device when using the remotebuild agent and VS 2015 RTM:** You need to install version 3.1.1 of the ios-sim node module. Run "npm install -g ios-sim@3.1.1" from the Terminal app in OSX to install. See [remotebuild installation instructions ](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +---------- +**Existing vs-mda-remote settings in Visual Studio do not work with the remotebuild agent:** You will need to generate and use a new PIN when setting up Visual Studio to connect to the remotebuild agent for the first time. If you are not using secure mode, turn secure mode on and then off again to cause VS to reinitalize. See [remotebuild installation instructions](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + ---------- **CordovaModuleLoadError from vs-mda-remote:** This error can occur if your ~/.npm folder or some of its contents were created while running as an administrator (sudo). To resolve, run the following commands after installing the latest version of the [vs-mda-remote package](https://www.npmjs.com/package/vs-mda-remote). These commands ensure your user has permissions to the contents of the npm package cache in your home directory when using older versions of Node.js and npm. Newer versions of Node.js and npm will do this for you automatically. @@ -38,6 +50,6 @@ As a workaround, if you enter this state, soft reset your iOS device. * [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) * [Follow us on Twitter](https://twitter.com/VSCordovaTools) * [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) -* [Read MSDN docs on using Visual Studo Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) * [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) * [Email us your questions](mailto://multidevicehybridapp@microsoft.com) diff --git a/known-issues/known-issues-ripple-cordova.md b/known-issues/known-issues-ripple-cordova.md index e0b94ca9..0f757f17 100644 --- a/known-issues/known-issues-ripple-cordova.md +++ b/known-issues/known-issues-ripple-cordova.md @@ -5,22 +5,14 @@ This article covers general [known issues](../Readme.md#knownissues) related to **Cordova 5.x.x:** See [Cordova 5.x.x known issues](known-issues-cordova5.md) for details on Cordova and Ripple related issues that are specific to Cordova 5.0.0 and up. ---------- -**Plugin with variables not working:** Due to a Cordova issue with Cordova 4.3.0, you can run into problems with plugin variables in Cordova < 5.0.0. Plugin variable information is lost if you install the "plugin" before the "platform" which can happen depending on your workflow. They do, however, function in Cordova 5.1.1 which you can use with VS 2015. To update to 5.1.1 and use plugin variables, you will need to update your VS project and use the command line. +**Plugin with variables not working:** Due to a Cordova issue with Cordova 4.3.0 and 4.3.1, you can run into problems with plugin variables in Cordova < 5.0.0. Plugin variable information is lost if you install the "plugin" before the "platform" which can happen depending on your workflow. They do, however, function in Cordova 5.1.1 which you can use with VS 2015. Follow these steps to use a plugin with variables: 1. Remove the plugins with the variables via the config designer. 2. Update to Cordova 5.1.1 via the config designer (Platforms > Cordova CLI) - 3. From the command line: - 1. Go to your project directory. - 2. Type the following from substituting project path, plugin name, and variables for those that apply to you: - - ~~~~~~~~~~~~~~ - cd - npm install -g cordova@5.1.1 - cordova plugin add nl.x-services.plugins.launchmyapp --variable URL_SCHEME=myscheme - ~~~~~~~~~~~~~~ - + 3. Re-add your plugin via "Plugins" tab in the config.xml designer + ---------- **TypeError: Request path contains unescaped characters:** When building or installing a plugin you may encounter this error if you are using a proxy with certain versions of Node.js and Cordova after a "npm http GET". This is a Cordova issue and the simplest workaround is to downgrade Node.js to 0.10.29. This will be resolved in a future version of Cordova. See [tips and workarounds](../tips-and-workarounds/general/README.md#cordovaproxy) for additional details. diff --git a/known-issues/known-issues-vs2015.md b/known-issues/known-issues-vs2015.md index c52ea818..8191254f 100644 --- a/known-issues/known-issues-vs2015.md +++ b/known-issues/known-issues-vs2015.md @@ -103,6 +103,18 @@ Lastly, you should add the following XML elements to your config.xml to ensure y ~~~~~~~~~~~~~~~~~~~~~~ +##Visual Studio 2015 RTM +---------- +**vs-ms-remote reports a 404 error when using VS 2015 RTM or later:** VS 2015 RTM and up uses a new "remotebuild" agent instead of vs-mda-remote. See [remotebuild installation instructions](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +---------- +**iOS Simulator does not work when using the remotebuild agent and VS 2015 RTM:** You need to install version 3.1.1 of the ios-sim node module. Run "npm install -g ios-sim@3.1.1" from the Terminal app in OSX to install. See [remotebuild installation instructions](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +---------- +**iPhone 4S Simulator appears when selecting iPad or other device when using the remotebuild agent and VS 2015 RTM:** You need to install version 3.1.1 of the ios-sim node module. Run "npm install -g ios-sim@3.1.1" from the Terminal app in OSX to install. See [remotebuild installation instructions ](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +**Existing vs-mda-remote settings in Visual Studio do not work with the remotebuild agent:** You will need to generate and use a new PIN when setting up Visual Studio to connect to the remotebuild agent for the first time. If you are not using secure mode, turn secure mode on and then off again to cause VS to reinitalize. See [remotebuild installation instructions](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + ##Visual Studio 2015 RC ---------- **VS 2015 RC and Cordova 5.x.x / Cordova Android 4.x.x:** See [Cordova 5.x.x known issues](known-issues-cordova5.md) for details on Android related issues that are specific to Cordova 5.0.0 and up. @@ -118,6 +130,7 @@ To install updated plugins, follow [this proceedure to install a npm sourced plu **Building a Cordova project from source control results in Cordova plugin APIs not returning results:** The following four json files can cause this to occur if added to source control. - plugins/android.json +- plugins/ios.json - plugins/windows.json - plugins/remote_ios.json - plugins/wp8.json. diff --git a/tutorial-cordova-5/README.md b/tutorial-cordova-5/README.md new file mode 100644 index 00000000..9ed10708 --- /dev/null +++ b/tutorial-cordova-5/README.md @@ -0,0 +1,271 @@ +#Using Apache Cordova 5 +**Note that this documentation applies to Visual Studio 2015 and does not apply to Visual Studio 2013 CTPs.** + +Tools for Apache Cordova supports cordova 4.3.1 along with the newly released Cordova 5.1.1 version of cordova. As the major version number increase implies, Cordova 5 is a departure from 3.x and 4.x versions of Cordova in a number of very important ways. Note that there were a number of issues with Cordova 5.0.0 itself that kept us from recommending its use including an [Android security issue](https://github.com/Chuxel/cordova-docs/tree/master/tips-and-workarounds/android/security-05-26-2015). As a result, we strongly reccomend the use of **Cordova 5.1.1** with **Visual Studio 2015 RTM** and up. + +This article will summarize the changes in Cordova 5 and how you can take advantage of some of its new features and adapt existing apps. Specifically it will cover: + +1. [Security model changes to the Android and iOS platforms](#security) +1. [Primary Cordova plugin repository switching to npm](#npm) +1. [Gradle build instead of Ant for Android](#gradle) +1. [Pluggable WebViews and the Crosswalk WebView for Android](#crosswalk) +1. [Windows 10 support and improved Cordova interoperability](#win10) + +New projects created using Tools for Apache Cordova will automatically use Cordova 4.3.1. You can switch to this version of Cordova by following these steps: + +1. Double click on config.xml + +2. Select the "Platforms" left navigation tab + +3. Change the version number to 5.1.1 and save config.xml + + ![Select Cordova Version]() + +Note that when you build this will **automatically remove any existing contents in the platforms folder in the filesystem**. If you have opted to customize the native project, you should consider migrating your custom assets to the **res/native** folder (ex: res/native/android) which will automatically add the files to the project before preparing the Cordova project to build. + +However, you will want to exercise care here since **Android in particular has undergone significant revisions in Cordova 5.** The remainder of this article will highlight these updates and cover tips for adapting your existing apps to these changes. + +###A Note on Cordova Version Numbers +Historically Cordova and all its components have used one unified version number. This was particularly true with Cordova versions prior to 3.0.0. Underneath the hood this changed when Cordova 4.0.0 was released but most end users were never exposed to this difference. With the release of Cordova 5.0.0 you may also see reference to the release of "Cordova Android 4.0.0." It's important to note that this does not refer to the top level Cordova version but instead the **platform** version. You can think of a platform in many ways as a native project generator combined with a set of scripts designed to build the app. + +Understanding these differences can be important when reading blog posts or updates on the Cordova web site. Here is how these different components are typically described: + +- **Cordova 5.1.1** refers to version 5.1.1 of the [Cordova CLI](http://cordova.apache.org/docs/en/5.0.0/guide_cli_index.md.html#The%20Command-Line%20Interface) (and an underlying core library called [cordova-lib](https://www.npmjs.com/package/cordova-lib)). [Documentation](http://cordova.apache.org/docs/en/5.0.0/guide_overview_index.md.html#Overview) on the Cordova web site will also refer to this version number. + +- **Cordova CLI 5.1.1** is largely equivalent to Cordova 5.1.1 but is specifically referring to the [Cordova CLI npm package](https://www.npmjs.com/package/cordova). + +- **Platform versions** follow a different numbering scheme. A given Cordova CLI version "pins" a set of platform versions by default since all testing for the release was done using this specific combination of components. The Cordova OSS project does not typically back-test earlier versions of the CLI with newer platforms unless specifically noted in the release notes. You will typically see these platform versions mentioned in a form similar to "Cordova Android 4.0.0". This naming scheme inherits its name from the [cordova-android](https://www.npmjs.com/package/cordova-android) and other similarly named npm packages that are installed when the platform is added to your project. Visual Studio will automatically perfom this "platform add" operation on your behalf but you may notice a version number like this in the Output Window when you build. + + The following Cordova platform versions supported by Tools for Apache Cordova are pinned in **Cordova CLI 5.1.1** (or [see here](http://cordova.apache.org/news/2015/06/10/tools-release.html) for a complete list): + + - Cordova Android 4.0.2 + - Cordova iOS 3.8.0 + - Cordova Windows 4.0.0 + - Cordova WP8 3.8.1 + +Other components are also versioned independantly, but typically you will not be directly exposed to them. It is the release of Cordova Android 4.0.0 that triggered the major version increase for Cordova as a whole given it had a number of breaking changes. Windows 4.0.0 is also a major release that includes Windows 10 support but was designed to not have breaking changes when building for Windows or Windows Phone 8.1. + +Note that you can actually add different platform versions to your project for a given CLI version through the use of some XML elements or command line options for edge case scenarios. See the [May 26th, 2015 Android Cordova Platform Security Issue](../tips-and-workarounds/android/security-05-26-2015) article for a specific example of how this works. + + +##Security Model Changes for Android and iOS +One of the more confusing changes about Cordova 5 is that the updated version of the Android platform (also called Cordova Android 4.x) and iOS now follow a different, but more powerful security model designed to provide developers with the tools needed to prevent cross-site scripting attacks among other issues. A critical aspect of this security model is that **absolutely no network access of any kind is allowed without the installation of a Cordova plugin**. + +There are a whole host of new security features available and we **strongly reccomend you read the [Introduction to Cordova 5 Security](./cordova-5-security.md) document** for a introduction on them. This article will focus on getting you up and running with the basics. + +###The New Whitelist Plugin +The new [Cordova Whitelist plugin (cordova-plugin-whitelist)](https://github.com/apache/cordova-plugin-whitelist) is the recommended base security plugin to use for managing network security access. Historically there was one **access** element in config.xml element used to control all access to network resources. For example, adding the following to config.xml resulted in the app not only being able to make XHR calls, access images, or reference remote scripts but also allowed Cordova to navigate to any URI. + +The problem with this model is you may want to be able to make an XHR request to a service like Azure Mobile Services without actually allowing your app to navigate to an Azure web page in the same domain. The reason this is a concern is that this remote web page is then given access to all Cordova and plugin APIs. Further, for Android, the access element has been overloaded to control "intents" in the wake of a discovered [security issue in Cordova 3.5.0 and below](http://cordova.apache.org/announcements/2014/08/04/android-351.html) which has led to a syntax that strayed away from the original [W3C Widget spec](http://www.w3.org/TR/widgets/) that config.xml's structure is based on. Some restructuring and improvements were therefore appropriate for the Cordova 5.0.0 release. + +As a result, the new whitelist plugin actually introduces three separate elements designed to enable more discrete control. The **access** element returns but only controls where your app can make XHR requests or access other external content from a web page for Android and iOS. It no longer controls whether you can navigate to a different domain. A new **allows-navigation** element has been added that then enables you to specify where the app can navigate instead. Finally, a new **allows-intent** element has been introduced specifically designed to control Android intents. + +Projects created using the Cordova CLI contain fairly restrictive rules that are intended to represent a reasonable starting point for most projects. Specifically it: + +1. Allows XHR and images to originate from any URL +2. Disallows navigation to external URLs (hosted content) +3. Disallows inline script (Meaning no <script> tags or "on" attributes on HTML elements) on recent versions of Android, iOS, or Windows via a W3C Content Security Policy (CSP) in index.html +4. Allows the "tel:", "sms:", "mailto:", and "geo:" intents + +You'll want to start your project with roughly these same defaults and alter as needed. See below for how to add these defaults to your porject and the [Introduction to Cordova 5 Security](./cordova-5-security.md) document for details on why these defaults are in palce and how to change them. + +###Configuring Security Settings from a VS Project +When you upgrade a project to Cordova 5.0.0+, you will want to take the following steps to if you wish to mirror the base security policy listed above. You can then customize as needed to meet your needs. + +1. Add the whitelist plugin to your project via config.xml: + + 1. Right-click on config.xml and select "View Code" + + 2. Add the following XML elements under the <widget> element: + + ~~~~~~~~~~~~~~~~~~~~~~~ + + ~~~~~~~~~~~~~~~~~~~~~~~ + + The next time you build in Visual Studio, VS will install this version of the whitelist plugin. You can update the version number as needed. + +2. Update config.xml with the allow-intent or allow-navigation elements as needed: + 1. If you have not already, right-click on config.xml and select "View Code" + + 2. Add the following XML elements under the <widget> element: + + ~~~~~~~~~~~~~~~~~~~~~~~ + + + + + + + ~~~~~~~~~~~~~~~~~~~~~~~ + + You should already have an <access> element in your config.xml. You can use the "Domain Access" list under the "Common" tab in the config.xml designer to add or edit your current list. + + 3. Optionally, you can allow navigation to hosted content by adding URLs to config.xml as follows: + + ~~~~~~~~~~~~~~~~~~~~~~~ + + ~~~~~~~~~~~~~~~~~~~~~~~ + +3. Add a Content Security Policy (CSP) to your HTML pages: + 1. Add the following <meta> tag to each of your top level HTML pages (like index.html). + + ~~~~~~~~~~~~~~~~~~~~~~~ + + ~~~~~~~~~~~~~~~~~~~~~~~ + + Note: It does not need to be added to pages dynamically loaded by a JavaScript framework like AngluarJS or WinJS - many times you just need to add it to index.html. + + 2. Customize the CSP policy to meet your needs. See [Introduction to Cordova 5 Security](./cordova-5-security.md) for details. + + 3. You may wish to use the Crosswalk WebView plugin when targeting earlier versions of Android as CSP support was not introduced until Android 4.4. See [the section on Crosswalk later in this article](#crosswalk) for additional tips on using Crosswalk. + + +##Primary Cordova Plugin Repository is Now Npm +Another significant departure in Cordova 5 and the community as a whole is the migration of the primary source of Cordova plugins from the custom repository backed model that exists in Cordova 3.x and 4.x to the "Node Package Manager" (npm) repository. The plugins.cordova.io repository has seen a few service interruptions and given the web community's increased use of Node.js for client-side development and Cordova's heavy use of npm for not only its command line interface but as a source for Cordova "platforms," the natural next step was to migrate plugins to npm as well. More details on this transition [can be found here.](http://cordova.apache.org/announcements/2015/04/21/plugins-release-and-move-to-npm.html) + +However, unfortunately this switch over is not transparent. For a few very specific reasons, this change over can be a bit confusing and we're working with the community to determine some ways to make the transition a bit more seamless going forward. + +###Plugin ID Changes +A significant change to be aware of is that the IDs used to refer to many Cordova plugins have changed. This was done for two reasons. First, the different ID helps to re-enforce that older versions of Cordova will not get plugin updates. Rather than having an arbitrary version number where the updates stop, using a different ID makes this change over explicit. Second, the old reverse domain style for Cordova plugin IDs does not conform to community best practices for package names in npm. + +As a result, core plugins like Camera have changed from [org.apache.cordova.camera](http://plugins.cordova.io/#/package/org.apache.cordova.camera) in version 0.3.6 of the plugin to [cordova-plugin-camera](https://www.npmjs.com/package/cordova-plugin-camera) in versions 1.0.0 and higher. + +![Custom Local Plugin]() + +![Custom Local Plugin]() + +You can find running list of [old verses new plugin IDs in this location](https://github.com/stevengill/cordova-registry-mapper/blob/master/index.js). You will be informed of the new ID whenever you add a plugin from this list when either using the command line or the config.xml designer. The config.xml designer will automatically add these new IDs for Cordova 5.0.0+ and the old IDs for older versions of Cordova that do not support them. + +###Cordova Plugin Registry +Unfortunately the community is in a state of flux when it comes to a "source of truth" for all available Cordova plugins. + +- For the time being, [plugins.cordova.io](http://plugins.cordova.io) **does not contain npm sourced plugins.** +- For npm sourced plugins, you should instead search npm using the [ecosystem:cordova](https://www.npmjs.com/search?q=ecosystem%3Acordova) tag. + + ![Custom Local Plugin]() + +Both sets of plugins can be used with Cordova 5.0.0+ so in the short term you should search in both locations for plugins. Plugins found in npm are the most likely to work without issue with Cordova 5.0.0 and higher and may or may not work with earlier versions of Cordova. Npm will be the eventual source of truth, but things are a bit messy during this transition period. + +We are actively working with the community on the best way to merge some of the functionality of the existing plugins.cordova.io site with the reliability and improvements npm provides. + + +###Cordova 3.x and 4.x Don't Support Npm as a Plugin Source +An early source of confusion can lead from the fact that Cordova 3.x and 4.x cannot use plugins sourced from npm. The Cordova CLI in these versions simply does not have the capability. A specific issue that can come up here is that updates to plugins will now generally be going to npm **not** the older plugin registry sourced method used by these earlier version of Cordova plugins. + +Generally your best course of action if you need an updated plugin is to also update to Cordova 5.1.1 or later. See the [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-npm) section if you absolutley must get an updated plugin for a project that uses an earlier version of Cordova for potential options. + + +##Gradle Build Instead of Ant for Android +On the surface, this seems like a fairly innocuous change but we've continued to hear about unexpected issues in some 3rd party Cordova plugins because of this change so it is worth a mention. + +Up until Cordova 5.0.0 (Cordova Android platform version 4.0.0), Cordova used [Apache Ant](http://ant.apache.org/) as the primary build system to build an Android version of an app. This has now changed to [Gradle](http://gradle.org/) as the default though developers can force an Ant build using the Cordova CLI as follows: + +~~~~~~~~~~~~~~~~~~~~~~~ +cordova build android -- --ant +~~~~~~~~~~~~~~~~~~~~~~~ + +There are three major ways that switching to Gradle can affect your project: + +1. The way you specify signing information is different. See the [Packaging & Publishing tutorial for details](../tutorial-package-publish). +1. Some 3rd party plugins may now require Gradle and thus typically only work on Cordova 5.0.0 and up. In particular, plugins that modify Android build artifacts in a non-standard way can run into issues. +1. Other 3rd party plugins may not have updated to support Gradle yet and still require Ant to be used. Generally these plugins are designed for Cordova versions < 5.0.0. + +A good example of a plugin that requires Gradle is the [Crosswalk plugin](https://github.com/crosswalk-project/cordova-plugin-crosswalk-webview) we will cover a bit in this article. While at one point it also worked with Ant builds, it now errors out if you are not building with Gradle. As a result, Visual Studio 2015 now uses Gradle to build Android in Cordova 5.0.0+ instead of Ant (2015 RC still used Ant). The end result is you could hit compatibility issues with lesser known 3rd party plugins particularly if you have not updated them. + + +###Migrating an Existing Project to Use Gradle +Because of these differences you should take the following steps: + +1. If you encounter an unexpected build error specifically for Android, see if the error references Cordova plugin source code. If so, update it by removing the plugin using the "Installed" tab of the config.xml designer and re-add the plugin. If you cannot determine which plugin is causing the issue, you can opt to proactively upgrade all of them. + +2. If a plugin update doesn't solve the issue, try these steps to eliminate other factors. + 1. Create a fresh project and see if the problem reproduces. + 2. To eliminate Visual Studio as a potential culprit, you can test using a standard Cordova CLI project by entering the following in a command prompt: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + npm install -g cordova@5.1.1 + cordova create testProj + cd testProj + cordova platform add android + cordova plugin add cordova-plugin-in-question + cordova build android + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ... replacing the Cordova version and plugin name for those that apply to your situation. You can also specify a fully qualified Git URI or filesystem path in place of the plugin name. + + 2. If the problem reproduces, you may want to contact the plugin author and let them know about the problem. Before doing so, be sure to check for existing open issue as more than likely there's already one on the plugin author's GitHub site that you can use to provide additional information. Mention that you encountered issues when using Tools for Apache Cordova but include the Cordova CLI repro for the plugin author's benefit. See the [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-troubleshoot) section of our docs for additional troubleshooting tips. + +3. If you've already added release signing information into ant.properties in your project, you'll need to place this information in a new file in your project. See the [Packaging & Publishing tutorial for details](../tutorial-package-publish) for details. + + +##Pluggable WebViews and the Crosswalk WebView for Android +An exciting new development in the Cordova Android platform is the support for what are called "pluggable WebViews." What this feature allows you to do is swap out the built in Android WebView with a completely different WebView implementation. This is a significant improvement as the Android browser and thus the WebView has been locked at a specific version without the ability to update unless you update the version of the OS on the device. This has changed in the Android OS as of 5.0 (API 22), but unlike iOS or Windows where devices can opt to upgrade and developers need only concern themselves with a few major versions of the browser, older Android devices are locked at a particular sub-revision of Android and thus the browser with no ability to upgrade the device in many cases. The end result has been a vast array of small differences between Android devices. + +[Crosswalk](https://crosswalk-project.org/) is a project that is designed to allow developers to take embed a very recent and specific version of the Chromium WebView inside their Android app. The Crosswalk WebView can be embedded in apps running on Android 4.0 and up and brings with it the significant advantage of a consistent WebView implementation across all Android device versions it supports. + +There is now a [Cordova Crosswalk plugin](https://www.npmjs.com/package/cordova-plugin-crosswalk-webview/) that takes advantage of the new pluggable WebView features in Cordova 5.0.0+ (and the Cordova Android 4.0.0 platform it uses) and makes it simple to add into your project. + +*Note: Because using the Crosswalk plugin does slow down build times given its size, we recommend developers start out building apps with the stock Android WebView on a recent device or emulator (Android 4.4+). You can then add the Crosswalk plugin later in your development cycle and make the necessary adjustments.* + +###Installing the Crosswalk Plugin from VS +To use the Crosswalk WebView plugin from Visual Studio, follow these steps: + +1. Right-click on config.xml and select "View Code" + +2. Add the following XML elements under the <widget> element: + + ~~~~~~~~~~~~~~~~~~~~~~ + + ~~~~~~~~~~~~~~~~~~~~~~ + +The next time you build, your app will be running in the Crosswalk WebView. Note that the first build for Android in particular will take a bit given the plugin does some dynamic acquisition. + +###Tips on Using the Crosswalk +If you are using the standard Android Emulator, be sure to check the **Use Host CPU** option in the AVD you create and have up to date graphics drivers installed on your system or the app will crash due to Crosswalk's support of WebGL. + +![Use Host GPU]() + +Finally, if you encounter a "Could not create the Java Virtual Machine" error, add the following environment variable to your system and restart VS to bump up Java's heap memory: + +~~~~~~~~~~~~~~~~~~~~~~ +_JAVA_OPTIONS=-Xmx512M +~~~~~~~~~~~~~~~~~~~~~~ + + +##Windows 10 Support +Historically, Windows and Windows Phone 8.1 have had a number of compatibility challenges with Cordova apps due to underlying platform differences around security rules. A [JavaScript compatibility](https://github.com/MsopenTech/winstore-jscompat) framework was released to help alleviate some of these issues on 8.1, but starting with **Cordova 5.1.1**, you can now build Windows 10 apps. In addition to supporting the new Windows Universal platform that allows a single code base and app package to be used across a number of different devices, Windows 10 also brings a number of significant improvments to Apache Cordova users. + +In particular: + +1. Elimination of the existing dynamic content restrictions in Windows 8.0 and 8.1. +2. Cordova plugin support for external hosted content through the use of the same <allow-navigation> element used by Android and iOS. +3. Support for the powerful Content Security Policy (CSP) that is also now reccomended for use with the Android and iOS Cordova platforms. See [this article for more details](./cordova-5-security.md). +4. Apps can now run in two different security modes: + 1. Remote mode: The default, flexible security mode that only has a hand full of store submission restrictions + 2. Local mode: A more secure mode that adds additional protections but disables hosted content and inline script + +These improvements mean that the Windows platform now has a flexible model compatible with Cordova platforms like Android and iOS while still providing you the tools you need to secure your app. Check out the [Cordova Windows 10](http://go.microsoft.com/fwlink/?LinkID=617471) documentation for more information on new features. + +You can follow these steps to use Cordova Windows 10 with Visual Studio: + +1. Install the [Windows 10 Tools for Visual Studio](http://go.microsoft.com/fwlink/?LinkID=617471) if you have not already. + +2. In your project, open the config.xml designer by double clicking on config.xml + +3. Click on the "Windows" tab + +4. Change the "Windows Target Version" to "Windows 10.0" + + ![Select Cordova Version]() + +That's it! Underneath the convers Cordova will switch from an 8.1 project to a new Universal App project and take care of the rest! Just use the "Debug" dropdown to deploy to a Windows 10 device, use your Windows 10 PC, or use a Windows 10 emulator. + +## More Information +* [Learn about security features in Apache Cordova 5](./cordova-5-security.md) +* [Read tutorials and learn about tips, tricks, and known issues](../Readme.md) +* [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) +* [Follow us on Twitter](https://twitter.com/VSCordovaTools) +* [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) +* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file diff --git a/tutorial-cordova-5/cordova-5-security.md b/tutorial-cordova-5/cordova-5-security.md new file mode 100644 index 00000000..0aa43108 --- /dev/null +++ b/tutorial-cordova-5/cordova-5-security.md @@ -0,0 +1,171 @@ +#Introduction to Cordova 5 Security +One of the more confusing changes about Cordova 5 is that the updated version of the Android platform (also called Cordova Android 4.x) and iOS now follow a different, but more powerful security model designed to provide developers with the tools needed to prevent cross-site scripting attacks among other issues. A critical aspect of this security model is that **absolutely no network access of any kind is allowed without the installation of a Cordova plugin**. + +##Cordova Whitelists +The new [Cordova Whitelist plugin (cordova-plugin-whitelist)](https://github.com/apache/cordova-plugin-whitelist) is the recommended base security plugin to use for managing network security access. Historically there was one **access** element in config.xml element used to control all access to network resources. For example, adding the following to config.xml resulted in the app not only being able to make XHR calls, access images, or reference remote scripts but also allowed Cordova to navigate to any URI. + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + +The problem with this model is you may want to be able to make an XHR to a service like Azure Mobile Services without actually allowing your app to navigate to an Azure web page in the same domain. The reason this is a concern is that this remote web page is then given access to all Cordova and plugin APIs. Further, for Android, the access element has been overloaded to control "intents" in the wake of a discovered [security issue in Cordova 3.5.0 and below](http://cordova.apache.org/announcements/2014/08/04/android-351.html) which has led to a syntax that strayed away from the original [W3C Widget spec](http://www.w3.org/TR/widgets/) that config.xml's structure is based on. Some restructuring and improvements were therefore appropriate for the Cordova 5.0.0 release. + +###cordova-plugin-whitelist +As a result, the new whitelist plugin actually introduces three separate elements designed to enable more discrete control. The **access** element returns but only controls where your app can make XHR requests or access other external content from a web page for Android and iOS. It no longer controls whether you can navigate to a different domain. A new **allows-navigation** element has been added that then enables you to specify where the app can navigate instead. Finally, a new **allows-intent** element has been introduced specifically designed to control Android intents. + +The default Cordova CLI template has a config.xml file in it that is designed to allow the app to make external requests anywhere, allows a specific subset of intents, and prevents the WebView in the Cordova app to navigate anywhere other than local content. + +~~~~~~~~~~~~~~~~~~~~~~~ + + + + + + + +~~~~~~~~~~~~~~~~~~~~~~~ + +If we wanted to add the ability for the root WebView to navigate to www.microsoft.com, we can add this XML element: + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + +Note that if you simply wanted to display www.microsoft.com without giving it access to Cordova or plugin APIs, you can use the **[InAppBrowser plugin](https://github.com/apache/cordova-plugin-inappbrowser)** without adding the allow-navigation element to your config.xml file. + +There is still some variation in behavior by platform for these whitelist features based on the concerns and capabilities of the underlying native technology. + +1. **Android** supports the use of access, allow-navigation, and allows-intent. Intents are an Android specific concept. +2. **iOS** supports the use of access, and allow-navigation. +3. **Windows 10** via the Windows platform supports the allow-navigation element. The access element behaves slightly differently in that navigation is allowed to these URIs but Cordova and plugin APIs are disabled thereby reducing risk. XHR, CSS, and image access rules are intended to be controlled by a Content Security Policy (CSP) rather than specific whitelists. We'll cover more details on how to use CSPs later in this document. +4. **Windows 8.0, 8.1, and Windows Phone 8.1** via the Windows platform does support the navigating to external URIs outside of a x-ms-webview element or the InAppBrowser plugin due to fundamental platform limitations. XHR calls are always allowed to any domain. +5. The **Windows Phone 8 (WP8)** platform still uses the old definition of the access element. + +Note that if you would prefer to retain the old behavior of the access element for Android and iOS, you can install [cordova-plugin-legacy-whitelist](https://github.com/apache/cordova-plugin-legacy-whitelist) though this is intended only to be used for backwards compatibility and new apps should generally move towards using cordova-plugin-whitelist. + +###Automatically Adding the Plugin +You will also notice this default template contains the following in config.xml: + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + +This takes advantage of a new feature in Cordova 5.0.0+ to ensure the Cordova Whitelist plugin (whose ID is cordova-plugin-whitelist) is automatically installed if it is not present when the project is prepared for building any platform. It will automatically add the latest version of the plugin whose version number starts with 1 (1.x.x). You can also update this to be a specific version or remove this element and install the plugin yourself. + +Note that this capability can be used with any Cordova plugin and is conceptually similar to the Visual Studio specific "vs:plugin" element. We worked with the community to get it added into the core and over time we will discontinue the use of the "vs" prefix but we have left the feature in place for backwards compatibility (as Cordova 4.3.0 does not have this feature). Near term most VS documentation will recommend the use of "vs:plugin" instead. Ex: + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + + +##The W3C Content Security Policy (CSP) +A topic of frequent conversation for security focused developers on the web is the [W3C Content Security Policy (CSP)](http://www.w3.org/TR/CSP/) feature that is available in Chrome, Safari, and Internet Explorer Edge. CSP support is available natively to Cordova apps targeting iOS, Windows 10 and up, and Android 4.4 and up. However, you can get support back to Android 4.0 by using something called the Crosswalk WebView. See [Using Apache Cordova 5](./README.md#crosswalk) for information adding Crosswalk to your project. + +###The CSP in Cordova 5 +The CSP is a native browser capability that allows you to control exactly what content your app can access and at a very granular level. In fact, when using the CSP, you can generally keep the access origin to "*" as you'll be able to more tightly control security using the policy. + +A CSP policy is applied at a page level through a few different mechanisms, but for Cordova apps you typically use a meta tag. Here is the CSP policy on index.html in the default Cordova template: + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + +You will need to include a tag like this on each page you navigate to at the top level (a navigation that results in a different window.location.href). With "Single Page Apps", you generally will only need to put it on index.html, but it's worth noting that you can apply completely different security rules based on your situation by modifying this policy. For example, if you have a page that is collecting sensitive data, you may wish to strongly lock down access while keeping things more open on other pages. + +The only problem with the CSP is this: It's pretty confusing to read at first and its defaults can cause some behaviors web devs are not at all used to working around. + +You can find a [great tutorial on using the CSP in detail here](http://www.html5rocks.com/en/tutorials/security/content-security-policy/), but here are some common "gotchas" for those new to the concepts: + +1. By default, applying a CSP **disables both eval() and inline script** while the CSP policy in the **Cordova template leave inline disabled but enables eval()**. + - Disabling both eval and inline script means no script tags with JavaScript in it, no "on" event handler attributes on HTML elements, no eval(), no new Function(), etc. Disabling these features effectively makes it impossible to do cross-site scripting because there is no way to inject JavaScript anywhere that does not originate from a file. If you're property managing your whitelists, you're very secure. + + - The problem is that disabling eval() in particular can break quite a few web frameworks. + + - As a result, the CSP in the base Cordova template specifies **unsafe-eval** for **default-src** which enables JavaScript code to use eval and similar dynamic script techniques. Ex: + + ~~~~~~~~~~~~~~~~~~~~~~~ + default-src 'self' 'unsafe-eval'; + ~~~~~~~~~~~~~~~~~~~~~~~ + + - If your app and your frameworks don't need eval, remove the unsafe-eval declaration. + + - If you really need inline script, you can add the 'unsafe-inline' declaration. Of the two, inline script is actually a higher risk than eval since something as simple as using innerHTML without proper filtering can allow a hacker to add inline script. Inline script is very common, but if your app is security focused, you should avoid it. Note that the 'unsafe-inline' declaration in the Cordova template applies to style-src which enables inline CSS declarations not JavaScript. + +1. The default CSP policy in the Cordova template only allows access to JavaScript and CSS files inside the app or the same domain, not a different domain. **As a result, CDN hosted content typically cannot be referenced.** + + - This is another technique to reduce risk by stating that a given web page can only reference content from **'self'**. The end result is that cross-site scripting vulnerabilities are further reduced by preventing your web page from being hijacked to include content from an external, untrusted sourced. + + - You can loosen this restriction by listing other trusted domains. In fact, the default Cordova template lists "https://ssl.gstatic.com" as a trusted domain since Android needs it for TalkBack to function properly. + + ~~~~~~~~~~~~~~~~~~~~~~~ + default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; + ~~~~~~~~~~~~~~~~~~~~~~~ + + This above CSP policy says that content originating from the same domain ('self'), data URIs (data:), Cordova internal APIs (gap:), https://ssl.gstatic.com, and eval statments are allowed, but all others are denied. + +##Migrating an Existing Project +When you upgrade a project to Cordova 5.0.0+ from Cordova 4.3.1 or below in Visual Studio, you will want to take the following steps to ensure your app functions as you would expect. + +1. Add the whitelist plugin to your project via config.xml: + + 1. Right-click on config.xml and select "View Code" + + 2. Add the following XML elements under the <widget> element: + + ~~~~~~~~~~~~~~~~~~~~~~~ + + ~~~~~~~~~~~~~~~~~~~~~~~ + + The next time you build in Visual Studio, VS will install this version of the whitelist plugin. You can update the version number as needed. + +2. Update config.xml with the allow-intent or allow-navigation elements as needed: + + 1. If you have not already, right-click on config.xml and select "View Code" + + 2. Add the following XML elements under the <widget> element: + + ~~~~~~~~~~~~~~~~~~~~~~~ + + + + + + + ~~~~~~~~~~~~~~~~~~~~~~~ + + You should already have an <access> element in your config.xml. You can use the "Domain Access" list under the "Common" tab in the config.xml designer to add or edit your current list. + + 3. Optionally, if your app is using hosted content, or you'd prefer not to restrict where the WebView can navigate during development, you can also add the following elements: + + ~~~~~~~~~~~~~~~~~~~~~~~ + + + + ~~~~~~~~~~~~~~~~~~~~~~~ + + However, we strongly recommend narrowing down your access before releasing your app as many app stores will not accept apps that are completely open without filing for an exception and having a very good reason to do so. + +3. Due to the significant security benefits associated with using a CSP policy, we strongly recommend taking the Cordova template's CSP metatag and add it to the header of any page the app will navigate to in your app. Note that **you can use add a CSP meta tag to hosted content too.** + + ~~~~~~~~~~~~~~~~~~~~~~~ + + + + My Super Cool Cordova App + + ~~~~~~~~~~~~~~~~~~~~~~~ + + Start with the most locked down security policy you can and back away as needed. That way you'll ensure you're using the most secure practices you can from the start. + + To reiterate, **CSP support is only available on Android 4.4+ devices or Android 4.0+ when using Crosswalk.** See [Using Apache Cordova 5](./README.md#crosswalk) for information adding Crosswalk to your project. + +## More Information +* [Read more about Apache Cordova 5](./README.md) +* [Read tutorials and learn about tips, tricks, and known issues](../Readme.md) +* [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) +* [Follow us on Twitter](https://twitter.com/VSCordovaTools) +* [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) +* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file diff --git a/tutorial-cordova-5/media/cordova-5-0.png b/tutorial-cordova-5/media/cordova-5-0.png new file mode 100644 index 00000000..1d8646ec Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-0.png differ diff --git a/tutorial-cordova-5/media/cordova-5-1.png b/tutorial-cordova-5/media/cordova-5-1.png new file mode 100644 index 00000000..e5202be6 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-1.png differ diff --git a/tutorial-cordova-5/media/cordova-5-2.png b/tutorial-cordova-5/media/cordova-5-2.png new file mode 100644 index 00000000..1343f82c Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-2.png differ diff --git a/tutorial-cordova-5/media/cordova-5-3.png b/tutorial-cordova-5/media/cordova-5-3.png new file mode 100644 index 00000000..eb1d9602 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-3.png differ diff --git a/tutorial-cordova-5/media/cordova-5-4.png b/tutorial-cordova-5/media/cordova-5-4.png new file mode 100644 index 00000000..fd735f7a Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-4.png differ diff --git a/tutorial-cordova-5/media/cordova-5-5.png b/tutorial-cordova-5/media/cordova-5-5.png new file mode 100644 index 00000000..669d87c6 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-5.png differ diff --git a/tutorial-cordova-5/media/cordova-5-6.png b/tutorial-cordova-5/media/cordova-5-6.png new file mode 100644 index 00000000..7f8cc717 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-6.png differ diff --git a/tutorial-cordova-5/media/cordova-5-7.png b/tutorial-cordova-5/media/cordova-5-7.png new file mode 100644 index 00000000..4e3dbd97 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-7.png differ diff --git a/tutorial-cordova-5/media/cordova-5-8.png b/tutorial-cordova-5/media/cordova-5-8.png new file mode 100644 index 00000000..4921fe69 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-8.png differ diff --git a/tutorial-cordova-5/media/npm-local-1.png b/tutorial-cordova-5/media/npm-local-1.png new file mode 100644 index 00000000..ddb665a6 Binary files /dev/null and b/tutorial-cordova-5/media/npm-local-1.png differ diff --git a/tutorial-cordova-5/media/npm-local-2.png b/tutorial-cordova-5/media/npm-local-2.png new file mode 100644 index 00000000..fd7c2799 Binary files /dev/null and b/tutorial-cordova-5/media/npm-local-2.png differ diff --git a/tutorial-gulp/gulp-ci.md b/tutorial-gulp/gulp-ci.md index 034b881f..75f37e1d 100644 --- a/tutorial-gulp/gulp-ci.md +++ b/tutorial-gulp/gulp-ci.md @@ -104,7 +104,7 @@ gulp.task("default", function () { Underneath the covers, the script will do the following: -1. First, it check **taco.json** to see if a Cordova version is specified. If not, it assumes you want Cordova 4.3.0. +1. First, it check **taco.json** to see if a Cordova version is specified. If not, it assumes you want Cordova 5.1.1. 2. Next, it checks to see if this version of cordova-lib has already been installed at a location set in the **CORDOVA\_CACHE** environment variable. If no CORDOVA_CACHE environment variable is set, the cache location will default to %APPDATA%\\cordova-cache on Windows and ~/.cordova-cache on OSX. You can also set this location programmatically using the module's configure method. diff --git a/tutorial-team-build/Jenkins.md b/tutorial-team-build/Jenkins.md index 59c9b002..c033c81d 100644 --- a/tutorial-team-build/Jenkins.md +++ b/tutorial-team-build/Jenkins.md @@ -1,11 +1,12 @@ #Using Tools for Apache Cordova with the Jenkins CI System -**This tutorial is part of a [series of tutorials](http://go.microsoft.com/fwlink/?LinkID=533743) on building Visual Studio 2015 Tools for Apache Cordova projects in a Team / CI environment and does not apply to Visual Studio 2013 CTPs.** +This tutorial is part of a [series of tutorials](./README.md) on building Visual Studio 2015 Tools for Apache Cordova projects in a Team / CI environment. +##Background [Jenkins](http://go.microsoft.com/fwlink/?LinkID=613695) is a hugely popular CI server with a large install base so using it to build your Cordova project may be the way to go if you already have it installed and running in your environment. Fortunatley Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. [Gulp](http://go.microsoft.com/fwlink/?LinkID=533803) is an increasingly popular JavaScript based task runner with a large number of [useful plugins](http://go.microsoft.com/fwlink/?LinkID=533790) designed to automate common “tasks” for everything from compilation, to packaging, deployment, or simply copying files around. Both Gulp and Cordova CLI are Node.js based which makes the two highly complementary technologies. For these reasons, this tutorial will focus on the use Gulp rather than MSBuild as the primary build language for Cordova apps when using Jenkins. -**Troubleshooting Tip: Be aware that a bug in VS templates in VS 2015 RC included four json files that can cause issues if added to source control: plugins/android.json, plugins/remote_ios.json, plugins/windows.json, and plugins/wp8.json.** Adding these files to source control can result in a build that appears to succeed but is missing plugin native code. They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. +**Troubleshooting Tip:** Be aware that we recommend against adding the "platforms" folder or the following json files in the "plugins" folder into source control: android.json, ios.json, remote_ios.json, windows.json, and wp8.json. See "What to Add to Source Control" in the [general team build tutorial](./README.md) for additional details. ##Initial Setup Since the build process we will describe here is not directly dependent on MSBuild or Visual Studio, you have two options for installing pre-requisites on Windows: @@ -124,9 +125,9 @@ Next you will need to set the following environment variables if they have not a | **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | |:-------------------|:-----------------------------------------|:-----------------------------------------|:------------------------------------------| -| **ANDROID\_HOME** | Android | Location of the Android SDK | %PROGRAMFILES(x86)%\\Android\\android-sdk | -|**JAVA\_HOME** | Android | Location of Java | %PROGRAMFILES(x86)%\\Java\\jdk1.7.0\_55 | -| **ANT\_HOME** | Android when building using Ant (not Gradle) | Location of Ant | %PROGRAMFILES(x86)%\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | +| **ANDROID\_HOME** | Android | Location of the Android SDK | C:\\Program Files (x86)\\Android\\android-sdk | +|**JAVA\_HOME** | Android | Location of Java | C:\\Program Files (x86)\\Java\\jdk1.7.0\_55 | +| **ANT\_HOME** | Android when building using Ant (not Gradle) | Location of Ant | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | | **GRADLE\_USER\_HOME** | Optional | Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ | If not specified, uses %HOME%\\.gradle on Windows or ~/.gradle on OSX | | **CORDOVA\_CACHE** | Optional | Overrides the default location used by the [sample build script](http://go.microsoft.com/fwlink/?LinkID=533736) to cache installs of multiple versions of Cordova. | If not specified, uses %APPDATA%\\cordova-cache on Windows and ~/.cordova-cache on OSX | @@ -236,4 +237,4 @@ The OSX version of the build is similar but adds one additional requirement: Unl * [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) * [Read MSDN docs on using Visual Studo Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) * [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) -* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file +* [Email us your questions](mailto:/vscordovatools@microsoft.com) diff --git a/tutorial-team-build/RC/TFS2013.md b/tutorial-team-build/RC/TFS2013.md new file mode 100644 index 00000000..7e089b84 --- /dev/null +++ b/tutorial-team-build/RC/TFS2013.md @@ -0,0 +1,182 @@ +#Using Tools for Apache Cordova 2015 RC with Team Foundation Services 2013 +**This article is specific to using Tools for Apache Cordova 2015 *RC* with TFS 2013. See [this article for details on Visual Studio 2015 RTM or later](../TFS2013.md).** + +Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. However, you may want to use Team Foundation Services 2013 build agents. + +It is important to note that as a general recommendation, we encourage the use of [TFS 2015's next generation cross-platform build system](http://go.microsoft.com/fwlink/?LinkID=533772) and [Gulp](http://go.microsoft.com/fwlink/?LinkID=533742) based build capabilities rather than TFS 2013 or MSBuild since this provides the ability build directly from TFS on Windows or OSX. See the [TFS 2015 tutorial](http://go.microsoft.com/fwlink/?LinkID=533771) for details. Visual Studio Online's support for building Cordova apps will focus on the Gulp based TFS 2015 approach rather than MSBuild. + +This tutorial will describe how to configure TFS to build a Tools for Apache Cordova project using MSBuild and the steps provided here will generally apply to using MSBuild with TFS 2015 as well. + +**Troubleshooting Tip: Be aware that a bug in VS templates in VS 2015 RC included four json files that can cause issues if added to source control: plugins/android.json, plugins/remote_ios.json, plugins/windows.json, and plugins/wp8.json.** Adding these files to source control can result in a build that appears to succeed but is missing plugin native code. They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. + +##Initial Setup +Before getting started with setting up your TFS Build Agent, you should install Visual Studio 2015 with the Tools for Apache Cordova option. You will also want to select the Windows / Windows Phone 8.1 tools and the Windows Phone 8.0 tools if you want to build for any of these platforms. From there you will want to configure a build agent on the server you have installed Visual Studio 2015. + +- See [Tools for Apache Cordova documentation](http://go.microsoft.com/fwlink/?LinkID=533794) for setup details on Visual Studio 2015. +- See [Team Foundation 2013 Build documentation](http://go.microsoft.com/fwlink/?LinkID=533786) for setup details on Team Foundation Services 2013. + +Note that you may also use a stand-alone build agent integrated with Visual Studio Online. + +**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) if your build servers have limited Internet connectivity or require routing traffic through a proxy. + +##Common Build Definition Parameters & Environment Variables +###Updated Build Process Template +Before you get started, it's important to note that you will need to use v14 of MSBuild when building a Tools for Apache Cordova project. Build definition templates that ship with TFS 2013 support v11 and v12. As a result, you will need to create a modified TFS Build Process Template for TFS to use MSBuild v14.0. To do this, you can simply download the v12 template (or your own custom one) and append ToolVersion="14.0" to the end of the **RunMSBuild** element and upload it as a new template. Ex: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See [TFS 2013 documentation](http://go.microsoft.com/fwlink/?LinkID=533787) for additional information on modifying build process templates. + +You can then [create a build definition](http://go.microsoft.com/fwlink/?LinkID=533788) for your project and select this updated template. + +###Getting Resulting Packages to Land in the Drop Folder + +To get the resulting packages from the Cordova build process to land in the configured TFS drop folder, you will need to add in a simple post-build PowerShell script to your project. + +First, create a PowerShell script called postbuild.ps1 in your project under a solution folder that contains the following script: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +$packages = gci $Env:TF_BUILD_SOURCESDIRECTORY -recurse -include $("bin") | ?{ $_.PSIsContainer } | foreach { gci -Path $_.FullName -Recurse -include $("*.apk", "*.ipa", "*.plist", "*.xap") } +foreach ($file in $packages) { + Copy $file $Env:TF_BUILD_BINARIESDIRECTORY +} +gci $Env:TF_BUILD_SOURCESDIRECTORY -recurse -include $("AppPackages") | ?{ $_.PSIsContainer } | Copy -Destination $Env:TF_BUILD_BINARIESDIRECTORY –Recurse -Force +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This will copy any .apk, .ipa, or .plist file from the project's "bin" folder to the drop location and will also grab generated AppPackages under the platforms/windows/AppPackages folder from your project. Place this script under a solution folder such as "build". + +![Solution with Build Script]() + +Now, create a build definition if you have not done so already and add the PowerShell script as a post-build script under "Process =\> Build =\> Advanced =\> Post-build script path". The file will be under the solution so you will need include the solution folder name in the path. You will also want to ensure your build definition with the output location (Process =\> Build =\> 4. Output location) as "SingleFolder" rather than AsConfigured. + +![Build Definition with PowerShell Script]() + +##Common Environment Variables +There are a set of environment variables that need to be made available to MSBuild. These can either be setup on your machine as system environment variables or using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). + +**Troubleshooting Tip:** Use full, absolute paths and be sure to remove any leading or trailing spaces in the your variable paths! Also note that whenever you set a system environment variable you will need to restart the build service to get it to pick up the change. + +| **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | +|:------------------|:-----------------------------------|:-----------------------------------------|:---------------------------------------------------| +| **MDAVSIXDIR** | Any operation | Location of the Tools for Apache Cordova VSIX. With Visual Studio 2015, its location is always the same. In VS 2013, you will need to search for the VSIX by finding a folder containing the "vs-mda-targets" folder. | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Common7\\IDE\\Extensions\\ApacheCordovaTools | +| **NODEJSDIR** | Any operation | Location of Node.js | C:\\Program Files (x86)\\nodejs | +| **NPMINSTALLDIR** | Any operation | Location to install npm packages when building. | C:\\Users\your-user-here\\AppData\Roaming\\npm | +| **LANGNAME** | Any operation | Language used for messaging from node scripts. | en-us | +| **BUILDVERBOSITY**| Any operation | Logging level for the Node.js portion of the build.
Set using the /p MSBuild argument in your build definition (Process =\> Advanced =\> MSBuild Arguments). | Normal | +| **GIT\_HOME** | Optional: Plugins Acquired via Git | Location of the Git Command Line Tools | C:\\Program Files (x86)\\git | +| **GRADLE\_USER\_HOME** | Optional | Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ | If not specified, uses %HOME%\\.gradle | + +## Building Android + +If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. + +###Android Environment Variables + +In addition to the common environment variables mentioned above, the following variable can either be set as system environment variables or semi-colon delimited using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). + +**Note that whenever you set a system environment variable you will need to restart the build service to get it to pick up the change.** + +| **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | +|:------------------|:-----------------|:----------------------------|:------------------------------------------| +| **ANT\_HOME** | Android | Location of Ant | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | +| **ANDROID\_HOME** | Android | Location of the Android SDK | C:\\Program Files (x86)\\Android\\android-sdk | +| **JAVA\_HOME** | Android | Location of Java | C:\\Program Files (x86)\\Java\\jdk1.7.0\_55 | + +##Android Build Definition Settings + +In addition to your other build definition settings, you will want to use the following build parameter values. + +| **Parameter** | **Purpose** | **Value** | +|:-----------------------------------------|:-----------------------------------------|:-----------------------------------------| +| **Process =\> Items To Build =\> Configurations to Build**| Platform to build| **Configuration: Debug or Release**
**Platform: Android** | +| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: emulator, ripple, or device. | **/p:DebuggerFlavor=AndroidDevice** | +  +##Building iOS +If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. In addition you will need to have a remote build agent configured on an OSX machine. See [Tools for Apache Cordova documentation](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +**Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. + +###iOS Environment Variables and Cert Setup +In addition to the common environment variables mentioned above, the following variable can either be set as system environment variables or semi-colon delimited using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). + +Using an environment variable is most useful when you want a single build definition to be able to be used with different remote build agents originating from different TFS build agents and thus do not want to have the agent URI in the build definition itself. + +| **Variable** | **Required For** | **Purpose** | **Example** | +|:-------------------------|:-----------------|:-----------------------------------------|:-----------------------------------------| +| **iOSRemoteBuildServer** | iOS | Host and port for iOS remote agent. | https://chux-mini.local:3000 | +| **iOSRemoteSecureBuild** | iOS | Indicates whether a secure connection should be used to connect to the agent | true | + +By far the easiest way to import the client SSL certificate used for secure remote build is to simply start up Visual Studio and configure the remote agent there. This will import the client SSL cert into your local certificate store so it can be used during build. See [Tools for Apache Cordova documentation](http://go.microsoft.com/fwlink/?LinkID=533745) for details. + +**Note: You also need to configure the TFS build service on your build server to run using the same user that you used to log in and configure Visual Studio.** + +![Build Service with User]() + +#### Manual Import of SSL Cert +However, it is also possible to manually import the SSL cert by following these steps: + +1. Generate a security PIN. This automatically occurs the first time you start up the remote build agent but you can also generate a new one using the following command: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + vs-mda-remote generateClientCert + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2. Get the generated .p12 file from the agent using the following URI in a browser using the host, port, and PIN from the agent output. **Be sure you start vs-mda-remote if it is not running before accessing this URI.** + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + https://:/certs/ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +3. Ignore the SSL security warning + +4. Download the .p12 file and save it. **Note: For security reasons, this PIN will be automatically invalidated after you download the file.** You may, however, use the cert file on multiple machines if needed. + +6. You now simply open the p12 file from the file system to import the cert using the Certificate Import Wizard that appears. + +###iOS Build Definition Settings + +In addition to your other build definition settings, you will want to use the following build parameter values. + +| **Parameter** | **Purpose** | **Value** | +|:-----------------------------------------|:-----------------------------------------|:-----------------------------------------| +| **Process =\> Items To Build =\> Configurations to Build** | Platform to build | **Configuration: Debug or Release**
**Platform: iOS** | +| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: simulator, ripple, or device. | **/p:DebuggerFlavor=iOSLocalDevice** | + +##Building Windows / Windows Phone 8.1 +If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. + +###Windows 8.1 Build Definition Settings +In addition to your other build definition settings, you will want to use the following build parameter values. + +| **Parameter** | **Purpose** | **Value** | +|:-----------------------------------------|:-----------------------------------------|:-----------------------------------------| +| **Process =\> Items To Build =\> Configurations to Build** | Platform to build | **Configuration: Debug or Release**
**Platform: One or more of the following depending on the chipsets you need to support:**
Windows-AnyCPU
Windows-ARM
Windows-x64
Windows-x86 | +| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: simulator or device. | **/p:DebuggerFlavor=WindowsLocal** | + +###Windows Phone 8.1 Build Definition Settings +In addition to your other build definition settings, you will want to use the following build parameter values. + +| **Parameter** | **Purpose** | **Value** | +|:-----------------------------------------|:-----------------------------------------|:-----------------------------------------| +| **Process =\> Items To Build =\> Configurations to Build** | Platform to build | **Configuration: Debug or Release**
**Platform: Windows Phone (Universal)** | +| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: emulator or device. | **/p:DebuggerFlavor=PhoneDevice** | + +##Building Windows Phone 8.0 +If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. + +###Build Definition Settings +In addition to your other build definition settings, you will want to use the following build parameter values. + +| **Parameter** | **Purpose** | **Value** | +|:-----------------------------------------|:-----------------------------------------|:-----------------------------------------| +| **Process =\> Items To Build =\> Configurations to Build** | Platform to build | **Configuration: Debug or Release**
**Platform: Windows Phone 8** | +| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: emulator or device. | **/p:DebuggerFlavor=PhoneDevice** | + +## More Information +* [Learn about other Team Build / CI options](../README.md) +* [Read tutorials and learn about tips, tricks, and known issues](../../Readme.md) +* [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) +* [Follow us on Twitter](https://twitter.com/VSCordovaTools) +* [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) +* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file diff --git a/tutorial-team-build/RC/TFS2015.md b/tutorial-team-build/RC/TFS2015.md new file mode 100644 index 00000000..1a59a9a8 --- /dev/null +++ b/tutorial-team-build/RC/TFS2015.md @@ -0,0 +1,191 @@ +#Using Tools for Apache Cordova with Team Foundation Services 2015 RC +**This article is specific to using Tools for Apache Cordova 2015 with TFS 2015 *RC*. See [this article for details on Visual Studio Online or TFS 2015 RTM or later](../TFS2015.md).** + +Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. Team Foundation Services 2015 provides a new [cross-platform agent](http://go.microsoft.com/fwlink/?LinkID=533789) and [Gulp](http://go.microsoft.com/fwlink/?LinkID=533742lp) based build capabilities that enables TFS to build directly on Windows or OSX which is a critical capability Cordova based development. In addition, Gulp also enables you to easily add in a large number of "[plugins](http://go.microsoft.com/fwlink/?LinkID=533790)" to perform useful build tasks in environments that you do not control directly like Visual Studio Online. + +For these reasons, this tutorial will focus on the use of the cross-platform agent and Gulp rather than MSBuild as the primary build language for Cordova apps. If you still need to use the legacy XAML / MSBuild based approach, see the [TFS 2013](http://go.microsoft.com/fwlink/?LinkID=533770) tutorial for details on setup. The instructions generally still apply to TFS 2015. + +**Troubleshooting Tip: Be aware that a bug in VS templates in VS 2015 RC included four json files that can cause issues if added to source control: plugins/android.json, plugins/remote_ios.json, plugins/windows.json, and plugins/wp8.json.** Adding these files to source control can result in a build that appears to succeed but is missing plugin native code. They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. + +##Initial Setup +Since the build process we will describe here is not directly dependent on MSBuild or Visual Studio for Android, you have two options for installing pre-requisites on Windows: + +1. Install Visual Studio 2015 and select the Tools for Apache Cordova option and let it install the pre-requisites for you + +2. Manually install only the pre-requisites needed for the specific platforms you intend to build. For example, you do not need to install Visual Studio at all if you only intend to target Android. See "Installing Dependencies" in the [Building Cordova Apps in a Team / Continuous Integration Environment](http://go.microsoft.com/fwlink/?LinkID=533743) tutorial for details. + +Next you will need to install the Windows build agent to build Android, Windows, or Windows Phone, and the [cross-platform build agent](http://go.microsoft.com/fwlink/?LinkID=533789) on an OSX machine if you intend to build iOS. See [TFS 2015 documentation](http://go.microsoft.com/fwlink/?LinkID=533772) for detailed instructions on configuring the agent for use with an on premise TFS 2015 instance or Visual Studio Online. + +**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) if your build servers have limited Internet connectivity or require routing traffic through a proxy. + +###Visual Studio Online +As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Online. This allows you to build without setting up a Windows build agent on premise. iOS builds are not yet available. + +When using the Hosted Agent Pool in Visual Studio Online (VSO), all pre-requisites will already be installed and Node.js will be in your path. However, Apache Ant, required for building Android with Cordova 4.3.0 and below, will not be in your path. Fortunately you can resolve this issue in a few simple steps. We will cover these details step-by-step later in this tutorial. + +###Meet the Cross-Platform Build Agent +Since it is a new capability, let's pause and briefly highlight the new TFS [cross-platform build agent](http://go.microsoft.com/fwlink/?LinkID=533789) we will be using in this tutorial for building iOS on OSX since setup is different than traditional TFS build agents. The agent is a Node.js based service that uses a HTTPS connection to your TFS 2015 server to fetch work. As a result, your OSX machine only needs to have HTTP access to your TFS instance but not the other way around. This makes setup and configuration quite simple. The agent is for use with TFS 2015 and Visual Studio Online's [next generation build system](http://go.microsoft.com/fwlink/?LinkID=533772), not the legacy XAML/MSBuild based system. + +The pre-requisites in this case are simple: Your OSX machine needs to have Node.js and Xcode installed. Simply open the OSX Terminal app and follow the [setup instructions](http://go.microsoft.com/fwlink/?LinkID=533789). The agent will automatically register itself with TFS when you start up the agent for the first time. + +Because of its design, you can also easily use an **on-premise OSX machine with Visual Studio Online.** The OSX machine simply needs to have HTTP access to your VSO domain URI. You do not need a VPN connection and VSO does not need access to the OSX machine. Simply enter the your VSO project's domain URI when prompted during agent setup (Ex: "https://myvsodomain.visualstudio.com"). All other setup instructions apply directly. + +##Environment Variables +You should set the following environment variables if they have not already been configured. Note that you can also set these in the "Variables" section of your build definition if you would prefer. + +| **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | +|:-------------------|:-----------------------------------------|:-----------------------------------------|:------------------------------------------| +| **ANDROID\_HOME** | Android | Location of the Android SDK | %PROGRAMFILES(x86)%\\Android\\android-sdk | +|**JAVA\_HOME** | Android | Location of Java | %PROGRAMFILES(x86)%\\Java\\jdk1.7.0\_55 | +| **ANT\_HOME** | Android when building using Ant (not Gradle) | Location of Ant | %PROGRAMFILES(x86)%\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | +| **GRADLE\_USER\_HOME** | Optional | Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ | If not specified, uses %HOME%\\.gradle on Windows or ~/.gradle on OSX | +| **CORDOVA\_CACHE** | Optional | Overrides the default location used by the [sample build module](http://go.microsoft.com/fwlink/?LinkID=533736) to cache installs of multiple versions of Cordova. | If not specified, uses %APPDATA%\\cordova-cache on Windows and ~/.cordova-cache on OSX | + +Note that you can opt to pre-populate the GRADLE_USER_HOME and CORDOVA_CACHE locations with the versions of Cordova and its dependencies you want to use by updating the [prep-cache PowerShell script](https://github.com/Chuxel/taco-team-build/tree/master/samples/prep-cache) in the samples directory of the sample build module GitHub repo. + +###Setting Your Path +The following will also need to be in your path: +- **Node.js** should already be in your path on OSX simply by the fact that you've setup the cross-platform build agent, but if it is not in your path on Windows you will want to be sure it is configured for use. The default location of Node.js on Windows is **%PROGRAMFILES(x86)%\nodejs**. +- **%ANT_HOME%\bin** should be added to your path if you are using a version of Cordova < 5.0.0 or have specified the "--ant" build option + +When using the Hosted Agent Pool in Visual Studio Online (VSO), all other pre-requisites will already be installed and these environment variables will be set. Node.js will be in your path but Apache Ant, required for building Android with Cordova 4.3.0 and below, will not be in your path. Fortunately you can resolve this issue in a few simple steps. We will cover these details in the "Build Definition for Windows" section below. + +##Project Setup & Build Definitions +###Adding Gulp to Your Project +Using Gulp in a team environment is fairly straight forward as you can see in the detailed [Gulp tutorial](http://go.microsoft.com/fwlink/?LinkID=533742). However, to streamline setup, follow these steps: + +1. Take the sample "gulpfile.js" and "package.json" file from the "samples/gulp" folder [from this GitHub repo](http://go.microsoft.com/fwlink/?LinkID=533736) and place them in the root of your project + +2. Check these two files into source control with your project + +From here you can modify gulpfile.js and add other gulp plugins. The [Gulp tutorial](http://go.microsoft.com/fwlink/?LinkID=533742) provides additional detail on what the gulpfile does and how to wire Gulp tasks as "hooks" into Cordova build events. + +###Creating Your Build Definitions +We'll assume for the purposes of this tutorial that we want to build our Cordova app for Android, iOS, and Windows. The Windows Cordova platform can only be built on Windows and iOS can only be built on OSX. As a result, we'll need the ability to be able to queue a build that can target one of these two operating systems. + +There are two ways that this can be accomplished: + +1. Setting up separate build queues for OSX vs Windows machines and then queueing the same build definition in the appropriate build queue based on the desired platform + +2. Using the concept of a "demand" in two separate build definitions to route the work to the correct OS from the same queue + +For the sake of this tutorial, we'll cover option 2. The sample "gulpfile.js" assumes you want to build Android, Windows, and Windows Phone on Windows and iOS on OSX. Technically you could also opt to have Android built on OSX but we will not cover that in detail in this tutorial. + +#### Build Definition for Windows +**Note:** *For this tutorial we have opted to use the "Command Line" build task since as of this writing the "Npm install" and "Gulp" build tasks were not available from the Windows agent. You can opt to use these build tasks instead and this tutorial will be updated as these features come on-line.* + +Detailed instructions on creating build definitions in TFS 2015 can be found in [its documentation](http://go.microsoft.com/fwlink/?LinkID=533772), but here are the specific settings you will need to use to configure a build. + +1. Depending on the version of TFS 2015 you are using, you may need to click on the **BUILD.PREVIEW** menu option to access the next generation TFS build system. + + ![BUILD.PREVIEW]() + +2. Create a new build definition and select "Empty" as the template. We'll start out targeting platforms that can be built on Windows so give the build definition a name that indicates that this is the case. + +3. Now we will configure the build definition to install any Gulp or npm package dependencies your build may have. + 1. Under the "Build" tab, add a new build step and select **Command Line** from the **Utility** category + 2. Use the following settings: + - **Tool:** cmd + - **Arguments:** /c npm install + - **Advanced =\> Working Directory**: Location of the Cordova project itself inside your solution (not the solution root). + - **Advanced =\> Fail on Standard Error**: Unchecked. + + ![Windows Build Definition - npm]() + + We need to use cmd.exe here due as npm is a batch file rather than an executable and thus is not found by the Command Line build task. This will be resolved in future updates. + +4. Next we'll configure Gulp itself. + + 1. Under the "Build" tab, add a new build step and select **Command Line** from the **Utility** category. + 2. Use the following settings: + - **Tool:** node + - **Arguments:** node_modules/gulp/bin/gulp.js + - **Advanced =\> Working Directory**: Location of the Cordova project itself inside your solution (not the solution root). + - **Advanced =\> Fail on Standard Error**: Unchecked. + + ![Windows Build Definition - gulp]() + +5. Next we need to ensure that this particular build runs on Windows rather than OSX. Under the "General" tab, verify a demand that "Cmd" exists is present. If not, add one. + + ![Windows Build Definition - Demand]() + +6. As an optional step, you can configure your build to upload the resulting build artifacts to your TFS or VSO instance for easy access. The sample gulpfile.js script places the resulting output in the "bin" folder to make configuration simple. **TFS 2015 RC on-premise installs vary here slightly.** + + For **Visual Studio Online and post-RC TFS 2015** releases: + + 1. Under the "Build" tab, add a new build step and select **Publish Artifact** from the **Build** category. + 2. Use the following settings: + - **Copy Root**: Location of the Cordova project itself inside your solution (not the solution root). + - **Contents:** bin/* + - **Artifact Name:** bin + - **Artifact Type:** Server + + ![Windows Build Definition - Drop location]() + + For **TFS 2015 RC** on-premise installs, go to the "Options" tab and enter the following information: + - **Copy to Staging Folder:** Checked + - **Copy to Staging Folder =\> Search Pattern:** \*/bin + - **Create Build Drop:** Checked + - **Create Build Drop =\> Drop location:** Server + + +Finally, click the "Queue build..." button to validate your setup. You'll see a real-time console view of your build progressing so you can quickly fine tune your definition. + +That's it for Windows! You're now able to build using the Android, Windows, and Windows Phone 8 (WP8) Cordova platforms. + +####Using the Hosted Agent Pool in Visual Studio Online +As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Online. This allows you to build without setting up a Windows build agent on-premise. iOS builds are not yet available. + +When using Hosted build agents in Visual Studio Online (VSO), Node.js will already be in your path but Ant will not. Fortunately you can resolve this issue in a few simple steps as all of the other required environment variables will be set for you. + +1. Create a batch file called "setenv.cmd" and place it in a solution folder with the following contents: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + @SET PATH=%PATH%;%ANT_HOME%\bin + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2. Check this into source control with the rest of your project. + + ![setenv.cmd in solution]() + +3. Next, under the "Build" tab in your Windows Build Definition, add a new build step, select **Batch Script** from the **Utility** category, and enter the following settings: + + - **Path:** setenv.cmd + - **Modify Environment:** Checked. + +4. Make this the first build step in your build definition. + + ![Windows Build Definition - setenv.cmd]() + +You are now ready to go in VSO! + +#### Build Definition for OSX +Now let's create a version of this same build definition to target iOS that will run on a configured cross-platform agent on OSX. + +1. Right click on the Windows build definition and select "Clone." Once you save you should give this definition a name that indicates it's the OSX build. + +2. Next we need to update our call to "npm install" to be OSX friendly. + 1. Select the existing "Run cmd" Command Line build step + 2. Update the following settings: + - **Tool:** npm + - **Arguments:** install + + ![OSX Build Definition - Update npm install]() + +3. Now we need to add a demand that will route builds to OSX machines rather than Windows. Under the "General" tab, remove the "Cmd" demand if present and add a demand that "xcode" exists. + + ![OSX Build Definition - Demand]() + +You are now all set! You can configure either of these build definitions further as you see fit including having them automatically fire off on check-in or adding other validations. + +**Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. + +## More Information +* [Learn about other Team Build / CI options](../README.md) +* [Read tutorials and learn about tips, tricks, and known issues](../../Readme.md) +* [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) +* [Follow us on Twitter](https://twitter.com/VSCordovaTools) +* [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) +* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file diff --git a/tutorial-team-build/RC/media/tfs2013-1.png b/tutorial-team-build/RC/media/tfs2013-1.png new file mode 100644 index 00000000..9f3c9a4e Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2013-1.png differ diff --git a/tutorial-team-build/RC/media/tfs2013-2.png b/tutorial-team-build/RC/media/tfs2013-2.png new file mode 100644 index 00000000..c7e25c4d Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2013-2.png differ diff --git a/tutorial-team-build/RC/media/tfs2013-3.png b/tutorial-team-build/RC/media/tfs2013-3.png new file mode 100644 index 00000000..7724925f Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2013-3.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-0.png b/tutorial-team-build/RC/media/tfs2015-0.png new file mode 100644 index 00000000..e928fe6b Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-0.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-1.png b/tutorial-team-build/RC/media/tfs2015-1.png new file mode 100644 index 00000000..0fcecf00 Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-1.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-2.png b/tutorial-team-build/RC/media/tfs2015-2.png new file mode 100644 index 00000000..dfcfe5cc Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-2.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-3.png b/tutorial-team-build/RC/media/tfs2015-3.png new file mode 100644 index 00000000..e4b89154 Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-3.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-4.png b/tutorial-team-build/RC/media/tfs2015-4.png new file mode 100644 index 00000000..7483cbbc Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-4.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-5.png b/tutorial-team-build/RC/media/tfs2015-5.png new file mode 100644 index 00000000..2392abd2 Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-5.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-6.png b/tutorial-team-build/RC/media/tfs2015-6.png new file mode 100644 index 00000000..f2c6bd36 Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-6.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-7.png b/tutorial-team-build/RC/media/tfs2015-7.png new file mode 100644 index 00000000..0f5a151b Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-7.png differ diff --git a/tutorial-team-build/RC/media/tfs2015-8.png b/tutorial-team-build/RC/media/tfs2015-8.png new file mode 100644 index 00000000..2eab3f3e Binary files /dev/null and b/tutorial-team-build/RC/media/tfs2015-8.png differ diff --git a/tutorial-team-build/README.md b/tutorial-team-build/README.md index c5807fff..b4be14d6 100644 --- a/tutorial-team-build/README.md +++ b/tutorial-team-build/README.md @@ -5,15 +5,32 @@ With the release of Visual Studio 2015, you now have a number of options for how For abridged informaiton on specific build systems, you may find this sample [taco-team-build node module](http://go.microsoft.com/fwlink/?LinkID=533736) useful along with the following tutorials: -- [Gulp - Using Gulp to Build Cordova in a Team / CI Environment](http://go.microsoft.com/fwlink/?LinkID=533742) -- [Team Foundation Services 2015 and Visual Studio Online](http://go.microsoft.com/fwlink/?LinkID=533771) -- [Team Foundation Services 2013](http://go.microsoft.com/fwlink/?LinkID=533770) -- [Jenkins CI](http://go.microsoft.com/fwlink/?LinkID=613703) +- **[Getting Started with Cordova & TFS 2015 or Visual Studio Online](./TFS2015.md)** +- **[Getting Started with Cordova & TFS 2013](./TFS2013.md)** +- **[Getting Started with Cordova & Jenkins CI](./Jenkins.md)** +- **[Getting Started with Cordova & Automating Builds with Gulp](../tutorial-gulp/gulp-ci.md)** + +Read these articles to get up and running quickly! + +This remaineder of this article will go through the general approach for tackling a number challenges that exist when building Cordova apps and cover what the [taco-team-build node module](http://go.microsoft.com/fwlink/?LinkID=533736) effectively does behind the scenes. + +It has the following sections: + +- [What to Add to Source Control](#whattoadd) +- [Basic Workflow using the Cordova CLI](#basic) +- [Installing Dependencies](#depends) +- [Internet Access & Proxy Setup](#proxy) +- [Cordova Challenges](#challenges) + - [Building with Multiple Versions of the Cordova CLI](#multicli) + - [Adding Platforms](#platforms) + - [Generating an iOS App Store Package](#ipa) + - [Visual Studio Specific Features](#vsspecific) +- [OSX Gotchas: Troubleshooting Tips for Building on OSX](#osxgotcha) -This article will go through the general approach for tackling a number challenges that exist when building Cordova apps and cover what the taco-team-build node module effectively does behind the scenes. *Note that Team Foundation Services 2013 cannot easily take advantage of the workflow described here (though 2015 can) as it is MSBuild based. See the [Team Foundation Services 2013](http://go.microsoft.com/fwlink/?LinkID=533770) tutorial for details.* + ##What to Add to Source Control On the surface, this seems like all files in a given Cordova project should be added to source control. However, to avoid unexpected issues, we recommend excluding the following files and folders from source control. @@ -31,10 +48,11 @@ On the surface, this seems like all files in a given Cordova project should be a - *.suo - *.jsproj.user -**Troubleshooting Tip: Be aware that a bug in VS templates in VS 2015 RC included four json files that can cause issues if added to source control: plugins/android.json, plugins/windows.json, plugins/remote_ios.json, and plugins/wp8.json.** Adding these files to source control can result in a build that appears to succeed but is missing plugin native code. They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. +**Troubleshooting Tip:** Adding plugins/android.json, plugins/ios.json, plugins/remote_ios.json, plugins/windows.json, or plugins/wp8.json adding these files to source control can result in a build that **appears to succeed but is missing plugin native code.** They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. Note that you **can** add "plugins/fetch.json" to source control along with the rest of the contents of the plugins folder. See [our Issues, Tips, and Workarounds documentation](../tips-and-workarounds) for additional tips on addressing common build issues. + ##Basic Workflow Each build server technology is a bit different and in this article we will focus on the general steps required to build a Cordova app regardless of technology using the Cordova Command Line Interface. @@ -56,12 +74,20 @@ The basic flow for building a Cordova app is simple on the surface: The Cordova CLI is node.js based, so these exact same steps can be run from Windows or an OSX machine or from a cloud hosted VM like [MacInCloud](http://go.microsoft.com/fwlink/?LinkID=533746). See the [Cordova CLI documentation](http://go.microsoft.com/fwlink/?LinkID=533773) for additional details. -Exactly how these steps are executed will vary depending on your build server. However, there are a few challenges that may not be immediately obvious when setting up an automated build environment. This are article will describe some techniques for dealing with these common problems. +Exactly how these steps are executed will vary depending on your build server. However, there are a **number of challenges that may not be immediately obvious** when setting up an automated build environment. This are article will describe some techniques for dealing with these common problems. +###A Note on TypeScript +Unlike Visual Studio, it's important to note that the base Cordova CLI does not itself automatically compile TypeScript code. If you are using a build language like Gulp or Grunt, there are convenient plugins that you can use to compile your TypeScript code. Otherwise there is also a node.js based command line utility that works both on Windows and OSX. See the following links for additional details: + +- [Compiling TypeScript from the command line](http://go.microsoft.com/fwlink/?LinkID=533802) +- [gulp-typescript](http://go.microsoft.com/fwlink/?LinkID=533748) +- [grunt-typescript](http://go.microsoft.com/fwlink/?LinkID=533779) + + ##Installing Dependencies Cordova builds require that a number of dependencies be properly installed and configured on the system. However, exactly which dependencies are required varies based on the Cordova "platform" (Android, iOS, Windows 8.0/8.1 and Phone 8.1, Windows Phone 8.0) you want to build. -Installing Visual Studio 2015 with the Tools for Apache Cordova option will automatically install these dependencies but you will still need to configure some of the environment variables by hand for Android. See [Team Foundation Services 2015 and Visual Studio Online](http://go.microsoft.com/fwlink/?LinkID=533771) for a summary of these variables. +Installing Visual Studio 2015 with the Tools for Apache Cordova option will automatically install these dependencies but you will still need to configure some of the environment variables by hand for Android. See [Team Foundation Services 2015 and Visual Studio Online](./TFS2015.md) for a summary of these variables. Otherwise you can manually install only those dependencies that are needed for building the platforms you are interested in. @@ -91,7 +117,8 @@ Otherwise you can manually install only those dependencies that are needed for b 1. [Windows and Windows Phone 8.1+ Platfrom Guide](http://go.microsoft.com/fwlink/?LinkID=533777) 2. [Windows Phone 8.0 Platform Guide](http://go.microsoft.com/fwlink/?LinkID=533778) -###Internet Access & Proxy Setup + +##Internet Access & Proxy Setup If your build server is running in a datacenter, it may be very locked down and not have unrestricted access to the Internet. Due to dynamic acquistion requirements, you will need to allow the build servers to access the following domains: - npm: http://registry.npmjs.org @@ -116,17 +143,13 @@ You may also need to configure proxy settings for Java. This can be [accomplishe JAVA_OPTS=-Dhttps.proxyHost= -Dhttps.proxyPort= -Dhttp.proxyHost= -Dhttp.proxyPort= -DproxySet=true ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -###A Note on TypeScript -Unlike Visual Studio, it's important to note that the base Cordova CLI does not itself automatically compile TypeScript code. If you are using a build language like Gulp or Grunt, there are convenient plugins that you can use to compile your TypeScript code. Otherwise there is also a node.js based command line utility that works both on Windows and OSX. See the following links for additional details: - -- [Compiling TypeScript from the command line](http://go.microsoft.com/fwlink/?LinkID=533802) -- [gulp-typescript](http://go.microsoft.com/fwlink/?LinkID=533748) -- [grunt-typescript](http://go.microsoft.com/fwlink/?LinkID=533779) +Finally, if you see the error "**TypeError: Request path contains unescaped characters**" when building or installing a plugin you may need to downgrade [Node.js 0.10.29](http://nodejs.org/dist/v0.10.29/). See [tips and workarounds](../tips-and-workarounds/general/README.md#cordovaproxy) for additional details. + ##Cordova Challenges When building Cordova projects in a server environment, there are a number of challenges you may encounter. This tutorial will describe simple ways to handle these problems without going into specifics on particular CI servers so that this information can be adapted to your favorite build technology. -If you are looking for a quick solution you may want to read the [Gulp](http://go.microsoft.com/fwlink/?LinkID=533742) tutorial and [this Git repository](http://go.microsoft.com/fwlink/?LinkID=533736) with a sample taco-team-build node module designed to help resolve these problems regardless of build system. +If you are looking for a quick solution you may want to read the [Gulp](../tutorial-gulp/gulp-ci.md) tutorial and [this Git repository](http://go.microsoft.com/fwlink/?LinkID=533736) with a sample taco-team-build node module designed to help resolve these problems regardless of build system. The challenges are as follows: @@ -143,6 +166,7 @@ The challenges are as follows: 5. **OSX Gotchas.** If you spend most of your time developing in the Windows environment, there are a few common, easily resolved issues that can pop up when you start trying to build your project on OSX. + ###Building with Multiple Versions of the Cordova CLI The Cordova CLI is a standard Node.js npm package and thus can be installed either [globally or locally](http://go.microsoft.com/fwlink/?LinkID=533780). The trick, then, is to use a local installation of the Cordova CLI rather than a global one. There are two different methods that you can use to install Cordova locally: at the project level or in a global cache. @@ -243,8 +267,9 @@ To avoid re-installing each time, you can take advantage of Visual Studio's **ta 4. Use "./cordova.sh" (OSX) or "cordova.cmd" (Windows) to run additional Cordova commands -Note that this same script can be easily adapted to a [Gulp build task](http://go.microsoft.com/fwlink/?LinkID=533750). See the [Gulp](http://go.microsoft.com/fwlink/?LinkID=533742) tutorial for additional information. +Note that this same script can be easily adapted to a [Gulp build task](http://go.microsoft.com/fwlink/?LinkID=533750). See the [Gulp](../tutorial-gulp/gulp-ci.md) tutorial for additional information. + ###Adding Platforms Adding platforms in Cordova is quite simple using the "cordova platform" command. Ex: @@ -278,6 +303,7 @@ However, there are a couple of common problems when executing this command that if [ ! -d "platforms/android" ]; then cordova platform add android; fi; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ###Generating an iOS App Store Package In order to distribute your iOS application you will need to generate an "iOS App Store Package" or "ipa" file. These files can be imported into iTunes or enterprise app stores in addition to being distributed to the Apple App Store via the [Application Loader](http://go.microsoft.com/fwlink/?LinkID=533751). @@ -325,10 +351,11 @@ cordova build ios --device --release xcrun -v -sdk iphoneos PackageApplication "${WORKSPACE}/platforms/ios/build/device/My Cordova App.app" -o "${WORKSPACE}/platforms/ios/build/device/My Cordova App.ipa" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ###Visual Studio Specific Features A quick way to get you project working with Visual Studio specific features outside of Cordova is to add the sample [Visual Studio Tools for Apache Cordova CLI Support Plugin](http://go.microsoft.com/fwlink/?LinkID=533753) to your project. It adds in support for three things: -1. To support the Task Explorer, the plugin takes advantage of the technique illustrated in the [Gulp tutorial](http://go.microsoft.com/fwlink/?LinkID=533742) for wiring in Gulp tasks to Cordova build events. +1. To support the Task Explorer, the plugin takes advantage of the technique illustrated in the [Gulp tutorial](../tutorial-gulp/gulp-ci.md) for wiring in Gulp tasks to Cordova build events. 2. To support res/native, the plugin uses a similar approach and we will briefly cover how this works behind the scenes. 3. The plugin also adds in support for the VS specific Windows packaging elements in config.xml. @@ -371,6 +398,7 @@ function copyFiles(srcPath, destPath) { You can place this into a "hooks\before_prepare" folder Visual Studio Cordova project and check it into source control and it will automatically be used. + ### OSX Gotchas: Troubleshooting Tips for Building on OSX There are a few relativley common issues when building a Cordova app on OSX related to permissions that are worth noting. @@ -421,6 +449,6 @@ There are a few relativley common issues when building a Cordova app on OSX rela * [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) * [Follow us on Twitter](https://twitter.com/VSCordovaTools) * [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) -* [Read MSDN docs on using Visual Studo Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) * [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) * [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file diff --git a/tutorial-team-build/TFS2013.md b/tutorial-team-build/TFS2013.md index 5ca520d1..1a953008 100644 --- a/tutorial-team-build/TFS2013.md +++ b/tutorial-team-build/TFS2013.md @@ -1,27 +1,28 @@ -#Using Tools for Apache Cordova with Team Foundation Services 2013 -**This tutorial is part of a [series of tutorials](http://go.microsoft.com/fwlink/?LinkID=533743) on building Visual Studio 2015 Tools for Apache Cordova projects in a Team / CI environment and does not apply to Visual Studio 2013 CTPs.** +#Using Tools for Apache Cordova (RTM) with Team Foundation Services 2013 +**This article is intended for use with Visual Studio 2015 RTM or later. See [this alternate tutorial](./RC/TFS2013.md) for details on using Visual Studio 2015 RC.** -Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. However, you may want to use Team Foundation Services 2013 build agents. +The article is part of a [series of tutorials](./README.md) on building Visual Studio 2015 Tools for Apache Cordova projects in a Team / CI environment. -It is important to note that as a general recommendation, we encourage the use of [TFS 2015's next generation cross-platform build system](http://go.microsoft.com/fwlink/?LinkID=533772) and [Gulp](http://go.microsoft.com/fwlink/?LinkID=533742) based build capabilities rather than TFS 2013 or MSBuild since this provides the ability build directly from TFS on Windows or OSX. See the [TFS 2015 tutorial](http://go.microsoft.com/fwlink/?LinkID=533771) for details. Visual Studio Online's support for building Cordova apps will focus on the Gulp based TFS 2015 approach rather than MSBuild. +##Background +Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. However, you have an existing Team Foundation Services 2013 installation and would like to use existing configured build agents. + +It is important to note that as a general recommendation, we encourage the use of [TFS 2015's next generation cross-platform build system](./TFS2015.md) and [Gulp](../tutorial-gulp) based build capabilities rather than TFS 2013 or MSBuild since this provides the ability build directly from TFS on Windows or OSX. See the [TFS 2015 tutorial](http://go.microsoft.com/fwlink/?LinkID=533771) for details. Visual Studio Online's support for building Cordova apps will focus on the Gulp based TFS 2015 approach rather than MSBuild. This tutorial will describe how to configure TFS to build a Tools for Apache Cordova project using MSBuild and the steps provided here will generally apply to using MSBuild with TFS 2015 as well. -**Troubleshooting Tip: Be aware that a bug in VS templates in VS 2015 RC included four json files that can cause issues if added to source control: plugins/android.json, plugins/remote_ios.json, plugins/windows.json, and plugins/wp8.json.** Adding these files to source control can result in a build that appears to succeed but is missing plugin native code. They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. +**Troubleshooting Tip:** Be aware that we recommend against adding the "platforms" folder or the following json files in the "plugins" folder into source control: android.json, ios.json, remote_ios.json, windows.json, and wp8.json. See "What to Add to Source Control" in the [general team build tutorial](./README.md) for additional details. ##Initial Setup -Before getting started with setting up your TFS Build Agent, you should install Visual Studio 2015 with the Tools for Apache Cordova option. You will also want to select the Windows / Windows Phone 8.1 tools and the Windows Phone 8.0 tools if you want to build for any of these platforms. From there you will want to configure a build agent on the server you have installed Visual Studio 2015. +Before getting started with setting up your TFS Build Agent, you should install Visual Studio 2015 with the Tools for Apache Cordova option. You will also want to select the Windows / Windows Phone 8.1 tools and the Windows Phone 8.0 tools if you want to build for any of these platforms. From there you will want to configure a TFS build agent on the server you have installed Visual Studio 2015. - See [Tools for Apache Cordova documentation](http://go.microsoft.com/fwlink/?LinkID=533794) for setup details on Visual Studio 2015. - See [Team Foundation 2013 Build documentation](http://go.microsoft.com/fwlink/?LinkID=533786) for setup details on Team Foundation Services 2013. -Note that you may also use a stand-alone build agent integrated with Visual Studio Online. - -**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) if your build servers have limited Internet connectivity or require routing traffic through a proxy. +**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](./README.md) if your build servers have limited Internet connectivity or require routing traffic through a proxy. ##Common Build Definition Parameters & Environment Variables ###Updated Build Process Template -Before you get started, it's important to note that you will need to use v14 of MSBuild when building a Tools for Apache Cordova project. Build definition templates that ship with TFS 2013 support v11 and v12. As a result, you will need to create a modified TFS Build Process Template for TFS to use MSBuild v14.0. To do this, you can simply download the v12 template (or your own custom one) and append ToolVersion="14.0" to the end of the **RunMSBuild** element and upload it as a new template. Ex: +Before you get started, it's important to note that you will need to use v14 of MSBuild when building a Tools for Apache Cordova project. Build definition templates that ship with TFS 2013 support v11 and v12. As a result, you will need to create a modified TFS Build Process Template for TFS to use MSBuild v14.0. To do this, you can simply download the TfvcTemplate.12.xaml MSBuild v12 template (or your own custom one) and append ToolVersion="14.0" to the end of the **RunMSBuild** element and upload it as a new template. Ex: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -56,14 +57,14 @@ Now, create a build definition if you have not done so already and add the Power ##Common Environment Variables There are a set of environment variables that need to be made available to MSBuild. These can either be setup on your machine as system environment variables or using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). -**Troubleshooting Tip:** Use full, absolute paths and be sure to remove any leading or trailing spaces in the your variable paths! Also note that whenever you set a system environment variable you will need to restart the build service to get it to pick up the change. +**Troubleshooting Tip:** Use full, absolute paths and be sure to remove any leading or trailing spaces in your variable paths! Also note that whenever you set a system environment variable you will need to restart the build service to get it to pick up the change. | **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | |:------------------|:-----------------------------------|:-----------------------------------------|:---------------------------------------------------| | **MDAVSIXDIR** | Any operation | Location of the Tools for Apache Cordova VSIX. With Visual Studio 2015, its location is always the same. In VS 2013, you will need to search for the VSIX by finding a folder containing the "vs-mda-targets" folder. | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Common7\\IDE\\Extensions\\ApacheCordovaTools | | **NODEJSDIR** | Any operation | Location of Node.js | C:\\Program Files (x86)\\nodejs | | **NPMINSTALLDIR** | Any operation | Location to install npm packages when building. | C:\\Users\your-user-here\\AppData\Roaming\\npm | -| **LANGNAME** | Any operation | Language used for messaging from node scripts. | en-us | +| **LANGNAME** | Any operation | Language used for VS generated Cordova build messages. | en-us | | **BUILDVERBOSITY**| Any operation | Logging level for the Node.js portion of the build.
Set using the /p MSBuild argument in your build definition (Process =\> Advanced =\> MSBuild Arguments). | Normal | | **GIT\_HOME** | Optional: Plugins Acquired via Git | Location of the Git Command Line Tools | C:\\Program Files (x86)\\git | | **GRADLE\_USER\_HOME** | Optional | Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ | If not specified, uses %HOME%\\.gradle | @@ -74,13 +75,13 @@ If you have not already, create a build definition for your project. Note that c ###Android Environment Variables -In addition to the common environment variables mentioned above, the following variable can either be set as system environment variables or semi-colon delimited using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). +In addition to the common environment variables mentioned above, the following variables can either be set as system environment variables or semi-colon delimited using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). **Note that whenever you set a system environment variable you will need to restart the build service to get it to pick up the change.** | **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | |:------------------|:-----------------|:----------------------------|:------------------------------------------| -| **ANT\_HOME** | Android | Location of Ant | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | +| **ANT\_HOME** | Android in Cordova < 5.0.0 | Location of Ant | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | | **ANDROID\_HOME** | Android | Location of the Android SDK | C:\\Program Files (x86)\\Android\\android-sdk | | **JAVA\_HOME** | Android | Location of Java | C:\\Program Files (x86)\\Java\\jdk1.7.0\_55 | @@ -94,19 +95,26 @@ In addition to your other build definition settings, you will want to use the fo | **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: emulator, ripple, or device. | **/p:DebuggerFlavor=AndroidDevice** |   ##Building iOS -If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. In addition you will need to have a remote build agent configured on an OSX machine. See [Tools for Apache Cordova documentation](http://go.microsoft.com/fwlink/?LinkID=533745) for details. +Building for iOS with TFS 2013 requires that a TFS agent running on Windows be configured to communicate with a Visual Studio remote build agent running on OSX. See [the remote agent section](http://go.microsoft.com/fwlink/?LinkID=533745) of the Tools for Apache Cordova installation documentation for details on setting up the remote agent on OSX. + +**Note that Visual Studio 2015 RTM uses a different remote agent package (remoteagent)** than the vs-mda-remote agent used in VS 2015 RC and below. + +If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. **Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. ###iOS Environment Variables and Cert Setup -In addition to the common environment variables mentioned above, the following variable can either be set as system environment variables or semi-colon delimited using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). +In addition to the common environment variables mentioned above, the following variables can either be set as system environment variables or semi-colon delimited using the "/p" option in your build definition (Process =\> Advanced =\> MSBuild Arguments). -Using an environment variable is most useful when you want a single build definition to be able to be used with different remote build agents originating from different TFS build agents and thus do not want to have the agent URI in the build definition itself. +For iOS, using a system environment variable is most useful when you want a single iOS build definition to built on a number of separate Windows TFS based build agents with a set of different OSX remote build agents instances in your build farm. -| **Variable** | **Required For** | **Purpose** | **Example** | +|**Variable** | **Required For** | **Purpose** | **Example** | |:-------------------------|:-----------------|:-----------------------------------------|:-----------------------------------------| -| **iOSRemoteBuildServer** | iOS | Host and port for iOS remote agent. | https://chux-mini.local:3000 | | **iOSRemoteSecureBuild** | iOS | Indicates whether a secure connection should be used to connect to the agent | true | +| **iOSRemoteBuildServer** | iOS | URI of the iOS remote agent. Form:
http(s)://<host>:<port>/cordova
Use "https" in secure mode. | https://chux-mini.local:3000/cordova | +| **iOSCertificateName** | iOS | Name of the SSL certificate for secure mode. Form:
remotebuild.<host> | remotebuild.chux-mini.local | + +###Importing the Secure Connection SSL Certificate By far the easiest way to import the client SSL certificate used for secure remote build is to simply start up Visual Studio and configure the remote agent there. This will import the client SSL cert into your local certificate store so it can be used during build. See [Tools for Apache Cordova documentation](http://go.microsoft.com/fwlink/?LinkID=533745) for details. @@ -114,23 +122,26 @@ By far the easiest way to import the client SSL certificate used for secure remo ![Build Service with User]() -#### Manual Import of SSL Cert +#### (Optional) Manual Import of SSL Cert However, it is also possible to manually import the SSL cert by following these steps: 1. Generate a security PIN. This automatically occurs the first time you start up the remote build agent but you can also generate a new one using the following command: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - vs-mda-remote generateClientCert + remoteagent generateClientCert ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -2. Get the generated .p12 file from the agent using the following URI in a browser using the host, port, and PIN from the agent output. **Be sure you start vs-mda-remote if it is not running before accessing this URI.** +2. Get the generated .p12 file from the agent using the following URI in a browser using substituting host, port, and PIN from the agent output. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ https://:/certs/ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -3. Ignore the SSL security warning -4. Download the .p12 file and save it. **Note: For security reasons, this PIN will be automatically invalidated after you download the file.** You may, however, use the cert file on multiple machines if needed. + Be sure you start the remote agent if it is not running before accessing this URI. + -6. You now simply open the p12 file from the file system to import the cert using the Certificate Import Wizard that appears. +3. Ignore the SSL security warning that may appear and download the .p12 file and save it. **Note: For security reasons, this PIN will be automatically invalidated after you download the file.** You may, however, use the cert file on multiple machines if needed. + +6. You now simply open the p12 file from the file system to import the cert using into your user's certificate store by accepting all the defaults in the Certificate Import Wizard that appears. ###iOS Build Definition Settings @@ -144,7 +155,7 @@ In addition to your other build definition settings, you will want to use the fo ##Building Windows / Windows Phone 8.1 If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. -###Windows 8.1 Build Definition Settings +###Windows 8.1 / 10 Build Definition Settings In addition to your other build definition settings, you will want to use the following build parameter values. | **Parameter** | **Purpose** | **Value** | @@ -158,7 +169,7 @@ In addition to your other build definition settings, you will want to use the fo | **Parameter** | **Purpose** | **Value** | |:-----------------------------------------|:-----------------------------------------|:-----------------------------------------| | **Process =\> Items To Build =\> Configurations to Build** | Platform to build | **Configuration: Debug or Release**
**Platform: Windows Phone (Universal)** | -| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: emulator or device. | **/p:DebuggerFlavor=PhoneDevice** | +| **Process =\> Advanced =\> MSBuild Arguments** | Indicates the type of build to create: emulator or device. | **/p:DebuggerFlavor=AppHostLocalDebugger** | ##Building Windows Phone 8.0 If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target. @@ -177,6 +188,6 @@ In addition to your other build definition settings, you will want to use the fo * [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) * [Follow us on Twitter](https://twitter.com/VSCordovaTools) * [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) -* [Read MSDN docs on using Visual Studo Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) * [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) -* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file +* [Email us your questions](mailto:/vscordovatools@microsoft.com) diff --git a/tutorial-team-build/TFS2015.md b/tutorial-team-build/TFS2015.md index 733c2ce8..b41eee81 100644 --- a/tutorial-team-build/TFS2015.md +++ b/tutorial-team-build/TFS2015.md @@ -1,64 +1,63 @@ -#Using Tools for Apache Cordova with Visual Studio Online and Team Foundation Services 2015 (RC) -**This tutorial is part of a [series of tutorials](http://go.microsoft.com/fwlink/?LinkID=533743) on building Visual Studio 2015 Tools for Apache Cordova projects in a Team / CI environment and does not apply to Visual Studio 2013 CTPs.** +#Using Tools for Apache Cordova with Visual Studio Online and Team Foundation Services 2015 (RTM) +**This article is intended for use with TFS 2015 RTM and Visual Studio Online. See [this alternate tutorial](./RC/TFS2015.md) for details on using TFS 2015 RC.** -Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. Team Foundation Services 2015 provides a new [cross-platform agent](http://go.microsoft.com/fwlink/?LinkID=533789) and [Gulp](http://go.microsoft.com/fwlink/?LinkID=533742lp) based build capabilities that enables TFS to build directly on Windows or OSX which is a critical capability Cordova based development. In addition, Gulp also enables you to easily add in a large number of "[plugins](http://go.microsoft.com/fwlink/?LinkID=533790)" to perform useful build tasks in environments that you do not control directly like Visual Studio Online. +The article is part of a is part of a [series of tutorials](./README.md) on building Visual Studio 2015 Tools for Apache Cordova projects in a Team / CI environment. -For these reasons, this tutorial will focus on the use of the cross-platform agent and Gulp rather than MSBuild as the primary build language for Cordova apps. If you still need to use the legacy XAML / MSBuild based approach, see the [TFS 2013](http://go.microsoft.com/fwlink/?LinkID=533770) tutorial for details on setup. The instructions generally still apply to TFS 2015. +##Background +Tools for Apache Cordova is designed to work with a number of different team build systems since the projects it creates are standard [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. Team Foundation Services 2015 provides a new [cross-platform agent](http://go.microsoft.com/fwlink/?LinkID=533789) and [Gulp](../tutorial-gulp) based build capabilities that enables TFS to build directly on Windows or OSX which is a critical capability Cordova based development. In addition, Gulp also enables you to easily add in a large number of "[plugins](http://go.microsoft.com/fwlink/?LinkID=533790)" to perform useful build tasks in environments that you do not control directly like Visual Studio Online. -**Troubleshooting Tip: Be aware that a bug in VS templates in VS 2015 RC included four json files that can cause issues if added to source control: plugins/android.json, plugins/remote_ios.json, plugins/windows.json, and plugins/wp8.json.** Adding these files to source control can result in a build that appears to succeed but is missing plugin native code. They should only be included if the "platforms" folder is also checked in which is not recommended. Simply remove these files from source control to resolve the issue. +For these reasons, this tutorial will focus on the use of the cross-platform agent and Gulp rather than MSBuild as the primary build language for Cordova apps. If you still need to use the legacy XAML / MSBuild based approach, see the [TFS 2013](./TFS2013.md) tutorial for details on setup. The instructions generally still apply to TFS 2015. + +**Troubleshooting Tip:** Be aware that we recommend against adding the "platforms" folder or the following json files in the "plugins" folder into source control: android.json, ios.json, remote_ios.json, windows.json, and wp8.json. See "What to Add to Source Control" in the [general team build tutorial](./README.md) for additional details. ##Initial Setup Since the build process we will describe here is not directly dependent on MSBuild or Visual Studio for Android, you have two options for installing pre-requisites on Windows: 1. Install Visual Studio 2015 and select the Tools for Apache Cordova option and let it install the pre-requisites for you -2. Manually install only the pre-requisites needed for the specific platforms you intend to build. For example, you do not need to install Visual Studio at all if you only intend to target Android. See "Installing Dependencies" in the [Building Cordova Apps in a Team / Continuous Integration Environment](http://go.microsoft.com/fwlink/?LinkID=533743) tutorial for details. +2. Manually install only the pre-requisites needed for the specific platforms you intend to build. For example, you do not need to install Visual Studio at all if you only intend to target Android. See "Installing Dependencies" in the [Building Cordova Apps in a Team / Continuous Integration Environment](./README.md) tutorial for details. -Next you will need to install the Windows build agent to build Android, Windows, or Windows Phone, and the [cross-platform build agent](http://go.microsoft.com/fwlink/?LinkID=533789) on an OSX machine if you intend to build iOS. See [TFS 2015 documentation](http://go.microsoft.com/fwlink/?LinkID=533772) for detailed instructions on configuring the agent for use with an on premise TFS 2015 instance or Visual Studio Online. +3. Next you will need to install the Windows build agent to build Android, Windows, or Windows Phone, and the [VSO cross-platform build agent](http://go.microsoft.com/fwlink/?LinkID=533789) on an OSX machine if you intend to build iOS. See [TFS 2015 documentation](http://go.microsoft.com/fwlink/?LinkID=533772) for detailed instructions on configuring the agent for use with an on premise TFS 2015 instance or Visual Studio Online. -**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) if your build servers have limited Internet connectivity or require routing traffic through a proxy. +**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](./README.md) if your build servers have limited Internet connectivity or require routing traffic through a proxy. ###Visual Studio Online -As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Online. This allows you to build without setting up a Windows build agent on premise. iOS builds are not yet available. - -When using the Hosted Agent Pool in Visual Studio Online (VSO), all pre-requisites will already be installed and Node.js will be in your path. However, Apache Ant, required for building Android with Cordova 4.3.0 and below, will not be in your path. Fortunately you can resolve this issue in a few simple steps. We will cover these details step-by-step later in this tutorial. +As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Online. This allows you to build without setting up a Windows build agent on premise. iOS builds are not yet available. When using the Hosted Agent Pool in Visual Studio Online (VSO), all pre-requisites will already be installed and Node.js will be in your path. -###Meet the Cross-Platform Build Agent +####Meet the VSO Cross-Platform Build Agent Since it is a new capability, let's pause and briefly highlight the new TFS [cross-platform build agent](http://go.microsoft.com/fwlink/?LinkID=533789) we will be using in this tutorial for building iOS on OSX since setup is different than traditional TFS build agents. The agent is a Node.js based service that uses a HTTPS connection to your TFS 2015 server to fetch work. As a result, your OSX machine only needs to have HTTP access to your TFS instance but not the other way around. This makes setup and configuration quite simple. The agent is for use with TFS 2015 and Visual Studio Online's [next generation build system](http://go.microsoft.com/fwlink/?LinkID=533772), not the legacy XAML/MSBuild based system. The pre-requisites in this case are simple: Your OSX machine needs to have Node.js and Xcode installed. Simply open the OSX Terminal app and follow the [setup instructions](http://go.microsoft.com/fwlink/?LinkID=533789). The agent will automatically register itself with TFS when you start up the agent for the first time. Because of its design, you can also easily use an **on-premise OSX machine with Visual Studio Online.** The OSX machine simply needs to have HTTP access to your VSO domain URI. You do not need a VPN connection and VSO does not need access to the OSX machine. Simply enter the your VSO project's domain URI when prompted during agent setup (Ex: "https://myvsodomain.visualstudio.com"). All other setup instructions apply directly. -##Environment Variables -You should set the following environment variables if they have not already been configured. Note that you can also set these in the "Variables" section of your build definition if you would prefer. +###Environment Variables +You should set the following environment variables if they have not already been configured on each server you have configured a build agent. Note that you can also set these in the "Variables" section of your build definition if you would prefer. | **Variable** | **Required For** | **Purpose** | **Default Location (Visual Studio 2015)** | |:-------------------|:-----------------------------------------|:-----------------------------------------|:------------------------------------------| -| **ANDROID\_HOME** | Android | Location of the Android SDK | %PROGRAMFILES(x86)%\\Android\\android-sdk | -|**JAVA\_HOME** | Android | Location of Java | %PROGRAMFILES(x86)%\\Java\\jdk1.7.0\_55 | -| **ANT\_HOME** | Android when building using Ant (not Gradle) | Location of Ant | %PROGRAMFILES(x86)%\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | +| **ANDROID\_HOME** | Android | Location of the Android SDK | C:\\Program Files (x86)\\Android\\android-sdk | +|**JAVA\_HOME** | Android | Location of Java | C:\\Program Files (x86)\\Java\\jdk1.7.0\_55 | +| **ANT\_HOME** | Android when building using Ant (not Gradle) | Location of Ant | C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\Apps\\apache-ant-1.9.3 | | **GRADLE\_USER\_HOME** | Optional | Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ | If not specified, uses %HOME%\\.gradle on Windows or ~/.gradle on OSX | | **CORDOVA\_CACHE** | Optional | Overrides the default location used by the [sample build module](http://go.microsoft.com/fwlink/?LinkID=533736) to cache installs of multiple versions of Cordova. | If not specified, uses %APPDATA%\\cordova-cache on Windows and ~/.cordova-cache on OSX | -Note that you can opt to pre-populate the GRADLE_USER_HOME and CORDOVA_CACHE locations with the versions of Cordova and its dependencies you want to use by updating the [prep-cache PowerShell script](https://github.com/Chuxel/taco-team-build/tree/master/samples/prep-cache) in the samples directory of the sample build module GitHub repo. - -###Setting Your Path +####Setting Your Path The following will also need to be in your path: - **Node.js** should already be in your path on OSX simply by the fact that you've setup the cross-platform build agent, but if it is not in your path on Windows you will want to be sure it is configured for use. The default location of Node.js on Windows is **%PROGRAMFILES(x86)%\nodejs**. - **%ANT_HOME%\bin** should be added to your path if you are using a version of Cordova < 5.0.0 or have specified the "--ant" build option -When using the Hosted Agent Pool in Visual Studio Online (VSO), all other pre-requisites will already be installed and these environment variables will be set. Node.js will be in your path but Apache Ant, required for building Android with Cordova 4.3.0 and below, will not be in your path. Fortunately you can resolve this issue in a few simple steps. We will cover these details in the "Build Definition for Windows" section below. +When using the Hosted Agent Pool in Visual Studio Online (VSO), all pre-requisites will already be installed and these environment variables will be set. ##Project Setup & Build Definitions ###Adding Gulp to Your Project -Using Gulp in a team environment is fairly straight forward as you can see in the detailed [Gulp tutorial](http://go.microsoft.com/fwlink/?LinkID=533742). However, to streamline setup, follow these steps: +Using Gulp in a team environment is fairly straight forward as you can see in the detailed [Gulp tutorial](../tutorial-gulp/gulp-ci.md). However, to streamline setup, follow these steps: 1. Take the sample "gulpfile.js" and "package.json" file from the "samples/gulp" folder [from this GitHub repo](http://go.microsoft.com/fwlink/?LinkID=533736) and place them in the root of your project 2. Check these two files into source control with your project -From here you can modify gulpfile.js and add other gulp plugins. The [Gulp tutorial](http://go.microsoft.com/fwlink/?LinkID=533742) provides additional detail on what the gulpfile does and how to wire Gulp tasks as "hooks" into Cordova build events. +From here you can modify gulpfile.js and add other gulp plugins. The [Gulp tutorial](../tutorial-gulp/gulp-ci.md) provides additional detail on what the gulpfile does and how to wire Gulp tasks as "hooks" into Cordova build events. ###Creating Your Build Definitions We'll assume for the purposes of this tutorial that we want to build our Cordova app for Android, iOS, and Windows. The Windows Cordova platform can only be built on Windows and iOS can only be built on OSX. As a result, we'll need the ability to be able to queue a build that can target one of these two operating systems. @@ -72,8 +71,6 @@ There are two ways that this can be accomplished: For the sake of this tutorial, we'll cover option 2. The sample "gulpfile.js" assumes you want to build Android, Windows, and Windows Phone on Windows and iOS on OSX. Technically you could also opt to have Android built on OSX but we will not cover that in detail in this tutorial. #### Build Definition for Windows -**Note:** *For this tutorial we have opted to use the "Command Line" build task since as of this writing the "Npm install" and "Gulp" build tasks were not available from the Windows agent. You can opt to use these build tasks instead and this tutorial will be updated as these features come on-line.* - Detailed instructions on creating build definitions in TFS 2015 can be found in [its documentation](http://go.microsoft.com/fwlink/?LinkID=533772), but here are the specific settings you will need to use to configure a build. 1. Depending on the version of TFS 2015 you are using, you may need to click on the **BUILD.PREVIEW** menu option to access the next generation TFS build system. @@ -83,35 +80,26 @@ Detailed instructions on creating build definitions in TFS 2015 can be found in 2. Create a new build definition and select "Empty" as the template. We'll start out targeting platforms that can be built on Windows so give the build definition a name that indicates that this is the case. 3. Now we will configure the build definition to install any Gulp or npm package dependencies your build may have. - 1. Under the "Build" tab, add a new build step and select **Command Line** from the **Utility** category + 1. Under the "Build" tab, add a new build step and select **npm install** from the **Package** category 2. Use the following settings: - - **Tool:** cmd - - **Arguments:** /c npm install - **Advanced =\> Working Directory**: Location of the Cordova project itself inside your solution (not the solution root). - - **Advanced =\> Fail on Standard Error**: Unchecked. ![Windows Build Definition - npm]() - We need to use cmd.exe here due as npm is a batch file rather than an executable and thus is not found by the Command Line build task. This will be resolved in future updates. - 4. Next we'll configure Gulp itself. - 1. Under the "Build" tab, add a new build step and select **Command Line** from the **Utility** category. + 1. Under the "Build" tab, add a new build step and select **Gulp** from the **Build** category. 2. Use the following settings: - - **Tool:** node - - **Arguments:** node_modules/gulp/bin/gulp.js + - **Gulp File Path**: Location gulpfile.js in your Cordova project (not the solution root). - **Advanced =\> Working Directory**: Location of the Cordova project itself inside your solution (not the solution root). - - **Advanced =\> Fail on Standard Error**: Unchecked. ![Windows Build Definition - gulp]() -5. Next we need to ensure that this particular build runs on Windows rather than OSX. Under the "General" tab, verify a demand that "Cmd" exists is present. If not, add one. +5. Next we need to ensure that this particular build runs on Windows rather than OSX. Under the "General" tab, add a demand that "Cmd" exists. ![Windows Build Definition - Demand]() -6. As an optional step, you can configure your build to upload the resulting build artifacts to your TFS or VSO instance for easy access. The sample gulpfile.js script places the resulting output in the "bin" folder to make configuration simple. **TFS 2015 RC on-premise installs vary here slightly.** - - For **Visual Studio Online and post-RC TFS 2015** releases: +6. As an optional step, you can configure your build to upload the resulting build artifacts to your TFS or VSO instance for easy access. The sample gulpfile.js script places the resulting output in the "bin" folder to make configuration simple. 1. Under the "Build" tab, add a new build step and select **Publish Artifact** from the **Build** category. 2. Use the following settings: @@ -122,63 +110,22 @@ Detailed instructions on creating build definitions in TFS 2015 can be found in ![Windows Build Definition - Drop location]() - For **TFS 2015 RC** on-premise installs, go to the "Options" tab and enter the following information: - - **Copy to Staging Folder:** Checked - - **Copy to Staging Folder =\> Search Pattern:** \*/bin - - **Create Build Drop:** Checked - - **Create Build Drop =\> Drop location:** Server - - Finally, click the "Queue build..." button to validate your setup. You'll see a real-time console view of your build progressing so you can quickly fine tune your definition. That's it for Windows! You're now able to build using the Android, Windows, and Windows Phone 8 (WP8) Cordova platforms. -####Using the Hosted Agent Pool in Visual Studio Online -As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Online. This allows you to build without setting up a Windows build agent on-premise. iOS builds are not yet available. - -When using Hosted build agents in Visual Studio Online (VSO), Node.js will already be in your path but Ant will not. Fortunately you can resolve this issue in a few simple steps as all of the other required environment variables will be set for you. - -1. Create a batch file called "setenv.cmd" and place it in a solution folder with the following contents: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - @SET PATH=%PATH%;%ANT_HOME%\bin - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - -2. Check this into source control with the rest of your project. - - ![setenv.cmd in solution]() - -3. Next, under the "Build" tab in your Windows Build Definition, add a new build step, select **Batch Script** from the **Utility** category, and enter the following settings: - - - **Path:** setenv.cmd - - **Modify Environment:** Checked. - -4. Make this the first build step in your build definition. - - ![Windows Build Definition - setenv.cmd]() - -You are now ready to go in VSO! - #### Build Definition for OSX Now let's create a version of this same build definition to target iOS that will run on a configured cross-platform agent on OSX. 1. Right click on the Windows build definition and select "Clone." Once you save you should give this definition a name that indicates it's the OSX build. -2. Next we need to update our call to "npm install" to be OSX friendly. - 1. Select the existing "Run cmd" Command Line build step - 2. Update the following settings: - - **Tool:** npm - - **Arguments:** install - - ![OSX Build Definition - Update npm install]() - -3. Now we need to add a demand that will route builds to OSX machines rather than Windows. Under the "General" tab, remove the "Cmd" demand if present and add a demand that "xcode" exists. +2. Now we need to add a demand that will route builds to OSX machines rather than Windows. Under the "General" tab, remove the "Cmd" demand and add a demand that "xcode" exists. ![OSX Build Definition - Demand]() You are now all set! You can configure either of these build definitions further as you see fit including having them automatically fire off on check-in or adding other validations. -**Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](http://go.microsoft.com/fwlink/?LinkID=533743) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. +**Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](./README.md) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. ## More Information * [Learn about other Team Build / CI options](README.md) @@ -186,6 +133,6 @@ You are now all set! You can configure either of these build definitions further * [Download samples from our Cordova Samples repository](http://github.com/Microsoft/cordova-samples) * [Follow us on Twitter](https://twitter.com/VSCordovaTools) * [Visit our site http://aka.ms/cordova](http://aka.ms/cordova) -* [Read MSDN docs on using Visual Studo Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) +* [Read MSDN docs on using Visual Studio Tools for Apache Cordova](http://go.microsoft.com/fwlink/?LinkID=533794) * [Ask for help on StackOverflow](http://stackoverflow.com/questions/tagged/visual-studio-cordova) -* [Email us your questions](mailto:/vscordovatools@microsoft.com) \ No newline at end of file +* [Email us your questions](mailto:/vscordovatools@microsoft.com) diff --git a/tutorial-team-build/media/tfs2015-1.png b/tutorial-team-build/media/tfs2015-1.png index 0fcecf00..e603d894 100644 Binary files a/tutorial-team-build/media/tfs2015-1.png and b/tutorial-team-build/media/tfs2015-1.png differ diff --git a/tutorial-team-build/media/tfs2015-2.png b/tutorial-team-build/media/tfs2015-2.png index dfcfe5cc..ef8d209d 100644 Binary files a/tutorial-team-build/media/tfs2015-2.png and b/tutorial-team-build/media/tfs2015-2.png differ diff --git a/tutorial-team-build/media/tfs2015-3.png b/tutorial-team-build/media/tfs2015-3.png index e4b89154..00486638 100644 Binary files a/tutorial-team-build/media/tfs2015-3.png and b/tutorial-team-build/media/tfs2015-3.png differ diff --git a/tutorial-team-build/media/tfs2015-4.png b/tutorial-team-build/media/tfs2015-4.png index 7483cbbc..425e6fdf 100644 Binary files a/tutorial-team-build/media/tfs2015-4.png and b/tutorial-team-build/media/tfs2015-4.png differ