Creating a Build Definition for Team Foundation Server 2010

Before you can build your application, you must first create a build definition, which specifies which Ant or Maven projects to compile and where builds should occur. After you create a build definition, you can queue builds.

When you create build definitions for Visual Studio Team Foundation Server 2010, you can specify the trigger that causes the build to be queued automatically or you can manually run those builds. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

To create a build definition for Team Foundation Server 2010, you perform the following tasks:

• Open the Build Definition Dialog Box

• Specify a Name and Description for the Build Definition

• Specify the Build Trigger

• Specify the Working Folders to Include in the Build

• Specify the Default Settings for the Build

• Specify the Project File Location

• Specify the Retention Policy for the Build

• Save the Build Definition

Required Permissions

To perform this procedure, you must have the Edit Build Definition permission set to Allow. For more information, see the following page on the Microsoft Web site: Team Foundation Server Permissions.

Open the Build Definition Dialog Box

1. In Team Explorer, expand the team project for which you want to create a build definition.

2. Right-click the Builds node and click New Build Definition.

   The Build Definition dialog box appears. The General tab is active.

   Next, you specify a name and description for your build definition.

Specify a Name and Description for the Build Definition

1. Click the General tab.

2. In Build definition name, type the name that you want to give this build definition.

   The specified name must be unique within the team project.

3. (Optional) In Description, provide a description for this build definition.

4. (Optional) If you want to disable this build definition, click Disable this build definition.

   You might do this if, for example, you want to define an automated build, but are not yet ready for that build to run automatically.

Next, you specify the build trigger to define when a build should be run.

Specify the Build Trigger

You can specify one of the five types of build trigger with Team Foundation Server 2010:

• Build on demand (manual trigger)

• Build continuously on each check-in. If the build agent has not finished performing an earlier build, the new build will be queued.

• Each check-in should add a build to the queue to be run as soon as an agent is free.  This can also be limited so that a minimum time between builds is provided.  You might choose this option if your build takes a long time and you have a large number of check-ins that would result in an unacceptable number of builds in the build queue.

• Gated check-in builds. When a gated check-in build is created, changes that you submit are placed in a shelveset and automatically built in your build system. The build must be successful for the check-in process to be completed.

• Scheduled (daily) builds.  You can specify the days on which the build is performed and the time. You can also force the build to always run at that time, even if no changes have been performed in the intervening period.

  Note

  If you create the build definition on a computer that is in a different time zone than the computer on which the builds will run, the build might run at an unexpected time during a period when daylight savings between those two time zones is different.

To create a build definition that is triggered on demand

1. Click the Trigger tab.

2. Click Check-ins do not trigger a new build.

3. Click OK to save the build definition to the server.

   You should perform a test build to verify that your build definition is working as you expect. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

To create a build definition that builds continuously on each check-in

1. Click the Trigger tab.

2. Click Build each check-in.

3. Click OK to save the build definition to the server.

   You should perform a test build to verify that your build definition is working as you expect. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

To create a build definition that builds continuously as agents are available

1. Click the Trigger tab.

2. Click Accumulate check-ins until the prior build finished.

3. (Optional) If you want to further restrict the frequency of builds, select the Build no more often than every check box. In the minutes box, specify the minimum number of minutes that you want to elapse between builds.

4. Click OK to save the build definition to the server.

   You should perform a test build to verify that your build definition is working as you expect. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

To create a gated check-in build

1. Click the Trigger tab.

2. Click Gated Check-in – accept check-ins only if the submitted changes merge and build successfully. For more information about gated check-ins, see Check In Pending Changes that Are Controlled by a Gated Check-in Build (Team Explorer Everywhere).

3. Click OK to save the build definition to the server.

   You should perform a test build to verify that your build definition is working as you expect. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

To create a build definition that builds on a specified schedule

1. Click the Trigger tab.

2. Click Build every week on the following days.

3. Select the check boxes that correspond to the days on which you want the build to run.

4. In Queue the build on the default build agent at, specify the time at which you want the build to be queued.

5. (Optional) Select the Build even if nothing has changed since the previous build check box.

6. Click OK to save the build definition to the server.

   You should perform a test build to verify that your build definition is working as you expect. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

Next, you specify the working folders that you want to include in the build.

