diff --git a/Readme.md b/Readme.md index 734105ba..bd5e7fb9 100644 --- a/Readme.md +++ b/Readme.md @@ -11,10 +11,11 @@ This repository contains a set of documents and tutorials for the **Visual Studi 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 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. [General CI Guidence, Information, and Troubleshooting](./tutorial-team-build/General.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) diff --git a/known-issues/known-issues-cordova5.md b/known-issues/known-issues-cordova5.md index d0400130..63aa1012 100644 --- a/known-issues/known-issues-cordova5.md +++ b/known-issues/known-issues-cordova5.md @@ -6,11 +6,9 @@ In general we recommend **using Cordova 5.1.1 or above** instead of 5.0.0 as the ##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. +**config.xml Designer Does Not Show Updated Plugin IDs with Cordova 5.0.0+:** 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) with Cordova 4.3.1 and below since this version of the Cordova < 5.0.0 do not support npm. -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. +However, if you update your Cordova version to 5.0.0 or later the config.xml designer should automatically see the new IDs in the "Plugins" tab of the designer. If you do not see this behavior, update Tools for Apache Cordova since a small post-RTM update enabled this functionality. Some very early adopters may not see some of the improvments described in this document until after you update. You will get an update notification soon prompting you to update or you can click "Install Tools for Apache Cordova" from the Apache Cordova templates section when creating a new project. Be sure to remove plugins with the older IDs before updating via the "Installed" tab to avoid unexpected behaviors. ---------- **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: diff --git a/known-issues/known-issues-general.md b/known-issues/known-issues-general.md index 3695a74d..0b6f6c2f 100644 --- a/known-issues/known-issues-general.md +++ b/known-issues/known-issues-general.md @@ -31,11 +31,9 @@ Remove these files from source control if you are not checking in the "platforms **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. +**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) with Cordova 4.3.1 and below since this version of the Cordova < 5.0.0 do not support npm. -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. +If you update your Cordova version to 5.1.1 or later the config.xml designer will automatically switch to using the new IDs. If you do not see this behavior, update Tools for Apache Cordova. Some very early adopters may not see some of the improvments described in this document until after you update since a small post-RTM update enabled this functionality. You will get an update notification soon prompting you to update or you can click "Install Tools for Apache Cordova" from the Apache Cordova templates section when creating a new project. Be sure to remove plugins using older IDs from your project before adding the updated plugins with the new IDs. ---------- **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"). diff --git a/known-issues/known-issues-vs2015.md b/known-issues/known-issues-vs2015.md index 7a60bd34..2c853fda 100644 --- a/known-issues/known-issues-vs2015.md +++ b/known-issues/known-issues-vs2015.md @@ -118,8 +118,14 @@ In some cases, when you uninstall VS2013 or a previous version (RC) of VS2015, a ---------- **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. +---------- +**config.xml Designer Does Not Show Updated Plugin IDs with Cordova 5.0.0+:** 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) with Cordova 4.3.1 and below since this version of the Cordova < 5.0.0 do not support npm. + +However, if you update your Cordova version to 5.0.0 or later the config.xml designer should automatically see the new IDs in the "Plugins" tab of the designer. If you do not see this behavior, update Tools for Apache Cordova since a small post-RTM update enabled this functionality. You will get an update notification soon prompting you to update or you can click "Install Tools for Apache Cordova" from the Apache Cordova templates section when creating a new project. Be sure to remove plugins with the older IDs before updating via the "Installed" tab to avoid unexpected behaviors. + ##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. diff --git a/tutorial-cordova-5/README.md b/tutorial-cordova-5/README.md index 5b29e05a..901fc83a 100644 --- a/tutorial-cordova-5/README.md +++ b/tutorial-cordova-5/README.md @@ -1,5 +1,5 @@ #Using Apache Cordova 5 -**Note that this documentation applies to Visual Studio 2015 and does not apply to Visual Studio 2013 CTPs.** +**Note: If the default blank template in Visual Studio 2015 is does not default to 5.1.1, you should update Tools for Apache Cordova.** Some very early adopters may not see some of the improvments described in this document until after you update. You will soon see a notification in the in the notification center (flag in the upper right) prompting you to update. 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. @@ -11,7 +11,7 @@ This article will summarize the changes in Cordova 5 and how you can take advant 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: +You can update your project to use Cordova 5.1.1 by following these steps: 1. Double click on config.xml @@ -74,15 +74,13 @@ When you upgrade a project to Cordova 5.0.0+, you will want to take the followin 1. Add the whitelist plugin to your project via config.xml: - 1. Right-click on config.xml and select "View Code" + 1. Double click on config.xml in your project + + 2. Click on the "Plugins" tab - 2. Add the following XML element under the <widget> element: + 2. Select "Whitelist" and click "Add" - ~~~~~~~~~~~~~~~~~~~~~~~ - - ~~~~~~~~~~~~~~~~~~~~~~~ - - 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. + ![Add Whitelist Plugin]() 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" @@ -136,13 +134,11 @@ As a result, core plugins like Camera have changed from [org.apache.cordova.came 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: +The config.xml designer in Visual Studio will automatically use the new plugin IDs if you are targeting Cordova 5.0.0+ and use the old plugin IDs for 4.3.1 and below where npm based plugin support is not available (see below for details). -~~~~~~~~~~~~~~~~~ - -~~~~~~~~~~~~~~~~~ +**If you do not see this behavior, update Tools for Apache Cordova.** Some very early adopters may not see some of the improvments described in this document until after you update. You will soon see a notification in the in the notification center (flag in the upper right) prompting you to update. -See [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-npm) for additional details on add npm versions of plugins to your project. +See [tips and workarounds](../tips-and-workarounds/general/README.md#plugin-npm) for additional details on adding npm versions of plugins to your project. ###Cordova Plugin Registry As of 7/14/2015, plugins.cordova.io now has two registry sections: @@ -184,7 +180,7 @@ Simply updating to Cordova 5.0.0+ will automatically cause Gradle to be used fro 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. +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 re-adding the plugin. 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. @@ -216,14 +212,14 @@ There is now a [Cordova Crosswalk plugin](http://go.microsoft.com/fwlink/?LinkID ###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: +1. Double click on config.xml in your project + +2. Click on the "Plugins" tab - ~~~~~~~~~~~~~~~~~~~~~~ - - ~~~~~~~~~~~~~~~~~~~~~~ +2. Select "Crosswalk WebView" and click "Add" + ![Add Crosswalk Plugin]() + 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 diff --git a/tutorial-cordova-5/cordova-5-security.md b/tutorial-cordova-5/cordova-5-security.md index 2fa4ebb0..540d10ca 100644 --- a/tutorial-cordova-5/cordova-5-security.md +++ b/tutorial-cordova-5/cordova-5-security.md @@ -1,4 +1,7 @@ #Introduction to Cordova 5 Security + +**Note: If the default blank template in Visual Studio 2015 is does not default to 5.1.1, you should update Tools for Apache Cordova.** Some very early adopters may not see some of the improvments described in this document until after you update. You will soon see a notification in the in the notification center (flag in the upper right) prompting you to update. + 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 @@ -58,6 +61,7 @@ VS syntax (works with any Cordova version): ~~~~~~~~~~~~~~~~~~~~~~~ +Both the default Cordova CLI template and Visual Studio's blank template use this feature to install the Whitelist plugin automatically on first build. ##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. @@ -107,18 +111,16 @@ You can find a [great tutorial on using the CSP in detail here](http://go.micros ##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. Add the whitelist plugin to your project via config.xml: - 1. Right-click on config.xml and select "View Code" + 1. Double click on config.xml in your project + + 2. Click on the "Plugins" tab - 2. Add the following XML elements under the <widget> element: + 2. Select "Whitelist" and click "Add" - ~~~~~~~~~~~~~~~~~~~~~~~ - - ~~~~~~~~~~~~~~~~~~~~~~~ - - 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. - + ![Add Whitelist Plugin]() + 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 diff --git a/tutorial-team-build/General.md b/tutorial-team-build/General.md new file mode 100644 index 00000000..961b5c22 --- /dev/null +++ b/tutorial-team-build/General.md @@ -0,0 +1,454 @@ +#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 / continuous 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: + +- **[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) + + +*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. + +- The following folders should be excluded: + - platforms + - bld + - .vs +- The following files should be excluded: + - plugins/android.json + - plugins/windows.json + - plugins/wp8.json + - plugins/ios.json + - plugins/remote_ios.json + - changeList.json + - *.suo + - *.jsproj.user + +**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. + +The basic flow for building a Cordova app is simple on the surface: + +1. Check the project out from source control + +2. Add the platforms you want to build to the project using the "cordova platform add" command. Ex: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + cordova platform add android + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +3. Build the project using the "cordova build" command: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + cordova build android --release + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 **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](./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. + +1. Install Node.js and make sure it is available to the system user you intend to have run your builds + +2. Install the platform specific dependencies on the server and make them available to this same user. See the following guides for details: + + 1. [Android Platform Guide](http://go.microsoft.com/fwlink/?LinkID=533774) + + 1. You do not need to install Android Studio or Eclipse + + 2. Instead you may download and install one of the ["SDK Tools Only" packages](http://go.microsoft.com/fwlink/?LinkID=533747). + + 3. When building, you may encounter an error telling you that you need to install specific SDK versions or tools depending on the version of Cordova you are using. Note that these messages are talking about the *tools and SDK* versions *not* the device target versions. + + 1. You can install additional SDKs using [the Android SDK Manager](http://go.microsoft.com/fwlink/?LinkID=533775). + + 2. Note that only the "SDK Platform" is required for a given API level so you may uncheck other options. Android system images in particular are large and are not needed. + + 3. Be sure to also install the "platform tools" + + 4. Projects created using Visual Studio will typically use either the API SDK 19, 21, or API 22. + + 2. OSX only: [iOS Platform Guide](http://go.microsoft.com/fwlink/?LinkID=533776). You do not need to install the deployment tools mentioned. + + 3. Windows only: + 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 +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 +- GitHub: https://github.com +- Apache ASF Git: https://git-wip-us.apache.org +- gradle.org: http://services.gradle.org +- maven.org: https://*.maven.org + +If you need to use a proxy, you will need to configure both npm and Git command line tools to use them. Open a command prompt on Windows or the Terminal app on OSX and type the following: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +npm config set proxy http://:@ +npm config set https-proxy http://:@ +git config --global http.proxy http://:@ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +...where "<username>:<password>@" is optional and should contain the appropriate user name and password for proxy access while <host> is the correct proxy host and port (ex: myproxy.mycompany.com:8080). + +You may also need to configure proxy settings for Java. This can be [accomplished via the Java control panel (reccomended)](http://java.com/en/download/help/proxy_setup.xml) or by setting an environment variable as the follows: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +JAVA_OPTS=-Dhttps.proxyHost= -Dhttps.proxyPort= -Dhttp.proxyHost= -Dhttp.proxyPort= -DproxySet=true +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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](../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: + +1. **Building with Multiple Versions of the Cordova CLI.** While in an ideal world everyone would use the edge version of the Cordova CLI and associated platforms, the reality is that for a given build server you will want to use multiple versions of the Cordova CLI. This means that the common practice of installing Cordova [globally](http://go.microsoft.com/fwlink/?LinkID=533780) will not work. + +2. **Adding Cordova Platforms.** As of Cordova 4.3.0, the "cordova platform add" CLI command still needs to be explicitly run to build a platform unless you opted to check in the contents of the "platforms" folder which is not recommended. However, using the platform command can cause your build to fail under certain circumstances. + +3. **Generating an iOS App Store Package.** By default, the iOS build in Cordova generates an ".app" structure rather than an ".ipa" for device deployment. An ipa can be generated from the command line quite easily but build servers like Jenkins require an extra step. + +4. **Visual Studio Specific Features** + 1. **Supporting res/native.** The "res/native" folder in Visual Studio projects provides a useful way to update native project build artifacts without having to check in the platforms folder. It is not currently a base Cordova CLI feature. + 2. **Supporting Visual Studio specific Windows packaging settings.** Currently the Cordova CLI does not have a standard location for storing platform specific packaging information. While this is something actively being pursued by the community, Visual Studio uses a set of non-standard config.xml elements to store mandatory fields for store submission. + 3. **Supporting the Task Runner Explorer.** Visual Studio now has a convenient Task Runner Explorer that allows you to attach Gulp and Grunt tasks to build events. + +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. + +#### Project Level +Installing and using the correct version of the Cordova CLI at the project level is simple thanks to something called [package.json](http://go.microsoft.com/fwlink/?LinkID=533781). Here is the general approach: + +1. Create a package.json file in the root of your Cordova project. +2. Add the following json to the file where "4.3.0" is the version of the Cordova CLI you intend to use: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + { + "devDependencies": { + "cordova": "4.3.0" + } + } + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +3. Check this into source control with your project. + +4. Configure your build system to run the following command as its first task. This will then install the correct version of the CLI in a new "node\_modules" folder under your project. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + npm install + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +5. When executing a Cordova CLI command for your build task, you can then use the following commands: + + Windows: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + node_modules\cordova\bin\cordova + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + OSX: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ./node_modules/cordova/bin/cordova + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Ex: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ./node_modules/cordova/bin/cordova platform add android + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The downside of this method is that you will end up installing the Cordova CLI each time you execute a "clean" build which will slow down your build times particularly on Windows as the CLI consists of around 25mb of small files. + +### Global Cache +To avoid re-installing each time, you can take advantage of Visual Studio's **taco.json** file and a Node.js script to perform the installation in a specific location that you then use to execute Cordova commands. + +1. Add an environment variable to your system (or build) called **CORDOVA\_CACHE** pointing to where you want to create "cache" of the different versions of the Cordova CLI used to build your projects. + +2. Add this node.js script to your project and call it "setup-cordova.js": + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + var fs = require("fs"), + path = require("path"), + exec = require("child_process").exec; + + // Load taco.json + var taco = require("./taco.json"); + var cordovaVersion = taco["cordova-cli"]; + + // Check if Cordova is already present in the cache, install it if not + var cordovaModulePath = path.resolve(process.env["CORDOVA_CACHE"], cordovaVersion); + if (!fs.existsSync(cordovaModulePath)) { + fs.mkdirSync(cordovaModulePath); + fs.mkdirSync(path.join(cordovaModulePath, "node_modules")); + console.log("Installing Cordova " + cordovaVersion + "."); + exec("npm install cordova@" + cordovaVersion, { cwd: cordovaModulePath }, function (err, stdout, stderr) { + console.log(stdout); + if (stderr) { + console.error(stderr); + } + if (err) { + console.error(err); + process.exit(1); + } + console.log("Cordova " + cordovaVersion + " installed at " + cordovaModulePath); + }); + } else { + console.log("Cordova " + cordovaVersion + " already installed at " + cordovaModulePath); + } + + // Create shell scripts + if (process.platform == "darwin") { + // OSX + fs.writeFileSync("cordova.sh", "#!/bin/sh\n" + path.join(cordovaModulePath, "node_modules", "cordova", "bin", "cordova") + " $@", "utf8"); + fs.chmodSync("cordova.sh", "0777") + } else { + // Windows + fs.writeFileSync("cordova.cmd", "@" + path.join(cordovaModulePath, "node_modules", "cordova", "bin", "cordova") + " %*", "utf8"); + } + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +3. In your team / CI build definition or script, add a build task to execute "node setup-cordova.js" from your project root + +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](../tutorial-gulp/gulp-ci.md) tutorial for additional information. + + +###Adding Platforms +Adding platforms in Cordova is quite simple using the "cordova platform" command. Ex: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +cordova platform add android +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +However, there are a couple of common problems when executing this command that you could run into. + + +1. **Platform Download Messages Result in Build Failures.** Where things can get a bit tricky is that Node.js emits warnings to "Standard Error." The issue is that "platform add" command can result in warnings being reported when the CLI is downloading a version of a given Cordova platform for the first time. This is not an error, but some build systems will assume anything sent to standard error means a build failure occurred. + + Many CI systems provide a "continue on error" option that you can select to get around this particular problem or you can pipe standard error to standard out if you'd prefer. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + cordova platform add ios 2>&1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2. **Errors During Incremental Builds.** If you are doing an incremental build and the platform you are building has already been added, the resulting exit code will be non-zero and may be interpreted as a build failure. If your build system supports a "continue on error" option for a given task, you can simply select that. + + However, a more robust solution is to simply conditionally call "platform add" if the appropriate folder in the platforms folder in your project is not found. In the scripts below replace "cordova" with the appropriate command from the "Building with Multiple Versions of the Cordova CLI" section above. + + Windows: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + IF NOT EXIST platforms/android CALL cordova platform add android + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + OSX: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 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). + +#### Using xcrun +Future versions of the Cordova CLI will likely support generating these archives directly. However, current state it is not supported so an Xcode command line tool needs to be used instead. Ex: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +xcrun -v -sdk iphoneos PackageApplication source.app -o dest.ipa +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Cordova projects, the source ".app" package can be found in the platforms/ios/build/device folder in your project after a successful Cordova "device" build. As an important detail, "source.app" and "dest.ipa" above should be **absolute paths** and the name of the package is taken from the "Display Name" (widget/@name) in config.xml which may not match your project folder name. Ex: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +xcrun -v -sdk iphoneos PackageApplication "/Users/cdvusr/Documents/cordova/myapp/platforms/ios/build/device/My Cordova App.app" -o "/Users/cordova/Documents/cordova/myapp/platforms/ios/build/device/My Cordova App.ipa" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each build system has a different mechanisms in place for passing the absolute path of the project to shell scripts, but typically it involves the use of an environment variable. For example, in Jenkins you can use the following: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +xcrun -v -sdk iphoneos PackageApplication "${WORKSPACE}/platforms/ios/build/device/My Cordova App.app" -o "${WORKSPACE}/platforms/ios/build/device/My Cordova App.ipa" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command will automatically match a developer signing identitiy (when building Debug) or distribution (when building Release) signing identity based on the app's package name. When you are using res/native, you can place a custom [build-debug.xcconfig](http://go.microsoft.com/fwlink/?LinkID=533752) or [build-release.xcconfig](http://go.microsoft.com/fwlink/?LinkID=533782) file in res/native/ios/cordova in your Cordova project to override signing identities and other [build settings](http://go.microsoft.com/fwlink/?LinkID=533783) for these configurations. + +However, additional command line arguments can also be passed such as "--sign" to resign the app using a specific signing identity or a path to a .p12 file and "--embed" to specify the path to a provisioning profile. Ex: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +xcrun -v -sdk iphoneos PackageApplication "${WORKSPACE}/platforms/ios/build/device/My Cordova App.app" -o "${WORKSPACE}/platforms/ios/build/device/My Cordova App.ipa" –-sign "/path/to/signing.p12" --embed "/path/to/some.mobileprovision" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#### Solving Keychain Permission Errors +When auto-matching, you may hit permissions issues when using a build server like [Jenkins](http://go.microsoft.com/fwlink/?LinkID=533784) because the build agent does not have permissions to access the login keychain. To solve this problem, you'll need to unlock the keychain before you build and package your Cordova app. + +Most build servers provide a way to inject secure environment variables before executing build tasks. In Jenkins this is accomplished by using the "Environment Injector Plugin." By then setting a KEYCHAIN\_PWD environment variable you can add the following command to your build. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +security unlock-keychain -p ${KEYCHAIN_PWD} ${HOME}/Library/Keychains/login.keychain +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To then build and package your iOS app, you can run the following commands: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +security unlock-keychain -p ${KEYCHAIN_PWD} ${HOME}/Library/Keychains/login.keychain +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](../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. + +##### Behind the Scenes: res/native Hook +If you are using Tools for Apache Cordova in Visual Studio, you may be taking advantage of the "res/native" folder in your project. This provides a useful way to update native project build artifacts without having to check in the platforms folder but is not currently a base Cordova CLI feature. + +You can take a look at the sample [Tools for Apache Cordova CLI Support Plugin](http://go.microsoft.com/fwlink/?LinkID=533753) for a quick way to add in support. The plugin takes advantage of something called a [Cordova hook](http://go.microsoft.com/fwlink/?LinkID=533744) that allows you to wire in build steps in the Cordova CLI build process. A Cordova hook can be implemented using either shell scripts (batch, bash, or Node.js based) or as a node.js module. + +For this behind the scenes tutorial, we'll use a Node.js based shell script for simplicity sake. All that needs to happen is the following script should be placed in the "hooks/before\_prepare" folder. We will call the file "hook-res-native.js" but the filename itself does not matter. + +Add the following to the file: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#!/usr/bin/env node +var fs = require("fs"), + path = require("path"); + +process.env["CORDOVA_PLATFORMS"].split(",").forEach(function(platform) { + console.log("Processing res/native for " + platform); + var resNative = path.join(process.cwd(), "res", "native", platform) + if (fs.existsSync(resNative)) { + copyFiles(resNative, path.join(process.cwd(), "platforms", platform)); + } +}); + +// Recursive copy function for res/native processing +function copyFiles(srcPath, destPath) { + if (fs.statSync(srcPath).isDirectory()) { + if (!fs.existsSync(destPath)) { + fs.mkdirSync(destPath); + } + fs.readdirSync(srcPath).forEach(function (child) { + copyFiles(path.join(srcPath, child), path.join(destPath, child)); + }); + } else { + fs.writeFileSync(destPath, fs.readFileSync(srcPath)); + } +} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +1. **You are seeing permission errors from "npm":** If you are seeing permission errors from "npm," you may be running into a situation where the build agent user's cache folder (~/.npm) is inaccessible. Generally this occurs if the folder or some of its contents was created while running as an administrator (sudo). Fortunately this is easy to resolve: + + 1. Log into OSX with the user that installed and set up the cross-platform agent + 2. Open the Terminal app and type: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + sudo npm cache clear + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 3. Next, type: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + sudo chown -R `whoami` ~/.npm + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +3. **You checked in the "platforms" folder from Windows and are seeing permission errors:** If you are seeing errors that are originating from files in your project's "platforms" folder, the root cause may be that you checked in shell scripts under the "platforms/android/cordova" or "platforms/ios/cordova" folders from Windows. This is because the NTFS file system has no concept of an "execute bit" that is required to run these from OSX. (The contents of the platforms is generally not intended for checked in and by default are excluded from Cordova projects in Visual Studio as a result.) + + For example, this error is saying the "version" script is not executable: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + [17:41:57] Error: + /Users/vsoagent/vsoagent/agent/work/build/b424d56537be4854de825289f019285698609afddf826d5d1a185eb60b806e47/repo/tfs-vnext test/platforms/android/cordova/version: + Command failed with exit code EACCES + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 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**](../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: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + #!/bin/sh + find -E platforms/ios/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + + find -E platforms/android/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + + find -E platforms/windows/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + + find -E platforms/wp8/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 2. Add this file to your project in Visual Studio and check it into source control + + 3. Add a "shell script" build step at the very beginning of your build definition that runs the above script. + +## More Information +* [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) diff --git a/tutorial-team-build/Jenkins.md b/tutorial-team-build/Jenkins.md index a008be5f..672c14a6 100644 --- a/tutorial-team-build/Jenkins.md +++ b/tutorial-team-build/Jenkins.md @@ -6,16 +6,16 @@ This tutorial is part of a [series of tutorials](./README.md) on building Visual [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 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. +**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](./General.md#whattoadd) 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: 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](./General.md#depends) tutorial for details. -**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](./General.md#proxy) if your build servers have limited Internet connectivity or require routing traffic through a proxy. For OSX, the pre-requisites will need to be installed manually, but mirror [the requirements for the Visual Studio remote build agent](http://go.microsoft.com/fwlink/?LinkID=533745). However, unlike with TFS 2013, you do not need to install the remote build agent itself if your OSX machine will only be used for team / CI builds. @@ -227,7 +227,7 @@ The OSX version of the build is similar but adds one additional requirement: Unl 8. Click "Save" and then "Build Now" to verify everything is working! - **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. + **Trouble Shooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](./General.md#osxgotcha) 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) diff --git a/tutorial-team-build/README.md b/tutorial-team-build/README.md index a7c06628..1b9ef015 100644 --- a/tutorial-team-build/README.md +++ b/tutorial-team-build/README.md @@ -1,448 +1,77 @@ -#Building Cordova Apps in a Team / Continuous Integration (CI) Environment +#Getting Started 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. +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 / continuous 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. -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: +In this tutorial, we will cover how you can get your project running in nearly any CI system quickly using the [taco-team-build node module](http://go.microsoft.com/fwlink/?LinkID=533736) and Gulp. Note that the method described here can be used with Visual Studio Online, TFS 2015, Jenkins, and others but will not work with TFS 2013. See [this tutorial](./TFS2013.md) for details on TFS 2013. -- **[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) - - -*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. - -- The following folders should be excluded: - - platforms - - bld - - .vs -- The following files should be excluded: - - plugins/android.json - - plugins/windows.json - - plugins/wp8.json - - plugins/ios.json - - plugins/remote_ios.json - - changeList.json - - *.suo - - *.jsproj.user - -**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. - -The basic flow for building a Cordova app is simple on the surface: - -1. Check the project out from source control - -2. Add the platforms you want to build to the project using the "cordova platform add" command. Ex: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - cordova platform add android - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -3. Build the project using the "cordova build" command: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - cordova build android --release - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 **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](./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. - -1. Install Node.js and make sure it is available to the system user you intend to have run your builds - -2. Install the platform specific dependencies on the server and make them available to this same user. See the following guides for details: +To get going quickly, follow these steps: - 1. [Android Platform Guide](http://go.microsoft.com/fwlink/?LinkID=533774) +1. First, either install Visual Studio with the Tools for Apache Cordova option on your build server or simply install the pre-requisites for the platforms you are targeting separately. In brief: + - Visual Studio itself is **only** required if you are building for **Windows or Windows Phone**. + - Install [Node.js](http://go.microsoft.com/fwlink/?LinkID=396867) and you'll also need to install the [Git command line tools](http://go.microsoft.com/fwlink/?LinkID=396870) on Windows. Note that the default option for Git's install does not place the tools in the path. Select option to run the tools from the command prompt. + - **Android** requires the [Java](http://go.microsoft.com/fwlink/?LinkID=396871), [Ant](http://go.microsoft.com/fwlink/?LinkID=396869) (Cordova < 5.0.0 only), and the [Android SDK](http://go.microsoft.com/fwlink/?LinkID=533747) with the correct API level installed (usually API 21 or 22). Add environment variables for ANDROID_HOME pointing to your Android SDK install, ANT_HOME to your Ant install, and JAVA_HOME to your Java install. Add %ANT_HOME%\bin to your path. + - **iOS** requires Xcode (from the Mac app store) and [Node.js](http://go.microsoft.com/fwlink/?LinkID=396867) + - See the [General CI tutorial](./General.md#depends) or [Install Dependencies Manually](https://msdn.microsoft.com/en-us/library/dn771551.aspx) in MSDN for some information on what to install for a given platform. - 1. You do not need to install Android Studio or Eclipse +2. Add these lines to a package.json file in your project. Use [this version](https://github.com/Chuxel/taco-team-build/blob/master/samples/gulp/package.json) if you do not yet have a package.json file in the root of your project. - 2. Instead you may download and install one of the ["SDK Tools Only" packages](http://go.microsoft.com/fwlink/?LinkID=533747). - - 3. When building, you may encounter an error telling you that you need to install specific SDK versions or tools depending on the version of Cordova you are using. Note that these messages are talking about the *tools and SDK* versions *not* the device target versions. - - 1. You can install additional SDKs using [the Android SDK Manager](http://go.microsoft.com/fwlink/?LinkID=533775). - - 2. Note that only the "SDK Platform" is required for a given API level so you may uncheck other options. Android system images in particular are large and are not needed. - - 3. Be sure to also install the "platform tools" - - 4. Projects created using Visual Studio will typically use either the API SDK 19, 21, or API 22. - - 2. OSX only: [iOS Platform Guide](http://go.microsoft.com/fwlink/?LinkID=533776) - - 3. Windows only: - 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 -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 -- GitHub: https://github.com -- Apache ASF Git: https://git-wip-us.apache.org -- gradle.org: http://services.gradle.org -- maven.org: https://*.maven.org - -If you need to use a proxy, you will need to configure both npm and Git command line tools to use them. Open a command prompt on Windows or the Terminal app on OSX and type the following: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -npm config set proxy http://:@ -npm config set https-proxy http://:@ -git config --global http.proxy http://:@ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -...where "<username>:<password>@" is optional and should contain the appropriate user name and password for proxy access while <host> is the correct proxy host and port (ex: myproxy.mycompany.com:8080). - -You may also need to configure proxy settings for Java. This can be [accomplished via the Java control panel (reccomended)](http://java.com/en/download/help/proxy_setup.xml) or by setting an environment variable as the follows: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -JAVA_OPTS=-Dhttps.proxyHost= -Dhttps.proxyPort= -Dhttp.proxyHost= -Dhttp.proxyPort= -DproxySet=true -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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](../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: - -1. **Building with Multiple Versions of the Cordova CLI.** While in an ideal world everyone would use the edge version of the Cordova CLI and associated platforms, the reality is that for a given build server you will want to use multiple versions of the Cordova CLI. This means that the common practice of installing Cordova [globally](http://go.microsoft.com/fwlink/?LinkID=533780) will not work. - -2. **Adding Cordova Platforms.** As of Cordova 4.3.0, the "cordova platform add" CLI command still needs to be explicitly run to build a platform unless you opted to check in the contents of the "platforms" folder which is not recommended. However, using the platform command can cause your build to fail under certain circumstances. - -3. **Generating an iOS App Store Package.** By default, the iOS build in Cordova generates an ".app" structure rather than an ".ipa" for device deployment. An ipa can be generated from the command line quite easily but build servers like Jenkins require an extra step. - -4. **Visual Studio Specific Features** - 1. **Supporting res/native.** The "res/native" folder in Visual Studio projects provides a useful way to update native project build artifacts without having to check in the platforms folder. It is not currently a base Cordova CLI feature. - 2. **Supporting Visual Studio specific Windows packaging settings.** Currently the Cordova CLI does not have a standard location for storing platform specific packaging information. While this is something actively being pursued by the community, Visual Studio uses a set of non-standard config.xml elements to store mandatory fields for store submission. - 3. **Supporting the Task Runner Explorer.** Visual Studio now has a convenient Task Runner Explorer that allows you to attach Gulp and Grunt tasks to build events. - -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. - -#### Project Level -Installing and using the correct version of the Cordova CLI at the project level is simple thanks to something called [package.json](http://go.microsoft.com/fwlink/?LinkID=533781). Here is the general approach: - -1. Create a package.json file in the root of your Cordova project. -2. Add the following json to the file where "4.3.0" is the version of the Cordova CLI you intend to use: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~ { - "devDependencies": { - "cordova": "4.3.0" - } + "devDependencies": { + "gulp": "latest", + "gulp-typescript": "latest", + "taco-team-build": "http://aka.ms/tacoteambuild-rel" + } } - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -3. Check this into source control with your project. - -4. Configure your build system to run the following command as its first task. This will then install the correct version of the CLI in a new "node\_modules" folder under your project. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - npm install - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -5. When executing a Cordova CLI command for your build task, you can then use the following commands: - - Windows: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - node_modules\cordova\bin\cordova - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~ - OSX: +3. Add [this Gulp file](https://github.com/Chuxel/taco-team-build/blob/master/samples/gulp/gulpfile.js) to the root of your project - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ./node_modules/cordova/bin/cordova - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ![gulpfile.js in project]() - Ex: +4. Test out your build by dropping to the command line, and running the following commands from the root of your Cordova project (not the solution root): - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ./node_modules/cordova/bin/cordova platform add android - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The downside of this method is that you will end up installing the Cordova CLI each time you execute a "clean" build which will slow down your build times particularly on Windows as the CLI consists of around 25mb of small files. - -### Global Cache -To avoid re-installing each time, you can take advantage of Visual Studio's **taco.json** file and a Node.js script to perform the installation in a specific location that you then use to execute Cordova commands. - -1. Add an environment variable to your system (or build) called **CORDOVA\_CACHE** pointing to where you want to create "cache" of the different versions of the Cordova CLI used to build your projects. - -2. Add this node.js script to your project and call it "setup-cordova.js": - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - var fs = require("fs"), - path = require("path"), - exec = require("child_process").exec; - - // Load taco.json - var taco = require("./taco.json"); - var cordovaVersion = taco["cordova-cli"]; - - // Check if Cordova is already present in the cache, install it if not - var cordovaModulePath = path.resolve(process.env["CORDOVA_CACHE"], cordovaVersion); - if (!fs.existsSync(cordovaModulePath)) { - fs.mkdirSync(cordovaModulePath); - fs.mkdirSync(path.join(cordovaModulePath, "node_modules")); - console.log("Installing Cordova " + cordovaVersion + "."); - exec("npm install cordova@" + cordovaVersion, { cwd: cordovaModulePath }, function (err, stdout, stderr) { - console.log(stdout); - if (stderr) { - console.error(stderr); - } - if (err) { - console.error(err); - process.exit(1); - } - console.log("Cordova " + cordovaVersion + " installed at " + cordovaModulePath); - }); - } else { - console.log("Cordova " + cordovaVersion + " already installed at " + cordovaModulePath); - } - - // Create shell scripts - if (process.platform == "darwin") { - // OSX - fs.writeFileSync("cordova.sh", "#!/bin/sh\n" + path.join(cordovaModulePath, "node_modules", "cordova", "bin", "cordova") + " $@", "utf8"); - fs.chmodSync("cordova.sh", "0777") - } else { - // Windows - fs.writeFileSync("cordova.cmd", "@" + path.join(cordovaModulePath, "node_modules", "cordova", "bin", "cordova") + " %*", "utf8"); - } - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -3. In your team / CI build definition or script, add a build task to execute "node setup-cordova.js" from your project root - -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](../tutorial-gulp/gulp-ci.md) tutorial for additional information. - - -###Adding Platforms -Adding platforms in Cordova is quite simple using the "cordova platform" command. Ex: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -cordova platform add android -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -However, there are a couple of common problems when executing this command that you could run into. - - -1. **Platform Download Messages Result in Build Failures.** Where things can get a bit tricky is that Node.js emits warnings to "Standard Error." The issue is that "platform add" command can result in warnings being reported when the CLI is downloading a version of a given Cordova platform for the first time. This is not an error, but some build systems will assume anything sent to standard error means a build failure occurred. - - Many CI systems provide a "continue on error" option that you can select to get around this particular problem or you can pipe standard error to standard out if you'd prefer. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - cordova platform add ios 2>&1 - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -2. **Errors During Incremental Builds.** If you are doing an incremental build and the platform you are building has already been added, the resulting exit code will be non-zero and may be interpreted as a build failure. If your build system supports a "continue on error" option for a given task, you can simply select that. - - However, a more robust solution is to simply conditionally call "platform add" if the appropriate folder in the platforms folder in your project is not found. In the scripts below replace "cordova" with the appropriate command from the "Building with Multiple Versions of the Cordova CLI" section above. - - Windows: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - IF NOT EXIST platforms/android CALL cordova platform add android - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - OSX: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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). - -#### Using xcrun -Future versions of the Cordova CLI will likely support generating these archives directly. However, current state it is not supported so an Xcode command line tool needs to be used instead. Ex: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -xcrun -v -sdk iphoneos PackageApplication source.app -o dest.ipa -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In Cordova projects, the source ".app" package can be found in the platforms/ios/build/device folder in your project after a successful Cordova "device" build. As an important detail, "source.app" and "dest.ipa" above should be **absolute paths** and the name of the package is taken from the "Display Name" (widget/@name) in config.xml which may not match your project folder name. Ex: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -xcrun -v -sdk iphoneos PackageApplication "/Users/cdvusr/Documents/cordova/myapp/platforms/ios/build/device/My Cordova App.app" -o "/Users/cordova/Documents/cordova/myapp/platforms/ios/build/device/My Cordova App.ipa" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Each build system has a different mechanisms in place for passing the absolute path of the project to shell scripts, but typically it involves the use of an environment variable. For example, in Jenkins you can use the following: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -xcrun -v -sdk iphoneos PackageApplication "${WORKSPACE}/platforms/ios/build/device/My Cordova App.app" -o "${WORKSPACE}/platforms/ios/build/device/My Cordova App.ipa" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This command will automatically match a developer signing identitiy (when building Debug) or distribution (when building Release) signing identity based on the app's package name. When you are using res/native, you can place a custom [build-debug.xcconfig](http://go.microsoft.com/fwlink/?LinkID=533752) or [build-release.xcconfig](http://go.microsoft.com/fwlink/?LinkID=533782) file in res/native/ios/cordova in your Cordova project to override signing identities and other [build settings](http://go.microsoft.com/fwlink/?LinkID=533783) for these configurations. - -However, additional command line arguments can also be passed such as "--sign" to resign the app using a specific signing identity or a path to a .p12 file and "--embed" to specify the path to a provisioning profile. Ex: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -xcrun -v -sdk iphoneos PackageApplication "${WORKSPACE}/platforms/ios/build/device/My Cordova App.app" -o "${WORKSPACE}/platforms/ios/build/device/My Cordova App.ipa" –-sign "/path/to/signing.p12" --embed "/path/to/some.mobileprovision" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -#### Solving Keychain Permission Errors -When auto-matching, you may hit permissions issues when using a build server like [Jenkins](http://go.microsoft.com/fwlink/?LinkID=533784) because the build agent does not have permissions to access the login keychain. To solve this problem, you'll need to unlock the keychain before you build and package your Cordova app. - -Most build servers provide a way to inject secure environment variables before executing build tasks. In Jenkins this is accomplished by using the "Environment Injector Plugin." By then setting a KEYCHAIN\_PWD environment variable you can add the following command to your build. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -security unlock-keychain -p ${KEYCHAIN_PWD} ${HOME}/Library/Keychains/login.keychain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To then build and package your iOS app, you can run the following commands: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -security unlock-keychain -p ${KEYCHAIN_PWD} ${HOME}/Library/Keychains/login.keychain -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](../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. - -##### Behind the Scenes: res/native Hook -If you are using Tools for Apache Cordova in Visual Studio, you may be taking advantage of the "res/native" folder in your project. This provides a useful way to update native project build artifacts without having to check in the platforms folder but is not currently a base Cordova CLI feature. - -You can take a look at the sample [Tools for Apache Cordova CLI Support Plugin](http://go.microsoft.com/fwlink/?LinkID=533753) for a quick way to add in support. The plugin takes advantage of something called a [Cordova hook](http://go.microsoft.com/fwlink/?LinkID=533744) that allows you to wire in build steps in the Cordova CLI build process. A Cordova hook can be implemented using either shell scripts (batch, bash, or Node.js based) or as a node.js module. - -For this behind the scenes tutorial, we'll use a Node.js based shell script for simplicity sake. All that needs to happen is the following script should be placed in the "hooks/before\_prepare" folder. We will call the file "hook-res-native.js" but the filename itself does not matter. - -Add the following to the file: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/env node -var fs = require("fs"), - path = require("path"); - -process.env["CORDOVA_PLATFORMS"].split(",").forEach(function(platform) { - console.log("Processing res/native for " + platform); - var resNative = path.join(process.cwd(), "res", "native", platform) - if (fs.existsSync(resNative)) { - copyFiles(resNative, path.join(process.cwd(), "platforms", platform)); - } -}); - -// Recursive copy function for res/native processing -function copyFiles(srcPath, destPath) { - if (fs.statSync(srcPath).isDirectory()) { - if (!fs.existsSync(destPath)) { - fs.mkdirSync(destPath); - } - fs.readdirSync(srcPath).forEach(function (child) { - copyFiles(path.join(srcPath, child), path.join(destPath, child)); - }); - } else { - fs.writeFileSync(destPath, fs.readFileSync(srcPath)); - } -} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - -1. **You are seeing permission errors from "npm":** If you are seeing permission errors from "npm," you may be running into a situation where the build agent user's cache folder (~/.npm) is inaccessible. Generally this occurs if the folder or some of its contents was created while running as an administrator (sudo). Fortunately this is easy to resolve: + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + npm install + node_modules\.bin\gulp + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ...or on a Mac... - 1. Log into OSX with the user that installed and set up the cross-platform agent - 2. Open the Terminal app and type: + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + npm install + ./node_modules/.bin/gulp + ~~~~~~~~~~~~~~~~~~~~~~~~~~ - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - sudo npm cache clear - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You can also install Gulp globally (npm install -g gulp) and omit "node_modules\\.bin" from the command above. - 3. Next, type: + Gulp will now build Android, Windows, and Windows Phone 8 versions of your project when run from Windows and iOS when run from OSX. You can change this behavior by updating the following lines in gulpfile.js. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + var winPlatforms = ["android", "windows", "wp8"], + osxPlatforms = ["ios"], + ... + ~~~~~~~~~~~~~~~~~~~~~~~~~~ - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - sudo chown -R `whoami` ~/.npm - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +5. Assuming all goes well, add your project into the appropriate source code repository. -3. **You checked in the "platforms" folder from Windows and are seeing permission errors:** If you are seeing errors that are originating from files in your project's "platforms" folder, the root cause may be that you checked in shell scripts under the "platforms/android/cordova" or "platforms/ios/cordova" folders from Windows. This is because the NTFS file system has no concept of an "execute bit" that is required to run these from OSX. (The contents of the platforms is generally not intended for checked in and by default are excluded from Cordova projects in Visual Studio as a result.) +6. Next, configure your Team / CI server to fetch your project and execute the exact same commands mentioned above from the root of your Cordova project after fetching the source code. - For example, this error is saying the "version" script is not executable: +7. Finally, configure an build agent / slave on both Windows and OSX so you can build for any platform. See the tutorials below for some specifics on how to configure your CI system. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - [17:41:57] Error: - /Users/vsoagent/vsoagent/agent/work/build/b424d56537be4854de825289f019285698609afddf826d5d1a185eb60b806e47/repo/tfs-vnext test/platforms/android/cordova/version: - Command failed with exit code EACCES - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +That's it! - 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**](../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: +For additional detail on configuring specific build systems, see the following detailed tutorials: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - #!/bin/sh - find -E platforms/ios/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + - find -E platforms/android/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + - find -E platforms/windows/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + - find -E platforms/wp8/cordova -type f -regex "[^.(LICENSE)]*" -exec chmod +x {} + - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- **[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)** - 2. Add this file to your project in Visual Studio and check it into source control +The following articles also provide some additional details and troubleshooting information: - 3. Add a "shell script" build step at the very beginning of your build definition that runs the above script. +- **[Getting Started with Cordova & Automating Builds with Gulp](../tutorial-gulp/gulp-ci.md)** +- **[General Information on Building in a CI Environment](./General.md)** ## More Information * [Read tutorials and learn about tips, tricks, and known issues](../Readme.md) diff --git a/tutorial-team-build/TFS2013.md b/tutorial-team-build/TFS2013.md index 000d6fb4..9d204bba 100644 --- a/tutorial-team-build/TFS2013.md +++ b/tutorial-team-build/TFS2013.md @@ -10,7 +10,7 @@ It is important to note that as a general recommendation, we encourage the use o 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 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. +**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](./General.md#whattoadd) 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 TFS build agent on the server you have installed Visual Studio 2015. @@ -18,7 +18,7 @@ Before getting started with setting up your TFS Build Agent, you should install - 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. -**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. +**Troubleshooting Tip:** See ["Internet Access & Proxy Setup" in the general CI tutorial](./General.md#proxy) 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 @@ -101,7 +101,7 @@ Building for iOS with TFS 2013 requires that a TFS agent running on Windows be c 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. +**Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](./General.md#osxgotcha) 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 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). diff --git a/tutorial-team-build/TFS2015.md b/tutorial-team-build/TFS2015.md index cfbbf3a8..378950c3 100644 --- a/tutorial-team-build/TFS2015.md +++ b/tutorial-team-build/TFS2015.md @@ -3,30 +3,30 @@ 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. -**Advisory: You may encoutner a "EPERM" error when executing these instructions in Visual Studio Online.** We are working with the VSO team to resolve a permissions issue with cache locations. Short term you can work around the issue adding a "Variable" to your build definition called "CORDOVA_CACHE" with a value of "C:\cordova-cache" and a variable of "GRADLE_USER_HOME" with a value of "c:\gradle". This will force the tools to be re-acquired instead of using the cached versions. +**Advisory: You may encoutner a "EPERM" error when executing these instructions from a "Hosted" agent in Visual Studio Online.** We are working with the VSO team to resolve a permissions issue with cache locations. Short term you can work around the issue adding a variable under the "Variables" tab of build definition called "CORDOVA_CACHE" with a value of "C:\cordova-cache" and a variable of "GRADLE_USER_HOME" with a value of "c:\gradle". This will force the tools to be re-acquired instead of using the cached versions. Note that this will not occur at all if you use your own build agents. ##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. 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. +**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](./General.md#whattoadd) 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](./README.md) 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#depends) tutorial for details. 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](./README.md) 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](./General.md#proxy) 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 though you can use the VSO Cross-Platform Build agent with Visual Studio Online (see 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 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. +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 two environment variables due to a permissions issue. See [Short Term Workaround: VSO](#vso) for details if you encounter an EPERM error. You can skip this if you do not encounter an Ant related build error. ####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. @@ -51,7 +51,7 @@ 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 -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. +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 two environment variables due to a permissions issue. See [Short Term Workaround: VSO](#vso) for details if you encounter an EPERM error. You can skip this if you do not encounter an Ant related build error. ##Project Setup & Build Definitions ###Adding Gulp to Your Project @@ -129,32 +129,13 @@ Now let's create a version of this same build definition to target iOS that will 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. +**Troubleshooting Tip:** See ["Troubleshooting Tips for Building on OSX" in the general CI tutorial](./General.md#osxgotcha) for tips on resolving common build errors that can occur when building Cordova projects on that operating system. - -## 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. + +## Short Term Workaround for EPERM Error with VSO Hosted Agents +You may encoutner a "EPERM" error when executing these instructions from a "Hosted" agent in Visual Studio Online. We are working with the VSO team to resolve a permissions issue with cache locations. Short term you can work around the issue adding a "Variable" to your build definition called "CORDOVA_CACHE" with a value of "C:\cordova-cache" and a variable of "GRADLE_USER_HOME" with a value of "c:\gradle". This will force the tools to be re-acquired instead of using the cached versions. Note that this will not occur at all if you use your own build agents. -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: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - @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]() +![VSO Workaround]() You are now ready to go in VSO! diff --git a/tutorial-team-build/media/quick-1.png b/tutorial-team-build/media/quick-1.png new file mode 100644 index 00000000..ab6860c5 Binary files /dev/null and b/tutorial-team-build/media/quick-1.png differ diff --git a/tutorial-team-build/media/vso-workaround.png b/tutorial-team-build/media/vso-workaround.png new file mode 100644 index 00000000..7e582e71 Binary files /dev/null and b/tutorial-team-build/media/vso-workaround.png differ