Skip to content

Commit 447f493

Browse files
kevcadieuxShannonLeavitt
kevcadieux
authored and
ShannonLeavitt
committed
Build insights (#2314)
* Initial Work. * Adding images and tweaking the layout. * Adding a TOC entry. Setting up a bread crumb. Tweaking a sentence. * Initial Work. * Adding images and tweaking the layout. * Adding a TOC entry. Setting up a bread crumb. Tweaking a sentence. * Fixing locale in WPA documentation link. * Fixing style issues uncovered by Acrolinx. * Attempting to fix internal link warning. * Improving style and fixing a typo. * Minor style edit. * Moving the MSVC Build Insights section under Pojects and build systems. * Fixing breadcrumb. * Added a vcperf.exe reference page. * Actually adding the vcperf reference page. * Trying spaces between the vcperf arguments. * Name change and removing colored boxes. * Acrolinx fixes. * Fix spelling error. * Acrolinx feedback. * Name change and new GUID for vcperf-reference page. * Adding the WPA views reference. * Address Acrolinx feedback. * Adding the WPA basics page. * Acrolinx feedback. * Fixing image borders. * Adding the WPA basics page in the TOC. * Adding a link to the WPA basics page on the Getting started page. * Using the correct URL for the WPA basics link. * Moved the WPA basics link above the vcperf.exe reference link. * Removing en-us from URL.
1 parent 183c45c commit 447f493

14 files changed

Lines changed: 301 additions & 0 deletions

‎docs/build-insights/getting-started.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "Getting started with C++ Build Insights"
3+
description: "A high-level overview of how to use the tools that are part of C++ Build Insights."
4+
ms.date: "09/06/2019"
5+
helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"]
6+
ms.assetid: 88dbcc3a-787b-4da5-b6ae-738fe6f02e7f
7+
---
8+
# Getting started with C++ Build Insights
9+
10+
## Introduction
11+
12+
C++ Build Insights is a collection of tools that provides increased visibility into the Microsoft Visual C++ (MSVC) tool chain. It collects data about your C++ builds and presents it in a format that can help you answer common questions like:
13+
14+
- Are my builds sufficiently parallelized?
15+
- What should I include in my pre-compiled header (PCH)?
16+
- Is there a specific bottleneck I should focus on to increase my build speeds?
17+
18+
The two principal components of this technology are the command-line utility *vcperf.exe* and an add-in for the Windows Performance Analyzer (WPA) trace viewer. The utility is used to collect traces of your build, while the add-in allows you to view them in WPA. On this page, we will show you how to quickly get started using these two tools.
19+
20+
## Step 1: Install and configure Windows Performance Analyzer
21+
22+
WPA is a trace viewer available in the Windows Assessment and Deployment Kit (ADK). It needs to be obtained separately from Visual Studio. Acquiring and setting up this component can be done by following the steps below.
23+
24+
### Acquisition steps
25+
26+
A version of WPA that supports C++ Build Insights is currently only available in the Windows ADK Insider Preview. To access this preview, you will need to sign up to the Windows Insider Program. You do not need to install the Windows 10 Insider Preview operating system to obtain the Windows ADK preview; simply registering your Microsoft account with the Windows Insider Program is enough.
27+
28+
1. Browse to the Windows ADK Insider Preview [download page](https://www.microsoft.com/software-download/windowsinsiderpreviewADK).
29+
1. Download the Windows ADK Insider Preview. It is a disk image.
30+
1. Open the disk image and run the *adksetup.exe* installer.
31+
1. When prompted for the features that you want to install, select the Windows Performance Toolkit. You may select other features if you wish, but they are not required to install WPA.
32+
33+
The image below shows an appropriate feature selection:
34+
35+
![The Windows Performance Analyzer installer's feature selection screen](media/wpa-installation.png)
36+
37+
### Configuration steps
38+
39+
1. Launch WPA.
40+
1. Select Window -> Select Tables (Experimental).
41+
1. Scroll down to the Diagnostics section.
42+
1. Make sure all the C++ Build Insights views are selected.
43+
44+
A correctly configured table selection looks like the following image:
45+
46+
![Windows Performance Analyzer's table selection panel](media/wpa-configuration.png)
47+
48+
## Step 2: Trace your build with vcperf.exe
49+
50+
Viewing C++ Build Insights data requires you to first collect it into a trace file by following these steps:
51+
52+
1. Open a native tools or cross tools command prompt for Visual Studio 2019 in administrative mode.
53+
1. Issue the following command: `vcperf.exe /start SessionName`. Choose a session name that you will remember.
54+
1. Build your project as you normally would. You do not need to use the same command prompt.
55+
1. Issue the following command: `vcperf.exe /stop SessionName traceFile.etl`. Use the same session name that was chosen when issuing the start command. Give your trace file an appropriate name.
56+
57+
The image below illustrates the use of *vcperf.exe*:
58+
59+
![A simple vcperf.exe usage scenario](media/vcperf-simple-usage.png)
60+
61+
### Important notes about vcperf.exe
62+
63+
- Starting and stopping a trace with *vcperf.exe* requires administrative privileges.
64+
- Only one tracing session at a time may run on a machine.
65+
- Make sure to remember the session name you used to start your trace. Stopping a running session without knowing its name can be troublesome.
66+
- Just like *cl.exe* and *link.exe*, the command-line utility *vcperf.exe* is included in an MSVC installation. No additional step is required to obtain this component.
67+
- *vcperf.exe* collects information about all MSVC tools running on your system. As a result, it is not necessary to start your build from the command prompt that you used to collect the trace. If desired, you can build your project from either a different command prompt or even Visual Studio.
68+
69+
## Step 3: View your trace in Windows Performance Analyzer
70+
71+
Launch WPA and open the trace you just collected. WPA should recognize it as a C++ Build Insights trace, and the following views should appear in the Graph Explorer panel on the left:
72+
73+
- Build Explorer
74+
- Files
75+
- Function
76+
77+
If you cannot see these views, double-check that WPA has been configured correctly as described in [Configuration steps](#configuration-steps). You can view your build data by dragging the views into the empty Analysis window on the right. This step is shown in the image below.
78+
79+
Other views might also be available in the Graph Explorer panel. Feel free to also drag them into the Analysis window if you are interested in the information they contain. A useful one is the CPU (Sampled) view, which shows CPU utilization throughout your build.
80+
81+
![Viewing a C++ Build Insights trace in Windows Performance Analyzer](media/wpa-viewing-trace.gif)
82+
83+
## More information
84+
85+
[Windows Performance Analyzer basics](wpa-basics.md)<br/>
86+
Learn about common WPA operations that can help you analyze your build traces.
87+
88+
[vcperf.exe reference](vcperf-reference.md)<br/>
89+
View this page for a list of *vcperf.exe* commands.
90+
91+
[Windows Performance Analyzer views reference](wpa-views-reference.md)<br/>
92+
Refer to this page for details about the C++ Build Insights views in WPA.
93+
94+
[Windows Performance Analyzer](https://docs.microsoft.com/windows-hardware/test/wpt/windows-performance-analyzer)<br/>
95+
The official WPA documentation site.

‎docs/build-insights/media/vcperf-simple-usage.png‎

30.5 KB
Loading

‎docs/build-insights/media/wpa-configuration.png‎

90.2 KB
Loading

‎docs/build-insights/media/wpa-grouping.gif‎

411 KB
Loading

‎docs/build-insights/media/wpa-installation.png‎

97.6 KB
Loading

‎docs/build-insights/media/wpa-presets.png‎

48 KB
Loading

‎docs/build-insights/media/wpa-switching-view-mode.gif‎

90.1 KB
Loading

‎docs/build-insights/media/wpa-viewing-trace.gif‎

82.6 KB
Loading

‎docs/build-insights/media/wpa-zooming.gif‎

192 KB
Loading

‎docs/build-insights/vcperf-reference.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: "C++ Build Insights: vcperf.exe reference"
3+
description: "Reference for the command-line utility vcperf.exe."
4+
ms.date: "09/16/2019"
5+
helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"]
6+
ms.assetid: a2a4c05a-4a77-44da-922e-d2c939cfd4e6
7+
---
8+
# C++ Build Insights: vcperf.exe reference
9+
10+
## Introduction
11+
12+
This section describes the commands that are available in *vcperf.exe* and how to use them.
13+
14+
## Commands to start and stop traces
15+
16+
*IMPORTANT: the following commands all require administrative privileges.*
17+
18+
| Option | Arguments and description |
19+
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
20+
| `/start` | `[/nocpusampling]` `<sessionName>` |
21+
| | Instructs *vcperf.exe* to start a trace under the given session name. There may only be one active session at a time on a given machine. <br/><br/> If the `/nocpusampling` option is specified, *vcperf.exe* will not collect CPU samples. This will prevent the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but will make the collected traces smaller. <br/><br/> Once tracing is started, *vcperf.exe* returns immediately. Events are collected system-wide for all processes running on the machine. This means that you do not need to build your project from the same command prompt as the one you used to run *vcperf.exe*. For example, you can build your project from Visual Studio. |
22+
| `/stop` | `<sessionName>` `<outputFile.etl>` |
23+
| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file that can be viewed in Windows Performance Analyzer (WPA). For the best viewing experience, you will need a version of WPA that includes the C++ Build Insights add-in. For more information, please see the [Getting started](getting-started.md) page. The `<outputFile.etl>` parameter specifies the location where the output file will be saved. |
24+
| `/stopnoanalyze` | `<sessionName>` `<rawOutputFile.etl>` |
25+
| | Stops the trace identified by the given session name and writes the raw, unprocessed data in the specified output file. The resulting file is not meant to be viewed in WPA. <br/><br/> The post-processing step involved in the `/stop` command can sometimes be lengthy. You can use the `/stopnoanalyze` command to delay this post-processing step. Use the `/analyze` command when you are ready to produce a file that can be viewed in Windows Performance Analyzer. |
26+
27+
## Miscellaneous commands
28+
29+
| Option | Arguments and description |
30+
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
31+
| `/analyze` | `<rawInputFile.etl> <outputFile.etl>` |
32+
| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate a file that is suitable for viewing in Windows Performance Analyzer. For the best viewing experience, you will need a version of WPA that includes the C++ Build Insights add-in. For more information, please see the [Getting started](getting-started.md) page. |

0 commit comments

Comments
 (0)