[docs] [tools] Document and alphabetize all llvm-config command-line options

[fw-immunant]

Summary

Also implements explicit handling for the already-documented --help flag.

[jhenderson]

Could you please reupload this patch, with full diff context, i.e. using something like -U999999 when creating the diff. This will help verify the full document.

I'd probably recommend reordering the options to be in alphabetical order too. There are some other general tidy-ups I think should be made to this document (using e.g. the option-specific rst syntax), but that's probably outside the scope of this change.

[fw-immunant]

Uploaded with full diff context.

[jhenderson]

I'd probably recommend reordering the options to be in alphabetical order too.

Apologies if this wasn't clear, but I think the alphabetical ordering should be done in this patch.

llvm/docs/CommandGuide/llvm-config.rst

66

I believe "cmake" is actually written "CMake".

156

"CMake" (though I wonder whether this statement is accurate in the presence of gn or bazel).

[GMNGeoffrey]

llvm/docs/CommandGuide/llvm-config.rst

156

Bazel is unsupported, etc. etc., but yeah I think the "always cmake" bit here isn't super helpful. Even if not upstream I know various people build LLVM with various build systems

[fw-immunant]

Alphabetized options in docs and usage, added explicit handling for --help, corrected spelling of CMake, clarified what might be returned by --build-system.

[fw-immunant]

llvm/docs/CommandGuide/llvm-config.rst

156

The only other option I saw as possible based on a grep for LLVM_BUILD_SYSTEM is gn, so I've mentioned it here. Unlike the other mention of lower-case "cmake", this one is actually correct--the value printed is lowercase.

[jhenderson]

Looks good from my point of view.

llvm/docs/CommandGuide/llvm-config.rst

46

I'd actually get rid of "gn" to avoid confusion, as I believe gn builds aren't officially supported by core LLVM (it's maintained by the users of gn, rather than the wider community), like bazel, but I don't mind that much.

[fw-immunant]

llvm/docs/CommandGuide/llvm-config.rst

46

There seems to be code in the LLVM tree (in llvm/utils/gn/secondary/llvm/tools/llvm-config/BUILD.gn) that will result in gn appearing here, so I think it's reasonable to document the possibility. If you want it removed say so and I'll change it.

[fw-immunant]

llvm/docs/CommandGuide/llvm-config.rst

46

Otherwise, go ahead and commit, as I don't have commit access myself.

[jhenderson]

llvm/docs/CommandGuide/llvm-config.rst

46

Today's my last day in the office, before the Christmas break, so I don't want to be committing anything, in case I break things, as I won't necessarily have time to do the fix.

@andreadb/@GMNGeoffrey are either of you in a position to do so?

@fw-immunant, we'll need the name and email address you want this committed under, so that it appears in the git author details. Feel free to email directly, if preferred.

If nobody else gets to this, I'm happy to do it when I come back to work, although you could also try asking on llvm-dev for someone to take care of it.

[GMNGeoffrey]

llvm/docs/CommandGuide/llvm-config.rst

46

I'll be around until Thursday 2021-12-23 PT, so I can land, but I don't really have much context on this patch other than my filter for patches containing "Bazel" flagged it :-)

[jhenderson]

@GMNGeoffrey, (or anybody else) did you land this change yet? If not, I can probably arrange for it this week.

[GMNGeoffrey]

In D115533#3221708, @jhenderson wrote:

@GMNGeoffrey, (or anybody else) did you land this change yet? If not, I can probably arrange for it this week.

I didn't hear from @fw-immunant what name and email to use, so I didn't take any action

[jhenderson]

In D115533#3222806, @GMNGeoffrey wrote:

In D115533#3221708, @jhenderson wrote:

@GMNGeoffrey, (or anybody else) did you land this change yet? If not, I can probably arrange for it this week.

I didn't hear from @fw-immunant what name and email to use, so I didn't take any action

Ah, good point. @fw-immunant, please email or post your name and email address so that one of us can appropriately assign the commit author when landing this.

[fw-immunant]

Sorry, I missed this. Name is Frances Wingerter and e-mail is <[e-mail]>.

Is there anything else needed? Thanks.

[jhenderson]

In D115533#3418038, @fw-immunant wrote:

Sorry, I missed this. Name is Frances Wingerter and e-mail is <[e-mail]>.

Is there anything else needed? Thanks.

I've gone ahead and pushed this. Please keep an eye out for related buildbot failure emails.

Whilst building your patch, I noticed that the llvm-config doc doesn't use the correct markup for command-line options and references to them. Basically, I think throughout it's misusing bold ** formatting. If you fancy a follow-up, I recommend fixing this. Docs like llvm-readobj.rst are a good reference point.

