From 2d370a7ef6d296822a00407fd2f5b59a4a92ac94 Mon Sep 17 00:00:00 2001 From: Gregg Miskelly Date: Fri, 2 Dec 2022 13:44:26 -0800 Subject: [PATCH 1/3] Update documentation for FASTLINK The documentation for FASTLINK had a few issues that this PR attempts to address: * The sentence about "executable is deployed on another computer" was confusing because deploying the executable isn't a problem if you are doing so to remote debug. The real problem is attempting to deploy the PDB. * The performance notes on FASTLINK were not correct for Visual Studio 2019 and later --- docs/build/reference/debug-generate-debug-info.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/build/reference/debug-generate-debug-info.md b/docs/build/reference/debug-generate-debug-info.md index 7bc0fcc21b0..9a04d494b1e 100755 --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -20,7 +20,9 @@ The linker puts the debugging information into a program database (PDB) file. It An executable (.exe file or DLL) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension .pdb to name the program database, and embeds the path where it was created. To override this default, set [/PDB](pdb-use-program-database.md) and specify a different file name. -The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option leaves private symbol information in the individual compilation products used to build the executable. It generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. This option can link from two to four times as fast as full PDB generation, and is recommended when you are debugging locally and have the build products available. This limited PDB can't be used for debugging when the required build products are not available, such as when the executable is deployed on another computer. In a developer command prompt, you can use the mspdbcmf.exe tool to generate a full PDB from this limited PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. +The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. This limited PDB can't be used to debug on computers other than the computer where the binary and its libs were built as the PDB is not intended to be used on any other computer. In Visual Studio 2017, this option can sometimes greatly improve link times compared with /DEBUG:FULL. In Visual Studio 2019 and later, /DEBUG:FULL is faster than earlier versions. Now, /DEBUG:FASTLINK isn't always faster than /DEBUG:FULL, and it is rarely more than twice as fast. + +A /DEBUG:FASTLINK PDB can be converted to a full PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. In a developer command prompt, you can use the mspdbcmf.exe tool. The **/DEBUG:FULL** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. From 8c7fce3dfb891616714897cc8734a1e8c7a394a7 Mon Sep 17 00:00:00 2001 From: Colin Robertson <3836425+corob-msft@users.noreply.github.com> Date: Fri, 2 Dec 2022 14:06:24 -0800 Subject: [PATCH 2/3] Style and Acrolinx fixes Make the grammar checker happy. Use consistent formatting of compiler options. --- docs/build/reference/debug-generate-debug-info.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/reference/debug-generate-debug-info.md b/docs/build/reference/debug-generate-debug-info.md index 9a04d494b1e..6a146f0fd8c 100755 --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -20,9 +20,9 @@ The linker puts the debugging information into a program database (PDB) file. It An executable (.exe file or DLL) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension .pdb to name the program database, and embeds the path where it was created. To override this default, set [/PDB](pdb-use-program-database.md) and specify a different file name. -The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. This limited PDB can't be used to debug on computers other than the computer where the binary and its libs were built as the PDB is not intended to be used on any other computer. In Visual Studio 2017, this option can sometimes greatly improve link times compared with /DEBUG:FULL. In Visual Studio 2019 and later, /DEBUG:FULL is faster than earlier versions. Now, /DEBUG:FASTLINK isn't always faster than /DEBUG:FULL, and it is rarely more than twice as fast. +The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. You can't use this limited PDB to debug on computers other than the computer where the binary and its libs were built, as the PDB isn't intended to be used on any other computer. In Visual Studio 2017, this option can sometimes greatly improve link times compared with **/DEBUG:FULL**. In Visual Studio 2019 and later, **/DEBUG:FULL** is faster than earlier versions. Now, **/DEBUG:FASTLINK** isn't always faster than **/DEBUG:FULL**, and it's rarely more than twice as fast. -A /DEBUG:FASTLINK PDB can be converted to a full PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. In a developer command prompt, you can use the mspdbcmf.exe tool. +A **/DEBUG:FASTLINK** PDB can be converted to a full PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. In a developer command prompt, you can use the `mspdbcmf.exe` tool. The **/DEBUG:FULL** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. From 916ede5eb6c898705c0fa085b2cbd10cfbfe43d8 Mon Sep 17 00:00:00 2001 From: Gregg Miskelly Date: Fri, 2 Dec 2022 14:39:19 -0800 Subject: [PATCH 3/3] Update remote deployment sentence --- docs/build/reference/debug-generate-debug-info.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/reference/debug-generate-debug-info.md b/docs/build/reference/debug-generate-debug-info.md index 6a146f0fd8c..a2a11e985ee 100755 --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -20,7 +20,7 @@ The linker puts the debugging information into a program database (PDB) file. It An executable (.exe file or DLL) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension .pdb to name the program database, and embeds the path where it was created. To override this default, set [/PDB](pdb-use-program-database.md) and specify a different file name. -The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. You can't use this limited PDB to debug on computers other than the computer where the binary and its libs were built, as the PDB isn't intended to be used on any other computer. In Visual Studio 2017, this option can sometimes greatly improve link times compared with **/DEBUG:FULL**. In Visual Studio 2019 and later, **/DEBUG:FULL** is faster than earlier versions. Now, **/DEBUG:FASTLINK** isn't always faster than **/DEBUG:FULL**, and it's rarely more than twice as fast. +The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. You can only use this limited PDB to debug from the computer where the binary and its libraries were built. If you deploy the binary elsewhere, you may debug it remotely from the build computer, but not directly on the test computer. In Visual Studio 2017, this option can sometimes greatly improve link times compared with **/DEBUG:FULL**. In Visual Studio 2019 and later, **/DEBUG:FULL** is faster than earlier versions. Now, **/DEBUG:FASTLINK** isn't always faster than **/DEBUG:FULL**, and it's rarely more than twice as fast. A **/DEBUG:FASTLINK** PDB can be converted to a full PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. In a developer command prompt, you can use the `mspdbcmf.exe` tool.