Build Apache Cordova apps

Last Update: 3/6/2017

Team Services | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

Notice: Apple's WWDR certificate expired on Feb 14th and as a result you may experience signing failures if you have not updated the cert and removed the old one. Follow the steps outlined by Apple under What should I do if Xcode doesn’t recognize my distribution certificate? to resolve the problem. Note that this also affects development certs despite the title.

Visual Studio Team Services (formerly Visual Studio Online) and Team Foundation Services (TFS) 2015 can be used for building and testing Cordova apps in a Continuous Integration (CI) environment thanks to a new cross-platform agent that supports OSX. The end result is you can use Visual Studio Team Services or TFS to build projects created using Tools for Apache Cordova or any Cordova compliant CLI like the Ionic, PhoneGap, or TACO CLI.

To streamline CI for Cordova-based projects, we have created a series of build tasks (or steps) that you can use: Cordova Build, Cordova Command, Ionic Command, and PhoneGap Command. These tasks will automatically handle fetching the correct version of the appropriate CLI and even setup the correct version of Node.js for you if not present!

Article sections:

Installing the Cordova Build task

To setup a Cordova build in Visual Studio Team Services or TFS 2015, you will need to install the Cordova Build task in your collection.

Project setup and build definitions

We'll assume for the purposes of this tutorial that you want to build a Cordova app for Android, iOS, and Windows and you want to build everything on Windows except iOS. We will accomplish this by using the concept of a "demand" in two separate build definitions to route the work to the correct OS.

Create the definition

  1. Open your team project in your web browser.

    • On-premises http://{your_server}:8080/tfs/DefaultCollection/{your_team_project}
    • Visual Studio Team Services https://{your_account}.visualstudio.com/DefaultCollection/{your_team_project}
  2. Create a build definition.

    New build definition

  3. Click Empty to start with an empty definition.

Building Android, Windows, or Windows Phone 8.0 on 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 to run on a Windows agent. We'll start with Android but the steps here generally apply to the Windows and WP8 platforms as well.

  1. First we need to ensure that this particular build runs on Windows rather than OSX. Under the General tab, add a demand that cmd exists.

    Windows Build Definition - Demand

  2. Next we will add some build steps.

    Build: Cordova Build
    Build: Cordova Build

    Settings:

    • Platform: android
    • Configuration: debug or release. You can also use a variable from the Variables tab to allow you to select at build time.
    • Cordova Version: Version of the Cordova CLI you want to use to build. If you're using Tools for Apache Cordova you can leave this blank and the correct version will be used based on the contents of taco.json. Otherwise, if not specified, it uses the version specified by the CORDOVA_DEFAULT_VERSION environment variable (like in Team Services) and falls back to the latest version if no environment variable is set.
    • Android: You may use these values to specify signing information for this build. See securing your signing keys for details.
    • Advanced > Working Directory: Location of the Cordova project itself inside your repository.
    Utility: Copy and Publish Build Artifacts
    Utility: Copy and Publish Build Artifacts

    Settings:


    • Copy Root: Location specified in Advanced > Output Directory in the Cordova Build step. Defaults to "bin."
    • Contents: *
    • Artifact Name: bin
    • Artifact Type: Server
  3. Finally, save and click "Queue Build..." to test it out!

That's it for Windows! You're now able to build Android. To build Windows or Windows Phone 8.0, follow these same steps and replace the "platform" value with "windows" or "wp8" respectively.

Optional: Multi-Configuration setup for Android, Windows, Windows Phone 8.0

If you intend to build more than just one platform on Windows you can use something called a "Multi-Configuration" setup to build for multiple platforms from a single build definition.

  1. Go to the Variables tab and enter a variable called Platform with a comma separated list of platforms you want to build. Ex: android, windows, wp8

  2. Go to the Options tab, check MultiConfiguration, and set Multipliers to Platform

  3. Update the Platform value for the Cordova Build step to be $(Platform) and update any platform specific options as appropriate.

Next time you build, it will queue up and build all three platforms and store separate artifacts for each using the platform name.

Building iOS on 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.

Troubleshooting Tip: You should either setup the cross-platform agent as a launch agent (./svc.sh install agent) or run it as an interactive process (node agent/vsoagent.js) when building an Cordova project targeting iOS due to issues with code signing certificate storage when using a launch daemon.

  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 iOS build.

  2. Change the Platform value for the Cordova Build step to ios

  3. Update the iOS category for the Cordova Build step. See securing your signing keys for details on the appropriate options to set for your situation. Be sure to check out the "P12 Certificate File" and "Provisioning Profile File" options that can really streamline setup! The Xcode Developer Path option also allows you to specify the path of a different version of Xcode than you have installed locally. (Ex: /Applicaitons/Xcode6.4.app/Contents/Developer will use Xcode 6.4 in MacinCloud.)

    Windows Build Definition - npm

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

    OSX Build Definition - Demand

Troubleshooting Tip: If you encounter a spawn EACCES error when building on a Mac or Linux, be sure all files in the hooks folder to have an "execute bit" set as this a requirement for Cordova. To resolve, add an execute bit to the files in source control or add the following using the Command Line task for each file in the folder: chmod +x <file name goes here>

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 Tools for Apache Cordova CI tutorial for tips on resolving common build errors that can occur when building Cordova projects on that operating system.

Optional: Using Gulp for script compilation and running tests

Using Gulp in a CI environment can allow you to easily compile / transpile scripts (TypeScript, LESS, SASS) and even run tests thanks to the "Gulp" and "npm install" build steps.

