Add -pathmap compiler option documentation for Visual Basic

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

Author: Copilot

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,65 @@
+---
+description: "Learn more about: -pathmap"
+title: "-pathmap"
+ms.date: 12/16/2024
+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:
+
+1. The source path is substituted for an argument when the <xref:System.Runtime.CompilerServices.CallerFilePathAttribute> is applied to an optional parameter.
+1. The source path is embedded in a PDB file.
+1. The path of the PDB file is embedded into a PE (portable executable) file.
+
+|To set -pathmap in the Visual Studio integrated development environment|
+|---|
+|The **-pathmap** option is not available from within the Visual Studio development environment; it is 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>