[llvm-ranlib] Support more than one input file

[MaskRay]

Summary

BSD and GNU ranlib support more than one input file. Implement this.

While here, update OVERVIEW (Ranlib => ranlib) since "ranlib" is more common.
Remove "speed access" since the index has nothing to do with performance: it is
mandatory for GNU ld and gold but ignored for ld.lld (D119074).

Close https://github.com/llvm/llvm-project/issues/54565

[MaskRay]

update overview
update doc

[jhenderson]

llvm/docs/CommandGuide/llvm-ranlib.rst

15

llvm/test/tools/llvm-ranlib/error-opening-permission.test

18

llvm/tools/llvm-ar/llvm-ar.cpp

1437–1442

Nit: I'd probably add a blank line between the two for loops.

1438–1441

It seems to me like you should generate the list of input files during the first loop, and then iterate over that rather than iterating over the full set of argv options twice? This will remove the risk of issues where the startswith("-")/consume_front("-") logic changes for some reason, which could result in the two getting out-of-sync.

[MaskRay]

Thanks for the review.
Addressed comments.

[MaskRay]

llvm/docs/CommandGuide/llvm-ranlib.rst

15

I have checked https://english.stackexchange.com/questions/13284/which-is-correct-one-or-more-is-or-one-or-more-are and I think I'll use the "plural" form :)

This motivated me to check the subject. I have re-read https://ell.stackexchange.com/questions/109363/more-than-one-does-or-more-than-one-do and will stick with the current "more than one input file".

llvm/docs/CommandGuide/llvm-ranlib.rst

 llvm-ranlib - generates an archive index
 ========================================
 
 .. program:: llvm-ranlib
 
 SYNOPSIS
 --------
 
-:program:`llvm-ranlib` [*options*]
+:program:`llvm-ranlib` [*options*] *archive...*
 
 DESCRIPTION
 -----------
 
 :program:`llvm-ranlib` is an alias for the :doc:`llvm-ar <llvm-ar>` tool that
-generates an index for an archive. It can be used as a replacement for GNU's
+generates an index for one or more archives. It can be used as a replacement for GNU's
 :program:`ranlib` tool.
 
 Running :program:`llvm-ranlib` is equivalent to running ``llvm-ar s``.
 
 SEE ALSO
 --------
 
 :manpage:`llvm-ar(1)`

llvm/test/tools/llvm-ranlib/D-flag.test

 # RUN: env TZ=UTC llvm-ar tv %t.a | FileCheck %s --check-prefix=REAL-VALUES
 
 ## Check that we accept multiple values and the last one wins:
 # RUN: cp %t-no-index.a %t.a && llvm-ranlib -UDU %t.a
 # RUN: env TZ=UTC llvm-ar tv %t.a | FileCheck %s --check-prefix=REAL-VALUES
 # RUN: cp %t-no-index.a %t.a && llvm-ranlib -UUD %t.a
 # RUN: env TZ=UTC llvm-ar tv %t.a | FileCheck %s --check-prefix=DETERMINISTIC-VALUES
 
-## Check arguments can be passed before and after the file name
-# RUN: cp %t-no-index.a %t.a && llvm-ranlib -U %t.a -D -U
+## Check multiple archives can be specified and arguments can be specified anywhere.
+# RUN: cp %t-no-index.a %t.a && cp %t-no-index.a %t2.a
+# RUN: llvm-ranlib -U %t.a -D %t2.a -U
 # RUN: env TZ=UTC llvm-ar tv %t.a | FileCheck %s --check-prefix=REAL-VALUES
+# RUN: env TZ=UTC llvm-ar tv %t2.a | FileCheck %s --check-prefix=REAL-VALUES
 
 ## Check that the -D/-U option is only accepted with a single dash. This matches
 ## the GNU ranlib behaviour.
 # RUN: not llvm-ranlib --D %t.a 2>&1 | FileCheck %s --check-prefix=BAD-OPT-D
 # BAD-OPT-D: error: Invalid option: '--D'
 # RUN: not llvm-ranlib --U %t.a 2>&1 | FileCheck %s --check-prefix=BAD-OPT-U
 # BAD-OPT-U: error: Invalid option: '--U'
 # RUN: not llvm-ranlib -x %t.a 2>&1 | FileCheck %s --check-prefix=BAD-OPT-x

llvm/test/tools/llvm-ranlib/error-opening-permission.test

