Building Visual Studio Solutions from the Command Line

CloudBees Accelerator can build Visual Studio solutions in three different modes:

  • Using Electrify (recommended for VC++)

  • Using ecdevenv as a drop-in replacement for your command-line build

  • Creating a makefile containing the devenv calls and/or MSBuild calls

Using Electrify

If you choose to use Electrify, specify your devenv.exe or msbuild command as follows:

electrify.exe --emake-cm=<cluster_manager_name_or_IP> <emake_options> --electrify-remote=cl.exe;link.exe;lib.exe --electrify-localfile=y --electrifymon --your devenv/msbuild command>

Using the ecmsbuild.exe Wrapper with Electrify

The ecmsbuild.exe wrapper provides a simpler command syntax for using Electrify to build Visual Studio solutions and MSBuild projects from the command line.

ecmsbuild.exe Command Syntax

The syntax of the command is:

ecmsbuild <msbuild_project/solution/project> [<build> <configuration>] [<electrify_args>] [<msbuild_args>] [<ecmsbuild_args>]

You can provide the arguments in any order. Any --emake- and --electrify- prefixes are interchangeable. For example:

ecmsbuild.exe --emake-virtualize --emake-cm=localhost --emake-annodetail=basic solution.sln /t:rebuild /p:Configuration=Debug,Platform=Win32
The ecmsbuild.exe wrapper is best used for a single project. For multiple projects, CloudBees recommends that you use MSBuild. For details, see Using MSBuild.

Following are the ecmsbuild.exe arguments:

Argument Description Default

--electrify-virtualize= version

Virtualizes the specified Visual C++ toolchain

Detects the Visual Studio version from the solution or project file

--electrify-tool=[msbuild|devenv]

Overrides the default tool selection

  • Visual Studio 2005 or 2008: devenv

  • Visual Studio 2010 or newer: MSBuild

--electrify-expand-inline-files=[true|false]

Sets the ELECTRIFY_EXPAND_INLINE_FILES variable to expand the inline files of cl.exe to enable JobCache. (Note that JobCache is incompatible with incremental builds and should be used only for full builds)

true

--electrify-force-z7=[true|false]

Sets the ELECTRIFY_FORCE_Z7 variable to enable /Z7 compiler options for all C++ files

false

--electrify-split-pdbs=[true|false]

Sets the ELECTRIFY_SPLIT_PDBS variable to split the debug information into multiple PDF files

false

--electrify-max-source-files=< n >

Sets the ELECTRIFY_MAX_SRC_FILES variable to ensure that cl.exe builds a maximum of <n> files per invocation

Unlimited

ecmsbuild.exe Variables

ecmsbuild.exe sets certain variables automatically:

Electrify or MSBuild Parameter Description Default Overridable?

--emake-root

Additional eMake roots for virtualization

Added automatically. The solution directory and user profile directory are always added.

No. But you can append additional roots.

--emake-reg-roots

Registry (”reg”) roots for virtualization

Added automatically

No. But you can append additional roots.

/maxcpucount ` or `/m

Number of threads

64

Yes

--emake-jobcache

Enables the JobCache feature for all make invocations in a build. (Note that JobCache is incompatible with incremental builds and should be used only for full builds)

cl

Yes

--electrify-remote

Commands to distribute to the cluster

cl.exe;link.exe;lib.exe

Yes

--electrify-localfile

Integrates local file access (create, rename, and so on) by locally running tools with the remote file system

y

No (causes an error)

--electrifymon

Tells Electrify to monitor the local file system

Set automatically

No (causes an error)

/nodeReuse or /nr

Enables the reuse of MSBuild nodes

false

No (causes an error)

--

Used by Electrify to separate the Electrify arguments from the command that Electrify is about to run

Added automatically by ecmsbuild.exe when it calls Electrify

No (causes an error)

For ecmsbuild.exe, you must set the eMake roots correctly for your project.

Side Effects of Using ecmsbuild.exe

To ensure the correct operation of Electrify, ecmsbuild.exe has several side effects:

  • Kills the following processes that might interfere with Electrify if they remain dormant: msbuild.exe, mspdbsrv.exe, electrify.exe, electrifymon.exe, electrify_proxy.exe, csc.exe, link.exe, and cl.exe.

  • Turns off the Visual Studio Customer Experience Improvement Program (VSCEIP).

    For Visual Studio 2012 and newer, this is per machine; otherwise, it is user-specific.

  • Prevents mspdbsrv from existing after a job completes (sets MSPDBSRV=-shutdowntime 0 )

  • Prevents VBCSCompiler.exe from existing after a job completes (sets UseSharedCompilation=false )

  • Enables JobCache by default (sets --emake-jobcache=cl and sets ELECTRIFY_EXPAND_INLINE_FILES=true in environment).

    Can be overridden from the command line.

  • Does not allow --electrify-localfile=y, --electrifymon, or -- as arguments (automatically added by ecmsbuild.exe )

Using ecdevenv

If you choose to use ecdevenv, replace:

devenv.com Solution.sln /build Debug

with:

ecdevenv Solution.sln /build Debug -–emake-cm=<your_cm> /virtualize

ecdevenv does the following:

  1. Converts Solution.sln to NMAKE format.

  2. Calls eMake on the generated files.

The /virtualize flag virtualizes the Visual Studio toolchain, negating the need to install Visual Studio on the agents. You must, however, ensure the relevant versions of .NET and redistributables are installed.

devenv must be in the PATH environment variable before you execute ecdevenv.

Creating a Makefile

Before you can use Accelerator to build your Visual Studio project, make sure you have already installed and run Visual Studio on each agent host for each user (all ECloudInternalUsers ).

Virtualization of the toolchain is not possible when using this method.

If you currently invoke Visual Studio from inside a makefile, you are ready. If you invoke Visual Studio directly from the command line or through a batch file, you must create a makefile for eMake to run. For example:

all:
      devenv /build Release foo.sln

 — or — 

all:
      devenv /build Release foo.sln /project bar.vcproj

The makefile must invoke devenv with the options you currently use. Ensure the correct version of devenv is in your path:

devenv /?

and ensure that the usual Visual Studio environment variables are set.

For Visual Studio 2015 and later, you must add “ /vsp ” to the end of the command line. (When building from ecdevenv.exe, this is added automatically.)

For example:

all:
devenv /build Release foo.sln /vsp

Setting the Path for 64-Bit or Xbox Builds

To run 64-bit or Xbox builds, you must set the path manually.