Explain --reproduce option.

[ruiu]

Summary

I think --reproduce is no longer a debug-only option but a useful
option that a common user may want to use. So, this patch updates
the description of the option in the manual page.

[MaskRay]

The updated description looks good to me. I even use this option to debug GNU linkers a lot (usually to check why/how they do ABC) because they don't provide this nice feature...

+@grimar @peter.smith in case they have wording suggestions.

[ruiu]

Yeah, I actually like this option *a lot*. This is one of the best features we've added to lld.

[peter.smith]

It would be good to get at least the tar file part added to the ld.lld --help option, I remember having to use the file command the first time I used --reproduce and I think more people will use --help than look in the man page.

lld/trunk/docs/ld.lld.1

411 ↗

(On Diff #216781)

I think this will work fine. A suggestion that gives a bit more detail on the contents, not got a strong opinion so by all means keep the original.

Write a tar file containing all the input files needed to reproduce the link, a text file called response.txt containing the command line options and a text file called version.txt containing the output of ld.lld --version. The archive when unpacked can be used to re-run the linker with the same options and input files.

[ruiu]

In D60557#1642458, @peter.smith wrote:

It would be good to get at least the tar file part added to the ld.lld --help option, I remember having to use the file command the first time I used --reproduce and I think more people will use --help than look in the man page.

I like that detailed explanation. I've already submitted this change, but can you submit yours to update it?

[peter.smith]

In D60557#1642466, @ruiu wrote:

In D60557#1642458, @peter.smith wrote:

It would be good to get at least the tar file part added to the ld.lld --help option, I remember having to use the file command the first time I used --reproduce and I think more people will use --help than look in the man page.

I like that detailed explanation. I've already submitted this change, but can you submit yours to update it?

Sure I'll send out a review in a few moments.

lld/docs/ld.lld.1

 .Fl -static ,
 and
 .Fl -whole-archive.
 .It Fl -pop-state
 Undo the effect of
 .Fl -push-state.
 .It Fl -relocatable , Fl r
 Create relocatable object file.
-.It Fl -reproduce Ns = Ns Ar value
-Dump linker invocation and input files for debugging.
+.It Fl -reproduce Ns = Ns Ar path
+Write a tar file containing all input files and a text file describing the link invocation to
+.Ar path,
+so that you can easily re-run the linker with the same options and input files.
 .It Fl -retain-symbols-file Ns = Ns Ar file
 Retain only the symbols listed in the file.
 .It Fl -rpath Ns = Ns Ar value , Fl R Ar value
 Add a
 .Dv DT_RUNPATH
 to the output.
 .It Fl -rsp-quoting Ns = Ns Ar value
 Quoting style for response files.