Using the ecdevenv Utility

4 minute read

ecdevenv.exe is a command-line drop-in replacement for devenv.exe that builds Visual Studio solutions and projects using eMake. ecdevenv is available only from the command line (builds that you invoke via the GUI use Electrify instead of ecdevenv /eMake).

Following are the key ecdevenv features:

  • Skip generation of NMAKE makefiles

  • No makefiles are required

  • Visual Studio toolchain virtualization

  • Ability to build multiple solutions and projects in one command

  • Ability to specify global converter options in an options file

  • Forced regeneration of makefiles if required

  • Ability to generate makefiles without running eMake

The pre-4.0 behavior of ecdevenv is still supported in versions 4.0 and later.

About ecdevenv

No Makefiles are Required

Without ecdevenv, you must create a makefile to build using eMake:

all:
    devenv.exe solution.sln /build Debug

Then call this makefile with eMake:

emake.exe –-emake-cm=<your cm> --emake-emulation=nmake –f makefile

With ecdevenv, you can simply use the following command:

ecdevenv.exe solution.sln /build Debug –-emake-cm=<your cm>

ecdevenv converts the solution into NMAKE makefiles and runs eMake on them using the eMake parameters specified. Devenv and eMake arguments can be in any order. ecdevenv automatically uses NMAKE emulation.

ecdevenv always converts the solution locally, so any differences between the eMake machine and agent machines can be ignored.

When invoking ecdevenv, if you build a solution that was created in another version of Visual Studio, a warning appears at the command prompt. For example: Warning: 'MySolution.sln' version (2012) does not match version in use (2005).

Miscellaneous Files that ecdevenv Generates

ecdevenv creates several files in the build directory. You do not need to check these files in to your revision control system, unless you want to skip regeneration of NMAKE makefiles.

  • *.eccache

"*.eccache" files are created in the same directory as the solution files. One file is created for each invocation of ecdevenv. ecdevenv uses this file to determine whether it needs to regenerate the temporary makefiles. Delete these only if you want to force ecdevenv to regenerate makefiles.

  • metrics.sln.Release_Win32.ecmak ` and `metrics.vcxproj.Release_Win32.ecmak

These are temporary makefiles generated by ecdevenv. Do not delete them unless you are regenerating the temporary makefiles.

  • metrics_Release_Win32.sln

This is a copy of the original solution used to remove project dependencies. This was generated by ecdevenv (note the configuration name in the file name) Do not delete it unless you are regenerating the temporary makefiles.

  • metrics.sln, metrics.vcxproj, metrics.vcxproj.filters, metrics.vcxproj.user

These are Visual Studio files. Do not delete them.

  • .roots

This contains the list of generated eMake roots. Do not delete it. Note that Electrify uses the eMake command line options, which include the eMake root that is set.

You can relocate these files by using the ECADDIN_MAKEFILE_CACHE environment variable. For details, see the Relocating Makefiles Generated by the Converter Add-In section in the Setting Visual Studio Converter Add-In Environment Variables chapter.

Virtualizing the Visual Studio Toolchain

Use the /virtualize option to virtualize the Visual Studio toolchain. This virtualizes the Visual Studio installation directory, SDK directory, and relevant registry entries. This negates the need to install Visual Studio on the agent machines. Make sure that you have installed the following software before using this option:

  • Relevant .NET version that you are using

  • Relevant redistributable for your version of Visual Studio

Building Multiple Solutions and Projects

ecdevenv can build multiple solutions. To use this capability, create a makefile in the following format and (optionally) specify the projects and project configurations:

<BuildSpecification>
    <Solution>
        <Name>Solution1.sln</Name>
        <Platform>Mixed Platforms</Platform>
        <Configuration>Debug</Configuration>
            <Project>
            <Name>Project1\Project1.vbproj</Name>
            <Platform>Any CPU</Platform>
            <Configuration>Debug</Configuration>
        </Project>
        <Project>
            <Name>Project2\Project2.vcproj</Name>
            <Platform>Win32</Platform>
            <Configuration>Debug</Configuration>
        </Project>
    </Solution>
    <Solution>
        <Name>Solution2.sln</Name>
        <Platform>Mixed Platforms</Platform>
        <Configuration>Debug</Configuration>
    </Solution>
</BuildSpecification>

Then pass the name of the file to ecdevenv using /configuration=<filename>.

If you use the /configuration option, you cannot specify a solution, project, or project configuration on the command line.

Enabling Debugging Output

  • Set ECDEVENV_DEBUG=true to turn on debugging (output is sent to stdout by default).

  • Set ECDEVENV_DEBUG_LOG=<filename> to redirect output to a file.

Using ecdevenv Command Options

Option Description

/configuration=<file>

Specifies the configuration file that allows multiple solutions and projects to be built. See the Building Multiple Solutions and Projects section above.

/force

Forces the regeneration of makefiles.

/generate

Generates the NMAKE makefiles without running eMake.

/help

Displays a list of ecdevenv options and sample options and configuration files.

/localclean

Runs clean locally rather than on the cluster. This makes the clean faster and avoids conflicts in a rebuild.

/makefile

Specifies an alternative default makefile (rather than ecdevenv.mak).

/options= <file>

Specifies the converter options. The file uses the format shown in the Setting Visual Studio Converter Add-In Environment Variables chapter.

/quick

Converts the solution to NMAKE more quickly by parallelizing down to the project level only. For details, see the Using Fast Solution Conversion section below.

/skip

Never regenerates makefiles. You use this when you have cached makefiles. You must manually regenerate makefiles using /force when required.

/use64bit

Specifies the 64-bit version of eMake.

/version

Displays the ecdevenv version number.

/virtualize

Virtualize the Visual Studio toolchain (off by default). See the Virtualizing the Visual Studio Toolchain section above.

Using ecdevenv Environment Variables

Variable Description

ECDEVENV_DEBUG

Turns on debugging to stdout.

ECDEVENV_DEBUG_LOG

Redirects the debug output to a specified file.

ECDEVENV_NO_EXPLICIT_DEPS

Does not use project-to-project dependencies.

ECDEVENV_RUN_LOCAL

Specifies a list of projects to locally build #pragma runlocal. All project lists are delimited with semicolons.

See the converter option ECADDIN_RUN_LOCAL_ LINK.

ECDEVENV_SKIP_CHECKS

Skips checking for devenv.com in the PATH environment variable.

ECDEVENV_SKIP_DUPLICATE_PROJECTS

Skips projects if they have been previously built in a different solution.

ECDEVENV_USE_SOLUTION_CONTEXT

Builds all projects in the solution context. See the Debugging a Failed Build section.

ECDEVENV_USE_SOLUTION_CONTEXT_FOR_PROJECTS

Specifies a list of projects to build in the solution context. All project lists are delimited with semicolons.

See the Debugging a Failed Build section.

Using Fast Solution Conversion

Use /quick for fast solution conversion. This option converts the solution to NMAKE more quickly by parallelizing down to the project level only. The option is best suited to solutions containing no C++ projects.

When using the /quick option, you must also specify the full platform and configuration. For example, ecdevenv solution.sln /build "Release|Win32" /quick.

The option is available only with Visual Studio 2005 and newer versions. If you try to use the option when building a solution in Visual Studio 2002 or Visual Studio 2003, the following error message appears: Error: /quick can only be used with VS2005 and higher.

Visual Studio does not need to be installed for you to use fast solution conversion. However, MSBuild must be installed.

Supporting Multi-Byte Characters

When building solutions that have multi-byte characters in their pathnames, set the following environment variables:

  • ECADDIN_USE_INLINE_FILES=false

  • EMAKE_MAKEFILE_CODEPAGE=65001