[lld, ELF and mac] Add --time-trace=<file>, remove --time-trace-file=<file>

[thakis]

Summary

--time-trace=foo has the same behavior as --time-trace --time-trace-file=<file>
had previously.

Also, for mac, make --time-trace-granularity *not* imply --time-trace, to match
behavior of the ELF port.

---

My goal here is to have a short, single flag I can use to get LLD to write a trace, and to make ELF and MachO (and, in time, COFF – this requires teaching TimeProfiler to write a short summary to stdout and to switch lld/COFF to TimeTraceScope) behave the same way.

[MaskRay]

To have a single option, I suggest --time-trace=file beside the existing --time-trace.
You may even remove --time-trace-file=file. The options are for debugging and analysis, and do not need strong compatibility.

[thakis]

Good suggestion, thanks. Done.

[thakis]

simpler (?) impl by making --time-trace an alias for --time-trace= (without an arg)

[MaskRay]

Add an item to lld/docs/ReleaseNotes.rst "Breaking changes"

lld/ELF/Options.td

411–414

Use def time_trace

413

An alias does not need a name.

[thakis]

address most comments

lld/ELF/Options.td

411–414

why? it's an _eq option, no?

[MaskRay]

lld/ELF/Options.td

411–414

Using _eq looks good.

lld/docs/ReleaseNotes.rst

44

``--time-trace-file=<file>`` has been removed. Use ``--time-trace=<file>`` instead.
(`D128451 <https://reviews.llvm.org/D128451>`_)

[thakis]

Thanks!

lld/ELF/Driver.cpp

if (config->timeTraceEnabled)
     // values such as a default image base address.
     target = getTarget();
 
     link(args);
   }
 
   if (config->timeTraceEnabled) {
     checkError(timeTraceProfilerWrite(
-        args.getLastArgValue(OPT_time_trace_file_eq).str(),
-        config->outputFile));
+        args.getLastArgValue(OPT_time_trace_eq).str(), config->outputFile));
     timeTraceProfilerCleanup();
   }
 }
 
 static std::string getRpath(opt::InputArgList &args) {
   std::vector<StringRef> v = args::getStrings(args, OPT_rpath);
   return llvm::join(v.begin(), v.end(), ":");
 }
if (args.hasArg(OPT_thinlto_object_suffix_replace_eq))
       error("--thinlto-object-suffix-replace is not supported with "
             "--thinlto-emit-index-files");
     else if (args.hasArg(OPT_thinlto_prefix_replace_eq))
       error("--thinlto-prefix-replace is not supported with "
             "--thinlto-emit-index-files");
   }
   config->thinLTOModulesToCompile =
       args::getStrings(args, OPT_thinlto_single_module_eq);
-  config->timeTraceEnabled = args.hasArg(OPT_time_trace);
+  config->timeTraceEnabled = args.hasArg(OPT_time_trace_eq);
   config->timeTraceGranularity =
       args::getInteger(args, OPT_time_trace_granularity, 500);
   config->trace = args.hasArg(OPT_trace);
   config->undefined = args::getStrings(args, OPT_undefined);
   config->undefinedVersion =
       args.hasFlag(OPT_undefined_version, OPT_no_undefined_version, true);
   config->unique = args.hasArg(OPT_unique);
   config->useAndroidRelrTags = args.hasFlag(

lld/ELF/Options.td

defm target2:
   Eq<"target2", "Interpret R_ARM_TARGET2 as <type>, where <type> is one of rel, abs, or got-rel">,
   MetaVarName<"<type>">;
 
 defm threads
     : EEq<"threads",
          "Number of threads. '1' disables multi-threading. By default all "
          "available hardware threads are used">;
 
-def time_trace: FF<"time-trace">, HelpText<"Record time trace">;
-def time_trace_file_eq: JJ<"time-trace-file=">, HelpText<"Specify time trace output file">;
+def time_trace_eq: JJ<"time-trace=">, MetaVarName<"<file>">,
+  HelpText<"Record time trace to <file>">;
+def : FF<"time-trace">, Alias<time_trace_eq>,
+  HelpText<"Record time trace to file next to output">;
 
 defm time_trace_granularity: EEq<"time-trace-granularity",
   "Minimum time granularity (in microseconds) traced by time profiler">;
 
 defm toc_optimize : BB<"toc-optimize",
     "(PowerPC64) Enable TOC related optimizations (default)",
     "(PowerPC64) Disable TOC related optimizations">;
 

lld/MachO/Driver.cpp

message(StringRef("Framework search paths:") +
                 (config->frameworkSearchPaths.empty()
                      ? ""
                      : "\n\t" + join(config->frameworkSearchPaths, "\n\t")),
             lld::errs());
   }
 
   config->progName = argsArr[0];
 
