Add documentation for Visual Basic -pathmap compiler option (#48177)

* Initial plan

* Add -pathmap compiler option documentation for Visual Basic

Co-authored-by: BillWagner <[email protected]>

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

* Apply code review suggestions and add pathmap to Visual Basic TOC

Co-authored-by: BillWagner <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: BillWagner <[email protected]>
Co-authored-by: Bill Wagner <[email protected]>
Co-authored-by: Genevieve Warren <[email protected]>

Author: 3 people

docs/visual-basic/reference/command-line-compiler/compiler-options-listed-alphabetically.md

@@ -54,6 +54,7 @@ The Visual Basic command-line compiler is provided as an alternative to compilin
 |[-optionstrict](optionstrict.md)|Enforces strict language semantics.|  
 |[-out](out.md)|Specifies an output file.|  
 |<code>-parallel[+&#124;-]</code>|Specifies whether to use concurrent build (+).|  
+|[-pathmap](pathmap.md)|Specifies how to map physical paths to source path names output by the compiler.|
 |[-platform](platform.md)|Specifies the processor platform the compiler targets for the output file.|  
 |`-preferreduilang`|Specify the preferred output language name.|  
 |[-quiet](quiet.md)|Prevents the compiler from displaying code for syntax-related errors and warnings.|  

docs/visual-basic/reference/command-line-compiler/compiler-options-listed-by-category.md

@@ -113,6 +113,7 @@ The Visual Basic command-line compiler is provided as an alternative to compilin
 |[-noconfig](noconfig.md)|Do not compile with Vbc.rsp|  
 |[-nostdlib](nostdlib.md)|Causes the compiler not to reference the standard libraries.|  
 |[-nowin32manifest](nowin32manifest.md)|Instructs the compiler not to embed any application manifest into the executable file.|  
+|[-pathmap](pathmap.md)|Specifies how to map physical paths to source path names output by the compiler.|
 |[-platform](platform.md)|Specifies the processor platform the compiler targets for the output file.|  
 |[-recurse](recurse.md)|Searches subdirectories for source files to compile.|  
 |[-rootnamespace](rootnamespace.md)|Specifies a namespace for all type declarations.|  

docs/visual-basic/reference/command-line-compiler/pathmap.md

@@ -0,0 +1,62 @@
+---
+description: "Learn more about: -pathmap"
+title: "-pathmap"
+ms.date: 09/04/2025
+f1_keywords: 
+  - "pathmap"
+  - "-pathmap"
+helpviewer_keywords: 
+  - "-pathmap compiler option [Visual Basic]"
+  - "/pathmap compiler option [Visual Basic]"
+  - "pathmap compiler option [Visual Basic]"
+ai-usage: ai-generated
+---
+# -pathmap
+
+Specifies how to map physical paths to source path names output by the compiler.
+
+## Syntax
+
+```console
+-pathmap:path1=sourcePath1,path2=sourcePath2
+```
+
+## Arguments
+
+| Term              | Definition                                                                                                |
+|----------------|-----------------------------------------------------------------------------|
+| `path1`           | Required. The full path to the source files in the current environment. |
+| `sourcePath1` | Required. The source path substituted for `path1` in any output files.  |
+
+## Remarks
+
+> [!NOTE]
+> Specifying `-pathmap` prevents breakpoints from working in local debug builds. Only set `-pathmap` for production or continuous integration builds.
+
+The `-pathmap` compiler option specifies how to map physical paths to source path names output by the compiler. This option maps each physical path on the machine where the compiler runs to a corresponding path that should be written in the output files.
+
+To specify multiple mapped source paths, separate each with a comma.
+
+The compiler writes the source path into its output for the following reasons:
+
+- The source path is substituted for an argument when the <xref:System.Runtime.CompilerServices.CallerFilePathAttribute> is applied to an optional parameter.
+- The source path is embedded in a PDB file.
+- The path of the PDB file is embedded into a PE (portable executable) file.
+
+The `-pathmap` option is not available from within the Visual Studio development environment; it's available only when compiling from the command line.
+
+## Example
+
+The following example compiles `Test.vb` and maps the source paths:
+
+```console
+vbc -pathmap:C:\MyProject\=\BuildServer\,C:\Temp\=\BuildTemp\ Test.vb
+```
+
+In this example, if a source file is located at `C:\MyProject\Program.vb`, it will appear in the output as `\BuildServer\Program.vb`.
+
+## See also
+
+- [Visual Basic Command-Line Compiler](index.md)
+- [Sample Compilation Command Lines](sample-compilation-command-lines.md)
+- <xref:System.Runtime.CompilerServices.CallerFilePathAttribute>

docs/visual-basic/toc.yml

@@ -1379,6 +1379,8 @@ items:
         href: reference/command-line-compiler/optionstrict.md
       - name: -out
         href: reference/command-line-compiler/out.md
+      - name: -pathmap
+        href: reference/command-line-compiler/pathmap.md
       - name: -platform
         href: reference/command-line-compiler/platform.md
       - name: -quiet