Merge pull request #5122 from MicrosoftDocs/main638670329827011265sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

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

@@ -14,24 +14,24 @@ The C++ Build Insights tools are available in Visual Studio 2019 and later. To s
 ::: moniker-end
 ::: moniker range=">=msvc-160"
 
-C++ Build Insights is a collection of tools that provides increased visibility into the Microsoft Visual C++ (MSVC) tool chain. The tools collect data about your C++ builds, and present it in a format that can help you answer common questions, like:
+C++ Build Insights is a collection of tools that collect data about your C++ builds, and present it in a format that can help you answer common questions such as:
 
 - Are my builds sufficiently parallelized?
 - What should I include in my pre-compiled header (PCH)?
 - Is there a specific bottleneck I should focus on to increase my build speeds?
 
 The main components of this technology are:
 
-- *vcperf.exe*, a command-line utility that you can use to collect traces for your builds,
-- a Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and
-- the C++ Build Insights SDK, a software development kit for creating your own tools that consume C++ Build Insights data.
+- `vcperf.exe`, a command-line utility that you can use to collect traces for your builds
+- A Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and
+- The C++ Build Insights software development kit for creating your own tools that consume C++ Build Insights data.
 
 ## Documentation sections
 
-[Tutorial: vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\
+[vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\
 Learn how to collect build traces for your C++ projects and how to view them in WPA.
 
-[Tutorial: Windows Performance Basics](tutorials/wpa-basics.md)\
+[Windows Performance Basics](tutorials/wpa-basics.md)\
 Discover useful WPA tips for analyzing your build traces.
 
 [C++ Build Insights SDK](reference/sdk/overview.md)\
@@ -41,20 +41,13 @@ An overview of the C++ Build Insights SDK.
 
 Read these articles from the official C++ team blog for more information on C++ Build Insights:
 
-[Introducing C++ Build Insights](https://devblogs.microsoft.com/cppblog/introducing-c-build-insights/)
-
-[Analyze your builds programmatically with the C++ Build Insights SDK](https://devblogs.microsoft.com/cppblog/analyze-your-builds-programmatically-with-the-c-build-insights-sdk/)
-
-[Finding build bottlenecks with C++ Build Insights](https://devblogs.microsoft.com/cppblog/finding-build-bottlenecks-with-cpp-build-insights/)
-
-[Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/)
-
-[Profiling template metaprograms with C++ Build Insights](https://devblogs.microsoft.com/cppblog/profiling-template-metaprograms-with-cpp-build-insights/)
-
-[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights/)
-
-[Introducing vcperf /timetrace for C++ build time analysis](https://devblogs.microsoft.com/cppblog/introducing-vcperf-timetrace-for-cpp-build-time-analysis/)
-
+[Introducing C++ Build Insights](https://devblogs.microsoft.com/cppblog/introducing-c-build-insights/)\
+[Analyze your builds programmatically with the C++ Build Insights SDK](https://devblogs.microsoft.com/cppblog/analyze-your-builds-programmatically-with-the-c-build-insights-sdk/)\
+[Finding build bottlenecks with C++ Build Insights](https://devblogs.microsoft.com/cppblog/finding-build-bottlenecks-with-cpp-build-insights/)\
+[Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/)\
+[Profiling template metaprograms with C++ Build Insights](https://devblogs.microsoft.com/cppblog/profiling-template-metaprograms-with-cpp-build-insights/)\
+[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights/)\
+[Introducing vcperf /timetrace for C++ build time analysis](https://devblogs.microsoft.com/cppblog/introducing-vcperf-timetrace-for-cpp-build-time-analysis/)\
 [Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/)
 
 ::: moniker-end

docs/build-insights/toc.yml

@@ -6,10 +6,12 @@ items:
 - name: "Tutorials"
   expanded: true
   items:
-    - name: "Tutorial: Troubleshoot function inlining on build time"
+    - name: "Troubleshoot function inlining on build time"
       href: ../build-insights/tutorials/build-insights-function-view.md
-    - name: "Tutorial: Troubleshoot header file impact on build time"
+    - name: "Troubleshoot header file impact on build time"
       href: ../build-insights/tutorials/build-insights-included-files-view.md
+    - name: "Build Insights tips and tricks"
+      href: ../build-insights/tutorials/build-insights-tips.md
     - name: "vcperf and Windows Performance Analyzer"
       href: ../build-insights/tutorials/vcperf-and-wpa.md
     - name: "Windows Performance Analyzer basics"

docs/build-insights/tutorials/build-insights-function-view.md

@@ -1,10 +1,10 @@
 ---
-title: "Tutorial: Troubleshoot function inlining on build time"
-description: "Tutorial on how to use Build Insights function view to troubleshoot the impact of function inlining on build time in your C++ projects."
+title: "Troubleshoot function inlining on build time"
+description: "Tutorial for how to use Build Insights function view to troubleshoot the impact of function inlining on build time in your C++ projects."
 ms.date: 5/30/2024
 helpviewer_keywords: ["C++ Build Insights", "inline function analysis", "build time analysis", "__forceinline analysis", "inlines analysis"]
 ---
-# Tutorial: Troubleshoot function inlining on build time
+# Troubleshoot function inlining on build time
 
 Use Build Insights **Functions** view to troubleshoot the impact of function inlining on build time in your C++ projects.
 
@@ -141,6 +141,7 @@ Double-click, right-click, or press **Enter** while on a file in the **Functions
 
 ## See also
 
+[Build Insights tips and tricks](build-insights-tips.md)\
 [Inline functions (C++)](../../cpp/inline-functions-cpp.md)\
 [Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time)\
 [Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\

docs/build-insights/tutorials/build-insights-included-files-view.md

@@ -1,10 +1,10 @@
 ---
-title: "Tutorial: Troubleshoot header file impact on build time"
+title: "Troubleshoot header file impact on build time"
 description: "Tutorial on how to use Build Insights Includes Files and Includes Tree views to troubleshoot the impact of #include files on build time."
 ms.date: 5/30/2024
 helpviewer_keywords: ["C++ Build Insights", "header file build time", "included files view", "include tree view", "#include analysis", "build time analysis"]
 ---
-# Tutorial: Troubleshoot header file impact on build time
+# Troubleshoot header file impact on build time
 
 Use Build Insights **Included Files** and **Include Tree** views to troubleshoot the impact of `#include` files on C and C++ build times.
 
@@ -44,7 +44,7 @@ Before gathering Build Insights data, set the build options for the type of buil
 
 ## Run Build Insights
 
-On a project of your choosing, and using the **Debug** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now.
+On a project of your choosing, and using the **Debug** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on \<project name\>** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now.
 
 :::image type="content" source="./media/build-insights-rebuild-project.png" alt-text="Screenshot of the main menu with Run Build Insights on Selection > Rebuild selected.":::
 
@@ -180,8 +180,9 @@ Or, you can right-click a file in the **Include Tree** view to jump to it in the
 
 ## See also
 
+[Build Insights tips and tricks](build-insights-tips.md)\
 [Compare header units, modules, and precompiled headers](../../build/compare-inclusion-methods.md)\
 [Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\
 [Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time)\
-[Tutorial: Troubleshoot function inlining on build time](build-insights-function-view.md)\
-[Tutorial: vcperf and Windows Performance Analyzer](vcperf-and-wpa.md)
+[Troubleshoot function inlining on build time](build-insights-function-view.md)\
+[vcperf and Windows Performance Analyzer](vcperf-and-wpa.md)

docs/build-insights/tutorials/build-insights-tips.md

@@ -0,0 +1,79 @@
+---
+title: "Build Insights tips and tricks"
+description: "Learn time-saving tips for using Build Insights."
+ms.date: 11/11/2024
+author: tylermsft
+ms.author: twhitney
+ms.topic: article
+helpviewer_keywords: ["C++ Build Insights tips and tricks"]
+---
+# Build Insights tips and tricks
+
+Learn time-saving tips for using Build Insights.
+
+## Run Build Insights on selected files
+
+This feature requires Visual Studio 2022 17.12 or later.
+
+If you're working on a specific file or files, and want to see how they impact your build time, you can run Build Insights on just those files. This feature is useful when you want to focus on a subset of files in your project.
+
+To try it, in **Solution Explorer** select the files in your project you want to profile, right-click, and choose **Run Build Insights on Selected Files**:
+
+  :::image type="content" source="./media/build-insights-run-on-selected-files.png" alt-text="A screenshot of files in the Solution Explorer. The context menu is open and the option to Run Build Insights on Selected Files is highlighted.":::
+
+## Filter Build Insights results
+
+This feature requires Visual Studio 2022 17.12 or later.
+
+If you have a large solution with many projects, you can filter the Build Insights results to see files only the projects you're interested in. This feature is useful when you want to focus on a subset of projects in your solution.
+
+To try it, click the filter button on the filter column header and select the projects you want to see results for:
+
+  :::image type="complex" source="./media/build-insights-filter-by-project.png" alt-text="A screenshot of the Build Insights window with the Included Files tab open.":::
+  The filter button is selected and a list of projects appears. Checkboxes next to two projects are checked.":::
+  :::image-end:::
+
+You can also use file wildcards to filter results. The search is case-insensitive:
+
+  :::image type="content" source="./media/build-insights-glob-filter.png" alt-text="A screenshot of the build insights filter dialog. There's a files to include text box and a files to exclude text box.":::
+
+This allows you to exclude files from a specific folder or only include files from a specific folder. For example, if your source is located at `C:\src\`, you could include files only from the renderer directory and its subdirectories by putting `C:/src/dev/renderer/**` into the **files to include** text box.
+
+Here are some other examples:
+
+- All files in the renderer directory: `C:/src/dev/renderer/*`
+- All files in the `C:/src/dev/renderer/` directory *and all its subdirectories*: `C:/src/dev/renderer/**`
+- All header files in the `C:/src/dev/renderer/` directory *and all its subdirectories*: `C:/src/dev/renderer/**/*.h`
+
+For more examples, see the [online glob pattern tester](https://globster.xyz/).
+
+The filter you enter into either text box persists per solution. Filtering by wildcards isn't supported for CMAKE projects.
+
+## Save Build Insights reports to a designated folder
+
+This feature requires Visual Studio 2022 17.12 or later.
+
+Now you can designate a folder to automatically save Build Insight reports to so you can easily access them.
+
+To set the designated folder, go to **Tools** > **Options** > **C++ Build Insights** > **Trace Collection**. Set a path in the **Store Build Insights reports in this directory** field:
+
+  :::image type="complex" source="./media/build-insights-reports-directory.png" alt-text="A screenshot of the options window.":::
+  tools > Options. Build Insights > Trace Collection is selected in the left pane. Collection Settings appears on the right. The Store Build Insights reports in this directory checkbox is selected, and the text box contains the path c:\users\contoso\workspace as an example.":::
+  :::image-end:::
+
+Reports are automatically saved to this folder when you run Build Insights. If a path isn't set, the `TEMP` folder is used.
+
+## Get help about the Build Insight window
+
+This feature requires Visual Studio 2022 17.12 or later.
+
+To see a short description for the tabs in the Build Insights window, along with a link to the documentation for a detailed explanation, click the question mark icon in the Build Insights window:
+
+  :::image type="content" source="./media/build-insights-view-explanations.png" alt-text="A screenshot of the Build Insights window with the view explanations button (a question mark in a circle) highlighted.":::
+
+## See also
+
+[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\
+[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights)\
+[Troubleshoot header file impact on build time](build-insights-included-files-view.md)\
+[Tutorial: Troubleshoot function inlining on build time](build-insights-function-view.md)