Specify the Working Folders to Include in the Build

On this tab, you specify the folders to include in the build. Each path is mapped to a relative location beneath a root build directory on the build agent that is referenced as $(SourceDir). The build agent will be running on a Windows operating system. Therefore, the relative Local Folder paths must be provided by using naming conventions for Windows directories. For example, you must use the backslash (\) as a path separator.

By default, the whole team project is included, but you should consider including only the folders that are necessary for your build definition. By doing this, you can reduce the number of files that are downloaded from version control to perform the build.

1. Click the Workspace tab.

2. To change the Working folders, perform one of the following tasks:

   • To copy another Team Foundation Server workspace definition, click Copy Existing Workspace and then specify the workspace that you want to copy.

   • To add a working folder, click Click here to enter a new working folder. Specify a Source Control Folder and a Local Folder for each working folder that you add. You can click browse (...) to specify the folders.

   • To delete a working folder, right-click the folder that you want to delete, and click Delete.

Next, you specify the default settings for the build.

Specify the Default Settings for the Build

You must specify a build controller and a drop location where build output will be staged.

1. Click the Build Defaults tab.

2. In Build Controller, specify the build agent that you want to use for the build definition.

3. Select the This build copies output files to a drop folder check box if it is not already selected.

4. In Builds will be staged to the following share, provide a valid path to a Windows file share (or a Samba share). The build server will copy the build output to this path.

   You must specify the path in the Uniform Naming Convention (UNC) format, such as \\ServerName\Share.

Next, you specify the location of the project file.

Specify the Project File Location

Team Foundation Build uses an MSBuild script that is named TFSBuild.proj to control the build process. You use the Profile File tab to browse to an existing TFSBuild.proj file in version control or to create a TFSBuild.proj file that you associate with the build definition. If two or more build definitions share a single TFSBuild.proj file, customizing it affects each build definition.

You can either specify a folder that contains an existing TFSBuild.proj file, or you can create a TFSBuild.proj file from an existing Ant build file (Build.xml) or Maven Project Object Model (pom.xml).

If you must manage a build definition from a Visual Studio 2005 client, you must store the project file in a folder called TeamBuildTypes in the root of the team project in version control. If all of the contributors to the build will be using Visual Studio 2008, Visual Studio 2010, or the Team Foundation Server plug-in for Eclipse, the build folder may exist anywhere within the team project in version control.

To specify an existing TFSBuild.proj file

1. Click the Project File tab.

2. Click Browse to specify the version control folder that contains the TFSBuild.proj file that you want to use.

To create a TFSBuild.proj file

1. Click the Project File tab.

2. Click Browse to specify the version control folder in which you want the new TFSBuild.proj file to be created.

3. Click Create.

   The Create Build Configuration Wizard appears.

4. In the Wizards list, click either MSBuild Configuration from Existing Ant Buildfile or MSBuild Configuration from Existing Maven POM file.

5. Click Next.

6. In Build File, specify the Ant build file or Maven POM file on the version control server.

7. Click Finish.

   A new TFSBuild.proj file is created from the Ant build file or Maven POM file.

Next, you specify a retention policy for the build to indicate for how long builds should be kept.

Specify the Retention Policy for the Build

For each status of completed builds, you can specify a number of builds of that type that will be automatically retained. For builds that you define for Team Foundation Server 2010, you can specify one retention policy for triggered and manual builds and another policy for private builds.

1. Click the Retention Policy tab.

2. Under Retention Policy, click the appropriate option next to each build status to specify how many builds should be kept.

   You can click Specify Count to Keep and then specify a specific number of builds if none of the provided values meet your requirements.

   Note

   Users can override the retention policy for one or more builds in Build Explorer by specifying Retain Indefinitely. For more information, see Retain a Build Indefinitely.

Save the Build Definition

• In the Build Definition dialog box, click OK.

  The build definition is saved to the server.

You should perform a test build to verify that your build definition is working as you expect. For more information, see Queuing a Build for Team Foundation Server 2010 (Team Explorer Everywhere).

See Also

Tasks

Creating a Build Definition for Visual Studio 2005 Team Foundation Server

Creating a Build Definition for Team System 2008 Team Foundation Server

Other Resources

Creating and Working with Build Definitions (Team Explorer Everywhere)