Initial draft of /LINKREPRO and related options

Author: Colin Robertson

docs/build/reference/linkrepro.md

@@ -0,0 +1,47 @@
+---
+title: "/LINKREPRO (Link repro directory name)"
+description: Linker option to set the directory for a link repro file.
+ms.date: "09/24/2019"
+f1_keywords: ["/LINKREPRO"]
+helpviewer_keywords: ["LINKREPRO linker option", "/LINKREPRO linker option", "-LINKREPRO linker option", "linker repro reporting"]
+---
+# /LINKREPRO (Link repro directory name)
+
+Tells the linker to generate a link repro in a specified directory.
+
+## Syntax
+
+> **/LINKREPRO:**_directory-name_
+
+### Arguments
+
+**/LINKREPRO:**_directory-name_\
+The user-specified directory to store the link repro in. Directory names that include spaces must be enclosed in double quotes.
+
+## Remarks
+
+The **/LINKREPRO** linker option is used to create a *link repro*. It's a set of build artifacts that allow Microsoft to reproduce a problem that occurs at link time. It's useful for problems such as a backend crash involving Link-Time Code Generation (LTCG), an LNK1000 linker error, or a linker crash. The linker produces a link repro when you specify the **/LINKREPRO** linker option, or when you set the `link_repro` environment variable in your command-line build environment.
+
+Create a link repro to get support for an LTCG crash, a linker crash, or an internal error that happens at link time. For more information, see the [Link repros](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md#link-repros) section of [How to report a problem with the Microsoft C++ toolset](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md).
+
+Both the **/LINKREPRO** linker option and the `link_repro` environment variable require you to specify an output directory for the link repro. On the command line or in the IDE, specify the directory by using a **/LINKREPRO:**_directory-name_ option. The _directory-name_ you specify may be an absolute or relative path, but the directory must exist. The command-line option overrides any directory value set in the `link_repro` environment variable. You must also specify the [/OUT](out-output-file-name.md) linker option when you use the **/LINKREPRO** option.
+
+For information on how to set a link repro file name, see the [/LINKREPROTARGET](linkreprotarget.md) linker option. This option can be used to specify different names for different link repros. It's useful in complex builds that invoke the linker more than once.
+
+### To set this linker option in the Visual Studio development environment
+
+1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
+
+1. Select the **Configuration Properties** > **Linker** > **Command Line** property page.
+
+1. Enter the **/LINKREPRO:**_directory-name_ option in the **Additional Options** box. The _directory-name_ value you specify must exist. Choose **OK** to apply the change.
+
+### To set this linker option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCLinkerTool.AdditionalOptions%2A>.
+
+## See also
+
+[MSVC linker reference](linking.md)\
+[MSVC Linker Options](linker-options.md)\
+[/LINKREPROTARGET](linkreprotarget.md)

docs/build/reference/linkreprotarget.md

@@ -0,0 +1,45 @@
+---
+title: "/LINKREPROTARGET (Link repro file name)"
+description: Linker option to set the directory for a link repro file.
+ms.date: "09/24/2019"
+f1_keywords: ["/LINKREPROTARGET"]
+helpviewer_keywords: ["LINKREPROTARGET linker option", "/LINKREPROTARGET linker option", "-LINKREPROTARGET linker option", "linker repro reporting"]
+---
+# /LINKREPROTARGET (Link repro file name)
+
+Tells the linker to generate a link repro that has a specified file name.
+
+## Syntax
+
+> **/LINKREPROTARGET:**_file-name_
+
+### Arguments
+
+**/LINKREPROTARGET:**_file-name_\
+The user-specified file name to store the link repro in. File names that include spaces must be enclosed in double quotes.
+
+## Remarks
+
+The **/LINKREPROTARGET** linker option is used to specify a file name for a *link repro*. A link repro is a set of build artifacts that allow Microsoft to reproduce a problem that occurs at link time. The linker produces a link repro when you specify the [/LINKREPRO](linkrepro.md) linker option, or when you set the `link_repro` environment variable in your command-line build environment. The **/LINKREPROTARGET** linker option is useful in complex builds that invoke the linker more than once. It lets you specify a different name for each link repro.
+
+For more information about how and when to create a link repro, see the [Link repros](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md#link-repros) section of [How to report a problem with the Microsoft C++ toolset](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md).
+
+To specify a **/LINKREPROTARGET** linker option, the **/LINKREPRO** and  [/OUT](out-output-file-name.md) linker options must also be set.
+
+### To set this linker option in the Visual Studio development environment
+
+1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
+
+1. Select the **Configuration Properties** > **Linker** > **Command Line** property page.
+
+1. Enter the **/LINKREPROTARGET:**_file-name_ option in the **Additional Options** box. Choose **OK** to apply the change.
+
+### To set this linker option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCLinkerTool.AdditionalOptions%2A>.
+
+## See also
+
+[MSVC linker reference](linking.md)\
+[MSVC Linker Options](linker-options.md)\
+[/LINKREPRO](linkrepro.md)

docs/overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md

@@ -313,7 +313,7 @@ Finally, attach the preprocessed repro files (*filename*.i and *modulename*.i) a
 
 A *Link repro* is the linker-generated contents of a directory specified by the **link\_repro** environment variable. It contains build artifacts that collectively demonstrate a problem that occurs at link time. Examples include a backend crash involving Link-Time Code Generation (LTCG), or a linker crash. These build artifacts are the ones needed as linker input so that the problem can be reproduced. A Link repro can be created easily by using this environment variable. It enables the linker's built-in repro generation capability.
 
-#### To generate a Link repro
+#### To generate a Link repro using the link_repro environment variable
 
 1. Capture the command-line arguments used to build your repro, as described in [To report the contents of the command line](#to-report-the-contents-of-the-command-line).
 
@@ -333,6 +333,12 @@ A *Link repro* is the linker-generated contents of a directory specified by the
 
 1. In the developer command prompt console window, enter the command **set link\_repro=** to clear the **link\_repro** environment variable.
 
+#### To generate a Link repro using the /LINKREPRO linker option
+
+The /LINKREPRO linker option has the same effect as the **link\_repro** environment variable. You can also use the /LINKREPROTARGET option to specify the name to use for the generated link repro. To use /LINKREPROTARGET, you must specify the /OUT option.
+
+<!-- TODO TODO -->
+
 Finally, package the repro by compressing the entire linkrepro directory into a .zip file or similar and attach it to your report.
 
 ### Other repros