Score Generation - Viladoman/CompileScore GitHub Wiki
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 |