+## Unsupported on windows as marking files "unreadable" is non-trivial on windows.
+# UNSUPPORTED: system-windows
+
+# RUN: rm -rf %t && split-file %s %t && cd %t
+# RUN: yaml2obj 1.yaml -o 1.o
+# RUN: llvm-ar rcS a.a 1.o
+# RUN: cp a.a b.a && cp a.a c.a && cp a.a d.a
+# RUN: chmod 100 c.a
+# RUN: not llvm-ranlib a.a b.a c.a d.a 2>&1 | FileCheck %s --check-prefix=NO-PERMISSION -DMSG=%errc_EACCES
+
+# NO-PERMISSION:     error: unable to open 'c.a': [[MSG]]
+# NO-PERMISSION-NOT: {{.}}
+
+## The archives before c.a (a.a and b.a) have been processed.
+# RUN: llvm-nm --print-armap a.a | FileCheck %s
+# RUN: cmp a.a b.a
+## The others (c.a and d.a) do not have a symbol table.
+# RUN: chmod 700 c.a
+# RUN: llvm-nm --print-armap c.a | FileCheck %s --check-prefix=NOMAP
+# RUN: cmp c.a d.a
+
+# CHECK:      Archive map
+# CHECK-NEXT: foo in 1.o
+# CHECK-EMPTY:
+
+# NOMAP-NOT: Archive map
+
+#--- 1.yaml
+--- !ELF
+FileHeader:
+  Class:   ELFCLASS64
+  Data:    ELFDATA2LSB
+  Type:    ET_REL
+  Machine: EM_X86_64
+Sections:
+  - Name: .text
+    Type: SHT_PROGBITS
+Symbols:
+  - Name:    foo
+    Binding: STB_GLOBAL
+    Section: .text

llvm/tools/llvm-ar/llvm-ar.cpp

 
 // The name this program was invoked as.
 static StringRef ToolName;
 
 // The basename of this program.
 static StringRef Stem;
 
 static void printRanLibHelp(StringRef ToolName) {
-  outs() << "OVERVIEW: LLVM Ranlib\n\n"
-         << "This program generates an index to speed access to archives\n\n"
-         << "USAGE: " + ToolName + " <archive-file>\n\n"
+  outs() << "OVERVIEW: LLVM ranlib\n\n"
+         << "Generate an index for archives\n\n"
+         << "USAGE: " + ToolName + " archive...\n\n"
          << "OPTIONS:\n"
          << "  -h --help             - Display available options\n"
          << "  -v --version          - Display the version of this program\n"
          << "  -D                    - Use zero for timestamps and uids/gids "
             "(default)\n"
          << "  -U                    - Use actual timestamps and uids/gids\n";
 }
 
for (ArrayRef<const char *>::iterator ArgIt = Argv.begin();
 
     Options += *ArgIt + 1;
   }
 
   return performOperation(parseCommandLine());
 }
 
 static int ranlib_main(int argc, char **argv) {
-  bool ArchiveSpecified = false;
+  std::vector<StringRef> Archives;
   for (int i = 1; i < argc; ++i) {
     StringRef arg(argv[i]);
     if (handleGenericOption(arg)) {
       return 0;
     } else if (arg.consume_front("-")) {
       // Handle the -D/-U flag
       while (!arg.empty()) {
         if (arg.front() == 'D') {
           Deterministic = true;
         } else if (arg.front() == 'U') {
           Deterministic = false;
         } else if (arg.front() == 'h') {
           printHelpMessage();
           return 0;
         } else if (arg.front() == 'v') {
           cl::PrintVersionMessage();
           return 0;
         } else {
           // TODO: GNU ranlib also supports a -t flag
           fail("Invalid option: '-" + arg + "'");
         }
         arg = arg.drop_front(1);
       }
     } else {
-      if (ArchiveSpecified)
-        fail("exactly one archive should be specified");
-      ArchiveSpecified = true;
-      ArchiveName = arg.str();
+      Archives.push_back(arg);
     }
   }
-  if (!ArchiveSpecified) {
-    badUsage("an archive name must be specified");
+
+  for (StringRef Archive : Archives) {
+    ArchiveName = Archive.str();
+    performOperation(CreateSymTab);
   }
-  return performOperation(CreateSymTab);
+  if (Archives.empty())
+    badUsage("an archive name must be specified");
+  return 0;
 }
 
 int llvm_ar_main(int argc, char **argv) {
   InitLLVM X(argc, argv);
   ToolName = argv[0];
 
   llvm::InitializeAllTargetInfos();
   llvm::InitializeAllTargetMCs();