This post was written by Olga Arkhipova.
Many projects need to use additional tools during their build to generate sources for further compilation or perform other custom build tasks. VC projects have always supported Custom Build Tool integration, but it had some limitations. One of the popular requests on UserVoice is Allow custom build tools to run in parallel. Another problem is that often custom build outputs need to be passed to other build tools (for instance, some tools can generate C/C++ sources, which need to be passed to the compiler) and there was no easy way to specify that.
To solve these problems, we added support for parallel execution of custom build tools and new options for easier build integration in Visual Studio 2017 15.8.
Also, one of the most common build customizations is copying files. Before, we recommended using “Custom Build Step” or “Custom Build Tool” and specifying copy commands there. Now you can use simple Copy File options.
Custom Build Tool Options
If you are familiar with Custom Build Tool usage, you can skip this section and go to New Custom Build Tool Options.
Custom Build Tool options are not visible in the “Project Properties” until you have at least one file using “Custom Build Tool” as its “Item Type”. You can set it in the file’s “General” properties:
As for other tools, you can set “Custom Build Tool” properties for each file, but usually it is easier to set them at the project configuration level, so they apply to all files which use “Custom Build Tool”. Note that you can use MSBuild Well-known Item Metadata there to specify file specific options. Unfortunately, you cannot use other item properties as they are not guaranteed to be defined before their usage.
Command Line
Specifies the command(s) to execute in cmd.exe. If you want several commands to be executed for the same file, you can add them to a script file or just enter them in the property editor, each command on a separate line:
Description
Specifies a message to be printed before execution of the command(s), optional. It is added as ‘’echo” command, so if you want to use “>” symbol, it needs to be escaped: “^>”.
Outputs
Specifies the output files the custom build tool generates.
Additional Dependencies
Specifies any additional input files to use for the custom build tool. Required for incremental build.
Link Objects
Specify whether the Inputs and outputs files with specific extensions (.obj, .lib, .res, .rsc) are passed to the linker.
This property was added in VS 2010 to maintain the behavior of pre-msbuild vc projects (VS 2009 and before) where file extensions determined which build action was performed on them.
MSBuild is operating on items included into a particular named ItemGroup (Item Type), so we recommend using the new “Add Outputs to Item Type” property instead.
Treat Output As Content
Specify whether the output file is a deployable content. Only used in projects supporting packaging (Universal Windows).
Content Root Folder
Content root folder to use for packaging.
Execute After, Execute Before
Define when to execute Custom Build Tool and Custom Build Step commands. For historical reasons they are executed at the same time.
The options are using msbuild target names, which requires you to have some understanding of msbuild targets execution order during build. There is a long list of the targets in the dropdown you can select from and you can type the target name there as well, but usually you just need to select one of the following targets which represent 3 main steps of C++ build:
- BuildGenerateSources
- BuildCompile
- BuildLink
If your custom build needs to be executed in more precise time, you might need to look at your detailed (or binary) build log – you’ll see all targets executed during build and their order.
New Custom Build Tool Options
Add Outputs to Item Type
If you want custom build outputs to become inputs for another build operation, you can specify it here.
For instance, if you want the outputs to be compiled, you need to add them to “C/C++ compiler” item type. You also need to make Custom Build Tool to be executed before C/C++ compilation by setting “Execute After” to “BuildGenerateSources” or “Execute Before” to “BuildCompile”.
Build in Parallel
Specifies that this item can be built in parallel with other custom build tool items.
Maximum Processes
Maximum number of CPU cores to use for parallel build. A value of 0 utilizes all available processors.
Maximum Batch size
Maximum number of items to execute together in one cmd.exe process during parallel build. A value of 0 divides items evenly into parallel batches. A value of 1 disables batching.
Launching a cmd.exe process takes some time, so larger batches will improve performance if the custom build tool processes items quickly. If your custom build takes significant time, disabling batching will give you better error reporting.
Copy File Options
If you need to copy a file to one or several locations during build, first you need to change its “Item Type” to “Copy file” and Apply. Then you’ll see “Copy File” properties.
Again, you can define the options for individual files, or, if they are similar, for project configuration using MSBuild Well-known Item Metadata:
Destination Directories
You can specify one or several directories (separated by ‘;’) to copy the file to. The default is $(OutDir).
Destination File Name
You can specify the file name for the destination file(s). The default is the same as source: %(Filename)%(Extension).
Other properties are the similar to Custom Build Tool and Custom Build step: you can set if the destination file(s) should be included into a package and when to copy the files during build.
Send Us Feedback
Please download Visual Studio 2017 version 15.8 and try the new Custom Build Tool and Copy File functionality. We would love to know how it is working for you. Please give us feedback via the comments below or via email (visualcpp@microsoft.com). For general issues please Report a Problem.