Score Generation

The main idea is to get the C++ compiler to output a trace for what happened during the build. We can then aggregate all that data using the Data Extractor in this repository, and consume it with the VS plugin or the standalone app.

The data extraction is an independent process in order to allow things like building the score file on a build server and consume it remotely. This can be useful in big codebases where we want the production floor to just use the reports from last night inside VS without having to profile locally.

To manually compute the scores, execute the following steps:

• Start the data extractor
• Build your project as usual
• Stop the data extractor. This process also reads, aggregates and generates the Score files.
• Consume the Score files with the Visual Studio extension or the Standalone App

The Data Extractor can be found in the Releases page or it can be build using the Visual Studio solution located at DataExtractor/Cpp/ScoreDataExtractor.sln. This program contains the generators for both pipelines (Clang and MSVC).

Generation

MSVC

For the Microsoft compiler we are using C++ Build Insights SDK, available on MSVC 16.1 (or newer). In a nutshell, the C++ Build Insights will listen to the OS events emitted by the compiler and keep track of them.

Simple console command example:

• Open a command-line prompt.
• Start Recording: ScoreDataExtractor.exe -msvc -start (Add -d <DetailNumber> to enable more in depth captures).
• Build your C++ project.
• Stop Recording: ScoreDataExtractor.exe -msvc -stop -o ./OutputFile.scor (Add more flags for custom generation)

Clang

Compile Score is using the compiler option -ftime-trace available on Clang 9 (or newer). This outputs a detailed report for each translation unit executed by the compiler. The recording process will generate a file at the root of the provided artifacts folder with the current timestamp in order to know which trace files have been generated inside the folder during the recording session.

Simple console command example:

• Open a console command-line prompt.
• Start Recording: ScoreDataExtractor.exe -clang -start -i ./FolderPathToClangTraces
• Build your C++ project.
• Stop Recording: ScoreDataExtractor.exe -clang -stop -i ./FolderPathToClangTraces -o ./OutputFile.scor

Cancel a recording in progress

If we started a build data capture but we are no longer interested in the capture and we don't want to waste resources processing the result, we can just cancel the recording with: ScoreDataExtractor.exe -msvc -cancel (for MSVC) or ScoreDataExtractor.exe -clang -cancel -i ./FolderPathToClangTraces (for Clang)

Working with Compiler Trace Logs

If we want to build only once per configuration and generate different reports later. We can just tell the stop command to generate a compiler trace instead of the final score file. Useful when we want to generate several .scor with different levels of details and store them remotely on a server, so by default we fetch a small report but we also have the full detailed one available.

In order to do that the output parameter when stopping the recording session needs to be .etl/.ctl instead of .scor;

• MSVC: ScoreDataExtractor.exe -msvc -stop -o ./TraceFile.etl
• Clang: ScoreDataExtractor.exe -clang -stop -i ./FolderPathToClangTraces -o ./TraceFile.ctl

.etl files can also be generated by tools like vcperf.

Then, when a .etl/.ctl wants to be processed:

• MSVC: ScoreDataExtractor.exe -msvc -extract -i ./TraceFile.etl -o ./OutputFile.scor
• Clang: ScoreDataExtractor.exe -clang -extract -i ./TraceFile.ctl -o ./OutputFile.scor

IMPORTANT: The .etl file contains all the data inside the file. Which means that it can be moved around without any issues. On the other hand, the .ctl file it is just a list of .json files that got modified within the recording session (basically a list of paths), meaning that if those artifacts move or are removed, the data is lost.

Process whole Directory

Because Clang works with files generated in the filesystem. We can also, only with Clang data, to just parse a full directory after compilation for all the possible .json traces.

ScoreDataExtractor.exe -clang -extract -i ./FolderPathToClangTraces -o ./OutputFile.scor

Data Extractor Options

Executable Flag	Arguments and description	Mandatory
-help (-h)	Displays all the command line options available	No
-version (-ve)	Displays the data version the binary will produce	No
-clang or -msvc	Sets the system to use the Clang (.json traces) or MSVC (.etl traces) importer	Yes
-start, -stop, -cancel, -extract or -clean	Execution command that will be performed	No
	start : Starts a recording session
	stop : Stops a recording session and generates an output file
	cancel : Cancels a recording session
	extract: Generates a Score file from a compiler trace log (default)
	clean: Deletes the clang trace json files in the given folder (Clang Only)
-input (-i)	Path to Input File	Yes (Clang) No (MSVC)
	The path to the input folder to parse for -ftime-trace data or .etl file
-output (-o)	Output file (compileData.scor by default)	No
	The output file full path for the results
-detail (-d)	Level (3 by default)	No
	The exported detail level for the overview and globals tables.
	Details table below. Useful to reduce the .scor file size on big projects
-timelinedetail (-td)	Level (3 by default)	No
	The exported detail level for the timeline nodes
	Details table below. Useful to reduce the .scor.txxxx file sizes or improve packing
-notimeline (-nt)	No timeline files will be generated	No
-timelinepack (-tp)	Number	No
	The number of timelines packed in the same file (100 by default)
-noincluders (-ni)	No includers file will be generated	No
-keepTemplateArgs (-kta)	Template argments will be kept and each instance will have its own entry	No
-verbosity (-v)	Level	No
	Sets the verbosity level:
	0 : Silent
	1 : Progress (default)
	2 : Full

Detail level table

#	Desc	General	Include	Parse	Instantiate	Code Generation
0	None	Yes	No	No	No	No
1	Basic	Yes	Yes	No	No	No
2	FrontEnd	Yes	Yes	Yes	Yes	No
3	Full	Yes	Yes	Yes	Yes	Yes