File inclusions

In this page we'll explore which info you can get from the FileInclusionTimes.csv and FileInclusions.dgml reports.

FileInclusions.dgml

This report presents the whole inclusion graph for your build.
To create it, we record all inclusions from all files as reported by the SDK.

You can open this file in Visual Studio with the DGML Editor (just drag-and-drop the file into Visual), which you can install from Visual Studio Installer. I also recommend installing the DGML Power Tools extension, which has cool features like only showing the direct and indirect inclusions for a file:

This report's viability is mostly aimed at small-sized projects (whose build you may not be even profiling).

Rule of thumb

Because it's cumbersome to inspect, just rely on this report to check for inclusions you didn't expect

FileInclusionTimes.csv

If we were to check the sample file provided in the repo we would find something like this:

File path	Average elapsed time (nanoseconds)	Minimum elapsed time (nanoseconds)	Maximum elapsed time (nanoseconds)	Standard deviation (nanoseconds)	Occurrences
Z:\cpp-build-analyzer\src\AnalysisData\PCH\PCH.h	2080628500	2080628500	2080628500	0	1
C:\Path\To\MSVC\include\iostream	948104200	948104200	948104200	0	1
C:\Path\To\WindowsSDK\um\Windows.h	635602700	632748100	638457300	2854600	2
...	...	...	...	...	...

These represent the time it took the front-end to perform the #include to each file, how long did they take and how many times they were included.

Let's take a look at a more interesting example:

File path	Average elapsed time (nanoseconds)	Minimum elapsed time (nanoseconds)	Maximum elapsed time (nanoseconds)	Standard deviation (nanoseconds)	Occurrences
C:\Path\To\WindowsSDK\shared\poppack.h	84538	70800	192200	18545	68
Z:\cpp-build-analyzer\src\AnalysisData\BuildTimeline\TimelineTypes.h	640210	77500	1310700	393882	10
Z:\cpp-build-analyzer\src\AnalysisData\BuildTimeline\TimelineEntry.h	50702300	21525800	97417500	23779099	7
...	...	...	...	...	...

We can see these files were included several times (i.e. 68, 10, 7).
Because the build we recorded had the /MP compiler flag enabled, files were compiled in parallel. That means some of these files may've been included by two different files at the same time.
That's why we can't sum all occurrences together: that would only give us a valid number in a sequential compilation.

There's something you should keep in mind when looking at this report. Imagine we have this inclusion hierarchy:

Now imagine A.h takes a high average time to be included. That would mean you'd get high averages in B.h, C.h and D.h as well!

In this example, FunctionCompilationsAnalyzer.h is taking relatively long to be included because of another file.

Rule of thumb

Having a file with a lot of occurrences and a high average usually means that file is causing you issues.

What now?

Say you've found some file and want to fix the issue. Ask yourself these questions:

• Is it normal it's included so many times? Maybe you have a number of old #include to this file that are not required anymore.
• Is it normal it takes long to be included? Maybe you are including a lot of files in turn and you can convert them to forward declarations, or add them to a precompiled header.