C++20 demands a lot more from the ecosystem than ever before. With C++20 Modules on the horizon the compiler needs to work closely with project systems in order to provide rich information for build dependency gathering and making iterative builds faster for inner-loop development. The compiler and project teams have acknowledged the new relationship and collaborated together to bring a new switch to the compiler toolset which can provide useful information to the build system: /sourceDependencies.
Source Dependency Reporting
The new switch for the compiler toolset enables the compiler to generate a source-level dependency report for any given translation unit it compiles. This report is output as a JSON file and you can produce it like this:
$ cl /Yupch.pch /FIpch.h /std:c++latest /experimental:module /module:reference m=m.ifc /headerUnit other.h=other.h.ifc /sourceDependencies main.json main.cpp
Notice the use of /sourceDependencies main.json.
Given the following program:
// main.cpp
#include "header.h"
import m;
import "other.h";
int main() { }
The dependency report generated to main.json might look something like:
{
"Version": "1.0",
"Data": {
"Source": "C:\\...\\main.cpp",
"PCH": "C:\\...\\pch.pch",
"Includes": [
"C:\\...\\header.h"
],
"Modules": [
"C:\\...\\m.ifc",
"C:\\...\\other.h.ifc"
]
}
}
Additionally, the use of /sourceDependencies is not limited only to C++, it can also be used in translation units compiled as C! Moreover, the switch is designed to be used with multiple files and scenarios under /MP. Please see the documentation page for more information regarding these scenarios.
Stay Tuned
The /sourceDependencies output is subject to change and will evolve based on needs of the C++ build system ecosystem. The intent is to collect feedback from deployment in the field in order to provide feedback to the WG21/SG15 Study Group and to refine the proposal P1689. The documentation will be updated to reflect necessary future changes. We encourage users to leverage the Version field to account for the evolving nature, and to ensure that information contained in the dependency output are appropriately interpreted.
We urge you to go out and try using MSVC’s new /sourceDependencies switch. Visual Studio 2019 version 16.7 is available right now through the Visual Studio 2019 downloads page.
As always, we welcome your feedback. Feel free to send any comments through e-mail at visualcpp@microsoft.com or through Twitter @visualc. Also, feel free to follow me on Twitter @starfreakclone.
If you encounter other problems with MSVC in VS 2019 please let us know via the Report a Problem option, either from the installer or the Visual Studio IDE itself. For suggestions or bug reports, let us know through DevComm.
nice!
can’t wait for full modules support in visual studio, this is game changer!
Good job bro
download game pc .
Good article and a good starting point.
This feature seems to me to be very well suited to provide other tools with information for the analysis of single .CPP files.
What is still missing from my point of view:
* list of defines that are valid for the file
* Is it possible to store the data of several files in one JSON file? f1.cpp, f2.cpp => both in dependencies.json
* This also raises the question why...
I hope it also supports formats other than json in the future..
i like Visual Studio
good article
I’m also looking at titles like this
Is there an option to output to stdout like /showIncludes? Perhaps by doing “/sourceDependencies stdout” ? This would sound like an important feature for build systems like Ninja without needing to write to disk which will be slow.
As an interesting sidenote, this seems like a much nicer and more useful way to get the information than /showIncludes, because of the JSONification of things. I was annoyed years ago when JSON started to be the lingua-franca for lots of text-based data (another friggin notation for data?? No types? No predefined interfaces or layouts?), but it’s working out pretty well.
I should note though that /showIncludes does offer one thing that this feature currently does not, which is the tree structure of the includes. I look at the output of /showIncludes from time to time when I touch some header and then wonder why does a particular cpp file recompile as a result. By tracing the tracing the indentation, I can find the chain of dependencies that lead to why the particular cpp file is...
Hi e4lam,
Unfortunately, for 16.7 there is no option to emit the output report directly to stdout. 16.8 will change this behavior by offering the ability to emit the report directly to stdout. We will update the documentation when this happens, or once it is made available in 16.8 Preview 2 you can try it out for yourself by providing the output file of “-“.
Good job! This is a long waited feature, it should be a drop in replacement for the verbose /showIncludes !
Questions:
1. Any performance metrics of this operation?
2. If this dependency scanner can run before compile or it must be done along with a full compile?
Hi Yupeng,
Thank you! To answer some of your questions:
1. We have not extensively benchmarked the use of this switch in complex builds but when performing local benchmarks the perf impact appears to be < 0.05% where the majority of the time is spent simply writing the file. Thus, the overhead is proportional to file I/O on the dependency file itself. 2. The functionality of the dependency report is not to scan your source, it...