[all-commits] [llvm/llvm-project] d054c7: Add test utility 'extract'

[Fangrui Song via All-commits]

  Branch: refs/heads/master
  Home:   https://github.com/llvm/llvm-project
  Commit: d054c7ee2e9f4f98af7f22a5b00a941eb919bd59
      https://github.com/llvm/llvm-project/commit/d054c7ee2e9f4f98af7f22a5b00a941eb919bd59
  Author: Fangrui Song <maskray at google.com>
  Date:   2020-07-23 (Thu, 23 Jul 2020)

  Changed paths:
    M lld/test/CMakeLists.txt
    M lld/test/ELF/linkerscript/noload.s
    M lld/test/lit.cfg.py
    M llvm/docs/TestingGuide.rst
    M llvm/test/CMakeLists.txt
    M llvm/test/lit.cfg.py
    A llvm/test/tools/extract/Inputs/basic-aa.txt
    A llvm/test/tools/extract/Inputs/basic-bb.txt
    A llvm/test/tools/extract/basic.test
    A llvm/test/tools/extract/help.test
    A llvm/test/tools/extract/no-leading-lines.test
    M llvm/test/tools/gold/X86/multiple-sections.ll
    M llvm/test/tools/llvm-objcopy/ELF/strip-symbol.test
    M llvm/test/tools/llvm-strings/radix.test
    A llvm/tools/extract/.clang-tidy
    A llvm/tools/extract/CMakeLists.txt
    A llvm/tools/extract/extract.cpp

  Log Message:
  -----------
  Add test utility 'extract'

See https://lists.llvm.org/pipermail/llvm-dev/2020-July/143373.html
"[llvm-dev] Multiple documents in one test file" for some discussions.

`extract part filename` splits the input file into multiple parts separated by
regex `^(.|//)--- ` and extract the specified part to stdout or the
output file (if specified).

Use case A (organizing input of different formats (e.g. linker
script+assembly) in one file).

```
// RUN: extract lds %s -o %t.lds
// RUN: extract asm %s -o %t.s
// RUN: llvm-mc %t.s -o %t.o
// RUN: ld.lld -T %t.lds %t.o -o %t
This is sometimes better than the %S/Inputs/ approach because the user
can see the auxiliary files immediately and don't have to open another file.
```

Use case B (for utilities which don't have built-in input splitting
feature):

```
// RUN: extract case1 %s | llc | FileCheck %s --check-prefix=CASE1
// RUN: extract case2 %s | llc | FileCheck %s --check-prefix=CASE2
Combing tests prudently can improve readability.
This is sometimes better than having multiple test files.
```

Since this is a new utility, there is no git history concerns for
UpperCase variable names. I use lowerCase variable names like mlir/lld.

Reviewed By: jhenderson

Differential Revision: https://reviews.llvm.org/D83834