-  config->timeTraceEnabled = args.hasArg(
-      OPT_time_trace, OPT_time_trace_granularity_eq, OPT_time_trace_file_eq);
+  config->timeTraceEnabled = args.hasArg(OPT_time_trace_eq);
   config->timeTraceGranularity =
       args::getInteger(args, OPT_time_trace_granularity_eq, 500);
 
   // Initialize time trace profiler.
   if (config->timeTraceEnabled)
     timeTraceProfilerInitialize(config->timeTraceGranularity, config->progName);
 
   {
if (config->timeTraceEnabled)
     else
       writeResult<ILP32>();
 
     depTracker->write(getLLDVersion(), inputFiles, config->outputFile);
   }
 
   if (config->timeTraceEnabled) {
     checkError(timeTraceProfilerWrite(
-        args.getLastArgValue(OPT_time_trace_file_eq).str(),
-        config->outputFile));
+        args.getLastArgValue(OPT_time_trace_eq).str(), config->outputFile));
 
     timeTraceProfilerCleanup();
   }
   return errorCount() == 0;
 }

lld/MachO/Options.td

def reproduce_eq: Joined<["--"], "reproduce=">,
     HelpText<"Write tar file containing inputs and command to reproduce link">,
     Group<grp_lld>;
 def version: Flag<["--"], "version">,
     HelpText<"Display the version number and exit">,
     Group<grp_lld>;
 def no_lto_legacy_pass_manager : Flag<["--"], "no-lto-legacy-pass-manager">,
     HelpText<"Use the new pass manager in LLVM">,
     Group<grp_lld>;
-def time_trace: Flag<["--"], "time-trace">, HelpText<"Record time trace">,
+def time_trace_eq: Joined<["--"], "time-trace=">,
+    HelpText<"Record time trace to <file>">,
+    MetaVarName<"<file>">,
+    Group<grp_lld>;
+def : Flag<["--"], "time-trace">,
+    Alias<time_trace_eq>,
+    HelpText<"Record time trace to file next to output">,
     Group<grp_lld>;
 def time_trace_granularity_eq: Joined<["--"], "time-trace-granularity=">,
     HelpText<"Minimum time granularity (in microseconds) traced by time profiler">,
     Group<grp_lld>;
-def time_trace_file_eq: Joined<["--"], "time-trace-file=">,
-    HelpText<"Specify time trace output file">,
-    Group<grp_lld>;
 def deduplicate_literals: Flag<["--"], "deduplicate-literals">,
     HelpText<"Enable literal deduplication. This is implied by --icf={safe,all}">,
     Group<grp_lld>;
 def print_dylib_search: Flag<["--"], "print-dylib-search">,
     HelpText<"Print which paths lld searched when trying to find dylibs">,
     Group<grp_lld>;
 def icf_eq: Joined<["--"], "icf=">,
     HelpText<"Set level for identical code folding (default: none)">,

lld/docs/ReleaseNotes.rst

 * The GNU ld incompatible ``--no-define-common`` has been removed.
 * The obscure ``-dc``/``-dp`` options have been removed.
 * ``-d`` is now ignored.
 * If a prevailing COMDAT group defines STB_WEAK symbol, having a STB_GLOBAL symbol in a non-prevailing group is now rejected with a diagnostic.
   (`D120626 <https://reviews.llvm.org/D120626>`_)
 * Support for the legacy ``.zdebug`` format has been removed. Run
   ``objcopy --decompress-debug-sections`` in case old object files use ``.zdebug``.
   (`D126793 <https://reviews.llvm.org/D126793>`_)
