Tools for Apache Cordova is designed to work with a number of different continuous integration systems since the projects it creates are standard Apache Cordova Command Line interface (CLI) projects. Team Foundation Services 2013 cannot take advantage of this fact as it is designed to work with MSBuild and cannot directly build on a Mac for iOS. However, if you have an existing Team Foundation Services 2013 installation and cannot upgrade to TFS 2015 or use Visual Studio Team Services this tutorial can help get you started.
Note: This tutorial is here for historical purposes for TFS 2013 specifically. We strongly encourage the use of Visual Studio Team Services or TFS 2015's next generation cross-platform build system rather than TFS 2013 or the MSBuild/XAML based build system since the new build system requires far less setup and provides the ability build directly from TFS on Windows or OSX. You can even build iOS in the cloud using MacinCloud's VSTS plan. See the Visual Studio Team Services / TFS 2015 tutorial for details.
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.
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 CI guide for additional details.
- See Tools for Apache Cordova documentation for setup details on Visual Studio 2015.
- See Team Foundation 2013 Build documentation for setup details on Team Foundation Services 2013.
Troubleshooting Tip: See "Internet Access & Proxy Setup" in the general CI tutorial if your build servers have limited Internet connectivity or require routing traffic through a proxy.
Before you get started, it's important to note that you will need to use v14 of MSBuild when building a Tools for Apache Cordova project. Build definition templates that ship with TFS 2013 support v11 and v12. As a result, you will need to create a modified TFS Build Process Template for TFS to use MSBuild v14.0. To do this, you can simply download the TfvcTemplate.12.xaml MSBuild v12 template (or your own custom one) and append ToolVersion="14.0" to the end of the RunMSBuild element and upload it as a new template. Ex:
<mtba:RunMSBuild ToolVersion="14.0" DisplayName="Run MSBuild" OutputLocation="[OutputLocation]" CleanBuild="[CleanBuild]" CommandLineArguments="[String.Format("/p:SkipInvalidConfigurations=true {0}", AdvancedBuildSettings.GetValue(Of String)("MSBuildArguments", String.Empty))]" ConfigurationsToBuild="[ConfigurationsToBuild]" ProjectsToBuild="[ProjectsToBuild]" ToolPlatform="[AdvancedBuildSettings.GetValue(Of String)("MSBuildPlatform", "Auto")]" RunCodeAnalysis="[AdvancedBuildSettings.GetValue(Of String)("RunCodeAnalysis", "AsConfigured")]" />
See TFS 2013 documentation for additional information on modifying build process templates.
You can then create a build definition for your project and select this updated template.
To get the resulting packages from the Cordova build process to land in the configured TFS drop folder, you will need to add in a simple post-build PowerShell script to your project.
First, create a PowerShell script called postbuild.ps1 in your project under a solution folder that contains the following script:
$packages = gci $Env:TF_BUILD_SOURCESDIRECTORY -recurse -include $("bin") | ?{ $_.PSIsContainer } | foreach { gci -Path $_.FullName -Recurse -include $("*.apk", "*.ipa", "*.plist", "*.xap") }
foreach ($file in $packages) {
Copy $file $Env:TF_BUILD_BINARIESDIRECTORY
}
gci $Env:TF_BUILD_SOURCESDIRECTORY -recurse -include $("AppPackages") | ?{ $_.PSIsContainer } | Copy -Destination $Env:TF_BUILD_BINARIESDIRECTORY –Recurse -Force
This will copy any .apk, .ipa, or .plist file from the project's "bin" folder to the drop location and will also grab generated AppPackages under the platforms/windows/AppPackages folder from your project. Place this script under a solution folder such as "build".
Now, create a build definition if you have not done so already and add the PowerShell script as a post-build script under "Process => Build => Advanced => Post-build script path". The file will be under the solution so you will need include the solution folder name in the path. You will also want to ensure your build definition with the output location (Process => Build => 4. Output location) as "SingleFolder" rather than AsConfigured.
There are a set of environment variables that need to be made available to MSBuild when using Tools for Apache Cordova Update 4 and below. They should no longer be required as of Update 5. These can either be setup on your machine as system environment variables or using the "/p" option in your build definition (Process => Advanced => MSBuild Arguments).
Use full, absolute paths and be sure to remove any leading or trailing spaces in your variable paths! Also note that whenever you set a system environment variable you will need to restart the build service to get it to pick up the change.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Variable | Required For | Purpose | Default Location (Visual Studio 2015) |
| MDAVSIXDIR | Any operation | Location of the Tools for Apache Cordova VSIX. With Visual Studio 2015, its location is always the same. In VS 2013, you will need to search for the VSIX by finding a folder containing the "vs-mda-targets" folder. | C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\ApacheCordovaTools |
| NODEJSDIR | Any operation | Location of Node.js | C:\Program Files (x86)\nodejs |
| NPMINSTALLDIR | Any operation | Location to install npm packages when building. | C:\Users\your-user-here\AppData\Roaming\npm |
| LANGNAME | Any operation | Language used for VS generated Cordova build messages. | en-us |
| BUILDVERBOSITY | Any operation | Logging level for the Node.js portion of the build. Set using the /p MSBuild argument in your build definition (Process => Advanced => MSBuild Arguments). |
Normal |
| GIT_HOME | Optional: Plugins Acquired via Git | Location of the Git Command Line Tools | C:\Program Files (x86)\git |
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.
Cordova 5.0.0+ uses the Gradle build system for Android and force starts up a build daemon process that can result in hangs when building with TFS 2013 as the build agent will wait for the daemon to stop if it was started during the build. You will typically see this happen the first time you do a Cordova build after a restart. Cancelling the hung build will resolve the issue as the daemon is then running for subsequent build requests. To avoid this problem entirely, you can add a "hook" to your project that will simply shut down the daemon after a build.
Simply create stopGradle.cmd in the hooks\after_compile folder in your project with the following contents:
IF EXIST platforms\android platforms\android\gradlew --stop
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).
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>Note: Whenever you set a system environment variable you will need to restart the build service to get it to pick up the change.
| Variable | Required For | Purpose | Default Location (Visual Studio 2015) |
| ANT_HOME | Android in Cordova < 5.0.0 | Location of Ant | C:\Program Files (x86)\Microsoft Visual Studio 14.0\Apps\apache-ant-1.9.3 |
| ANDROID_HOME | Android | Location of the Android SDK | C:\Program Files (x86)\Android\android-sdk |
| JAVA_HOME | Android | Location of Java | C:\Program Files (x86)\Java\jdk1.7.0_55 |
| GRADLE_USER_HOME | Optional for Cordova 5.0.0+ | Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ | If not specified, uses %HOME%\.gradle |
In addition to your other build definition settings, you will want to use the following build parameter values.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Parameter | Purpose | Value |
| Process => Items To Build => Configurations to Build | Platform to build | Configuration: Debug or Release Platform: Android |
| Process => Advanced => MSBuild Arguments | Indicates the type of build to create: emulator, ripple, or device. | /p:DebuggerFlavor=AndroidDevice |
Building for iOS with TFS 2013 requires that a TFS agent running on Windows be configured to communicate with a Visual Studio remote build agent running on OSX. See the remote agent section of the Tools for Apache Cordova installation documentation for details on setting up the remote agent on OSX.
Note that Visual Studio 2015 RTM uses a different remote agent package (remoteagent) than the vs-mda-remote agent used in VS 2015 RC and below.
If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target.
Troubleshooting Tip: See "Troubleshooting Tips for Building on OSX" in the general CI tutorial for tips on resolving common build errors that can occur when building Cordova projects on that operating system.
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).
For iOS, using a system environment variable is most useful when you want a single iOS build definition to built on a number of separate Windows TFS based build agents with a set of different OSX remote build agents instances in your build farm.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Variable | Required For | Purpose | Example |
| iOSRemoteSecureBuild | iOS | Indicates whether a secure connection should be used to connect to the agent | true |
| iOSRemoteBuildServer | iOS | URI of the iOS remote agent. Form: http(s)://<host>:<port>/cordova Use "https" in secure mode. |
https://chux-mini.local:3000/cordova |
| iOSCertificateName | iOS | Name of the SSL certificate for secure mode. Form: remotebuild.<host> |
remotebuild.chux-mini.local |
By far the easiest way to import the client SSL certificate used for secure remote build is to simply start up Visual Studio and configure the remote agent there. This will import the client SSL cert into your local certificate store so it can be used during build. See Tools for Apache Cordova documentation for details.
Note: You also need to configure the TFS build service on your build server to run using the same user that you used to log in and configure Visual Studio.
However, it is also possible to manually import the SSL cert by following these steps:
-
Generate a security PIN. This automatically occurs the first time you start up the remote build agent but you can also generate a new one using the following command:
remoteagent generateClientCert -
Get the generated .p12 file from the agent using the following URI in a browser using substituting host, port, and PIN from the agent output.
https://<host>:<port>/certs/<pin>Be sure you start the remote agent if it is not running before accessing this URI.
-
Ignore the SSL security warning that may appear and download the .p12 file and save it. Note: For security reasons, this PIN will be automatically invalidated after you download the file. You may, however, use the cert file on multiple machines if needed.
-
You now simply open the p12 file from the file system to import the cert using into your user's certificate store by accepting all the defaults in the Certificate Import Wizard that appears.
In addition to your other build definition settings, you will want to use the following build parameter values.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Parameter | Purpose | Value |
| Process => Items To Build => Configurations to Build | Platform to build | Configuration: Debug or Release Platform: iOS |
| Process => Advanced => MSBuild Arguments | Indicates the type of build to create: simulator, ripple, or device. | /p:DebuggerFlavor=iOSLocalDevice |
If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target.
In addition to your other build definition settings, you will want to use the following build parameter values.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Parameter | Purpose | Value |
| Process => Items To Build => Configurations to Build | Platform to build | Configuration: Debug or Release Platform: One or more of the following depending on the chipsets you need to support: Windows-AnyCPU Windows-ARM Windows-x64 Windows-x86 |
| Process => Advanced => MSBuild Arguments | Indicates the type of build to create: simulator or device. | /p:DebuggerFlavor=WindowsLocal |
In addition to your other build definition settings, you will want to use the following build parameter values.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Parameter | Purpose | Value |
| Process => Items To Build => Configurations to Build | Platform to build | Configuration: Debug or Release Platform: Windows Phone (Universal) |
| Process => Advanced => MSBuild Arguments | Indicates the type of build to create: emulator or device. | /p:DebuggerFlavor=AppHostLocalDebugger |
If you have not already, create a build definition for your project. Note that currently you'll will need a separate build definition for each device platform you intend to target.
In addition to your other build definition settings, you will want to use the following build parameter values.
<style> table, th, td { border: 1px solid black; border-collapse: collapse; } th, td { padding: 5px; } </style>| Parameter | Purpose | Value |
| Process => Items To Build => Configurations to Build | Platform to build | Configuration: Debug or Release Platform: Windows Phone 8 |
| Process => Advanced => MSBuild Arguments | Indicates the type of build to create: emulator or device. | /p:DebuggerFlavor=PhoneDevice |