TypeScript example

To add TypeScript compilation into your build definition using Gulp, follow these steps:

  1. Take the sample files (gulpfile.js, package.json, karma.config.js) from the "samples/gulp" folder in this GitHub repo and place them in the root of your project Cordova project

  2. Add these files to source control with your project. From here you can modify gulpfile.js and add other Gulp plugins as you see fit.

  3. Next we will add some Gulp related build steps before the other steps in the definition.

Package: npm
Package: npm (or the older npm install)

Settings:

  • Command: install
  • Advanced > Arguments: --no-optional
  • Advanced > Working Directory: Location of the Cordova project itself inside your solution (not the solution root).

If you encounter EPERM errors you may also need to specify the --force option.

Build: Gulp
Build: Gulp

Settings:


  • Gulp File Path: Location gulpfile.js in your Cordova project.
  • Gulp Task(s): The Gulp task you want to run. In this case, we'll run scripts
  • Advanced > Working Directory: Location of the Cordova project itself inside your repository.

Using Gulp to run tests

You can also use the exact same Gulp build step above to run your tests! The scripts from the GitHub repo mentioned above are ready for use with Jasmine, Karma, and PhantomJS. See the Cordova test tutorials for details on setting up Gulp to run your tests.

Next, we will configure the definition to publish your test results to VS Team Services or TFS.

Build: Gulp
Build: Gulp

Update the Gulp Task(s) option in the Gulp step above to reference your "test" task. A value of "scripts test" will first compile TypeScript (or anything else you have configured) and then run tests.

Test: Publish Test Results
Test: Publish Test Results

Settings:

  • Test Result Format: The Karma config in the sample is set up to output JUnit formatted results
  • Test Results Files: The Karma config in the sample is set up to drop results in a _results folder
  • Control Options > Always Run: Be sure to check this option so your test results are published when the tests fail.

Windows Build Definition - npm

That's it!

In Depth: Private build agent setup

As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Team Services. This allows you to build without setting up a Windows build agent on premise. MacinCloud provides a special plan and streamlined setup experience for Team Services agents targeted at buillding iOS in the cloud. All Cordova prerequisites should already be installed and configured when using the Hosted Agent Pool in Visual Studio Team Services or MacinCloud's special Team Services plan.

If you are not using the Visual Studio Team Services Hosted Agent Pool or MacinCloud's streamlined VS Team Services plan, you can use your own hardware instead. Because of its design, you can easily install the Windows agent on Windows or the cross-platform agent on a Mac and integrate with either TFS or Visual Studio Team Services. The build machine simply needs to have HTTP access to the server with your TFS collection or Visual Studio Team Services.

Custom Agent 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 prerequisites on Windows:

  1. You can install Visual Studio 2015 and select the Tools for Apache Cordova option and let it install the prerequisites for you.

  2. Otherwise you can manually install only the prerequisites 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 general Tools for Apache Cordova CI tutorial for additional details.

Next you will need to install the Windows build agent to build Android, Windows, or Windows Phone, and the cross-platform build agent on a Mac if you intend to build iOS (and Android if you so desire). See the new build system documentation for information on getting started with setting up an agent. It is important to note that you should setup the cross-platform agent as a launch agent (./svc.sh install agent) or run it as an interactive process (node agent/vsoagent.js) when building an Cordova project targeting iOS due to issues with code signing certificate storage when using a launch daemon.

Troubleshooting Tip: See Internet Access & Proxy Setup" in the general Tools for Apache Cordova CI tutorial if your build servers have limited Internet connectivity or require routing traffic through a proxy.

Environment variables

You should set the following environment variables if they have not already been configured on each server you have configured a build agent.

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
GRADLE_USER_HOME Optional Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+ If not specified, uses %USERPROFILE%.gradle on Windows or ~/.gradle on OSX or Linux
CORDOVA_CACHE Optional Overrides the default location used by the Cordova Build Task to cache installs of multiple versions of Cordova. If not specified, uses %APPDATA%\cordova-cache on Windows and ~/.cordova-cache on OSX or Linux

Setting your path

The following will also need to be in your path:

  • Node.js should already be in your path on OSX/Linux simply by the fact that you've setup the cross-platform build agent. However, on Windows you should ensure both Node.js and the global modules folder (aka "prefix" location) is in your path as there a circumstances where one or the other may be missing. The default location of Node.js on Windows is %PROGRAMFILES(x86)%\nodejs while the default location where global node modules are installed is %APPDATA%\npm.

  • Gulp should also be installed globally if you intend to use the Gulp task. Once Node.js is installed, simply type npm install -g gulp from the command line.

  • %ANT_HOME%\bin (or $ANT_HOME\bin on OSX/Linux) should be added to your path if you are using a version of Cordova < 5.0.0 or have checked the "Force Ant" build option.

More information

Q&A

What other kinds of apps can I build?

Build your app

What other kinds of build steps are available?

Specify your build steps

How do we protect our codebase from build breaks?

How do I modify other parts of my build definition?

I selected parallel multi-configuration, but only one build is running at a time.

If you're using Team Services, you might need more concurrent pipelines. See Concurrent build and release pipelines in Visual Studio Team Services.

How do I see what has changed in my build definition?

View the change history of your build definition

Do I need a build agent?

You need at least one agent to run your build. Get an agent.

I can't select a default agent queue and I can't queue my build. How do I fix this?

See queues.

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.