Merge branch 'MicrosoftDocs:main' into cmake-presets-vs-compiler-selection

Author: crud89

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

@@ -45,15 +45,15 @@ Set the optimization level to maximum optimizations:
 
 1. In the **Solution Explorer**, right-click the project name and select **Properties**.
 1. In the project properties, navigate to **C/C++** > **Optimization**.
-1. Set the **Optimization** dropdown to **Maximum Optimization (Favor Speed) ([`/O2`](../../build/reference/ob-inline-function-expansion.md))**.
+1. Set the **Optimization** dropdown to **Maximum Optimization (Favor Speed) ([`/O2`](../../build/reference/o1-o2-minimize-size-maximize-speed.md))**.
 
     :::image type="content" source="./media/max-optimization-setting.png" alt-text="Screenshot of the project property pages dialog. The settings are open to Configuration Properties > C/C++ > Optimization. The Optimization dropdown is set to Maximum Optimization (Favor Speed) (/O2).":::
 
 1. Click **OK** to close the dialog.
 
 ## Run Build Insights
 
-On a project of your choosing, and using the **Release** 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 **Release** 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 that 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.":::
 
@@ -69,9 +69,9 @@ In the Function Name column, performPhysicsCalculations() is highlighted and mar
 
 The **Time [sec, %]** column shows how long it took to compile each function in [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). This metric distributes the wall clock time among functions based on their use of parallel compiler threads. For example, if two different threads are compiling two different functions simultaneously within a one-second period, each function's WCTR is recorded as 0.5 seconds. This reflects each function's proportional share of the total compilation time, taking into account the resources each consumed during parallel execution. Thus, WCTR provides a better measure of the impact each function has on the overall build time in environments where multiple compilation activities occur simultaneously.
 
-The **Forceinline Size** column shows roughly how many instructions were generated for the function. Click the chevron before the function name to see the individual inlined functions that were expanded in that function how roughly how many instructions were generated for each.
+The **Forceinline Size** column shows roughly how many instructions were generated for the function. Click the chevron before the function name to see the individual inlined functions that were expanded in that function and roughly how many instructions were generated for each.
 
-You can sort the list by clicking on the **Time** column to see which functions are taking the most time to compile. A 'fire' icon indicates that cost of generating that function is high and is worth investigating. Excessive use of `__forceinline` functions can significantly slow compilation.
+You can sort the list by clicking on the **Time** column to see which functions are taking the most time to compile. A 'fire' icon indicates that the cost of generating that function is high and is worth investigating. Excessive use of `__forceinline` functions can significantly slow compilation.
 
 You can search for a specific function by using the **Filter Functions** box. If a function's code generation time is too small, it doesn't appear in the **Functions** View.
 
@@ -89,7 +89,7 @@ By selecting the chevron before that function, and then sorting the **Forceinlin
 performPhysicsCalculations() is expanded and shows a long list of functions that were inlined inside it. There are multiple instances of functions such as complexOperation(), recursiveHelper(), and sin() shown. The Forceinline Size column shows that complexOperation() is the largest inlined function at 315 instructions. recursiveHelper() has 119 instructions. Sin() has 75 instructions, but there are many more instances of it than the other functions.
 :::image-end:::
 
-There are some larger inlined functions, such as `Vector2D<float>::complexOperation()` and `Vector2D<float>::recursiveHelper()` that are contributing to the problem. But there are many more instances (not all shown here) of `Vector2d<float>::sin(float)`, `Vector2d<float>::cos(float)`, `Vector2D<float>::power(float,int)`, and `Vector2D<float>::factorial(int)`. When you add those up, the total number of generated instructions quickly exceeds the few larger generated functions.
+There are some larger inlined functions, such as `Vector2D<float>::complexOperation()` and `Vector2D<float>::recursiveHelper()` that are contributing to the problem. But there are many more instances (not all shown here) of `Vector2D<float>::sin(float)`, `Vector2D<float>::cos(float)`, `Vector2D<float>::power(float,int)`, and `Vector2D<float>::factorial(int)`. When you add those up, the total number of generated instructions quickly exceeds the few larger generated functions.
 
 Looking at those functions in the source code, we see that execution time is going to be spent inside loops. For example, here's the code for `factorial()`:
 
@@ -108,15 +108,15 @@ static __forceinline T factorial(int n)
 
 Perhaps the overall cost of calling this function is insignificant compared to the cost of the function itself. Making a function inline is most beneficial when the time it takes to call the function (pushing arguments on the stack, jumping to the function, popping return arguments, and returning from the function) is roughly similar to the time it takes to execute the function, and when the function is called a lot. When that's not the case, there may be diminishing returns on making it inline. We can try removing the `__forceinline` directive from it to see if it helps the build time. The code for `power`, `sin()`, and `cos()` is similar in that the code consists of a loop that executes many times. We can try removing the `__forceinline` directive from those functions as well.
 
-We rerun Build Insights from the main menu by choosing **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. We choose **Rebuild** instead of **Build** to measure the build time for the entire project, as before, and not for just the few files may be dirty right now.
+We rerun Build Insights from the main menu by choosing **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. We choose **Rebuild** instead of **Build** to measure the build time for the entire project, as before, and not for just the few files that may be dirty right now.
 
 The build time goes from 25.181 seconds to 13.376 seconds and the `performPhysicsCalculations` function doesn't show up anymore in the **Functions** view because it doesn't contribute enough to the build time to be counted.
 
 :::image type="complex" source="./media/functions-view-after-fix.png" alt-text="Screenshot of the 2D vector header file.":::
 In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon.
 :::image-end:::
 
