Setting up Visual Studio Team Services to Run with IncrediBuild
Prerequisites
This extension is compatible with Visual Studio Team Services (i.e. VSTS) 2015 Update 3 and VSTS 2017.
An IncrediBuild infrastructure is required to be set in your environment in order to be able to accelerate your VSTS builds.
An IncrediBuild Agent needs to be installed on each VSTS build agents you'd like to accelerate using the IncrediBuild for VSTS extenstion
| Info |
|---|
In order to use the IncrediBuild VSTS extension, an Enterprise Edition of IncrediBuild is required. |
Installation
Installing the IncrediBuild extension for VSTS is as simple as navigating to the VSTS marketplace, searching for "IncrediBuild" and installing the extension.
For further information on installing Extensions in VSTS, see Get extensions for Visual Studio Team Services in the VSTS online manual.
To install the IncrediBuild extension in TFS 2015 Update 3 or TFS 2017, see Get extensions for Team Foundation Server (TFS).
Using the IncrediBuild Build Step
The IncrediBuild for VSTS Extension provides wrappers around the IncrediBuild’s BuildConsole and IBConsole commands as an alternative to running the commands in a shell or using batch scripts. Using the extension will ensure that the command line is properly formatted, including the log console output and parse exit code.
Adding an IncrediBuild Build Step to a VSTS Job
To add an IncrediBuild build step to a VSTS jobs:
- In your VSTS project, open the Build tab.
- Click +New to create a new empty build definition.
- In the new build definition click +Add build step… and select either IncrediBuild BuildConsole, IncrediBuild DevTools or IncrediBuild Make and Build Tools.
- Once a build step was added, you will be able to configure the step’s parameters just below the step's title (see screenshots in the following sections). For each parameter, clicking the help icon will open a tooltip with relevant information for the selected parameter.
- See the following sections for how to configure each of the IncrediBuild build steps.
- Click Save on the configuration page.
Configuring the IncrediBuild BuildConsole Step
This build step provides a wrapper around the IncrediBuild BuildConsole command, for distributing and accelerating compilations of Visual Studio solutions or projects.
For more information on using IncrediBuild to accelerate Visual Studio compilations, see IncrediBuild for Visual Studio in the IncrediBuild online manual.
Required Configurations
The “Target Solution File” configuration field is mandatory and should receive a solution name or project name to be compiled by IncrediBuild.
Optional Configurations
Other BuildConsole optional parameters are grouped as: Target and Configuration, Distribution Control, Output and Logging, Miscellaneous and Advanced.
For more information about the IncrediBuild console configuration fields see the "Build Steps Configuration Fields Table" section below.
Configuring IncrediBuild DevTools Step
This build step provides a wrapper around the IncrediBuild "IBConsole" command line, geared for accelerating various multi-process custom executions, such as unit tests, QA scripts, packaging, code analysis, asset builds, simulations and others.
For more information on using IncrediBuild to accelerate Visual Studio compilations, see IncrediBuild for DevTools in the IncrediBuild online manual.
Required Configurations
The “Command Line” configuration field is mandatory and should receive the command line to be executed and accelerated by IncrediBuild.
Optional Configurations
Other DevTool step optional parameters are grouped as: Target and Configuration, Distribution Control, Output and Logging, Miscellaneous and Advanced.
For more information about the IncrediBuild console configuration fields see the "Build Steps Configuration Fields Table" section below.
Configuring IncrediBuild Make and Other Build Tools Step
The Make and Other Build Tools build step provides a wrapper around the IncrediBuild "BuildConsole \Command" command line, geared for accelerating the build process of projects based on Make, MSBuild, WAF, ninja, scons, CMake or other build systems that are supported by default by IncrediBuild.
For a full list of pre-defined supported build tools and more information on using IncrediBuild to accelerate Make and other build tools, see IncrediBuild for Make and Other Build Tools in the IncrediBuild online manual.
Required Configurations
The “Command Line” configuration field is mandatory and should receive the command line to be executed and accelerated by IncrediBuild.
Note that by default, IncrediBuild automatically adds a parallel processes switch (in Make, this switch is named -j; in MSBuild it is /m:). If a parallel processes switch is already part of the command line, IncrediBuild will change its value to a larger value in order to execute (and distribute) much more processes in parallel.
In MSBuild for example, IncrediBuild will change the value of an existing /m switch to a /m64, in the Make build system the -J flag will be changed to -j200. If the executed command is given in a Batch file (i.e. /command = Batchfile), and the MSBuild command that runs the build is inside the Batch file, IncrediBuild won’t be able to determine how to change the /m value, and therefore won’t change it. In this case, it is up to the user to replace or add a /m command with a high value to it (the recommendation is more than 40 for MSBuild and more than 100 to Make build system variants).
Optional Configurations
Other Make and Build Tools optional parameters are grouped as: Target and Configuration, Distribution Control, Output and Logging, Miscellaneous and Advanced.
For more information about the IncrediBuild console configuration fields see the "Build Steps Configuration Fields Table" section below.
Build Steps Configuration Fields Table
Pay attention that some of the configuration fields below are only relevant for BuildConsole tasks and not for DevTools or Make & Build Tools tasks while the Command Line configuration field is only relevant for DevTools or Make & Build Tools tasks.
If not specifically mentioned, the configuration field can be applied to all tasks.
...
Field Name
...
Description
...
Target Solution File
...
The solution file to be built. (BuildConsole task)
...
Command Line
...
The command line to be executed and accelerated by IncrediBuild. (DevTools and Make & Build Tools tasks)
...
Build Type
...
The type of build to perform (BuildConsole task). Select either Build, Clean or Rebuild.
...
Configuration
...
Determines the solution’s platform|configuration to be built (e.g. Debug|Win32). Several comma-separated platform|configuration names can be specified: e.g. Debug|Win32,Release|Win32. (BuildConsole task)
...
Custom Configuration Preset
...
Determines the projects/configurations that will be built using a Preset previously saved in the Batch Build dialog.
- This option is useful when a complex combination of projects and configurations is required or when you are building multiple configurations in parallel.
- The /Preset command option replaces both the /cfg and the /prj options.
(BuildConsole task)
...
Project
...
Determines a specific project to be built. By default, the dependencies of the project will be built as well. (BuildConsole task)
...
Do Not Build Dependencies for the Project
...
Builds only the specified project, ignoring any dependencies these projects may have. When used in conjunction with Clean, this cleans only the specified projects. When used in conjunction with /Rebuild, this rebuilds only the specified projects. (BuildConsole task)
...
Build all Projects Regardless of Errors
...
When this option is specified, a build will continue compiling regardless of specific projects failing to build. Normally, IncrediBuild stops the build when a project fails to build successfully. This option instructs IncrediBuild to continue building the remaining projects, regardless of previous projects failing to build. (BuildConsole task)
...
useEnv
...
Use PATH, INCLUDE, LIBPATH, and LIB environment variables instead of MS Visual C++ IDE paths. (BuildConsole task)
...
Add Parameters to cl.exe
...
Allows additional compiler options to be added to all executions of cl.exe. Enter one or more commands separated by a space character, as they would appear in the cl.exe command line (e.g. /O2 /FA). (BuildConsole task)
...
Remove Parameters from cl.exe
...
Specifies compiler options that will be removed from all executions of cl.exe. Enter one or more commands separated by a space character, as they would appear in the cl.exe command line. (e.g. /Z7 /Zd /Zi /ZI). (BuildConsole task)
...
Force Visual Studio Version
...
Forces a specific version of Visual Studio toolset to be used. This is especially helpful when working with upgraded projects, since Visual Studio sometimes uses the incorrect version to build a solution after it was upgraded. (BuildConsole task)
...
Use MSBuild instead of Devenv
...
Sets MSBuild as the parent build executer instead of devenv. Use this if you are replacing an MSBuild build step with an IncrediBuild build step (this is very common to VSTS builds) or if you don’t have Visual Studio installed on the Initiator machine or if you need to pass arguments to MSBuild manually using the MsbuildArgs option. (BuildConsole task)
...
Arguments for MSBuild
...
Passes additional arguments to MSBuild when using the BuildConsole command's UseMsbuild switch. (BuildConsole task)
...
Profile.xml
...
The Profile XML file is usually used in the DevTools solution to define how IncrediBuild’s Automatic Interception Interface should handle the various processes involved in a distributed job. It can be used in Visual Studio or Make and Build tools builds to provide configuration options for extending the default behavior of these solutions to distribute additional tasks. This file is required in order to configure distributable processes in DevTools builds.
...
Avoid Task Execution on Local Machine when Possible
...
Overrides the Agent Settings dialog “Avoid task execution on local machine when possible” option. This allows you to free-up more resources on the initiator machine and could be beneficial to distribution in scenarios where the initiating machine is bottlenecking the build with High CPU and disk usage.
...
Maximum CPUs to Utilize in the Build
...
Specifies the maximum number of remote cores to utilize in the build. Overrides the global max. CPUs/Cores specified in the Agent Settings.
...
Newest Allowed Helper Machine OS
...
Specifies the newest operating system installed on a helper machine to be allowed to participate as helper in the build.
...
Oldest Allowed Helper Machine OS
...
Specifies the oldest operating system installed on a helper machine to be allowed to participate as helper in the build
...
Build Title
...
Specifies a custom header line which will be displayed in the beginning of the build output text. This title will also be used in the Build History, Build Monitor and the IncrediBuild dashboard.
...
Save IncrediBuild Monitor File
...
Writes a copy of the build progress (.ib_mon) file to the specified location.
- If only a folder name is given, IncrediBuild generates a GUID for the file name.
- A message containing the location of the saved .ib_mon file is added to the end of the build output.
...
Suppress STDOUT
...
Does not write anything to the standard output.
...
Output Log File
...
Writes the build output to a file.
...
Show Commands in Output
...
Shows, for each executed task, the command-line used by IncrediBuild to build the file.
...
Show Agents in Output
...
Shows the Agent used to execute each task.
...
Show Time in Output
...
Shows the start time and end time for each executed task.
...
Hide IncrediBuild Header in Output
...
Suppresses the IncrediBuild header in the build output.
...
Internal IncrediBuild Logging Level
...
Overrides the internal IncrediBuild logging level for this build. Does not affect output or any user accessible logging. Used mainly to troubleshoot issues with the assistance of IncrediBuild support.
...
Set an Environment Variable
...
Sets or overrides environment variables for the context of the build.
...
Stop On Errors
...
When specified, the execution will stop as soon as an error is encountered. This is the default behavior in Visual Studio builds, but not the default for Make and Build tools or Dev Tools builds.
...
Additional Arguments
...
