mac/lld: Update docs after yesterday's clang roll.

- remove many now-fixed issues, update open issues
- things basically work now, so recommend using trunk lld less strongly
- add section with pointers on how to make repros

Bug: 1149587
Change-Id: I4524c99c4894b1669a4d12dfcda677b31fea491c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2611444
Commit-Queue: Nico Weber <thakis@chromium.org>
Auto-Submit: Nico Weber <thakis@chromium.org>
Reviewed-by: Robert Sesek <rsesek@chromium.org>
Cr-Commit-Position: refs/heads/master@{#840270}

docs/mac_lld.md

@@ -14,10 +14,11 @@ file format on Windows).
 
 ld64, the standard Mach-O linker (the executable file format on iOS and macOS),
 is on the other hand already fairly fast and works well, so there are fewer
-advantages to using LLD here. (Having said that, LLD is currently 2-3x faster
-than ld64 in symbol\_level=0 release builds, despite ld64 being already fast.
-Maybe that's due to LLD not yet doing critical things and it will get slower,
-but at the moment it's faster than ld64.)
+advantages to using LLD here. (Having said that, LLD is currently 4x faster
+at linking Chromium Framework than ld64 in symbol\_level=0 release builds,
+despite ld64 being already fast. Maybe that's due to LLD not yet doing
+critical things and it will get slower, but at the moment it's faster than
+ld64.)
 
 LLD does have a few advantages unrelated to speed, however:
 
@@ -52,25 +53,17 @@ Visual Studio linker link.exe, the LLD Mach-O port tries to be
 commandline-compatible with ld64. This means LLD accepts different flags on
 different platforms.
 
-## Known issues
-
-- LLD/Mach-O is moving quickly, so things usually work best with a trunk build
-  of LLD instead of the prebuilt one
-- LLD-linked binaries don't work on macOS 10.13 or older
-  ([bug](https://llvm.org/PR48395), fixed upstream)
-- LLD-linked `protoc` crashes when it runs as part of the build
-  ([bug](https://llvm.org/PR48491), fixed upstream)
-- LLD cannot yet link swiftshader binaries
-  ([bug](https://llvm.org/PR48332), fixed upstream)
-- LLD-linked `v8_context_snapshot_generator` crashes when it runs as part of
-  the build ([bug](https://llvm.org/PR48511), fixed upstream)
-- verify\_framework\_order fails in LLD builds
-  ([bug](https://llvm.org/PR48536), fixed upstream)
-- LLD-built Chromium.app crashes with `malloc: *** error for object
-  0x7fa46941f20a: pointer being freed was not allocated` at starutp (FIXME:
-  file bug)
+## Current status and known issues
+
+A `symbol_level = 0` `is_debug = false` `use_lld = true` build produces
+a mostly-working Chromium.app, but there are open issues and missing features:
+
+- LLD-built Chromium.app has crashy renderer processes
+  ([bug](https://crbug.com/1162712))
 - LLD does not yet have any ARM support
-  ([in-progress patch](https://reviews.llvm.org/D88629))
+  - relocations are missing
+    ([in-progress patch](https://reviews.llvm.org/D88629))
+  - ad-hoc code signing is missing
 - LLD likely produces bad debug info, and LLD-linked binaries likely don't
   yet work in a debugger
 - LLD-linked base\_unittests fails some unwind-related tests
@@ -87,17 +80,19 @@ different platforms.
 
 1. First, obtain lld. Do either of:
 
-   1. build `lld` and `llvm-ar` locally and copy it to
+   1. run `src/tools/clang/scripts/update.py --package=lld_mac` to download a
+      prebuilt lld binary.
+   2. build `lld` and `llvm-ar` locally and copy it to
       `third_party/llvm-build/Relase+Asserts/bin`. Also run
       `ln -s lld third_party/llvm-build/Release+Asserts/bin/ld64.lld.darwinnew`.
-   2. run `src/tools/clang/scripts/update.py --package=lld_mac` to download a
-      prebuilt lld binary.
 
    You have to do this again every time `runhooks` updates the clang
    package.
 
    The prebuilt might work less well than a more up-to-date, locally-built
-   version.
+   version -- see the list of open issues above for details. If anything is
+   marked "fixed upstream", then the fix is upstream but not yet in the
+   prebuilt lld binary.
 
 2. Add `use_lld = true` to your args.gn
 
@@ -106,3 +101,28 @@ different platforms.
 `use_lld = true` makes the build use thin archives. For that reason, `use_lld`
 also switches from `libtool` to `llvm-ar`.
 
+## Creating stand-alone repros for bugs
+
+For simple cases, LLD's `--reproduce=foo.tar` flag / `LLD_REPRODUCE=foo.tar`
+env var is sufficient.
+
+See "Note to self:" [here](https://bugs.llvm.org/show_bug.cgi?id=48657#c0) for
+making a repro file that involved the full app and framework bundles.
+
+Locally, apply this patch before building chrome to make a repro that can
+be used with both lld and ld (useful for making comparisons):
+
+    diff --git a/build/config/compiler/BUILD.gn b/build/config/compiler/BUILD.gn
+    index 5ea2f2130abb..ed871642cee9 100644
+    --- a/build/config/compiler/BUILD.gn
+    +++ b/build/config/compiler/BUILD.gn
+    @@ -1780,7 +1780,7 @@ config("export_dynamic") {
+     config("thin_archive") {
+       # The macOS and iOS default linker ld64 does not support reading thin
+       # archives.
+    -  if ((is_posix && !is_nacl && (!is_apple || use_lld)) || is_fuchsia) {
+    +  if ((is_posix && !is_nacl && (!is_apple)) || is_fuchsia) {
+         arflags = [ "-T" ]
+       } else if (is_win && use_lld) {
+         arflags = [ "/llvmlibthin" ]
+