BuildConsole for Make and Build Tools

The /command switch enables the Make and Build Tools capability of the BuildConsole command line interface. This capability highly accelerates the build time of various build tools applications (e.g., Make and Ant), by distributing build tasks that are to be executed in parallel to remote machines across the network, utilizing their idle CPUs.

Only one build at a time can be executed on a single initiating machine. An attempt to run a build while another is running, pauses the build until the currently running build ends. Only then, does the new build begin to run.

To accelerate your build time, ensure that the build tools are installed on the initiating machine and then run:

BuildConsole /command="<your original build command line>" [Options]

For example:

BuildConsole /command="make --file=makefile.mak -B"

By default, Incredibuild automatically adds a parallel processes switch (in Make -j; in msbuild /m:).

  • If Make is executed directly, Incredibuild changes the value of an existing -j switch to 1024 (by default). Add the /keeporigjobsnum if you want to keep your –j switch value.

  • If Make is executed from a Batch file, that is, /command = Batchfile, Incredibuild does not change the -j value.

  • If <your original build command line> contains the -j switch (as used, for example, with Jom builds), it is recommended to define a high -j value, no fewer than the maximum number of cores.

Incredibuild changes the following switches:

  • FMakeTool2MultiJobsKey.Add('make', '-j', '--jobs', True);

  • FMakeTool2MultiJobsKey.Add('jam', '-j', '-j', True);

  • FMakeTool2MultiJobsKey.Add('bjam', '-j', '-j', True);

  • FMakeTool2MultiJobsKey.Add('jamplus', '-j', '-j', True);

  • FMakeTool2MultiJobsKey.Add('gmake', '-j', '-j', True);

  • FMakeTool2MultiJobsKey.Add('jom', '/j', '/j', True);

  • FMakeTool2MultiJobsKey.Add('msbuild', '/m:', '/m:', False);

  • FMakeTool2MultiJobsKey.Add('scons', '-j', '-j', True);

  • FMakeTool2MultiJobsKey.Add('waf', '-j', '-j', True);

Note: If when running BuildConsole /command, you get the error: BuildConsole is not recognized as an internal or external command, operable program or batch file., either manually add the Incredibuild installation folder to your system path, or rerun the Incredibuild setup application on your machine, making sure that the Add Incredibuild folder to the system path option is selected.

Command Line Options

Option

Function

Notes

/command

Enables the Make and Build Tools capability of the BuildConsole and allows execution of command lines of various build tools (e.g., Make and Ant), in a distributed manner, without the need to configure Incredibuild in any way.

The build tools must be installed on the initiating machine.

/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.

This will automatically use the 64 bit MSBuild for VS 2022 and later, and the 32 bit MSBuild for earlier VS versions.

To ignore this automatic detection and manually specify which version to use, add =32 or =64 (e.g. /usemsbuild=32)

/msbuildargs="/myarg1 /myarg2"

Passes additional arguments to MSBuild when using the BuildConsole command /usemsbuild switch.

For example:

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

@

Specifies a response file containing a BuildConsole /command command line.

Use this option when the command line for running BuildConsole /command is too long to specify explicitly in your script.

/SETENV="<name>=<value>"

Sets or overrides environment variables for the context of the run build.

Use /SETENV several times to set/override multiple variables.

/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.

/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 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, the BuildConsole/command 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 a BuildConsole/command, it exits with a Another build already running message.

 

/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 /command returns the code 3 when a build has been stopped. If /stop was used and no build is currently running, code 2 is returned.

/Enable

Enables the Incredibuild Agent.

 

/Disable

Disables the Incredibuild Agent.

 

/Reset

Clears the Agent file cache contents.

 

/Title=<build title>

Specifies a custom header line to be displayed in the beginning of the build output text. This title is also 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.

 

/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.

 

/MaxCPUS=<n>

Overrides global maximum 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 will not be assigned to the build. For example, 8 or 10.

/MinWinVer="<Version>"

Specifies the minimal operating system required by remote Agents assigned to this build.

Agents with an older OS will not be assigned to the build. For example, 8 or 10.

/StopOnErrors

Stops the build as soon as an error is encountered.

 

/KeepOrigJobsNum=[True/False]

Forces Incredibuild to use the original value for the -j switch.

By default, Incredibuild changes the value of the -j switch to 200 if the original value is higher than 200. Setting this option to True, allows for higher values of -j.

/LogLevel="<Level>"

Overrides the logging level for this build.

<Level> can be one of the following: Minimal, Basic, Intermediate, Extended, or Detailed.

/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.

/buildcacheremoteserver=[ip address:port]

Use a different build cache endpoint from the one defined in the Agent settings. The port must also be specified. For example: /buildcacheremoteserver=192.5.8.1:50222

 

/buildcachelocal=[ON|OFF]

Override the setting that defines if local Build Cache is enabled on this Initiator.

 

/UseCloudHelpers

When Cloud Helpers are enabled, this setting determines if they are used to assist in the current build. By default, the value is true. To prevent Cloud helpers from assisting in a build, set /UseCloudHelpers=false.

 

Return Codes

BuildConsole returns the following return codes:

  • 0 – Build succeeded with no errors

  • 1 – Build failed due to error not related to Incredibuild (e.g. compilation error)

  • 2 –Build cancelled by user request

  • 3 – Build failed due to Incredibuild system error

Make, Jom and NMAKE Samples

There are three pre-built sample projects demonstrating how to use Incredibuild in the Samples\Make And Build Tools folder under the Incredibuild installation.

To run the samples:

  1. Define the location of the Make/Jom/NMAKE executable in the path, to allow for initiation from any folder.

  2. Run the RunMakeSample.bat/RunJomSample.bat/RunNmakeSample.bat from the command prompt.

  3. The examples are configured to use the MS Visual Studio 2010 compiler.

    If you have a different Visual Studio version installed, open the bat files and replace call "%VS100COMNTOOLS%vsvars32.bat" with:

    • MS Visual Studio 8.0: call "%VS90COMNTOOLS%vsvars32.bat"     

    • MS Visual Studio 7.0: call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat (change the Visual Studio installation folder if required)