diff --git a/Readme.md b/Readme.md index 48a10a5a..734105ba 100644 --- a/Readme.md +++ b/Readme.md @@ -1,14 +1,26 @@ # 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. [Building Cordova Apps in a Team / Continuous Integration Environment](./tutorial-team-build) + 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 with Gulp](./tutorial-gulp/gulp-typescript.md) +1. [Building Cordova Apps in a Team / Continuous Integration (CI) Environment](./tutorial-team-build) + 1. [Getting Started with Cordova & TFS 2015 or Visual Studio Online](./tutorial-team-build/TFS2015.md) + 1. [Getting Started with Cordova & TFS 2013](./tutorial-team-build/TFS2013.md) + 1. [Getting Started with Cordova & Jenkins CI](./tutorial-team-build/Jenkins.md) 1. [Package & Publish your Cordova Applications](./tutorial-package-publish) 1. [Using TypeScript with your Cordova projects](./getting-started/tutorial-typescript.md) +1. [Build and Simulate iOS in the Cloud](http://go.microsoft.com/fwlink/?LinkID=618476) (MSDN) +1. [Build a Cordova app for iOS using Parallels](http://go.microsoft.com/fwlink/?LinkID=618477) (MSDN) +1. [Run the Android Emulator on OSX when using Windows in Parallels](http://go.microsoft.com/fwlink/?LinkID=618478) (MSDN) +1. [Convert a Cordova Project to a PhoneGap Project](http://go.microsoft.com/fwlink/?LinkID=618479) (MSDN) ## Tips & Workarounds @@ -33,7 +45,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) @@ -42,7 +53,7 @@ Help us improve out docuementaiton by sending us a pull-request or opening a [Gi * [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) diff --git a/cordova-docs-private b/cordova-docs-private new file mode 160000 index 00000000..faf2438d --- /dev/null +++ b/cordova-docs-private @@ -0,0 +1 @@ +Subproject commit faf2438d8c71c55bf5d683938bac73e9f0d55827 diff --git a/known-issues/known-issues-android.md b/known-issues/known-issues-android.md index 95d3e05f..8a6adb4e 100644 --- a/known-issues/known-issues-android.md +++ b/known-issues/known-issues-android.md @@ -46,6 +46,6 @@ If this does not resolve the issue, you can upgrade to a 64-bit version of the J * [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-cordova5.md b/known-issues/known-issues-cordova5.md index 80121ca2..d0400130 100644 --- a/known-issues/known-issues-cordova5.md +++ b/known-issues/known-issues-cordova5.md @@ -5,6 +5,13 @@ This article covers [known issues](../Readme.md#knownissues) related to Visual S In general we recommend **using Cordova 5.1.1 or above** instead of 5.0.0 as there are a number of issues including a security hole with Cordova 5.0.0. ##Apache Cordova 5.x.x General Issues +---------- +**Old versions of Cordova plugins due to Cordova plugin ID changes:** A significant change occurred with Cordova 5.0.0+ that also altered the IDs of many core Cordova plugins. The Visual Studio 2015 config.xml designer uses the old IDs (ex: org.apache.cordova.camera not cordova-plugin-camera) because Cordova 4.3.1 and below cannot access plugins using these new IDs and the default template uses 4.3.1. + +To install updated plugins, follow [this proceedure to install a npm sourced plugin](../tips-and-workarounds/general/README.md#plugin-npm). + +*Note that these updated plugins were tested on Cordova 5.0.0 or later and therefore may or may not work on earlier versions of Cordova.* We advise against updating your plugins when using older versions of Cordova unless you are attempting to solve a specific problem. + ---------- **Cannot access any network resources from Android app:** The Android platform contained within Cordova 5.0.0+ does not have a "whitelist" plugin installed by default and therefore blocks network access by default. There are now two whitelist plugins that can be installed: @@ -22,19 +29,17 @@ line or by adding this XML element to config.xml (see [this article for more det ~~~~~~~~~~~~~~~~~ ---------- -**Ripple throws error when starting up Cordova:** Ripple does not function properly in Cordova 5.0.0 due to a newly introduced validation check. This problem was fixed in Cordova 5.1.1. +**Error when adding plugin using Git URI with Cordova 5.1.1:** Cordova 5.1.1 has a bug that can cause plugins installed from a Git repo to fail with the error **Error: EXDEV, cross-device link not permitted** if the project is on a different drive than your temp folder. ----------- -**Missing Android SDK 22:** The Android platform in Cordova 5.0.0 requires Android SDK API Level 22 which is not pre-installed by Visual Studio. Install the SDK using the Android SDK manager. +See [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-xml) for information on adding plugins not in the config designer from either the Cordova plugin repository or npm. If you must add a Git version of the plugin, either move your project to the same drive as your temp folder when installing or you can instead download a copy, unzip it, and add the plugin from the filesystem. -##Apache Cordova 5.x.x and Visual Studio 2015 RC ---------- -**Old versions of Cordova plugins due to Cordova plugin ID changes:** A significant change occurred with Cordova 5.0.0+ that also altered the IDs of many core Cordova plugins. The Visual Studio 2015 RC config.xml designer uses the old IDs (ex: org.apache.cordova.camera not cordova-plugin-camera) because Cordova 4.3.1 and below cannot access plugins using these new IDs and the default template uses 4.3.0. +**Missing Android SDK 22:** The Android platform in Cordova 5.0.0 requires Android SDK API Level 22 which may not be installed on your system. Install the SDK using the Android SDK manager. -To install updated plugins, follow [this proceedure to install a npm sourced plugin](../tips-and-workarounds/general/README.md#plugin-npm). +---------- +**Ripple throws error when starting up Cordova 5.0.0:** Ripple does not function properly in Cordova 5.0.0 due to a newly introduced validation check. This problem was fixed in Cordova 5.1.1. -*Note that these updated plugins were tested on Cordova 5.0.0 or later and therefore may or may not work on earlier versions of Cordova.* We advise against updating your plugins when using older versions of Cordova unless you are attempting to solve a specific problem. - +##Apache Cordova 5.x.x and Visual Studio 2015 RC ---------- **Visual Studio 2015 RC uses Ant to build Android with Cordova 5.x.x:** Visual Studio 2015 RC uses Ant to build Android while the command line has switched to Gradle by default in version 5.0.0 of the CLI. When switching between Visual Studio and the command line with the version of Android in Cordova 5.0.0, you may want to specify that the platform should be built with Ant instead if you are running into unexpected issues. @@ -74,7 +79,7 @@ Finally, if you are still build errors, you may want to opt to remove and re-add * [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-debugger.md b/known-issues/known-issues-debugger.md index 0138fc3a..e42ee1ba 100644 --- a/known-issues/known-issues-debugger.md +++ b/known-issues/known-issues-debugger.md @@ -58,6 +58,6 @@ This article covers [known issues and limitations](../Readme.md#knownissues) rel * [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-general.md b/known-issues/known-issues-general.md index c04ee2c4..680ef6e2 100644 --- a/known-issues/known-issues-general.md +++ b/known-issues/known-issues-general.md @@ -11,51 +11,74 @@ 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. -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. +Remove these files from source control if you are not checking in the "platforms" folder (recommended). 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. +---------- +**Old versions of Cordova plugins due to Cordova plugin ID changes:** A significant change occurred with Cordova 5.0.0+ that also altered the IDs of many core Cordova plugins. The Visual Studio 2015 config.xml designer uses the old IDs (ex: org.apache.cordova.camera not cordova-plugin-camera) because Cordova 4.3.1 and below cannot access plugins using these new IDs and the default template uses 4.3.1. + +To install updated plugins, follow [this proceedure to install a npm sourced plugin](../tips-and-workarounds/general/README.md#plugin-npm). + +*Note that these updated plugins were tested on Cordova 5.0.0 or later and therefore may or may not work on earlier versions of Cordova.* We advise against updating your plugins when using older versions of Cordova unless you are attempting to solve a specific problem. + ---------- **Git sourced plugins will not install:** Git sourced plugins will not install properly if you have not installed the [Git command line tools](http://www.git-scm.com/downloads) and have them in your system path. During installation of the Git tools, select the "Use Git from the Windows Command Prompt" option or add the "bin" folder from the Git install location to your path and restart VS. (Usually "C:\Program Files (x86)\Git\bin"). +---------- +**Git sourced plugins will not install with Cordova 5.1.1 only:** Cordova 5.1.1 has a bug that can cause plugins installed from a Git repo to fail with the error "Error: EXDEV, cross-device link not permitted" if the project is on a different drive than your temp folder. + +See [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-xml) for information on adding plugins not in the config designer from either the Cordova plugin repository or npm. If you must add a Git version of the plugin, either move your project to the same drive as your temp folder when installing or you can instead download a copy, unzip it, and add the plugin from the filesystem. + ---------- **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 0.10.29](http://nodejs.org/dist/v0.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. +---------- +**Errors from npm related to permission problems:** If you installed Visual Studio or Node.js running as an administrator, you can run into problems where npm attempts to install npm packages under "C:\Program Files (x86)\node.js". You will typically see errors in the Output Window similar to this one: "npm ERR! error rolling back error : EPERM, unlink 'C:\Program Files (x86)\nodejs\vs-tac-cli.cmd'". To resolve this issue you can re-install Node.js or reconfigured npm using these commands from the command prompt and restarting Visual Studio: + +~~~~~~~~~~~~~~~~~~~~~~~ +npm config set prefix %APPDATA%\npm +npm config set cache %APPDATA%\npm-cache +~~~~~~~~~~~~~~~~~~~~~~~ + +---------- +**Frequent ECONRESET errors from npm when using VPN or proxy:** Node.js can experience intermittent issues connecting to the npm repository via SSL with certain versions of Node.js and npm when connected to VPN or when a proxy is configured. You can resolve this issue by configuring npm to connect to the registry using straight HTTP instead using this command from the command prompt: + +~~~~~~~~~~~~~~~~~~~~~~~ +npm config set registry http://registry.npmjs.org +~~~~~~~~~~~~~~~~~~~~~~~ + ---------- **FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - process out of memory:** This error can occur if you are using a recent version of Node.js (ex: 0.12.4) due to a [known npm issue](https://github.com/npm/npm/issues/8019). The simplest solution is to downgrade to [Node.js 0.10.29](http://nodejs.org/dist/v0.10.29/). ---------- -**Missing Intellisense:** -- No IntelliSense is provided for Cordova plugins in JavaScript files in Apache Cordova projects. As a workaround, developers can enable IntelliSense for Cordova plugins by explicitly adding “/// <reference group="Implicit (Multi-Device Apps)” />” to the JavaScript file. -- No IntelliSense is provided within JavaScript files for other JavaScript files included via a script tag in a referring HTML page. As a workaround, developers can enable IntelliSense for other referenced JavaScript files by explicitly adding “/// <reference path=”referencedFile.js” />” to the JavaScript file. +**Globally installed npm packages not available from command line:** If you have installed Visual Studio or Node.js with a different user than you are logging into Windows, you may need to update your path to access globally installed (npm install -g) npm packages from the command line. Specifically, ensure **%APPDATA%\npm** is either in your user or system PATH. By default the installation of Node.js will set the PATH as a user environment variable rather than system which is why you can encounter this behavior. ---------- **TypeScript code incorrectly identified as external, cannot read user configuration file:** When using TypeScript, there are known issues that will incorrectly identify project items as external code or will fail to read in a user configuration file. To avoid unexpected behavior when working with a Cordova TypeScript project, turn off Just My Code (Options > Debugger > General > uncheck Enable Just My Code). ---------- -**Globally installed npm packages not available from command line:** If you have installed Visual Studio or Node.js with a different user than you are logging into Windows, you may need to update your path to access globally installed (npm install -g) npm packages from the command line. Specifically, ensure **%APPDATA%\npm** is either in your user or system PATH. By default the installation of Node.js will set the PATH as a user environment variable rather than system which is why you can encounter this behavior. +**TypeScript breakpoints stop at the wrong location when using Ripple:** This is a known issue that is being activley worked. This problem does not occur when using devices or emulators. + +---------- +**Missing Intellisense:** +- No IntelliSense is provided for Cordova plugins in JavaScript files in Apache Cordova projects. As a workaround, developers can enable IntelliSense for Cordova plugins by explicitly adding “/// <reference group="Implicit (Multi-Device Apps)” />” to the JavaScript file. +- No IntelliSense is provided within JavaScript files for other JavaScript files included via a script tag in a referring HTML page. As a workaround, developers can enable IntelliSense for other referenced JavaScript files by explicitly adding “/// <reference path=”referencedFile.js” />” to the JavaScript file. ---------- **"res" folder contents cannot be referenced from web content:** By design, the contents of the “res” folder cannot be accessed by web content as they are copied into platform-specific native project locations. @@ -69,6 +92,6 @@ Remove these files from source control if you are not checking in the "platforms * [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-ios.md b/known-issues/known-issues-ios.md index 7a9cee6f..34745d13 100644 --- a/known-issues/known-issues-ios.md +++ b/known-issues/known-issues-ios.md @@ -2,7 +2,19 @@ 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. ---------- -**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. +**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 / remotbuild agent:** 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. sudo npm cache clear sudo chown -R `whoami` ~/.npm @@ -11,11 +23,14 @@ This article covers [known issues](../Readme.md#knownissues) related to Visual S **Slow first build:** The first build using the remote iOS build agent for a given version of Cordova will be slower than subsequent builds as the remote agent must first dynamically acquire Cordova on OSX. ---------- -**Adding "plugins/remote_ios.json" to source control can result in non-functional plugins:** Due to a bug in the VS 2015 RC, four json files that can cause issues if added to source control are missing from the default source code exclusion list including "plugins/remote_ios.json." If you encounter a build that has non-functional Cordova APIs after fetching the project from source control, you should ensure that "plugins/android.json", "plugins/windows.json", "plugins/remote_ios.json", "plugins/wp8.json" are removed from source control and retry. See this [Tips and Workarounds](../tips-and-workarounds/general/README.md#missingexclude) for additional details. +**Adding "plugins/remote_ios.json" to source control can result in non-functional plugins:** Five json files that can cause issues if added to source control are missing from the default source code exclusion list including "plugins/remote_ios.json." If you encounter a build that has non-functional Cordova APIs after fetching the project from source control, you should ensure that "plugins/android.json", "plugins/ios.json", "plugins/windows.json", "plugins/remote_ios.json", "plugins/wp8.json" are removed from source control and retry. See this [Tips and Workarounds](../tips-and-workarounds/general/README.md#missingexclude) for additional details. ---------- **Deploying to iOS 8.3 device fails from OSX Mavericks or below:** If deploying to iOS 8.3 device fails because vs-mda-remote cannot find DeveloperDiskImage.dmg, ensure you are running OSX Yosemite and Xcode 6.3. Xcode 6.3 is required to deploy to an 8.3 device and only runs on Yosemite. +---------- +**Incremental builds not faster than initial build when using VS 2015 RC or RTM:** Unfortunately this is a known issue with the iOS incremental build feature. We are actively working on a fix that will be resolved in a point release update. + ---------- **Unresponsive iOS device during app deployment:** In some circumstances, when deploying to iOS devices, they phone may enter an unresponsive state where apps may stops responding. Avoid deploying an app when the same app is still running. As a workaround, if you enter this state, soft reset your iOS device. @@ -38,6 +53,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..26a90971 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. @@ -36,6 +28,6 @@ This article covers general [known issues](../Readme.md#knownissues) related to * [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-vs2013.md b/known-issues/known-issues-vs2013.md index a1a98e8c..d512dc78 100644 --- a/known-issues/known-issues-vs2013.md +++ b/known-issues/known-issues-vs2013.md @@ -49,7 +49,7 @@ Alternatively you can install version 0.2.7 instead by using the following comma * [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-vs2015.md b/known-issues/known-issues-vs2015.md index c52ea818..5ba2c2f2 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. @@ -151,6 +164,6 @@ Remove these files from source control if you are not checking in the "platforms * [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-windows.md b/known-issues/known-issues-windows.md index 94495f9a..65ddedaa 100644 --- a/known-issues/known-issues-windows.md +++ b/known-issues/known-issues-windows.md @@ -1,6 +1,25 @@ #**Known Issues - Windows** This article covers [known issues](../Readme.md#knownissues) related to Visual Studio Tools for Apache Cordova 2015 when building or deploying to a Windows 8.0, 8.1, Windows Phone 8.1 or any Windows 10 device or emulator. +---------- +**Windows 10 version options and emulators do not appear after installing Windows 10 Tools in Visual Studio 2015 RC or RTM and selecting Cordova 5.1.1 or later:** Due to a bug, you will need to build once for Windows or Windows Phone 8.1 using Cordova 5.1.1 or later for these options to be available. Simply build once and then select Windows 10. We are actively working on a fix. + +---------- +**Version specified in "Windows" section of config designer or during "Create App Packages" wizard not used with Cordova 5.1.1:** Due to a Cordova issue, you will need to update the version number in the "Common" section of the config designer to cause the version number to update properly. We are working with the Cordova community on a fix. + +---------- +**"appxbundle" not generated by "Create App Packages" wizard for Windows or Windows Phone in Visual Studio 2015 RC or earlier:** This issue has been resolved in the RTM version of Visual Studio 2015 by selecting "Always" for the "Generate app bundle" option. For earlier versions you can take advantage of the [MakeAppx command line utiltiy](http://go.microsoft.com/fwlink/?linkid=618904) as follows: + +1. After running the "Create App Packages" wizard, copy your app's ".appx" files from the appropriate AppPackages sub-folders in your project (ignoring the WinJS appx file if present) into a new folder + +2. Open the Visual Studio Developer Command Prompt and go to the folder you placed the appx files + +3. Execute the following command replacing <name> with a name of your choice: + + ~~~~~~~~~~~~~~~~~~~~~~~~ + MakeAppx bundle /d . /p .appxbundle + ~~~~~~~~~~~~~~~~~~~~~~~~ + ---------- **Expired Temporary Certificate:** Due to a coding error, the Cordova Windows platform in Cordova **previous to 4.1.2** has a temporary key in it that expired on 11/11/2014. To work around this issue, update your Cordova version or [download this file](https://git-wip-us.apache.org/repos/asf?p=cordova-windows.git;a=blob;f=template/CordovaApp_TemporaryKey.pfx;h=90d7ab2208ce170d176a2ac8a60eb22fbc1cbf7a;hb=refs/tags/3.7.1) and place it in your Tools for Apache Cordova project in following location: @@ -10,7 +29,7 @@ This article covers [known issues](../Readme.md#knownissues) related to Visual S You can read more about the issue on the [MS Open Tech blog](http://go.microsoft.com/fwlink/?linkid=518810). ---------- -**Incorrect Application Id & Publisher Name after creating app packages in VS 2013:** While trying to associate a Cordova app with Windows store using Visual Studio 13 and CTP3.1, the AppxManifest.xml doesn’t get updated with the appropriate Application Id & publisher name. This has been fixed as of VS 2015 RC. To fix this issue in VS 2013, install the workaround plugin from https://github.com/Chuxel/taco-tricks/tree/master/plugin-windows-package-fix and try building your application again. +**Incorrect Application Id & Publisher Name after creating app packages in VS 2013:** While trying to associate a Cordova app with Windows store using Visual Studio 2013 and CTP3.1, the AppxManifest.xml doesn’t get updated with the appropriate Application Id & publisher name. This has been fixed as of VS 2015 RC. To fix this issue in VS 2013, install the workaround plugin from https://github.com/Chuxel/taco-tricks/tree/master/plugin-windows-package-fix and try building your application again. ---------- ## More Information @@ -18,6 +37,6 @@ You can read more about the issue on the [MS Open Tech blog](http://go.microsoft * [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/tips-and-workarounds/README.md b/tips-and-workarounds/README.md index b06a3b32..053bec44 100644 --- a/tips-and-workarounds/README.md +++ b/tips-and-workarounds/README.md @@ -18,6 +18,6 @@ Help us improve out docuementaiton by sending us a pull-request or opening a [Gi * [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/tips-and-workarounds/ios/README.md b/tips-and-workarounds/ios/README.md index 6c895e99..4cb79408 100644 --- a/tips-and-workarounds/ios/README.md +++ b/tips-and-workarounds/ios/README.md @@ -71,7 +71,7 @@ To resolve this problem you have two options: * [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) diff --git a/tutorial-cordova-5/README.md b/tutorial-cordova-5/README.md new file mode 100644 index 00000000..5b29e05a --- /dev/null +++ b/tutorial-cordova-5/README.md @@ -0,0 +1,281 @@ +#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 RTM has been tested with both Cordova 4.3.1 and Cordova 5.1.1. As the major version number increase implies, [Apache Cordova 5](http://http://go.microsoft.com/fwlink/?LinkID=617659) 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](http://http://go.microsoft.com/fwlink/?LinkID=617658). As a result, we strongly recommend 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. However, you can also update projects to 5.1.1 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://go.microsoft.com/fwlink/?LinkID=533773) (and an underlying core library called [cordova-lib](http://go.microsoft.com/fwlink/?LinkID=617661)). [Documentation](http://go.microsoft.com/fwlink/?LinkID=617659) 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](http://go.microsoft.com/fwlink/?LinkID=617660). + +- **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](http://go.microsoft.com/fwlink/?LinkID=617662) 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 are pinned in **Cordova CLI 5.1.1** (or [see here](http://go.microsoft.com/fwlink/?LinkID=617667) 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 recommend 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)](http://go.microsoft.com/fwlink/?LinkID=617668) is the recommended base security plugin to use for managing network security access. Historically there was one **access** element in config.xml used to control all access to network resources. + +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://go.microsoft.com/fwlink/?LinkID=617669) which has led to a syntax that strayed away from the original [W3C Widget spec](http://go.microsoft.com/fwlink/?LinkID=617670) 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 **allow-navigation** element has been added that then enables you to specify where the app can navigate instead. Finally, a new **allow-intent** element has been introduced specifically designed to control Android intents. + +Projects created using the Tools for Apache Cordova or Cordova CLI itself contain fairly restrictive default 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 element 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://go.microsoft.com/fwlink/?LinkID=617671) + +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. Cordova 3.x and 4.x simply do not support fetching plugins from npm. 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://go.microsoft.com/fwlink/?LinkID=617672) in version 0.3.6 of the plugin to [cordova-plugin-camera](http://go.microsoft.com/fwlink/?LinkID=617673) 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](http://go.microsoft.com/fwlink/?LinkID=617674). + +Visual Studio 2015 currently only uses the old IDs since these are required for the default version of Cordova 4.3.1. We will resolve this problem in a subseqent update by dynamically updating the list based on the Cordova version selected. However, you can add npm versions of plugins to your project fairly easily by adding an XML element to config.xml as follows: + +~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~ + +See [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-npm) for additional details on add npm versions of plugins to your project. + +###Cordova Plugin Registry +As of 7/14/2015, plugins.cordova.io now has two registry sections: + +- For the time being, the landing page of [plugins.cordova.io](http://go.microsoft.com/fwlink/?LinkID=618599) **does not contain npm sourced plugins** these plugins only work with Cordova 5.0.0+. +- However, npm sourced plugins can be found on the **new [npm registry section of plugins.cordova.io](http://go.microsoft.com/fwlink/?LinkID=618600)** or you can search npm iself using the [ecosystem:cordova](http://go.microsoft.com/fwlink/?LinkID=617675) tag. + + ![Npm Plugin Registry]() + +Both sets of plugins can be used with Cordova 5.0.0+ so in the short term you may need to 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 still in a transition period. + + +###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. + +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://go.microsoft.com/fwlink/?LinkID=617676) 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](http://go.microsoft.com/fwlink/?LinkID=617677) we will cover a bit later 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). However, 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 +Simply updating to Cordova 5.0.0+ will automatically cause Gradle to be used from that point forward. Because of the differences mentioned above you should take the following steps to adapt your project: + +1. 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. + +2. 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 add the latest npm based version using [the XML bassed approach](../tips-and-workarounds/general/README.md#plugin-npm) described earlier. If you cannot determine which plugin is causing the issue, you can opt to proactively upgrade all of them. + +3. 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. + + +##Pluggable WebViews and the Crosswalk WebView for Android +An exciting new development in the Cordova Android platform in Cordova 5 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 is 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, 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](http://go.microsoft.com/fwlink/?LinkID=617678) is a project that is designed to allow developers to 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](http://go.microsoft.com/fwlink/?LinkID=617679) 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 element 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](http://go.microsoft.com/fwlink/?LinkID=617680) 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 improvements to Apache Cordova users. + +In particular: + +- Elimination of the existing dynamic content restrictions in Windows 8.0 and 8.1. +- Cordova plugin support for external hosted content through the use of the same <allow-navigation> element used by Android and iOS. +- Support for the powerful Content Security Policy (CSP) that is also now recommended for use with the Android and iOS Cordova platforms. See [this article for more details](./cordova-5-security.md). +- Apps can now run in two different security modes: + - Remote mode: The default, flexible security mode that only has a hand full of store submission restrictions + - 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. First, install the [Windows 10 Tools for Visual Studio](http://go.microsoft.com/fwlink/?LinkID=617471) if you have not already. + +2. Update your project to Cordova 5.1.1 as described above if you have not already + +3. Now, **build once for Windows** (we're working to eliminate this step in future) + +4. Next, open the config.xml designer by double clicking on config.xml + +5. Click on the "Windows" tab + +6. 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..2fa4ebb0 --- /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 [Apache Cordova 5](http://go.microsoft.com/fwlink/?LinkID=617659) 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)](http://go.microsoft.com/fwlink/?LinkID=617668) is the recommended base security plugin to use for managing network security access. Historically there was one **access** element in config.xml 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://go.microsoft.com/fwlink/?LinkID=617669) which has led to a syntax that strayed away from the original [W3C Widget spec](http://go.microsoft.com/fwlink/?LinkID=617670) 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 **allow-navigation** element has been added that then enables you to specify where the app can navigate instead. Finally, a new **allow-intent** element has been introduced specifically designed to control Android intents. + +The base [Cordova CLI](http://aka.ms/cordova-cli) template (via the cordova create command) 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](http://go.microsoft.com/fwlink/?LinkID=617694)** 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 allow-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 exactly like iOS and Android. The access element is also supported but behaves a bit differently in that navigation is allowed to these URIs but Cordova and plugin APIs are disabled thereby reducing risk. In Windows 10, XHR, CSS, and image access rules are intended to be controlled by a Content Security Policy (CSP) via connect-src 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 not support navigating to external URIs outside of 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 and does not support allow-navigation or allow-intent. + +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](http://go.microsoft.com/fwlink/?LinkID=617695) 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 +A new feature in Cordova 5.0.0+ allows you specify plugins in config.xml that are then automatically added at build time. 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.1 does not have this feature). Near term most VS documentation will recommend the use of "vs:plugin" instead. + +Cordova 5.0.0+: + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + +VS syntax (works with any Cordova version): + +~~~~~~~~~~~~~~~~~~~~~~~ + +~~~~~~~~~~~~~~~~~~~~~~~ + + +##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://go.microsoft.com/fwlink/?LinkID=617696) 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 +CSP support 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 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 CLI project 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://go.microsoft.com/fwlink/?LinkID=617697), 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 in the **Cordova CLI template (cordova create command) disables inline but allows 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 CLI 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 CLI template applies to style-src which enables inline CSS declarations not JavaScript. + +1. The default CSP policy in the Cordova CLI 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 sources. + + - You can loosen this restriction by listing other trusted domains. In fact, the default Cordova CLI 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: + + 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 allow-intent or allow-navigation elements as needed: + + 1. Right-click on config.xml and select "View Code" if you have not already + + 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, we strongly recommend taking the Cordova CLI 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/cordova-5-9.png b/tutorial-cordova-5/media/cordova-5-9.png new file mode 100644 index 00000000..bc70e433 Binary files /dev/null and b/tutorial-cordova-5/media/cordova-5-9.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/README.md b/tutorial-gulp/README.md index 95bf3e72..d9d3c914 100644 --- a/tutorial-gulp/README.md +++ b/tutorial-gulp/README.md @@ -12,6 +12,6 @@ * [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-gulp/gulp-ci.md b/tutorial-gulp/gulp-ci.md index 7050359b..b1775cd5 100644 --- a/tutorial-gulp/gulp-ci.md +++ b/tutorial-gulp/gulp-ci.md @@ -46,10 +46,14 @@ gulp The "npm install -g gulp" command will install the Gulp command line interface and add it to your path while the "npm install" command will install the "devDepenencies" listed above in a node_modules folder for use in your gulp script. These two commands are only required if you need to install new dependencies that were added to package.json by hand or are installing Gulp globally for the first time. -You can also quickly execute Gulp tasks from the Task Runner Explorer right from Visual Studio. Simply go to View \> Other Windows \> Task Runner Explorer to bring it up for use. Even better, any dependencies you add to package.json will automatically be installed locally for use when you save the file. +You can also quickly execute Gulp tasks from the Task Runner Explorer right from Visual Studio. Simply go to View \> Other Windows \> Task Runner Explorer to bring it up for use. ![View Menu]() +Even better, all you need to do to install dependencies you add to package.json is to right-click on the Dependencies node in the Solution Explorer and select "Restore Packages". + +![Restore Packages]() + Note that the **"cordova" and "cordova-lib" npm package version numbers do not match for CLI 3.6.3 or earlier**. If you need to target these older Cordova versions, you can instead reference the "cordova" npm package in your package.json file and edit the require statement in the above Gulp script as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -104,7 +108,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. @@ -187,6 +191,6 @@ npm install --save-dev gulp-uglify * [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) diff --git a/tutorial-gulp/gulp-task-runner-explorer.md b/tutorial-gulp/gulp-task-runner-explorer.md index 57a6892d..44cad24d 100644 --- a/tutorial-gulp/gulp-task-runner-explorer.md +++ b/tutorial-gulp/gulp-task-runner-explorer.md @@ -3,9 +3,7 @@ [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 the [Apache Cordova Command Line interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) are Node.js based which makes the two highly complementary technologies. -You may find it useful to fire off a Gulp task every time you do a Cordova build particularly when using Gulp to minify your JavaScript code or compile languages like [TypeScript](http://go.microsoft.com/fwlink/?LinkID=533748), [LESS](http://go.microsoft.com/fwlink/?LinkID=533791), or [SASS](http://go.microsoft.com/fwlink/?LinkID=533792). Fortunately, this is quite easy to do via a "before prepare" hook. A Cordova [hook](http://go.microsoft.com/fwlink/?LinkID=533744) enables you to fire off shell or Node.js scripts at any number of different points in the Cordova build lifecycle. In fact, hooks can cover everything from platform or plugin add to compilation and emulation. - -The "prepare" step in Cordova is in charge of transforming all of your content in www, plugins, and merges and preparing a native project for a given platform for compilation. The "build" command in Cordova does a "prepare" before moving on to compilation and as a result it is useful to use the "before prepare" hook to wire in pre-build tasks. +You may find it useful to fire off a Gulp task right from Visual Studio every time you do a Cordova build particularly when using a Gulp to minify your JavaScript code or compile languages like [TypeScript](http://go.microsoft.com/fwlink/?LinkID=533748), [LESS](http://go.microsoft.com/fwlink/?LinkID=533791), or [SASS](http://go.microsoft.com/fwlink/?LinkID=533792). Fortunately, this is quite easy to do thanks to the "Task Runner Explorer." ##Using the Visual Studio Task Runner Explorer The Visual Studio Task Runner Explorer provides a convenient way to run Gulp tasks right from Visual Studio. First let's install Gulp globally so it's convenient to use from the command line as well as Visual studio. Type the following from a command prompt: @@ -14,7 +12,7 @@ The Visual Studio Task Runner Explorer provides a convenient way to run Gulp tas npm install -g gulp ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, create a [package.json](http://go.microsoft.com/fwlink/?LinkID=533781) file in your project. This will be the location you will use to reference Gulp or any [Gulp plugins](http://go.microsoft.com/fwlink/?LinkID=533790) you want to use. +Next, create a [package.json](http://go.microsoft.com/fwlink/?LinkID=533781) file in your project (if one is not already present). This will be the location you will use to reference Gulp or any [Gulp plugins](http://go.microsoft.com/fwlink/?LinkID=533790) you want to use. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ { @@ -24,19 +22,25 @@ Next, create a [package.json](http://go.microsoft.com/fwlink/?LinkID=533781) fil } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Visual Studio will **automatically** execute the following command for you on save if you're editing package.json in VS, but if you're updating package.json outside of VS, type the following to install whatever you have added to package.json: +You can install these dependencies at any time in Visual Studio by right-clicking on the Dependencies node in the Solution Explorer and selecting "Restore Packages". + +![Restore Packages]() + +Note that, thanks to Visual Studio's command line interoperability, you can also update package.json outside of VS and type the following to install whatever you have added to package.json: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ npm install ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If editing from the command line you can then update package.json with additional dependencies by hand or use the npm "—save-dev" flag. For example, this will both install the [uglify Gulp plugin](http://go.microsoft.com/fwlink/?LinkID=533793) and add it as a dependency: +This is what the Task Runner Explorer execute under the covers when you "Restore Packages." In general you should not add the "node_modules" folder that is generated into source control and it is omitted from the Solution Explorer in Visual Studio for this reason. + +Similarly, you can update package.json with additional dependencies by hand in Visual Studio or use the npm "--save-dev" flag from the command line. For example, this will both install the [uglify Gulp plugin](http://go.microsoft.com/fwlink/?LinkID=533793) and add it as a dependency: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ npm install --save-dev gulp-uglify ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, create a file called "gulpfile.js" and add it to the root of your project. You'll author the build script for your project in this file. For example, here is a simple Gulp task. +Now that we have the needed dependiencies installed, create a file called "gulpfile.js" and add it to the root of your project. For example, here is a simple Gulp task. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ var gulp = require("gulp"); @@ -45,13 +49,11 @@ gulp.task("before-build", function() { }); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can name the task whatever you want. In the next step, we'll set it up to run before your project is built. - -In Visual Studio, open the Task Runner Explorer using the View \> Other Windows \> Task Runner Explorer menu. +In Visual Studio, open the Task Runner Explorer by going to View \> Other Windows \> Task Runner Explorer. ![View Menu]() -You'll then see the Task Runner Explorer and the before-build task we just created. +After clicking the "Refresh" button you will then see the Task Runner Explorer with the before-build task we created visible. ![Before Build Task]() @@ -59,152 +61,25 @@ Now to attach this to the "Before Build" event, right click and select Bindings ![Before Build Task Binding]() -The next time you run a build this task will automatically fire! - -###Supporting the Gulp Task Runner Explorer from Command Line Builds -If you want to use the "Before Build" and "After Build" event bindings **outside** of Visual Studio (say from the Cordova CLI itself) you may install the sample [Visual Studio Tools for Apache Cordova CLI Support Plugin](http://go.microsoft.com/fwlink/?LinkID=533753). This plugin works by wiring the "Before Build" event to "Before Prepare" in Cordova and "After Build" to "After Compile" when building outside of Visual Studio. **Note that currently this plugin only supports bindings defined in a gulpfile.js in the root of your project.** - -1. Open your project in Visual Studio -2. Double click on config.xml in your project -3. Select the "Plugins" tab -4. Select "Custom" and choose "Git" -5. Enter the following URI: https://github.com/Chuxel/taco-cordova-support-plugin.git -6. Click "Add" - -![Configuring the Apache Cordova CLI Support plugin]() - -See the [plugin's Git repository](http://go.microsoft.com/fwlink/?LinkID=533753) for additional information. We will cover a simplified version of what this plugin does behind the scenes in the next section. - -###Behind the Scenes: How does the Cordova hook call the Gulp task? -If you're looking for a quick way to run Gulp tasks as a part of Cordova build events, outside of Visual Studio, consider using the sample [Visual Studio Tools for Apache Cordova CLI Support Plugin](http://go.microsoft.com/fwlink/?LinkID=533753) described above. However, if you would prefer not to tie the implementation to the format used by the VS Task Runner Explorer, you can easily wire in your own Cordova hook using a similar technique. - -Hooks can be implemented in a number of different ways: shell scripts, Node.js scripts, or Node modules. In this example we'll use a Node.js module since it can run on both Windows and OSX and has less overhead than starting up a shell script. - -1. Run the following commands in the command line from the root of your project. We'll automate this step later. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - npm install gulp - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -2. Create a file called "hook-gulp.js" in a new "hooks" folder in your Cordova project -3. Place the following code in it: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - module.exports = function (context) { - - var Q = context.requireCordovaModule("q"), - fork = require("child_process").fork; - - // Use the gulp node module to execute the task and return a promise - var deferred = Q.defer(); - var child = fork("./node_modules/gulp/bin/gulp.js", context.hook); - child.on("error", function (err) { - deferred.reject(err); - }); - child.on("exit", function (code, signal) { - if (code === 0 && signal === null) { - deferred.resolve(); - } else { - deferred.reject("Non-zero exit code or signal."); - } - }); - return deferred.promise; - } - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - This code gets the name of the currently running hook event from a `context` object that is passed into the hook module. Then, it invokes a Gulp task of that same name by [forking](http://go.microsoft.com/fwlink/?LinkID=533804) the Gulp node module. Since this is done asynchronously, a promise is returned to Cordova. -4. To configure Cordova to run the hook, add the following element to config.xml in your Cordova project. In Visual Studio you can do this using the Right-Click \> View Code menu. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can wire Gulp tasks to any number of valid Cordova [hook events](http://go.microsoft.com/fwlink/?LinkID=533744) by simply adding additional hook elements to config.xml and replacing "before\_prepare" with the event you want to wire into. -5. Create a file called "gulpfile.js" and put it in the root of your Cordova project with the following code: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - var gulp = require("gulp"); - gulp.task("before_prepare", function() { - // Add anything you want to do before the build here - }); - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - To add additional hooks, you can repeat step 4 to configure the hook in Cordova and then add a new `gulp.task()` with the name of the new hook you want to script out in Gulp. -6. Now run a Cordova build and try it out! - -#### Automating Dependency Installation for our Task Runner Cordova Hook -At this point, anything you add to the "before\_prepare" Gulp task will be fired off on each build. It is really common to use other node modules in a Gulp task, particularly in the form of plugins. You can install these manually, but let's take the next step and automate installation of Gulp and any other node modules you may want to use. - -1. Create a "package.json" file in the root of your project and place the following in it: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - { - "devDependencies": { - "gulp": "latest" - } - } - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -2. Update "hook-gulp.js" as follows: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - module.exports = function (context) { - var Q = context.requireCordovaModule("q"), - fs = require("fs"), - path = require("path"), - fork = require("child_process").fork, - exec = Q.nfbind(require("child_process").exec); - - // Check to see if Gulp is installed and if not use "npm install" to - // install the contents of package.json in the node_modules folder - if (!fs.existsSync(path.join(process.cwd(), "node_modules", "gulp"))) { - console.log("Gulp not found. Installing package dependencies.") - return exec("npm install").then(function (result) { - console.log(result[0]); - if (result[1] != "") { - console.error(result[1]); - } - }) - .then(function () { return runGulpTask(context.hook); }); - } else { - return runGulpTask(context.hook); - } - - function runGulpTask(hook) { - // Use the gulp node module to execute the task and return a promise - var deferred = Q.defer(); - var child = fork("./node_modules/gulp/bin/gulp.js", hook); - child.on("error", function (err) { - deferred.reject(err); - }); - child.on("exit", function (code, signal) { - if (code === 0 && signal === null) { - deferred.resolve(); - } else { - deferred.reject("Non-zero exit code or signal."); - } - }); - return deferred.promise; - } - } - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - This will then first check to see if Gulp is already installed and if not, install everything you have in package.json automatically by executing the "npm install" command from the root of your project. Either way it calls the task matching the Cordova hook event. - -3. Now run a Cordova build and try it out! - -#### Adding Other Dependencies -Adding additional dependencies is simple from Visual Studio. VS will also **automaticlly** install any package added to the "devDependencies" list in package.json when you save the file. - -You can also install any additional dependencies and update package.json using the "--save" flag when calling "npm install" from the command line. For example, this command will add the [uglify Gulp plugin](http://go.microsoft.com/fwlink/?LinkID=533793) as a dependency: +The next time you run a build this task will automatically fire! You can also execute tasks without binding them to an event simply by selecting "Run" from the same context menu. + +##Supporting Task Runner Explorer Bindings from the Command Line +By default, bindings in the Task Runner Explorer only work inside of Visual Studio. When working outside of Visual Studio we generally recommend simply running the Gulp tasks directly from the command line. For example, this will run the Gulp task we created above: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -npm install --save-dev gulp-uglify +gulp before-build ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +However, you may want to be able to simply assign bindings in Visual Studio and have them apply from builds at the command line or in a team / Continuous Integration (CI) environment. Fortunately this is fairly straight forward to do via a [Cordova "hook"](http://go.microsoft.com/fwlink/?LinkID=533744). + +To do so, **[follow these directions to add a pre-built Cordova hook to your project](./hook-task-runner-binding)**. You can then modify it as you see fit to meet your needs. + ## More Information * [Learn more about using Gulp with your Cordova projects](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 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) diff --git a/tutorial-gulp/gulp-typescript.md b/tutorial-gulp/gulp-typescript.md index e341ddc3..8c3a49cd 100644 --- a/tutorial-gulp/gulp-typescript.md +++ b/tutorial-gulp/gulp-typescript.md @@ -25,6 +25,10 @@ See the ["Using Gulp to Build Cordova Projects" tutorial](http://go.microsoft.co } ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You can also manually edit package.json from Visual Studio and then install the dependency by right-clicking on the Dependency node in the Solution Explorer and selecting "Restore Packages." + + ![Restore Packages]() + 2. Add the following task to gulpfile.js: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -44,8 +48,26 @@ See the ["Using Gulp to Build Cordova Projects" tutorial](http://go.microsoft.co .pipe(gulp.dest("www/scripts")); }); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You could also use a tsconfig.json file (like the default VS template) and add the following instead: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + var ts = require("gulp-typescript"), + fs = require("fs"), + tsconfigPath = "scripts/tsconfig.json"; + + gulp.task("scripts", function () { + // Compile TypeScript code + if (fs.existsSync(tsconfigPath)) { + gulp.src("scripts/**/*.ts") + .pipe(ts(ts.createProject(tsconfigPath))) + .pipe(gulp.dest(".")); + } + }); - This will compile anything in the “scripts” folder in the root of your Cordova project and copy them as a single JavaScript file called “appBundle.js” under the “www/scripts” folder. You should update this with the location of all of the TypeScript files you want compiled. You can add an array of locations to compile as follows: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Either of these code snippets will compile anything in the “scripts” folder in the root of your Cordova project and copy them as a single JavaScript file called “appBundle.js” under the “www/scripts” folder. You should update this with the location of all of the TypeScript files you want compiled. You can add an array of locations to compile as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ gulp.src(["scripts/**/*.ts","www/typescript/**/*.ts"]) @@ -82,6 +104,6 @@ gulp watch * [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) diff --git a/tutorial-gulp/hook-task-runner-binding/LICENSE b/tutorial-gulp/hook-task-runner-binding/LICENSE new file mode 100644 index 00000000..80649e7c --- /dev/null +++ b/tutorial-gulp/hook-task-runner-binding/LICENSE @@ -0,0 +1,7 @@ +Copyright (c) Microsoft Corporation + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/tutorial-gulp/hook-task-runner-binding/README.md b/tutorial-gulp/hook-task-runner-binding/README.md new file mode 100644 index 00000000..f4f24fbe --- /dev/null +++ b/tutorial-gulp/hook-task-runner-binding/README.md @@ -0,0 +1,74 @@ +#Cordova Hook to Execute VS Task Runner Explorer Bindings from the Command Line + +License: MIT + +Use this hook if you want to be able to use the "Before Build" and "After Build" event bindings **outside** of Visual Studio (say from the Cordova CLI itself or during a CI build). It wires in the "Before Build" binding in the Task Runner Explorer to "Before Prepare" in Cordova and "After Build" in the Task Runner Explorer to "After Compile" in Cordova. **Note that currently this hook only supports bindings in gulpfile.js in the root of your project.** + +To install it: + +1. Grab the js file and drop it a "hooks" folder in your project root +2. Update config.xml with the following: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +##Using the Visual Studio 2015 Task Runner Explorer +The Visual Studio Task Runner Explorer allows users to tie Gulp tasks to specific build events. To use the Task Runner Explorer: + +1. Go to View > Other Windows > Task Runner Explorer +2. You will now see any gulpfiles you have in your project. (Hit the refresh icon if you added one after opening the window.) +3. To bind a task to an event, right click on the task, go to Bindings, and select the event you want + +**Note: The hook currently only works if "gulpfile.js" is in the root of the project. In addition, Clean and ProjectOpened do not have direct analogs in the Cordova CLI and are currently ignored.** + +This results in a comment being added to gulpfile.js with the bindings. Ex: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +/// +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The config.xml elements above will map the BeforeBuild task into the Cordova CLI before\_prepare event and the AfterBuild task to the Cordova CLI after\_compile event. These same events are fired by the cordova "build" command which combines "prepare" and "compile" in one comand while still allowing each of these commands to function separatley. + +While not supported via Visual Studio UI, you can wire in Gulp tasks to additiona Cordova hooks by simply using the hook name using the syntax above. Ex: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +/// +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The hook also automatically detects if Gulp is not installed in the node_modules folder in your project and will "npm install" the contents of package.json in your project to further streamline development. + +## Terms of Use +By downloading and running this project, you agree to the license terms of the third party application software, Microsoft products, and components to be installed. + +The third party software and products are provided to you by third parties. You are responsible for reading and accepting the relevant license terms for all software that will be installed. Microsoft grants you no rights to third party software. + + +## License +Unless otherwise mentioned, the code samples are released under the MIT license. + +``` +The MIT License (MIT) + +Copyright (c) Microsoft Corporation + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + diff --git a/tutorial-gulp/hook-task-runner-binding/hook-task-runner-binding.js b/tutorial-gulp/hook-task-runner-binding/hook-task-runner-binding.js new file mode 100644 index 00000000..1ca301c0 --- /dev/null +++ b/tutorial-gulp/hook-task-runner-binding/hook-task-runner-binding.js @@ -0,0 +1,94 @@ +/* + Copyright (c) Microsoft. All rights reserved. + Licensed under the MIT license. See LICENSE file in the project root for full license information. +*/ + +var exec, fork, fs, path, Q, hookTasks; + +module.exports = function (context) { + + // Skip processing if being called from within Visual Studio + if (process.env["VisualStudioEdition"]) { + return; + } + + fs = require('fs'); + path = require('path'); + Q = context.requireCordovaModule('q'); + exec = Q.nfbind(require('child_process').exec); + fork = require('child_process').fork; + + // Syntax: + /// + + // Check gulpfile.js for tasks to run for this hook + if (fs.existsSync(path.join(process.cwd(), "gulpfile.js"))) { + // Hooktasks should be cached after first execution since its at the module level + if (!hookTasks) { + console.log("Checking gulpfile for tasks to run for Cordova events.") + hookTasks = {}; + var gulpfile = fs.readFileSync("gulpfile.js", "utf8"); + var matches = gulpfile.match(/\/\/\/\s)/ig); + if (matches) { + var bindings = matches[0].split(" "); + bindings.forEach(function (binding) { + binding = binding.replace(/["|']/g, ""); + var bindParts = binding.split("=") + var hook = bindParts[0]; + var task = bindParts[1]; + if (hook.indexOf("_") == -1) { + switch (hook) { + case "BeforeBuild": hook = "before_prepare"; break; + case "AfterBuild": hook = "after_compile"; break; + case "Clean": return; // No cordova clean event + case "ProjectOpened": return; // No cordova project open event + } + } else { + hook = hook.toLowerCase(); + } + if (hookTasks[hook]) { + hookTasks[hook].push(task); + } else { + hookTasks[hook] = [task]; + } + }); + } + } + + if (hookTasks[context.hook]) { + // Install dependencies in package.json if gulp not present - Run the task either way + if (!fs.existsSync(path.join(process.cwd(), "node_modules", "gulp"))) { + console.log("Gulp not found. Installing package dependencies.") + return exec("npm install") + .then(function (result) { + console.log(result[0]); + if (result[1] != "") { + console.error(result[1]); + }; + }) + .then(function () { return runGulpTask(context.hook); }); + } else { + return runGulpTask(context.hook); + } + } + } + + function runGulpTask(hook) { + var deferred = Q.defer(); + console.log("Running gulp task " + hookTasks[hook] + " for Cordova event " + hook); + var child = fork("./node_modules/gulp/bin/gulp.js", hookTasks[hook]); + child.on("error", function (err) { + deferred.reject(err); + }); + child.on("exit", function (code, signal) { + if (code === 0 && signal === null) { + deferred.resolve(); + } else { + deferred.reject("Non-zero exit code or signal. Code: " + code + ", Signal: " + signal); + } + }); + return deferred.promise; + } + +}; + diff --git a/tutorial-gulp/media/gulp-4.png b/tutorial-gulp/media/gulp-4.png new file mode 100644 index 00000000..ad7008c5 Binary files /dev/null and b/tutorial-gulp/media/gulp-4.png differ diff --git a/tutorial-package-publish/README.md b/tutorial-package-publish/README.md index 6e4ad2fb..d117bcdd 100644 --- a/tutorial-package-publish/README.md +++ b/tutorial-package-publish/README.md @@ -24,9 +24,14 @@ The wizard guides you through a workflow that is similar to the workflow for cre Once you are ready to package your application for android, change the platform to the android platform, the build configuration to release and select ‘device’ as debug target as shown in the figure below: ![Android: Debug Target]() -If you initiate a build with this configuration, VS builds an unsigned release package that can be deployed to a machine but cannot be published to store. In order to create a release signed package, you need to provide keystore information to the build in the ant.properties file under res\native\android. A keystore is a binary file that contains a set of private keys. You must keep your keystore in a safe and secure place. +If you initiate a build with this configuration, VS builds an unsigned release package that can be deployed to a machine but cannot be published to store. + +**Cordova CLI verions < 5.0**, use ANT to build android applications. In order to create a release signed package, you need to provide keystore information to the build in the ant.properties file under res\native\android. A keystore is a binary file that contains a set of private keys. You must keep your keystore in a safe and secure place. ![Android: Build assets]() +**Cordova CLI verions > 5.0**, use GRADLE to build android applications. In order to create a release signed package, you need to provide keystore information to the build in the build.json file under the project root. A keystore is a binary file that contains a set of private keys. You must keep your keystore in a safe and secure place. +![Android: Build assets]() + You can either provide information about existing key-store or create a new one. Here I am going to explain how you can create a new key-store using standard tools from the Android SDK and the JDK: 1. Open a new admin command prompt. @@ -63,7 +68,7 @@ Running the above command, prompts you for passwords for the keystore and key, a ``` 4. It then generates the keystore as a file called **my-release-key.keystore** under *c:\* drive. The keystore contains a single key, valid for 10000 days. -5. Edit the **ant.properties in res\native\android** with the information for the keystore: +5. For Cordova CLI verions < 5.0, edit the **ant.properties in res\native\android** with the information for the keystore: ``` key.store=c:\\my-release-key.keystore @@ -71,8 +76,23 @@ Running the above command, prompts you for passwords for the keystore and key, a key.store.password= pwd123 key.alias.password= pwd123 ``` + For Cordova CLI verions > 5.0, edit the **build.json in the project root** with the information for the keystore: + + ``` + { + "android": { + "release": { + "keystore":"c:\\my-release-key.keystore" + "storePassword":"pwd123" + "alias":"johnS" + "password":"pwd123" + "keystoreType":"" + } + } + } + ``` -After you have edited ant.properties with the keystore information, building the app for release configuration, results in a release signed APK package at \bin\Android\Release. Once your app is ready for publishing, you can upload this app on Google play by signing into your [Google play developer console](https://play.google.com/apps/publish/). Please refer to [Launch Checklist for Google Play](http://developer.android.com/distribute/tools/launch-checklist.html) for successful publication of you app. +After you have edited the appropriate file with the keystore information, building the app for release configuration, results in a release signed APK package at \bin\Android\Release. Once your app is ready for publishing, you can upload this app on Google play by signing into your [Google play developer console](https://play.google.com/apps/publish/). Please refer to [Launch Checklist for Google Play](http://developer.android.com/distribute/tools/launch-checklist.html) for successful publication of you app. ### iOS: @@ -187,6 +207,6 @@ The Manage Your Apps page of iTunes Connect should now list an updated status 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 diff --git a/tutorial-package-publish/media/android_assets_cordova5.png b/tutorial-package-publish/media/android_assets_cordova5.png new file mode 100644 index 00000000..e00ea425 Binary files /dev/null and b/tutorial-package-publish/media/android_assets_cordova5.png differ diff --git a/tutorial-team-build/Jenkins.md b/tutorial-team-build/Jenkins.md index 59c9b002..a008be5f 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 | @@ -229,11 +230,11 @@ The OSX version of the build is similar but adds one additional requirement: Unl **Trouble Shooting 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) +* [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 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/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..e17c6bce 100644 --- a/tutorial-team-build/README.md +++ b/tutorial-team-build/README.md @@ -1,19 +1,36 @@ -#Building Cordova Apps in a Team / Continuous Integration Environment +#Building Cordova Apps in a Team / Continuous Integration (CI) Environment **Note that this documentation applies to Visual Studio 2015 and does not apply to Visual Studio 2013 CTPs.** With the release of Visual Studio 2015, you now have a number of options for how you can integrate Cordova apps with your favorite team / continous integration (CI) server thanks to the fact that projects created in Visual Studio are standard [Apache Cordova Command Line Interface](http://go.microsoft.com/fwlink/?LinkID=533773) (CLI) projects. In this tutorial, we will cover a few different approaches for building Cordova projects outside of Visual Studio. 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. @@ -401,7 +429,7 @@ There are a few relativley common issues when building a Cordova app on OSX rela To resolve this problem you have two options: 1. Don't check in the contents of the "platforms" folder into source control. This is by far the path of least resistance. The Gulp build script can add them at the time you build. - 2. If you absolutely must check in the contents of the platforms folder from Windows, you can craft a shell script to set the execute bits on these files and include it as a part of your build process. There is also a [**Cordova hook based version of this script**](https://github.com/Microsoft/cordova-docs/tree/master/tips-and-workarounds/ios/osx-set-execute) available in the tips and workarounds section. + 2. If you absolutely must check in the contents of the platforms folder from Windows, you can craft a shell script to set the execute bits on these files and include it as a part of your build process. There is also a [**Cordova hook based version of this script**](../tips-and-workarounds/ios/osx-set-execute) available in the tips and workarounds section. 1. Create a shell script called "set-execute.sh" with the following contents: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -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..000d6fb4 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. @@ -172,11 +183,11 @@ 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 or device. | **/p:DebuggerFlavor=PhoneDevice** | ## More Information -* [Learn about other Team Build / CI options](README.md) +* [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 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..a6b74030 100644 --- a/tutorial-team-build/TFS2015.md +++ b/tutorial-team-build/TFS2015.md @@ -1,64 +1,65 @@ -#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. +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 though you can use the VSO Cross-Platform Build agent with Visual Studio Online (see below). -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. +In the near very future, all Cordova pre-requisites will already be installed and configured when using the Hosted Agent Pool in Visual Studio Online (VSO). This update will also improve the performance of Cordova builds in Visual Studio Online. However, in the short term you may need to add Ant into the path when using Cordova versions lower than 5.0.0. See [Short Term Workaround: VSO and Ant](#vso-ant) for details if you encounter an error about Ant not being in the path. You can skip this if you do not encounter an Ant related build error. -###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. +In the near very future, all Cordova pre-requisites will already be installed and configured when using the Hosted Agent Pool in Visual Studio Online (VSO). This update will also improve the performance of builds in Visual Studio Online. However, in the short term you may need to add Ant into the path when using Cordova versions lower than 5.0.0. See [Short Term Workaround: VSO and Ant](#vso-ant) for details if you encounter an error about Ant not being in the path. ##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 +73,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 +82,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,21 +112,28 @@ 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. +#### 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. 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](./README.md) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. -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. + +## Short Term Workaround: VSO and Ant +In the near very future, all Cordova pre-requisites will already be installed and configured when using the Hosted Agent Pool in Visual Studio Online (VSO). This update will also improve the performance of Cordova builds in Visual Studio Online. However, in the short term you may need to add Ant into the path when using Cordova versions lower than 5.0.0. + +Follow these instructions if you encounter an error about Ant not being in the path when you build your Cordova app in VSO. Note that you can skip these steps if you do not encounter an Ant build error. 1. Create a batch file called "setenv.cmd" and place it in a solution folder with the following contents: @@ -159,33 +156,13 @@ When using Hosted build agents in Visual Studio Online (VSO), Node.js will alrea 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) +* [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 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