devenv-plugin

Overview

Warning

This plugin is under minimal maintenance and no new features are planned for it.

What is it?

This is a custom plugin for Gradle which provides the following.

Tasks for invoking devenv.com to build and clean a Visual Studio solution.
Auto-detecting a solution file in your module.
Automatic task dependencies between modules in a multi-module workspace. This means that a module which is a dependency of multiple modules will only be built once.
Integration with intrepid-plugin so that source code dependencies automatically configure build task dependencies.
Additional configuration for
- specifying a solution file;
- specifying which platforms to build; and
- specifying which version of devenv.com to use.

Example build script

Here is a minimal build script involving this plugin.

buildscript {
    gplugins.use "devenv:7.2.5"
}
gplugins.apply()

DevEnv.solutionFile "foo.sln"

When executed, it causes the following to happen.

Version 7.2.5 of the devenv plugin is fetched and used in the script.
The plugin is configured to use the solution file "foo.sln".
Build tasks including buildDebug, buildRelease, cleanDebug, and cleanRelease are defined to operate on the solution file.

DSL Guide

DevEnv

solutionFile

Currently, this is the only essential piece of configuration for this plugin. You have to tell the plugin which solution file to use, as in the following example.

DevEnv {
    solutionFile "my_module/build/my_solution.sln"
}

This tells the devenv plugin to use the my_solution.sln solution file in a my_module/build subdirectory of the build script directory.

version

This method defines the version of devenv.com that the tasks should when building or cleaning.

DevEnv {
    version "VS120"
}

The version must match one of the following forms.

VSnnn, where all except the last digit is used to match the major version.
nn.n, which matches an exact version (for Visual Studio 2017 and later; since Holy Gradle 7.10.3).
nn.+, which matches the major version and ignores the minor version (for Visual Studio 2017 and later; since Holy Gradle 7.10.3).

The version is used to construct a path to devenv.com as follows.

If the version string starts with "VS", get the value of the <version>COMNTOOLS environment variable, for example, VS100COMNTOOLS.
If that environment variable is defined and has a non-empty value, the resulting path will have ../IDE/devenv.com appended.
(Since Holy Gradle 7.10.1.) If the variable is undefined or empty, try to find the vswhere.exe tool in both %ProgramFiles(x86)%\Microsoft Visual Studio\Installer and %ProgramFiles%\Microsoft Visual Studio\Installer for vswhere.exe.
If it is not found, then fail.
If it is found, then pass the version string to vswhere.exe to find the installation path.
The resulting path will have /Common7/IDE/devenv.com appended.

The different versions of Visual Studio have environment variables and internal versions which correspond as follows. From Visual Studio 2017 onwards, there is no environment variable.

VS Product Version	Holy Gradle Version String	Variable	VS Internal Version
2005	`VS80` or `8.0`	`VS80COMNTOOLS`	8.0
2008	`VS90` or `9.0`	`VS90COMNTOOLS`	9.0
2010	`VS100` or `10.0`	`VS100COMNTOOLS`	10.0
2012	`VS110` or `11.0`	`VS110COMNTOOLS`	11.0
2013	`VS120` or `12.0`	`VS120COMNTOOLS`	12.0
2015	`VS140` or `14.0`	`VS140COMNTOOLS`	14.0
2017	`15.0`	n/a	15.0
	`15.1`	n/a	15.1
	etc.	n/a	etc.
	`15.`+	n/a	Latest of any installed "15.x"

→ Call this method exactly once. As of version 7.7.0, there is no default; previously it was "VS100".

platform

This method defines the platform parameter which will be passed on the command line to devenv.com when initiating a build or clean operation. If multiple values are passed in, separate build tasks will be created for each.

DevEnv {
    platform "Win32", "x64"
}

→ Default value: "x64"

incredibuild

For build tasks you have the option to replace the invocation of DevEnv with IncrediBuild. To do this, simply supply the full path to the IncrediBuild BuildConsole.exe e.g.

DevEnv {
    incredibuild "c:/Xoreax/IncrediBuild/BuildConsole.exe"
}

Tip	You may want to put this configuration in a user.gradle file in order to keep it out of build scripts that are committed to source control.

defineErrorRegex

This method allows you to define additional regular expressions to catch errors in the output of devenv.com, or any tools that are invoked by devenv.com. Errors are colour-coded as red and summarised at the bottom of the build output.

Here is an example of an error regex which is applied by default — you don’t need to define this yourself.

defineErrorRegex(/.* [error|fatal error]+ \w+\d{2,5}:.*/)

A tool such as http://www.regextester.com can help you develop your regex.

defineWarningRegex

This method allows you to define additional regular expressions to catch warnings in the output of devenv.com, or any tools that are invoked by devenv.com. Warnings are colour-coded as yellow and summarised at the bottom of the build output.

Here is an example of an warning regex which is applied by default — you don’t need to define this yourself.

defineWarningRegex(/.* warning \w+\d{2,5}:.*/)

A tool such as http://www.regextester.com can help you develop your regex.

Multi-project workspaces

In a multi-project workspace, you have the option of putting some of the above configuration in the root build-script instead of repeating it in the build-scripts for the individual projects. If you put a DevEnv block in your root build.gradle its configuration will automatically apply to all sub-projects, for example the following.

DevEnv {
    version "VS90"
    platform "Win32"
    incredibuild "c:/Xoreax/Incredibuild/BuildConsole.exe"
}

Sub-projects can also specify some or all of these values, which supersedes the configuration in the root project. The solutionFile method does not make sense in the root project, because sub-projects will have different solution file names.