ROUGH DRAFT

Test-Case Reproduction

LINK provides for reproducing test cases, both for LINK and LIB. This feature is at best semi-documented, and only then among Microsoft’s descriptions of possible errors and warnings.

Directory

The key point to the feature is to reproduce all the linker’s input into one directory for convenient and complete reference in any later examination of what the linker did.

The Repro directory is specified in a /linkrepro command-line option else a LINK_REPRO environment variable. If it is the current directory, the Repro feature is disabled, with a warning (LNK4046). Even if the Repro directory is acceptable, a warning (LNK4045) is issued, presumably to mark that this feature is unusual.

Response File

Useful examination will require some record of what the linker thinks it was asked to do. This goes into a response file. By default, this response file is named “link.rsp” in the Repro directory. However, the name is configurable through a LINK_REPRO_NAME environment variable. The value of this variable is appended directly to the Repro path, without an interceding backslash. To place the response file in the Repro directory, it is therefore necessary that the LINK_REPRO_NAME value start with a backslash. It is a fatal error (LNK1144) if the linker cannot create the response file, with exclusive write access.

The use of LINK_REPRO_NAME to name a response file has a notable side-effect when the linker copies files to the Repro directory. (See below.)

It may be that LINK_REPRO_NAME is left undocumented because it is intended solely for the linker’s internal use, specifically to name a separate response file (“deflib.rsp” in the Repro directory) for LINK’s re-execution of itself as LIB to generate an import library and export file.

Copied Input Files

The general aim is for the Repro directory to get a copy of each file that the linker uses as input. The ordinary behaviour is that the copy has the same name and extension as the actual input file and that a message is written to standard output to tell of the copying.

Variations from this behaviour occur if the target file for a proposed copy cannot be created as a new file without overwriting one that exists already.

If the LINK_REPRO_NAME environment variable was set, then the linker simply does not bother with the copy. The thinking may be to use this environment variable as a (quick and dirty) test of whether the linker is actually running because a parent instance of the linker has re-executed itself, such that files already in the Repro directory were copied there by the parent and need not be copied again by the child.

Without the LINK_REPRO_NAME environment variable, the linker tries a sequence of new names for the target file until creation succeeds and the copy can be proceeded with. The new names are formed by inserting a period and a serial number (beginning at 2) between the name and extension.