llvm/docs/CommandGuide/llvm-config.rst

.. code-block:: sh
 
    g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
    g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
        `llvm-config --libs engine bcreader scalaropts`
 
 OPTIONS
 -------
 
-**--version**
+**--assertion-mode**
 
- Print the version number of LLVM.
+ Print the assertion mode used when LLVM was built (ON or OFF).
 
-**-help**
+**--bindir**
 
- Print a summary of **llvm-config** arguments.
+ Print the installation directory for LLVM binaries.
 
-**--prefix**
+**--build-mode**
 
- Print the installation prefix for LLVM.
+ Print the build mode used when LLVM was built (e.g. Debug or Release).
 
-**--src-root**
+**--build-system**
 
- Print the source root from which LLVM was built.
+ Print the build system used to build LLVM (e.g. `cmake` or `gn`).
 
-**--obj-root**
+**--cflags**
 
- Print the object root used to build LLVM.
+ Print the C compiler flags needed to use LLVM headers.
 
-**--bindir**
+**--cmakedir**
 
- Print the installation directory for LLVM binaries.
+ Print the installation directory for LLVM CMake modules.
 
-**--includedir**
+**--components**
 
- Print the installation directory for LLVM headers.
+ Print all valid component names.
 
-**--libdir**
+**--cppflags**
 
- Print the installation directory for LLVM libraries.
+ Print the C preprocessor flags needed to use LLVM headers.
 
 **--cxxflags**
 
  Print the C++ compiler flags needed to use LLVM headers.
 
+**--has-rtti**
+
+ Print whether or not LLVM was built with rtti (YES or NO).
+
+**--help**
+
+ Print a summary of **llvm-config** arguments.
+
+**--host-target**
+
+ Print the target triple used to configure LLVM.
+
+**--ignore-libllvm**
+
+ Ignore libLLVM and link component libraries instead.
+
+**--includedir**
+
+ Print the installation directory for LLVM headers.
+
 **--ldflags**
 
  Print the flags needed to link against LLVM libraries.
 
-**--libs**
+**--libdir**
 
- Print all the libraries needed to link against the specified LLVM
- *components*, including any dependencies.
+ Print the installation directory for LLVM libraries.
+
+**--libfiles**
+
+ Similar to **--libs**, but print the full path to each library file.  This is
+ useful when creating makefile dependencies, to ensure that a tool is relinked if
+ any library it uses changes.
 
 **--libnames**
 
  Similar to **--libs**, but prints the bare filenames of the libraries
  without **-l** or pathnames.  Useful for linking against a not-yet-installed
  copy of LLVM.
 
-**--libfiles**
+**--libs**
 
- Similar to **--libs**, but print the full path to each library file.  This is
- useful when creating makefile dependencies, to ensure that a tool is relinked if
- any library it uses changes.
+ Print all the libraries needed to link against the specified LLVM
+ *components*, including any dependencies.
 
-**--components**
+**--link-shared**
 
- Print all valid component names.
+ Link the components as shared libraries.
+
+**--link-static**
+
+ Link the component libraries statically.
+
+**--obj-root**
+
+ Print the object root used to build LLVM.
+
+**--prefix**
+
+ Print the installation prefix for LLVM.
+
+**--shared-mode**
+
+ Print how the provided components can be collectively linked (`shared` or `static`).
+
+**--src-root**
+
+ Print the source root from which LLVM was built.
+
+**--system-libs**
+
+ Print all the system libraries needed to link against the specified LLVM
+ *components*, including any dependencies.
 
 **--targets-built**
 
  Print the component names for all targets supported by this copy of LLVM.
 
-**--build-mode**
+**--version**
 
- Print the build mode used when LLVM was built (e.g. Debug or Release)
+ Print the version number of LLVM.
 
 
 COMPONENTS
 ----------
 
 To print a list of all available components, run **llvm-config
 --components**.  In most cases, components correspond directly to LLVM
 libraries.  Useful "virtual" components include:
 
 **all**
 
  Includes all LLVM libraries.  The default if no components are specified.
 
 **backend**
 
  Includes either a native backend or the C backend.

llvm/tools/llvm-config/llvm-config.cpp

static std::vector<std::string> ComputeLibsForComponents(
   // in the reverse order of dependency.
   std::reverse(RequiredLibs.begin(), RequiredLibs.end());
 
   return RequiredLibs;
 }
 
 /* *** */
 
