Running from the Command Line (BuildConsole Interface)

BuildConsole Command Line Interface


Overview

BuildConsole.exe, located in the IncrediBuild installation folder, is a console application that allows running distributed Visual Studio builds from the command line, scripts, and applications, or continuous integration management tools such as TFS.

BuildConsole can also be used to accelerate other build tools such as Make, using the /command directive. Further information can be found in the IncrediBuild for Make & Build Tools section.

You can run a distributed job that uses one of the interfaces from the IncrediBuild Interfaces extension package, using the IBConsole.exe command line interface. This interface is used to accelerate your custom tool, such as rendering, simulations, unit testing, QA, scripts, and more.

Highlights

Usage

The following syntax is used to operate BuildConsole.exe:

BuildConsole <Target> [Options]

Where <Target> can be any of the following:

The BuildConsole command doesn’t force you to include the .sln file as part of the build command in order to build specific projects, however, omitting the .sln parameter is not recommended. Some of the information IncrediBuild may require in order to correctly compile the project may be missing from the project file. A known issue, for instance, is when a user would like to determine the Visual Studio version with which to build his project (this information is not part of the project file). For this specific purpose a flag "/VsVersion" was added to IncrediBuild's BuildConsole command that allows specifying the Visual Studio version with which IncrediBuild will build the projects (see the flag’s description here in this page).

The following are examples for running BuildConsole:

BuildConsole.exe MySln.sln /rebuild /cfg="Debug|Win32"

BuildConsole.exe MySln.sln /build /prj=Proj1 /cfg="Debug|Win32,Release|Win32"

BuildConsole.exe MySln.sln /build /preset="MyPreset"

In addition to this syntax, BuildConsole also supports msdev.exe and devenv.exe command line syntax for building projects. If you are already using batch files that spawn either msdev.exe or devenv.exe, replace the standard MSVC build with an IncrediBuild distributed build, by editing your files and replacing these program names with "BuildConsole.exe".

Note

Command Line Options

The following command line flags can be used with BuildConsole:

Option Function Notes
/UseMSBuild Forces the usage of MSBuild By default, IncrediBuild uses Devenv to perform the build. Using this switch, IncrediBuild will use MSBuild which will enable the option to add specific MSBuild flag using the /msbuildargs as can be seen below.
/msbuildargs="/myarg1 /myarg2" Passes additional arguments to MSBuild when using the buildconsole command's '/usemsbuild' switch.

For example:

BuildConsole dcom.sln /rebuild /cfg="debug|win32" /msbuildargs="/detailedsummary" /usemsbuild