+* ``--time-trace-file=<file>`` has been removed.
+  Use ``--time-trace=<file>`` instead.
+  (`D128451 <https://reviews.llvm.org/D128451>`_)
 
 COFF Improvements
 -----------------
 
 * Added autodetection of MSVC toolchain, a la clang-cl.  Also added
   ``/winsysroot:`` support for explicit specification of MSVC toolchain
   location, similar to clang-cl's ``/winsysroot``. For now,
   ``/winsysroot:`` requires also passing in an explicit ``/machine:`` flag.

lld/test/ELF/time-trace.s

 # REQUIRES: x86
 # RUN: llvm-mc -filetype=obj -triple=x86_64 %s -o %t.o
 
 # Test implicit trace file name
 # RUN: ld.lld --time-trace --time-trace-granularity=0 -o %t1.elf %t.o
 # RUN: cat %t1.elf.time-trace \
 # RUN:   | %python -c 'import json, sys; json.dump(json.loads(sys.stdin.read()), sys.stdout, sort_keys=True, indent=2)' \
 # RUN:   | FileCheck %s
 
 # Test specified trace file name
-# RUN: ld.lld --time-trace --time-trace-file=%t2.json --time-trace-granularity=0 -o %t2.elf %t.o
+# RUN: ld.lld --time-trace=%t2.json --time-trace-granularity=0 -o %t2.elf %t.o
 # RUN: cat %t2.json \
 # RUN:   | %python -c 'import json, sys; json.dump(json.loads(sys.stdin.read()), sys.stdout, sort_keys=True, indent=2)' \
 # RUN:   | FileCheck %s
 
 # Test trace requested to stdout
-# RUN: ld.lld --time-trace --time-trace-file=- --time-trace-granularity=0 -o %t3.elf %t.o \
+# RUN: ld.lld --time-trace=- --time-trace-granularity=0 -o %t3.elf %t.o \
 # RUN:   | %python -c 'import json, sys; json.dump(json.loads(sys.stdin.read()), sys.stdout, sort_keys=True, indent=2)' \
 # RUN:   | FileCheck %s
 
 # CHECK:      "beginningOfTime": {{[0-9]{16},}}
 # CHECK-NEXT: "traceEvents": [
 
 # Check one event has correct fields
 # CHECK:      "dur":

lld/test/MachO/time-trace.s

 ## When running main twice, we'll also output the time trace JSON twice, which
 ## breaks JSON parsing.
 # XFAIL: main-run-twice
 
 # REQUIRES: x86
 # RUN: llvm-mc -filetype=obj -triple=x86_64-apple-darwin %s -o %t.o
 
 ## Test implicit trace file name
 # RUN: %lld --time-trace --time-trace-granularity=0 -o %t1.macho %t.o
 # RUN: cat %t1.macho.time-trace \
 # RUN:   | %python -c 'import json, sys; json.dump(json.loads(sys.stdin.read()), sys.stdout, sort_keys=True, indent=2)' \
 # RUN:   | FileCheck %s
 
-## Test specified trace file name, also test that `--time-trace` is not needed if the other two are used.
-# RUN: %lld --time-trace-file=%t2.json --time-trace-granularity=0 -o %t2.macho %t.o
+## Test specified trace file name.
+# RUN: %lld --time-trace=%t2.json --time-trace-granularity=0 -o %t2.macho %t.o
 # RUN: cat %t2.json \
 # RUN:   | %python -c 'import json, sys; json.dump(json.loads(sys.stdin.read()), sys.stdout, sort_keys=True, indent=2)' \
 # RUN:   | FileCheck %s
 
-## Test trace requested to stdout, also test that `--time-trace` is not needed if the other two are used.
-# RUN: %lld --time-trace-file=- --time-trace-granularity=0 -o %t3.macho %t.o \
+## Test trace requested to stdout.
+# RUN: %lld --time-trace=- --time-trace-granularity=0 -o %t3.macho %t.o \
 # RUN:   | %python -c 'import json, sys; json.dump(json.loads(sys.stdin.read()), sys.stdout, sort_keys=True, indent=2)' \
 # RUN:   | FileCheck %s
 
 # CHECK:      "beginningOfTime": {{[0-9]{16},}}
 # CHECK-NEXT: "traceEvents": [
 
 ## Check one event has correct fields
 # CHECK:      "dur":