-The Diagnostics Session time is the overall time it took do the build plus any overhead for gathering the Build Insights data.
+The Diagnostics Session time is the overall time it took to do the build plus any overhead for gathering the Build Insights data.
 
 The next step would be to profile the application to see if the performance of the application is negatively impacted by the change. If it is, we can selectively add `__forceinline` back as needed.
 

docs/build/arm64-windows-abi-conventions.md

@@ -1,6 +1,6 @@
 ---
-description: "Learn more about: Overview of ARM64 ABI conventions"
 title: "Overview of ARM64 ABI conventions"
+description: "Learn more about: Overview of ARM64 ABI conventions"
 ms.date: 04/08/2025
 ---
 # Overview of ARM64 ABI conventions
@@ -123,7 +123,7 @@ To determine if an ARM CPU supports exceptions, write a value that enables excep
 
 On ARM64, Windows delivers exceptions for processors that support hardware floating-point exceptions.
 
-The [`_set_controlfp`](/cpp/c-runtime-library/reference/controlfp-s) function on ARM platforms correctly changes the FPCR register when unmasking floating-point exceptions. However, instead of raising an unmasked exception, Windows resets the FPCR register to its defaults every time an FP exception is about to be raised.
+The [`_set_controlfp`](../c-runtime-library/reference/controlfp-s.md) function on ARM platforms correctly changes the FPCR register when unmasking floating-point exceptions. However, instead of raising an unmasked exception, Windows resets the FPCR register to its defaults every time an FP exception is about to be raised.
 
 ## Parameter passing
 

docs/build/clang-support-cmake.md

@@ -26,19 +26,18 @@ You can use Visual Studio with Clang to edit and debug C++ CMake projects that t
 
 For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools** component.
 
-![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2019.png)
+:::image type="content" source="media/clang-install-vs2019.png" alt-text="Screenshot of the Visual Studio Installer Individual Components page. C++ Clang Compiler For Windows and C++ Clang-cl for v142 build tools are selected.":::
 
 ::: moniker-end
 ::: moniker range="msvc-170"
 
 For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **MSBuild support for LLVM (clang-cl) toolset** component.
 
-![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2022.png)
+:::image type="content" source="media/clang-install-vs2022.png" alt-text="Screenshot of the Visual Studio Installer Individual Components page. C++ Clang Compiler For Windows and MSBuild support for LLVM are selected.":::
 
 ::: moniker-end
 ::: moniker range=">=msvc-160"
 
-
 ## Create a new configuration
 
 To add a new Clang configuration to a CMake project:
@@ -47,11 +46,11 @@ To add a new Clang configuration to a CMake project:
 
 1. Under **Configurations**, press the **Add Configuration** button:
 
-   ![Screenshot of the controls at the top of the C Make Settings dialog, with the Add Configuration control highlighted.](media/cmake-add-config-icon.png)
+   :::image type="content" source="media/cmake-add-config-icon.png" alt-text="Screenshot of the controls at the top of the C Make Settings dialog. The Add Configuration button is highlighted.":::
 
 1. Choose the desired Clang configuration (note that separate Clang configurations are provided for Windows and Linux), then press **Select**:
 
-   ![Screenshot of the Add Configuration to C Make Settings dialog for Clang configuration.](media/cmake-clang-configuration.png)
+   :::image type="content" source="media/cmake-clang-configuration.png" alt-text="Screenshot of the Add Configuration to C Make Settings dialog for Clang configuration. Contains entries such as Mingw64-Release, x86-Debug, x64-Debug, x86-Clang Debug, and so on.":::
 
 1. To make modifications to this configuration, use the **CMake Settings Editor**. For more information, see [Customize CMake build settings in Visual Studio](customize-cmake-settings.md).
 
@@ -63,7 +62,7 @@ To modify an existing configuration to use Clang, follow these steps:
 
 1. Under **General** select the **Toolset** dropdown and choose the desired Clang toolset:
 
-   ![Screenshot of the General dialog box showing that the Toolset is selected and clang cl x 86 is highlighted.](media/cmake-clang-toolset.png)
+   ![Screenshot of the General dialog box showing the Toolset drop-down and clang cl x 86 is highlighted.](media/cmake-clang-toolset.png)
 
 ## Custom Clang locations
 
@@ -74,7 +73,7 @@ By default, Visual Studio looks for Clang in two places:
 
 You can specify another location by setting the **CMAKE_C_COMPILER** and **CMAKE_CXX_COMPILER** CMake variables in **CMake Settings**:
 
-![Screenshot of the C Make Settings dialog box with the C Make C X X Compiler highlighted.](media/clang-location-cmake.png)
+:::image type="content" source="media/clang-location-cmake.png" alt-text="Screenshot of the C Make Settings dialog box with the C Make C X X Compiler highlighted. C Make configurations are listed such as x64-Clang-Debug, Linux-Clang-Release, and so on." Lightbox="media/clang-location-cmake.png":::
 
 ## Clang compatibility modes
 
@@ -88,6 +87,6 @@ After you have set up a Clang configuration, you can build and debug the project
 
 When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue aren't available for Clang configurations.
 
-![Screenshot of the Visual Studio debugger debugging a CMake Clang project.](media/clang-debug-visualize.png)
+:::image type="content" source="media/clang-debug-visualize.png" alt-text="Screenshot of the Visual Studio debugger debugging a CMake Clang project.":::
 
 ::: moniker-end