TFS2015.md

#Using Tools for Apache Cordova with Visual Studio Online and Team Foundation Services 2015 Note that this documentation applies to Visual Studio 2015 and does not apply to Visual Studio 2013 CTPs.

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 (CLI) projects. Team Foundation Services 2015 provides a new cross-platform agent and 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" 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 MSBuild, see the TFS 2013 tutorial for details on setup. The instructions generally still apply to TFS 2015.

##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 tutorial for details.

For OSX, the pre-requisites will need to be installed manually, but mirror the requirements for the Visual Studio remote build agent. 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.

Next you will need to install the Windows build agent to build Android, Windows, or Windows Phone, and the cross-platform build agent on an OSX machine if you intend to build iOS. See TFS 2015 documentation for detailed instructions on configuring the agent for use with an on premise TFS 2015 instance or Visual Studio Online.

##Environment Variables You should set the following environment variables if they have not already been configured. Note that you can also set these in the "Variables" section of your build definition if you would prefer.

Variable	Required For	Purpose	Default Location (Visual Studio 2015)
ANDROID_HOME	Android	Location of the Android SDK	C:\Program Files (x86)\Android\android-sdk
JAVA_HOME	Android	Location of Java	C:\Program Files (x86)\Java\jdk1.7.0_55
ANT_HOME	Android when building using Ant (not Gradle)	Location of Ant	C:\Program Files (x86)\Microsoft Visual Studio 14.0\Apps\apache-ant-1.9.3
CORDOVA_CACHE	Optional	Improves build performance on Windows. Used by the sample build script to cache multiple versions of Cordova rather than installing local to the project.

Node.js should already be in your path simply by the fact that you've setup the cross-platform build agent, but if not you will want to be sure it is configured for use. Git command line tools should also be in the path if you intend to use plugins that require git (which is uncommon).

##Project Setup & Build Definitions ##Adding Gulp to Your Project Using Gulp in a team environment is fairly straight forward as you can see in the detailed Gulp tutorial. However, to streamline setup, follow these steps:

1. Take the sample "gulpfile.js" and "package.json" file from the "samples/gulp" folder of the from this GitHub repo and place them in the root of your project

2. Check these three two into source control with your project

From here you can modify gulpfile.js and add other gulp plugins. The Gulp tutorial provides additional detail on what the gulpfile does and how to wire Gulp tasks as "hooks" into Cordova build events.

###Creating Your Build Definitions We'll assume for the purposes of this tutorial that we want to build our Cordova app for Android, iOS, and Windows. The Windows Cordova platform can only be built on Windows and iOS can only be built on OSX. As a result, we'll need the ability to be able to queue a build that can target one of these two operating systems.

There are two ways that this can be accomplished:

1. Setting up separate build queues for OSX vs Windows machines and then queueing the same build definition in the appropriate build queue based on the desired platform

2. Using the concept of a "demand" in two separate build definitions to route the work to the correct OS from the same queue

For the sake of this tutorial, we'll cover option 2. The sample "gulpfile.js" assumes you want to build Android, Windows, and Windows Phone on Windows and iOS on OSX. Technically you could also opt to have Android built on OSX but we will not cover that in detail in this tutorial.

Build Definition for Windows

Detailed instructions on creating build definitions in TFS 2015 can be found in its documentation, but here are the specific settings you will need to use to configure a build.

1. Create a new build definition and select "Empty" as the template. We'll start out targeting platforms that can be built on Windows so give the build definition a name that indicates that this is the case.

2. Now we will configure the build definition to install any Gulp or npm package dependencies your build may have.

   1. Under the "Build" tab, add a new build step and select npm install from the Package category
   2. Set Advanced => Working Directory to location of the Cordova project itself inside your solution (not the solution root).

   

3. Next we'll configure Gulp itself. Under the "Build" tab, add a new build step and select Gulp from the Build category and use the following settings:

   1. Gulp File Path: The location of gulpfile.js in your solution (likely inside the Cordova project itself)
   2. Advanced => Working Directory: The location of the Cordova project itself inside your solution (not the solution root)

   

4. Next we need to ensure that this particular build runs on Windows rather than OSX. Under the "General" tab, add a demand that "windir" exists.

   

5. As an optional step, you can configure your build to upload the resulting build artifacts to your TFS or VSO instance for easy access. The sample gulpfile.js script places the resulting output in the "bin" folder to make configuration simple. Under the "Options" tab:

   1. Copy to Staging Folder: Checked
   2. Copy to Staging Folder => Search Pattern: */bin
   3. Create Build Drop: Checked
   4. Create Build Drop => Drop location: Server

   

6. Click the "Queue build..." button to validate your setup. You'll see a real-time console view of your build progressing so you can quickly fine tune your definition.

That's it for Windows!

Build Definition for OSX

Now let's create a version of this same build definition to target iOS that will run on a configured cross-platform agent on OSX.

1. Right click on the Windows build definition and select "Clone." Once you save you should give this definition a name that indicates it's the OSX build.

2. Now we need to add a demand that will route builds to OSX machines rather than Windows. Under the "General" tab, remove the "windir" demand and add a demand that "xcode" exists.

   

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.

See "Troubleshooting Tips for Building on OSX" in the general CI tutorial for tips on resolving common build errors that can occur when building Cordova projects on that operating system.