Skip to content

Commit 6aee7f0

Browse files
author
Colin Robertson
authored
C++ Build Insights SDK (#2676)
* Restructuring the C++ Build Insights docs to make room for the new C++ Build Insights SDK section. * Minor change. * Fixing links. * Fixing redirection. * Removing stale entries in the TOC. * Adding a small intro to the new vcperf and WPA tutorial. * Adding placeholders for C++ Build Insights SDK types reference. * Adding placeholders for the C++ Build Insights SDK function reference pages. Adding keywords for every SDK entry in the helpviewer array. * Fixing md file name. * Adding placeholder for SDK main page and entities reference. * Fix attempt. * Fix attempt. * Adding documentation for the Analyze and InjectEvent functions. * Fixing link. * Fixups * MakeDynamicAnalyzerGroup reference + some fixes. * Removing Group classes. * Finishing up the reference for group construction functions. * Fleshing out the documentation for some functions entirely. Setting up a skeleton for all classes including anchors, links, code and headers. * Adding skeleton for all remaining pages. * Adding missing C API functions. * Adding remaining structs for C API. * Last enums for the C API. * Finalizing the setup for all type pages.. * Fleshing out some pages. * Fixing link. * Adding more details on the Data field in the EVENT_DATA structure. * Fixing link. * Fixing table. * Adding reference to C++ API functions. * Renaming some structures. * Fleshed out some structures. * Finessing callbacks and descriptors. * Format changes * More structs. * Fix link * Fix name * Adding an Events page. * Fleshing out event table. * Finishing events page. * Structure changes. * Lowercase URL's and fixing links. * Links to lowercase * Fixing case and links. * Fixing links and case. * Adding C++ event classes for matching. * Fixes * Fixups. * Adding more information in the Events page. * Fixes and refinements. * Restructuring enums and flags. * Fixing links. * Fixing link. * Fixing spelling error. * Fixing global links and refining the events reference. * Fixing link. * Fixing links. * Finishing up the events reference. * Finishing Activity class. * Finishing the Entity class. * Some more C++ classes. * Finishing C++ event API pages. * Fixing links. * Fixing links. * Progress * Finishing all C and C++ types. * Fixing links. * Progress in functions. * Formatting changes. * Finishing up functions pages. * Fixing link. * Fixing links. * Changes * Progress * Progress * Progress * Progress * Fixing links. * Fixing links. * Fixups. * Fixing links. * Added a small intro to the overview. * Refinement * Fix * Fixing event names. * Fixing spacing. * Fixing links. * Fixing links. * Fixing links. * Fixing struct name. * Minor changes. * Fixing links. * Fixing links. * Fixing links. * Fixing links. * Fixing links. * Fixing links. * Reworking the overview to also contain information about events instead of having to go through 2 different pages. The previous events page is now only the event table. * Fixing links. * Adding the RawEvent class page. * Fixing some incorrect information. * Corrections. * Clarifying how to pass dynamic groups to the Analyze and Relog family of functions. * Partial Acrolinx pass. * Merge overview changes * Small tweak. * Acrolinx all the functions. * Moar Acrolinx fixes * Last Acrolinx mods Co-authored-by: Colin Robertson <corob@microsoft.com>
1 parent 8f9ef91 commit 6aee7f0

File tree

126 files changed

+7591
-117
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

126 files changed

+7591
-117
lines changed

‎.openpublishing.redirection.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -685,6 +685,21 @@
685685
"redirect_url": "/cpp/build-insights/get-started-with-cpp-build-insights",
686686
"redirect_document_id": false
687687
},
688+
{
689+
"source_path": "docs/build-insights/vcperf-reference.md",
690+
"redirect_url": "/cpp/build-insights/reference/vcperf-commands",
691+
"redirect_document_id": false
692+
},
693+
{
694+
"source_path": "docs/build-insights/wpa-basics.md",
695+
"redirect_url": "/cpp/build-insights/tutorials/wpa-basics",
696+
"redirect_document_id": false
697+
},
698+
{
699+
"source_path": "docs/build-insights/wpa-views-reference.md",
700+
"redirect_url": "/cpp/build-insights/reference/wpa-views",
701+
"redirect_document_id": false
702+
},
688703
{
689704
"source_path": "docs/c-language/index.md",
690705
"redirect_url": "/cpp/c-language/c-language-reference",

‎docs/build-insights/get-started-with-cpp-build-insights.md‎

Lines changed: 12 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Get started with C++ Build Insights"
3-
description: "A high-level overview of how to use the build-time performance analysis tools that are part of C++ Build Insights."
3+
description: "A high-level overview of C++ Build Insights."
44
ms.date: "11/03/2019"
55
helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"]
66
---
@@ -19,102 +19,21 @@ C++ Build Insights is a collection of tools that provides increased visibility i
1919
- What should I include in my pre-compiled header (PCH)?
2020
- Is there a specific bottleneck I should focus on to increase my build speeds?
2121

22-
The two main 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. Follow these steps to get started using these two tools.
22+
The main components of this technology are:
2323

24-
## Step 1: Install and configure Windows Performance Analyzer
24+
- *vcperf.exe*, a command-line utility that you can use to collect traces for your builds,
25+
- a Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and
26+
- the C++ Build Insights SDK, a software development kit for creating your own tools that consume C++ Build Insights data.
2527

26-
WPA is a trace viewer available in the Windows Assessment and Deployment Kit (ADK). It's a separate utility that's not part of the components you can install with the Visual Studio installer.
28+
Click on the links below to quickly get started with these components:
2729

28-
A version of WPA that supports C++ Build Insights is currently only available in the Windows ADK Insider Preview. To access this preview, you must sign up for the [Windows Insider program](https://insider.windows.com). You don't need to install the Windows 10 Insider Preview operating system to obtain the Windows ADK preview. You only need to register your Microsoft account with the Windows Insider Program.
30+
[Tutorial: vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\
31+
Learn how to collect build traces for your C++ projects and how to view them in WPA.
2932

30-
### To download and install WPA
33+
[Tutorial: Windows Performance Basics](tutorials/wpa-basics.md)\
34+
Discover useful WPA tips for analyzing your build traces.
3135

32-
NOTE: Windows 8 or above is required for installing the Windows Performance Analyzer.
33-
34-
1. Browse to the Windows ADK Insider Preview [download page](https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewADK).
35-
36-
1. Download the Windows ADK Insider Preview. It's a disk image.
37-
38-
1. Open the disk image and run the *adksetup.exe* installer.
39-
40-
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're not required to install WPA.
41-
42-
![The Windows Performance Analyzer installer's feature selection screen](media/wpa-installation.png)
43-
44-
### <a name="configuration-steps"></a> To configure Build Insights
45-
46-
1. Launch WPA.
47-
48-
1. Select **Window** > **Select Tables (Experimental)**.
49-
50-
1. Scroll down to the **Diagnostics** section.
51-
52-
1. Select all the MSVC Build Insights views.
53-
54-
![Windows Performance Analyzer's table selection panel](media/wpa-configuration.png)
55-
56-
## Step 2: Trace your build with vcperf.exe
57-
58-
To view C++ Build Insights data, first collect it into a trace file by following these steps:
59-
60-
1. Open a native tools or cross tools developer command prompt for Visual Studio 2019 in administrator mode. (Right-click the Start menu item and choose **More** > **Run as administrator**.)
61-
62-
1. In the command prompt window, enter this command:
63-
64-
**vcperf.exe /start _SessionName_**
65-
66-
Choose a session name you'll remember for *SessionName*.
67-
68-
1. Build your project as you normally would. You don't need to use the same command prompt window to build.
69-
70-
1. In the command prompt window, enter this command:
71-
72-
**vcperf.exe /stop _SessionName_ _traceFile.etl_**
73-
74-
Use the same session name you chose for *SessionName* before. Choose an appropriate name for the *traceFile.etl* trace file.
75-
76-
Here's what a typical *vcperf.exe* command sequence looks like in a developer command prompt window:
77-
78-
![A simple vcperf.exe usage scenario](media/vcperf-simple-usage.png)
79-
80-
### Important notes about vcperf.exe
81-
82-
- Administrator privileges are required to start or stop a *vcperf.exe* trace. Use a developer command prompt window that you open by using **Run as administrator**.
83-
84-
- Only one tracing session at a time may run on a machine.
85-
86-
- Make sure to remember the session name you used to start your trace. It can be troublesome to stop a running session without knowing its name.
87-
88-
- Just like *cl.exe* and *link.exe*, the command-line utility *vcperf.exe* is included in an MSVC installation. No additional steps are required to obtain this component.
89-
90-
- *vcperf.exe* collects information about all MSVC tools running on your system. As a result, you don't have to start your build from the same command prompt you used to collect the trace. You can build your project from either a different command prompt, or even in Visual Studio.
91-
92-
## Step 3: View your trace in Windows Performance Analyzer
93-
94-
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:
95-
96-
- Build Explorer
97-
- Files
98-
- Function
99-
100-
If you can't see these views, double-check that WPA is configured correctly, as described in [Step 1](#configuration-steps). You can view your build data by dragging the views into the empty Analysis window on the right, as shown here:
101-
102-
![Viewing a C++ Build Insights trace in Windows Performance Analyzer](media/wpa-viewing-trace.gif)
103-
104-
Other views are available in the Graph Explorer panel. Drag them into the Analysis window when you're interested in the information they contain. A useful one is the CPU (Sampled) view, which shows CPU utilization throughout your build.
105-
106-
## More information
107-
108-
[Windows Performance Analyzer basics](wpa-basics.md)\
109-
Learn about common WPA operations that can help you analyze your build traces.
110-
111-
[vcperf.exe reference](vcperf-reference.md)\
112-
The *vcperf.exe* command reference lists all the available command options.
113-
114-
[Windows Performance Analyzer views reference](wpa-views-reference.md)\
115-
Refer to this article for details about the C++ Build Insights views in WPA.
116-
117-
[Windows Performance Analyzer](/windows-hardware/test/wpt/windows-performance-analyzer)\
118-
The official WPA documentation site.
36+
[C++ Build Insights SDK](reference/sdk/overview.md)\
37+
An overview of the C++ Build Insights SDK.
11938

12039
::: moniker-end

‎docs/build-insights/reference/sdk/c-event-data-types/cl-pass-data-struct.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: "CL_PASS_DATA structure"
3+
description: "The C++ Build Insights SDK CL_PASS_DATA structure reference."
4+
ms.date: "02/12/2020"
5+
helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CL_PASS_DATA", "throughput analysis", "build time analysis", "vcperf.exe"]
6+
---
7+
# CL_PASS_DATA structure
8+
9+
::: moniker range="<=vs-2015"
10+
11+
The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio version selector control for this article to Visual Studio 2017 or Visual Studio 2019.
12+
13+
::: moniker-end
14+
::: moniker range=">=vs-2017"
15+
16+
The `CL_PASS_DATA` structure describes a compilation pass.
17+
18+
## Syntax
19+
20+
```cpp
21+
typedef struct CL_PASS_DATA_TAG
22+
{
23+
int TranslationUnitPassCode;
24+
const wchar_t* InputSourcePath;
25+
const wchar_t* OutputObjectPath;
26+
27+
} CL_PASS_DATA;
28+
```
29+
30+
## Members
31+
32+
| | |
33+
|--|--|
34+
| `TranslationUnitPassCode` | A code identifying the compilation pass being executed. For more information, see [TRANSLATION_UNIT_PASS_CODE](translation-unit-pass-code-enum.md). |
35+
| `InputSourcePath` | The C or C++ source file on which this compilation pass is being executed. |
36+
| `OutputObjectPath` | The object file being produced by the compiler. |
37+
38+
::: moniker-end

‎docs/build-insights/reference/sdk/c-event-data-types/event-collection-data-struct.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "EVENT_COLLECTION_DATA structure"
3+
description: "The C++ Build Insights SDK EVENT_COLLECTION_DATA structure reference."
4+
ms.date: "02/12/2020"
5+
helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_COLLECTION_DATA", "throughput analysis", "build time analysis", "vcperf.exe"]
6+
---
7+
# EVENT_COLLECTION_DATA structure
8+
9+
::: moniker range="<=vs-2015"
10+
11+
The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio version selector control for this article to Visual Studio 2017 or Visual Studio 2019.
12+
13+
::: moniker-end
14+
::: moniker range=">=vs-2017"
15+
16+
The `EVENT_COLLECTION_DATA` structure describes an array of [EVENT_DATA](event-data-struct.md) elements.
17+
18+
## Syntax
19+
20+
```cpp
21+
typedef struct EVENT_COLLECTION_DATA_TAG
22+
{
23+
unsigned int Count;
24+
const EVENT_DATA* Elements;
25+
26+
} EVENT_COLLECTION_DATA;
27+
```
28+
29+
## Members
30+
31+
| | |
32+
|--|--|
33+
| `Count` | The number of `EVENT_DATA` elements in the array. |
34+
| `Elements` | Pointer to the first `EVENT_DATA` element in the array. |
35+
36+
::: moniker-end

‎docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: "EVENT_DATA structure"
3+
description: "The C++ Build Insights SDK EVENT_DATA structure reference."
4+
ms.date: "02/12/2020"
5+
helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_DATA", "throughput analysis", "build time analysis", "vcperf.exe"]
6+
---
7+
# EVENT_DATA structure
8+
9+
::: moniker range="<=vs-2015"
10+
11+
The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio version selector control for this article to Visual Studio 2017 or Visual Studio 2019.
12+
13+
::: moniker-end
14+
::: moniker range=">=vs-2017"
15+
16+
The `EVENT_DATA` structure describes an event received from an analysis or relogging session. These sessions are started by calling the [Analyze](../functions/analyze.md), [AnalyzeA](../functions/analyze-a.md), [AnalyzeW](../functions/analyze-w.md), [Relog](../functions/relog.md), [RelogA](../functions/relog-a.md), or [RelogW](../functions/relog-w.md) functions.
17+
18+
## Syntax
19+
20+
```cpp
21+
typedef struct EVENT_DATA_TAG
22+
{
23+
unsigned short EventId;
24+
unsigned long long EventInstanceId;
25+
26+
long long TickFrequency;
27+
long long StartTimestamp;
28+
long long StopTimestamp;
29+
long long ExclusiveDurationTicks;
30+
long long CPUTicks;
31+
long long ExclusiveCPUTicks;
32+
long long WallClockTimeResponsibilityTicks;
33+
long long ExclusiveWallClockTimeResponsibilityTicks;
34+
35+
const void* Data;
36+
37+
unsigned long ProcessId;
38+
unsigned long ThreadId;
39+
unsigned short ProcessorIndex;
40+
41+
const char* EventName;
42+
const wchar_t* EventWideName;
43+
44+
} EVENT_DATA;
45+
```
46+
47+
## Members
48+
49+
| | |
50+
|--|--|
51+
| `EventId` | A number that identifies the event. For a list of event identifiers, see [EVENT_ID](event-id-enum.md). |
52+
| `EventInstanceId` | A number that uniquely identifies the current event inside a trace. This value doesn't change when analyzing or relogging the same trace multiple times. Use this field to identify the same event in multiple analysis or relogging passes over the same trace. |
53+
| `TickFrequency` | The number of ticks per second to use when evaluating a duration measured in ticks. |
54+
| `StartTimestamp` | When the event is an *Activity*, this field is set to a tick value captured at the time the activity started. If this event is a *Simple Event*, this field is set to a tick value captured at the time the event occurred. |
55+
| `StopTimestamp` | When the event is an *Activity*, this field is set to a tick value captured at the time the activity stopped. If the stop event hasn't yet been received for this activity, this field is set to zero. If this event is a *Simple Event*, this field is set to zero. |
56+
| `ExclusiveDurationTicks` | If this event is an *Activity*, this field is set to the number of ticks that occurred directly in this activity. The number of ticks that occurred in a child activity are excluded. This field is set to zero for *Simple Events*. |
57+
| `CPUTicks` | If this event is an *Activity*, this field is set to the number of CPU ticks that occurred during this activity. A CPU tick is different from a regular tick. CPU ticks are only counted when the CPU is executing code in an activity. CPU ticks aren't counted when the thread associated with the activity is sleeping. This field is set to zero for *Simple Events*. |
58+
| `ExclusiveCPUTicks` | This field has the same meaning as `CPUTicks`, except that it doesn't include CPU ticks that occurred in children activities. This field is set to zero for *Simple Events*. |
59+
| `WallClockTimeResponsibilityTicks` | If this event is an *Activity*, this field is set to a tick count that represents this activity's contribution to overall wall-clock time. A wall-clock time responsibility tick is different from a regular tick. Wall-clock time responsibility ticks take into account parallelism between activities. For example, two parallel activities may have a duration of 50 ticks and the same start and stop time. In this case, both will be assigned a wall-clock time responsibility of 25 ticks. This field is set to zero for *Simple Events*. |
60+
| `ExclusiveWallClockTimeResponsibilityTicks` | This field has the same meaning as `WallClockTimeResponsibilityTicks`, except that it doesn't include the wall-clock time responsibility ticks of children activities. This field is set to zero for *Simple Events*. |
61+
| `Data` | Points to additional data stored in the event. The type of data pointed to is different, depending on the `EventId` field. |
62+
| `ProcessId` | The identifier for the process in which the event occurred. |
63+
| `ThreadId` | The identifier for the thread in which the event occurred. |
64+
| `ProcessorIndex` | The zero-indexed CPU number on which the event occurred. |
65+
| `EventName` | An ANSI string containing the name of the entity identified by `EventId`. |
66+
| `EventWideName` | A wide string containing the name of the entity identified by `EventId`. |
67+
68+
## Remarks
69+
70+
Many fields in `EVENT_DATA` contain tick counts. C++ Build Insights uses Window's performance counter as a source of ticks. A tick count must be used with the `TickFrequency` field to convert it into an appropriate time unit such as seconds. See the example below for performing this conversion. `EVENT_DATA` doesn't contain a field for the regular tick count of an activity. To obtain this value, subtract `StartTimestamp` from `StopTimestamp`. `EVENT_DATA` is a structure that's meant to be used by C API users. For C++ API users, classes like [Event](../cpp-event-data-types/event.md) do time conversions automatically.
71+
72+
The value of the `EVENT_DATA` `Data` field depends on the value of its `EventId` field. The value of `Data` is described in the table below. Some entity identifiers may be missing from the table below. In this case, the `Data` field is set to `nullptr` or zero.
73+
74+
| `EventId` value | Type pointed to by `Data` |
75+
|--|--|
76+
| `EVENT_ID_BACK_END_PASS` | [CL_PASS_DATA](cl-pass-data-struct.md) |
77+
| `EVENT_ID_COMMAND_LINE` | `const wchar_t` |
78+
| `EVENT_ID_COMPILER` | [INVOCATION_DATA](invocation-data-struct.md) |
79+
| `EVENT_ID_ENVIRONMENT_VARIABLE` | [NAME_VALUE_PAIR_DATA](name-value-pair-data-struct.md) |
80+
| `EVENT_ID_EXECUTABLE_IMAGE_OUTPUT` | [FILE_DATA](file-data-struct.md) |
81+
| `EVENT_ID_EXP_OUTPUT` | [FILE_DATA](file-data-struct.md) |
82+
| `EVENT_ID_FILE_INPUT` | [FILE_DATA](file-data-struct.md) |
83+
| `EVENT_ID_FORCE_INLINE` | [FUNCTION_FORCE_INLINEE_DATA](function-force-inlinee-data-struct.md) |
84+
| `EVENT_ID_FRONT_END_FILE` | [FRONT_END_FILE_DATA](front-end-file-data-struct.md) |
85+
| `EVENT_ID_FRONT_END_PASS` | [CL_PASS_DATA](cl-pass-data-struct.md) |
86+
| `EVENT_ID_FUNCTION` | [FUNCTION_DATA](function-data-struct.md) |
87+
| `EVENT_ID_IMP_LIB_OUTPUT` | [FILE_DATA](file-data-struct.md) |
88+
| `EVENT_ID_LIB_OUTPUT` | [FILE_DATA](file-data-struct.md) |
89+
| `EVENT_ID_LINKER` | [INVOCATION_DATA](invocation-data-struct.md) |
90+
| `EVENT_ID_OBJ_OUTPUT` | [FILE_DATA](file-data-struct.md) |
91+
| `EVENT_ID_SYMBOL_NAME` | [SYMBOL_NAME_DATA](symbol-name-data-struct.md) |
92+
| `EVENT_ID_TEMPLATE_INSTANTIATION` | [TEMPLATE_INSTANTIATION_DATA](template-instantiation-data-struct.md) |
93+
94+
## Tick conversion example
95+
96+
```cpp
97+
//
98+
// We have the elapsed number of ticks, along with the
99+
// number of ticks per second. We use these values
100+
// to convert to the number of elapsed microseconds.
101+
// To guard against loss-of-precision, we convert
102+
// to microseconds *before* dividing by ticks-per-second.
103+
//
104+
105+
long long ConvertDurationToMicroseconds(const sruct EVENT_DATA& eventData)
106+
{
107+
long long duration = eventData.StopTimestamp - eventData.StartTimestamp;
108+
long long duration *= 1000000;
109+
return duration / eventData.TickFrequency;
110+
}
111+
```
112+
113+
::: moniker-end

0 commit comments

Comments
 (0)