@ Specifies a response file containing a BuildConsole command line. Use this option when the command line for running BuildConsole is too long to specify explicitly in your script.
/Cfg=<configuration> Determines the solution configuration to be built (with VC6 builds, this option specifies the project configuration). - Value should be enclosed in quotes.
- Several comma-separated configuration names can be specified.
- When building an MSVC 6.0 project, both the following formats are valid:
/cfg="Win32 Debug" 
and 
/cfg="myProj - Win32 Debug".
- Value is not case-sensitive.
/Prj=<project name> Determines the project to be built. - Value may be enclosed in quotes.
- Running BuildConsole on an .sln file without the /prj option will run the command on the specified solution configuration.
- The "*" and "?" characters may be used as wildcard signs when specifying project names, to perform an operation on several projects. Additionally, several project names may be entered, separated by commas. In this case, all projects are built using the same configuration name.
For example, to build all configurations in a solution/workspace, use the following syntax:
BuildConsole MyWksp /prj="*"
/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.
- The /Preset command option replaces both the /cfg and the /prj options.
/All Makes a solution/workspace build continue regardless of specific projects failing to build. Normally, IncrediBuild stops the build when a project fails to build its output file. This option instructs IncrediBuild to continue building the remaining project configurations, regardless of previous projects failing to build.
/Clean Cleans intermediate and output files for the project(s) and all dependencies.  
/Rebuild Performs a Clean operation before building the project.  
/SETENV="<name>=<value>" Sets or overrides environment variables for the context of the run build. Use /SetEnv several times to set/override multiple variables.
/NoRecurse Builds only the specified project configurations, ignoring any sub-projects these configurations may have. - When used in conjunction with /Clean, this cleans only the specified configurations.
- When used in conjunction with /Rebuild, this rebuilds only the specified configurations.
/UseEnv Use PATH, INCLUDE, LIBPATH, and LIB environment variables instead of MS Visual C++ IDE paths. - To set this option globally, use the Agent Settings dialog "Use environment variables instead of IDE paths" option.
- If a build is initiated from a Visual Studio IDE window instantiated using the devenv.exe "/useenv" command line option, this build will always use "/useenv".
/compile=<source file name> When used, only the specified file(s) are built. - Value may be surrounded by quotes.
- Several source filenames may be entered, separated by commas.
/Log[=filename] Writes build output to a file. If filename is omitted, a file named IB_<target-name>.log is created in the current directory.
/Mon[=filename] 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.
/DumpSourceFiles= Writes all of the source file paths in a project/solution to a file. <output filename> is mandatory.
/out=filename Redirects entire command line output to a file.
/Silent Does not write anything to the standard output. Default behavior is to write the build results, as seen in the Build Monitor's Output display.
/Attach Displays the build output of either the current or the last build. If a build is currently running on the machine, this displays the output for the build up to that point, and continues displaying the build's output until it ends. If no build is running, BuildConsole displays the entire build output for the last build initiated from this machine.
/Wait If another build initiated by this Agent is currently running, waits until that build is finished and then starts the new build. This is also the default behavior.
/NoWait When specified, if another build initiated by this Agent is already running, BuildConsole exits with a "Another build already running" message.
/cl_add="<options>" Allows additional compiler options to be added to all calls to cl.exe. Enter one or more commands separated by a space character, as they would appear in the cl.exe command line. For example:
BuildConsole MyProj /cl_add="/O2 /FA"
/cl_rem="<options>" Specifies compiler options that will be removed from all calls to cl.exe. Enter one or more commands separated by a space character, as they would appear in the cl.exe command line. For example:
BuildConsole MyProj /cl_rem="/Z7 /Zd /Zi /ZI"
/link_add="<options>" Allows additional linker options to be added to all calls to link.exe. Enter one or more commands separated by a space character, as they would appear in the cl.exe command line. For example:
BuildConsole MyProj /link_add="/map:MyProj.map"
/link_rem="<options>" Specifies linker options that will be removed from all calls to link.exe.

For VS 2008 and prior.

Enter one or more commands separated by a space character, as they would appear in the cl.exe command line. For example:
BuildConsole MyProj /link_rem="/map:MyProj.map"

/CEconfig="<configuration name>" Specifies theWCE platform for eMbedded Visual C++ 4.0 builds.  For VS 2008 and prior.
/IntelCLVersion="<version>" Overrides the default Intel Compiler version.

For VS 2008 and prior.

For example: /IntelCLVersion=11.1