-static void usage() {
+static void usage(bool ExitWithFailure = true) {
   errs() << "\
 usage: llvm-config <OPTION>... [<COMPONENT>...]\n\
 \n\
 Get various configuration information needed to compile programs which use\n\
 LLVM.  Typically called from 'configure' scripts.  Examples:\n\
   llvm-config --cxxflags\n\
   llvm-config --ldflags\n\
   llvm-config --libs engine bcreader scalaropts\n\
 \n\
 Options:\n\
-  --version         Print LLVM version.\n\
-  --prefix          Print the installation prefix.\n\
-  --src-root        Print the source root LLVM was built from.\n\
-  --obj-root        Print the object root used to build LLVM.\n\
+  --assertion-mode  Print assertion mode of LLVM tree (ON or OFF).\n\
   --bindir          Directory containing LLVM executables.\n\
-  --includedir      Directory containing LLVM headers.\n\
-  --libdir          Directory containing LLVM libraries.\n\
-  --cmakedir        Directory containing LLVM cmake modules.\n\
-  --cppflags        C preprocessor flags for files that include LLVM headers.\n\
+  --build-mode      Print build mode of LLVM tree (e.g. Debug or Release).\n\
+  --build-system    Print the build system used to build LLVM (e.g. `cmake` or `gn`).\n\
   --cflags          C compiler flags for files that include LLVM headers.\n\
+  --cmakedir        Directory containing LLVM CMake modules.\n\
+  --components      List of all possible components.\n\
+  --cppflags        C preprocessor flags for files that include LLVM headers.\n\
   --cxxflags        C++ compiler flags for files that include LLVM headers.\n\
+  --has-rtti        Print whether or not LLVM was built with rtti (YES or NO).\n\
+  --help            Print a summary of llvm-config arguments.\n\
+  --host-target     Target triple used to configure LLVM.\n\
+  --ignore-libllvm  Ignore libLLVM and link component libraries instead.\n\
+  --includedir      Directory containing LLVM headers.\n\
   --ldflags         Print Linker flags.\n\
-  --system-libs     System Libraries needed to link against LLVM components.\n\
-  --libs            Libraries needed to link against LLVM components.\n\
-  --libnames        Bare library names for in-tree builds.\n\
+  --libdir          Directory containing LLVM libraries.\n\
   --libfiles        Fully qualified library filenames for makefile depends.\n\
-  --components      List of all possible components.\n\
-  --targets-built   List of all targets currently built.\n\
-  --host-target     Target triple used to configure LLVM.\n\
-  --build-mode      Print build mode of LLVM tree (e.g. Debug or Release).\n\
-  --assertion-mode  Print assertion mode of LLVM tree (ON or OFF).\n\
-  --build-system    Print the build system used to build LLVM (always cmake).\n\
-  --has-rtti        Print whether or not LLVM was built with rtti (YES or NO).\n\
-  --shared-mode     Print how the provided components can be collectively linked (`shared` or `static`).\n\
+  --libnames        Bare library names for in-tree builds.\n\
+  --libs            Libraries needed to link against LLVM components.\n\
   --link-shared     Link the components as shared libraries.\n\
   --link-static     Link the component libraries statically.\n\
-  --ignore-libllvm  Ignore libLLVM and link component libraries instead.\n\
+  --obj-root        Print the object root used to build LLVM.\n\
+  --prefix          Print the installation prefix.\n\
+  --shared-mode     Print how the provided components can be collectively linked (`shared` or `static`).\n\
+  --src-root        Print the source root LLVM was built from.\n\
+  --system-libs     System Libraries needed to link against LLVM components.\n\
+  --targets-built   List of all targets currently built.\n\
+  --version         Print LLVM version.\n\
 Typical components:\n\
   all               All LLVM libraries (default).\n\
   engine            Either a native JIT or a bitcode interpreter.\n";
+  if (ExitWithFailure)
     exit(1);
 }
 
 /// Compute the path to the main executable.
 std::string GetExecutablePath(const char *Argv0) {
   // This just needs to be some symbol in the binary; C++ doesn't
   // allow taking the address of ::main however.
   void *P = (void *)(intptr_t)GetExecutablePath;
   return llvm::sys::fs::getMainExecutable(Argv0, P);
#endif
         OS << LLVM_SRC_ROOT << '\n';
       } else if (Arg == "--ignore-libllvm") {
         LinkDyLib = false;
         LinkMode = BuiltSharedLibs ? LinkModeShared : LinkModeAuto;
       } else if (Arg == "--link-shared") {
         LinkMode = LinkModeShared;
       } else if (Arg == "--link-static") {
         LinkMode = LinkModeStatic;
+      } else if (Arg == "--help") {
+        usage(false);
       } else {
         usage();
       }
     } else {
       Components.push_back(Arg);
     }
   }