[llvm-cov] Create syntax to pass source w/o binary.

[mysterymath]

Summary

Since binary ID lookup makes CLI object arguments optional, it should be
possible to pass a list of source files without a binary. Unfortunately,
the current syntax will always interpret the first source file as a
binary. This change adds a -sources option to cause all later
positional arguments to be considered sources.

[mysterymath]

Correct .rst syntax.

[mysterymath]

Full diff.

[gulfem]

compiler-rt/test/profile/Linux/binary-id-lookup.c

16

Can you please extend this test to cover the following possible combinations in llvm-cov as well?

1. object file(s) and source file(s)
2. debug-file-directory, object file(s) and source file(s)

[gulfem]

Please remove the dot at the end of the commit message.

[mysterymath]

Address review feedback.

compiler-rt/test/profile/Linux/binary-id-lookup.c

 // REQUIRES: linux
 // RUN: split-file %s %t
 // RUN: %clang_profgen -Wl,--build-id=0x12345678 -fcoverage-mapping -O2 -shared %t/foo.c -o %t/libfoo.so
 // RUN: %clang_profgen -Wl,--build-id=0xabcd1234 -fcoverage-mapping -O2 %t/main.c -L%t -lfoo -o %t.main
 // RUN: rm -rf %t.profdir
 // RUN: env LLVM_PROFILE_FILE=%t.profdir/default_%m.profraw LD_LIBRARY_PATH=%t %run %t.main
 // RUN: mkdir -p %t/.build-id/12 %t/.build-id/ab
 // RUN: cp %t/libfoo.so %t/.build-id/12/345678.debug
 // RUN: cp %t.main %t/.build-id/ab/cd1234.debug
 // RUN: llvm-profdata merge -o %t.profdata %t.profdir/default_*.profraw
 // RUN: llvm-cov show -instr-profile %t.profdata -debug-file-directory %t | FileCheck %s
+// RUN: llvm-cov show -instr-profile %t.profdata %t/libfoo.so -sources %t/foo.c -object %t.main | FileCheck %s --check-prefix=FOO-ONLY
+// RUN: llvm-cov show -instr-profile %t.profdata -debug-file-directory %t -sources %t/foo.c | FileCheck %s --check-prefix=FOO-ONLY
+// RUN: llvm-cov show -instr-profile %t.profdata -debug-file-directory %t %t/libfoo.so -sources %t/foo.c | FileCheck %s --check-prefix=FOO-ONLY
 // RUN: echo "bad" > %t/.build-id/ab/cd1234.debug
 // RUN: llvm-cov show -instr-profile %t.profdata -debug-file-directory %t %t.main | FileCheck %s
 // RUN: not llvm-cov show -instr-profile %t.profdata -debug-file-directory %t/empty 2>&1 | FileCheck %s --check-prefix=NODATA
 
 // CHECK: 1| 1|void foo(void) {}
 // CHECK: 2| 1|void bar(void) {}
 // CHECK: 3| 1|int main() {
 
+// FOO-ONLY: 1| 1|void foo(void) {}
 // NODATA: error: Failed to load coverage: '': No coverage data found
 
 //--- foo.c
 void foo(void) {}
 
 //--- main.c
 void foo(void);
 void bar(void) {}
 int main() {
   foo();
   bar();
   return 0;
 }

llvm/docs/CommandGuide/llvm-cov.rst

 .. _llvm-cov-show:
 
 SHOW COMMAND
 ------------
 
 SYNOPSIS
 ^^^^^^^^
 
-:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
+:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...
 
 DESCRIPTION
 ^^^^^^^^^^^
 
 The :program:`llvm-cov show` command shows line by line coverage of the
-binaries *BIN*,...  using the profile data *PROFILE*. It can optionally be
-filtered to only show the coverage for the files listed in *SOURCES*.
+binaries *BIN*...  using the profile data *PROFILE*. It can optionally be
+filtered to only show the coverage for the files listed in *SOURCE*....
 
 *BIN* may be an executable, object file, dynamic library, or archive (thin or
 otherwise).
 
 To use :program:`llvm-cov show`, you need a program that is compiled with
 instrumentation to emit profile and coverage data. To build such a program with
 ``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
 flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``

 .. _llvm-cov-report:
 
 REPORT COMMAND
 --------------
 
 SYNOPSIS
 ^^^^^^^^
 
-:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
+:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...
 
 DESCRIPTION
 ^^^^^^^^^^^
 
 The :program:`llvm-cov report` command displays a summary of the coverage of
-the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
-filtered to only show the coverage for the files listed in *SOURCES*.
+the binaries *BIN*... using the profile data *PROFILE*. It can optionally be
+filtered to only show the coverage for the files listed in *SOURCE*....
 
 *BIN* may be an executable, object file, dynamic library, or archive (thin or
 otherwise).
 
 If no source files are provided, a summary line is printed for each file in the
 coverage data. If any files are provided, summaries can be shown for each
 function in the listed files if the ``-show-functions`` option is enabled.
 

 .. _llvm-cov-export:
 
 EXPORT COMMAND
 --------------
 
 SYNOPSIS
 ^^^^^^^^
 
-:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
+:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...
 
 DESCRIPTION
 ^^^^^^^^^^^
 
 The :program:`llvm-cov export` command exports coverage data of the binaries
-*BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file
+*BIN*... using the profile data *PROFILE* in either JSON or lcov trace file
 format.
 
 When exporting JSON, the regions, functions, branches, expansions, and
 summaries of the coverage data will be exported. When exporting an lcov trace
 file, the line-based coverage, branch coverage, and summaries will be exported.
 
 The exported data can optionally be filtered to only export the coverage
-for the files listed in *SOURCES*.
+for the files listed in *SOURCE*....
 
 For information on compiling programs for coverage and generating profile data,
 see :ref:`llvm-cov-show`.
 
 OPTIONS
 ^^^^^^^
 
 .. option:: -arch=<name>

llvm/tools/llvm-cov/CodeCoverage.cpp

int CodeCoverageTool::run(Command Cmd, int argc, const char **argv) {
 
   cl::list<std::string> CovFilenames(
       "object", cl::desc("Coverage executable or object file"));
 
   cl::opt<bool> DebugDumpCollectedObjects(
       "dump-collected-objects", cl::Optional, cl::Hidden,
       cl::desc("Show the collected coverage object files"));
 
-  cl::list<std::string> InputSourceFiles(cl::Positional,
+  cl::list<std::string> InputSourceFiles("sources", cl::Positional,
                                          cl::desc("<Source files>"));
 
   cl::opt<bool> DebugDumpCollectedPaths(
       "dump-collected-paths", cl::Optional, cl::Hidden,
       cl::desc("Show the collected paths to source files"));
 
   cl::opt<std::string, true> PGOFilename(
       "instr-profile", cl::Required, cl::location(this->PGOFilename),