/BrowseInfo=[ON/OFF] Forces or suppresses creation of browse information, regardless of current browse information settings. See the Agent Settings section for more information regarding browse information settings.
/IncrediLink Forces IncrediLink mode for this build.  For VS 2008 and prior.
/NoIncrediLink Disables IncrediLink mode for this build.  For VS 2008 and prior.
/NoLink Performs all build steps except linking.  For VS 2008 and prior.
/NoLogo Suppresses the "IncrediBuild" header in the build output.  
/Beep Plays a sound when the build is complete.  
/Stop Stops a currently running build on the local machine. BuildConsole returns the code 3 when a build has been stopped. If /stop was used and no build is currently running, 2 is returned.
/Enable Enables the IncrediBuild Agent.  
/Disable Disables the IncrediBuild Agent.  
/Reset Clears the Agent's file cache contents.  
/Title=<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 for the Build History and Build Monitor displays. Value may be surrounded by quotes.
/QueryLicense Displays information regarding the active license, allocated packages, and maintenance expiration date.
/QueryPackage="<Package>" Checks whether a specific IncrediBuild extension package is allocated to the Agent, and sets exit code to 0 (allocated) or 1 (not allocated). "<Package>" can be either "VC", "C#", "BuildTools", "DevToolAcc", "XGE", "Xbox One", "PlayStation", "Cafe", "3DS", "KlocWorkPro" or "Coverity". In addition, the following cores packages are supported: "4Cores", "8Cores", "12Cores", "16Cores", "24Cores", "32Cores", "48Cores" and "64Cores".
/ShowCmd Shows, for each file built, the command-line used by IncrediBuild to build the file.  
/ShowAgent Shows the Agent used to build each file.  
/ShowTime Shows the Start and Finish time for each file built.  
/OpenMonitor Opens the Build Monitor window showing the build progress.  
/UseIDEMonitor When BuildConsole is run from the Visual Studio IDE with this option, the integrated IDE Build Monitor displays the build progress.  
/MaxCPUS=<n> Overrides global max. CPUs/Cores in build setting.  
/AvoidLocal=[On/Off] Overrides the Agent Settings dialog Avoid task execution on local machine when possible option. A value (either ON or OFF) is mandatory.
/MaxWinVer="<Version>" Specifies the maximal operating system required by remote Agents assigned to this build. Agents with a newer OS are not assigned to the build. Available values are: XP, 2003, VISTA, 2008, 7, 8 and 10.
/MinWinVer="<Version>" Specifies the minimal operating system required by remote Agents assigned to this build. Agents with an older OS are not assigned to the build. Available values are: XP, 2003, VISTA, 2008, 7, 8 and 10.
/LogLevel="<Level>" Overrides the logging level for this build "<Level>" can be one of the following: Minimal, Basic, Intermediate, Extended, Detailed
/VsVersion="<Version>" Forces a specific version of Visual Studio toolset to be used. "<Version>" can be one of the following: vc8 (for VS2005), vc9 (for VS2008), vc10 (for VS2010), vc11 (for VS2012), vc12 (for VS2013), vc14 (for VS2015)
/Help Shows usage help and version information.  
/NO_DOTNET_VIRT Disables the Virtualization of .NET environment on Helper machines. When this switch is specified in the command line it instructs IncrediBuild not to virtualize the .NET environment of the Initiator machine to the Helper machines. This switch was added to address .NET incompatibilities in a mixed OS environment.
/deploy Equivalent to the same DevEnv command line argument. For more information, see:  Devenv Command Line Switches .
/DisablePdbForwarding Disables the PDB forwarding mechanism for this build

Only relevant for Visual Studio 2010 builds.

Return Codes

BuildConsole returns the following return codes:

0 – No errors were encountered.
1 – Errors were encountered during the operation.
2 – A fatal IncrediBuild error was encountered (invalid parameters, input file not found, etc.).
3 – The operation was stopped before completing.

Using profile.xml to distribute custom steps and exec tasks in Visual Studio 2010 and later builds

By default, custom steps, exec tasks, and special build tools are not distributed to remote agents.
IncrediBuild can be enabled to distribute and manage these tasks, by using an XML file based on IncrediBuild Automatic Interception interface. A profile.xml file can be utilized in two ways in order to manage such tasks:

The following XML file instructs IncrediBuild to distribute every "gawk" task that is executed by the build. Note that even though the real file is "gawk.exe", the file extension is not specified:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<Profile FormatVersion="1">
<Tools>
<Tool Filename="gawk" AllowRemote="true" />
</Tools>
</Profile>

Other Automatic Interception Interface features can be used to fully control the tasks – see Automatic Interception Interface. 

Additional Notes: