Setting Visual Studio converter environment variables

6 minute read

Setting the converter variables

You can control the way the Visual Studio Converter works by setting these environment variables on the eMake machine. Alternatively, you can set the variables in a configuration file and set ECADDIN_CONFIGURATION_FILE to its full or relative pathname.

all: set ECADDIN_CONFIGURATION_FILE=addin.cfg devenv.com Solution.sln /build Debug

Sample addin.cfg:

<SolutionSettings> <DisableAddin>false</DisableAddin> <DoNotParseProjects>false</DoNotParseProjects> <ECBreakpoint>false</ECBreakpoint> <DoNotParseSpecificProjects /> <ECBreakpointProjects /> <RunLocalLink /> <UseDevenvForProject /> <EnableDebugLog>false</EnableDebugLog> <DebugLogName>ecdebug.log</DebugLogName> <MaxPDBFiles>16</MaxPDBFiles> <UseOrderOnlyPrereqs>true</UseOrderOnlyPrereqs> <EnableIncrementalLink>false</EnableIncrementalLink> <RemoveDependencies>true</RemoveDependencies> <ForceZ7>true</ForceZ7>y <UpToDateCheck>false</UpToDateCheck> <DoNotDeleteTempMakefiles>false</DoNotDeleteTempMakefiles> <DoNotUseUniqueNames>false</DoNotUseUniqueNames> <ExpandLinkerObjects>false</ExpandLinkerObjects> <RunDeploymentLocally>false</RunDeploymentLocally> <RunLocalProject /> <SerializeAllProjects>false</SerializeAllProjects> <UseDevenv>false</UseDevenv> <UseMSBuild>true</UseMSBuild> </SolutionSettings>

All environment variables override variables in the configuration file, so you can set them outside of the configuration file as needed. The EMAKE configuration file (in $(InstallDir)\i686_win32\conf\emake.conf ) may also override these settings.

Environment variables that take Boolean values can accept “0”, “no”, “false”, “off”, “1”, “yes”, “true”, or “on”. Case is not significant.
Environment Variable and Configuration File Variable Description Default

AddEmakeRootsAutomatically

Adds the locations of all inputs (such as .cpp and .h files) and outputs (such as .obj, .exe, and .dll files) to the eMake root automatically.

This variable applies only to C++ projects. For a C# project or a project with inputs and outputs not in the solution or project locations, you must add their locations to the eMake root manually.

This variable does not apply to third-party tools, because they cannot be virtualized. It also does not apply to project locations and each location for the solution(s), because they are always added automatically.

False (converter) True (ecdevenv)

ECADDIN_BUILD_ORDER

BuildOrder

Specifies projects' build order. Use only if CloudBees Build Acceleration is not building projects in the correct order.

ECADDIN_BUILD_PROJECTS_IN_SOLUTION_CONTEXT

BuildProjectsInSolutionContext

Modifies the call to MSBuild to build a project within the solution context. This overrides the ECADDIN_BUILD_SPECIFIC_PROJECTS_IN_SOLUTION_CONTEXT variable and the BuildSpecificProjectsInSolutionContext configuration file variable. This option is needed for unparsed projects (such as C# projects or unparsed C++ projects).

False

ECADDIN_BUILD_SPECIFIC_PROJECTS_IN_SOLUTION_CONTEXT

BuildSpecificProjectsInSolutionContext

Allows a list of projects to be built in the solution context in MSBuild. Supply a list of projects (separated by a semicolon but no spaces). This option is needed for specific unparsed projects (such as C# projects or unparsed C++ projects).

ECADDIN_CONFIGURATION_FILE

Sets the filename of the configuration file. Environment variables override the settings in this file.

ECADDIN_CREATE_MISSING_DEPENDENCIES

CreateMissingDependencies

Creates missing dependencies to avoid missing dependency warnings.

False

ECADDIN_DEBUG

EnableDebugLog

Setting this variable to any value causes debug log files to remain in `%TMP%\ecdebug<ID>.log ` on the agent host. These files are used for troubleshooting by CloudBees engineers. Normally, you do not need to set this value.

False

`ECADDIN_DEBUG_LOG_FILENAME `

DebugLogName

Specifies the debug log name. Requires ECADDIN_DEBUG. Use '$1' in the file specification to insert a unique ID. For example, C:\Users\Bill\ecdebug_$1.log. Use a file location outside of eMake root. The log file is stored on the agent.

ECADDIN_DISABLE_MINIMAL_REBUILDS

DisableMinimalRebuilds

Disables minimal rebuilds.

False

ECADDIN_DISALLOW_BSC

DisallowBSC

Does not generate browse information files.

False

ECADDIN_DISALLOW_PCH

DisallowPCH

Does not generate/use precompiled header files (implied by ECADDIN_MAX_PDB_FILES )

False

ECADDIN_DISALLOW_PDB

DisallowPDB

Does not generate PDB files.

False

ECADDIN_DISALLOW_SBR

DisallowSBR

Does not generate browse information files from sources.

False

ECADDIN_DONT_ADD_PCH_LOCATION

DoNotAddPCHLocation

Prevents the converter from adding the location of the PCH file in all cases. This variable is relevant only if ECADDIN_MAX_PDB_FILES or ECADDIN_DISALLOW_PCH is switched on.

False

ECADDIN_DONT_ALLOW_PCH_AND_PDB

DoNotAllowPCHAndPDB

Switches off PDB and PCH generation.

False

ECADDIN_DONT_PARSE_PROJECT

DoNotParseSpecificProjects

Prevents the Visual Studio Converter from breaking up specified C++ projects. This variable takes a list of project names separated by semicolons and without white spaces. This variable is useful for deploying the converter. If, for any reason, the converter cannot build some of your projects, this variable lets you work around the problem.

When using this variable, you might experience an the warning MSB4098. You can ignore this warning, because any project references are now converted into additional dependencies. MSBuild, however, does not provide a mechanism to turn off this warning.

ECADDIN_DONT_PARSE_PROJECTS

DoNotParseProjects

This variable takes any non-blank value and its behavior is similar to ECADDIN_SERIALIZE. It calls devenv on each project (the converter does not convert each project into individual compile/link steps).

ECADDIN_DONT_RM_TMP_MAKEFILES

DoNotDeleteTempMakefiles

Retains makefiles created during the build but normally deleted when the build finishes. This environment variable can have any value; it just needs to be set.

False

ECADDIN_DONT_RUN

DoNotRun

Test only. Convert makefiles without running Electrify.

False

ECADDIN_DONT_USE

DisableAddin

Disables the converter. This environment variable can have any value, it just needs to be set. Also, you can disable the converter on each host by using the Visual Studio Converter Manager (on the Tools menu).

False

ECADDIN_DONT_USE_UNIQUE

DoNotUseUniqueNames

Does not use unique names for temporary makefiles. Use with ECADDIN_DONT_RM_TMP_MAKEFILES.

False

ECADDIN_ECBREAKPOINT

ECBreakpoint

Determines whether to invoke ecbreakpoint on failed jobs.

False

ECADDIN_ECBREAKPOINT_PROJECTS

ECBreakpointProjects

Determines whether to invoke ecbreakpoint for specified projects. Use a semicolon to delimit projects.

ECADDIN_ENABLE_INCREMENTAL_LINK

EnableIncrementalLink

Inserts a call to ectouch.exe.. See Tuning Performance.

True

ECADDIN_EXPAND_LINKER_OBJECTS

ExpandLinkerObjects

Expands linker objects to one line per object. Prevents errors when link line length is exceeded.

False

ECADDIN_FORCE_Z7

ForceZ7

Enables /Z7 compiler options for all C++ files. Note that enabling this setting typically creates larger executable or library files. Enabling this setting adds debugging information to the object files and therefore overrides ECADDIN_MAX_PDB_FILES.

True

ECADDIN_INCLUDE_CMAKELISTS

IncludeCMakeLists

Excludes any source file with the name CMakeLists.txt. Set this variable to True to execute the file.

False

ECADDIN_INJECT_PCH_REFERENCE

InjectPCHReference

Adds /Yl <projectname> to the PCH creator (/Yc). Set it to false only if linker tools error LNK2005 (multiply-defined symbol error) appears.

True

ECADDIN_LINK_PARAMETERS

LinkParameters

Adds options to the linker command. You can specify one or more options separated by spaces. For example, ECADDIN_LINK_PARAMETERS=/OPT:REF or LinkParameters=/INCREMENTAL /NOLOGO /DEBUG /PDB:a.pdb.

ECADDIN_MAKEFILE_CACHE

MakefileCache

Path to an alternate location for the cached (temporary) makefiles that are generated by the converter. For details.

ECADDIN_MAX_PDB_FILES

MaxPDBFiles

Specifies the maximum number of PDB files to produce. This setting has no effect if you set ECADDIN_FORCE_Z7=true, which adds debugging information to the object files. For details, see Optimizing Parallelization Using PDB Splitting.

16

ECADDIN_MSBUILD_DIR

MSBuildDir

Path to the location of msbuild.exe if different from the default.

ECADDIN_MSBUILD_PARAMETERS

MSBuildParameters

Adds extra parameters to msbuild command line.

ECADDIN_NOLINK

NoLink

Performs all build steps except linking and post build steps. When this variable is enabled, Visual Studio displays the following message at build time: Warning: Not linking because ECADDIN_NOLINK is set."

False

ECADDIN_PARSE_BUILD_CUSTOMIZATIONS

ParseBuildCustomizations

Recognizes Visual Studio build customizations. If you encounter issues with a project when using this feature, you can disable it for all projects containing Build Customizations by setting it to FALSE or by disabling parsing for only that project by setting ECADDIN_DONT_PARSE_PROJECT or DoNotParseSpecificProjects to TRUE.

True

ECADDIN_NORECURSE

NoRecurse

Builds only the specified project configurations while ignoring dependent projects in those configurations. When used in conjunction with /Clean, this cleans only the specified configurations. When used in conjunction with /Rebuild, this rebuilds only the specified configurations.

False

ECADDIN_REMOVE_DEPENDENCIES

RemoveDependencies

Removes project-to-project dependencies to improve parallelization.

False

ECADDIN_RUN_DEPLOYMENT_PROJECTS_LOCALLY

RunDeploymentLocally

Runs deployment projects locally using #pragma runlocal.

False

ECADDIN_RUN_LOCAL_LINK

RunLocalLink

A list of projects where the linker will be run locally (using #pragma runlocal ).

`ECADDIN_RUN_LOCAL_PROJECT `

RunLocalProject

Use this variable if your build uses a local resource (for example, a resource only on the Electrify host (for example, a database). You do not need to set this variable if your project build includes web deployment; this is handled by the converter. The value of this variable is a list of project names separated by semicolons. Each project name must be the unique Visual Studio identifier for the project (for example, solution1/project1.vcproj ). Do not add quotation marks or white spaces.

EADDIN_SERIALIZE

SerializeAllProjects

Causes each project to be built serially. It inserts ‘#pragma allserial’ into each makefile. This variable is equivalent to setting ECADDIN_DONT_PARSE_PROJECTS.

False

ECADDIN_UP_TO_DATE_CHECK

UpToDatecheck

Pre-parses the projects to determine whether there is anything to build. Prevents unnecessary rebuilding of static build steps.

True

ECADDIN_USE_DEVENV

UseDevenv

Uses devenv (rather than msbuild ) for all unparsed projects.

False

ECADDIN_USE_DEVENV_FOR_PROJECT

UseDevenvForProject

Uses devenv (rather than msbuild ) to build specific projects. Supply a list of projects (separated by a semicolon) to be built with devenv.

ECADDIN_USE_LEGACY_CODE

UseLegacyCode

Use this variable to workaround a Visual Studio bug where AdditionalLibraryDirectories does not give the correct value.

False

ECADDIN_USE_MSBUILD

UseMSBuild

Uses msbuild internally for projects that the converter cannot parse.

True

ECADDIN_USE_MSBUILD_FOR_LINK

UseMSBuildForLink

(Visual Studio 2010 and newer versions) Uses msbuild internally for linking. These variables are a workaround for an issue in which VCManifestTool is not supported in Visual Studio 2015 and newer versions and might not be supported in Visual Studio 2010–2013.

True (VS 2015+)

False (VS 2010–2013)

ECADDIN_USE_ORDER_ONLY_PREREQS

UseOrderOnlyPreReqs

Uses order-only prerequisites (available in CloudBees Build Acceleration v7.0 and later). This allows for quicker first time (no history) builds.

True

ECADDIN_USE_RELATIVE_PATHS

UseRelativePaths

Uses relative paths in the makefile to reduce line lengths and to allow the build location to be changed without regenerating makefiles.

ECADDIN_USE_WCE_MACROS

UseWCEMacros

Loads platform macros.

False

ECADDIN_XBOX_INSTALL_DIR

XBoxInstallDir

Path to the location of Xbox SDK if different from the default.

ECADDIN_XBOX_VERSION

XBoxVersion

Xbox SDK version if different from the default.

Relocating Makefiles generated by the converter

Generated (temporary) makefiles include .ecmak files, solutions and projects, RC files, and up-to-date check files. By default, these files are in the same location as their corresponding solution or project. For example:

  • C:\Test\solution_001\solution_001.sln generates C:\Test\solution_001\solution_001.sln.ecmak

  • C:\Test\solution_001\project1\project1.vcxproj generates C:\Test\solution_001\project1\project1.vcxproj.ecmak

You can specify a path to an alternate location for these files by setting the ECADDIN_MAKEFILE_CACHE environment variable. For example, if you enter set ECADDIN_MAKEFILE_CACHE=C:\temp, then

  • C:\Test\solution_001\solution_001.sln generates C:\temp\solution_001.sln.ecmak

  • C:\Test\solution_001\project1\project1.vcxproj generates C:\temp\project1\project1.vcxproj.ecmak

(Note that the makefiles are relative to the solution directory.) This variable is useful when you want to keep eMake-generated files out of the source tree or when the source tree is read-only.

If you use this environment variable, keep in mind that the paths for the generated files must not exceed the Windows character limit.