[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".

128

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

[GMNGeoffrey]

llvm/docs/CommandGuide/llvm-config.rst

128

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

128

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**
+**--help**
 
- Print the version number of LLVM.
+ Print a summary of **llvm-config** arguments.
 
-**-help**
+**--version**
 
- Print a summary of **llvm-config** arguments.
+ Print the version number of LLVM.
 
 **--prefix**
 
  Print the installation prefix for LLVM.
 
 **--src-root**
 
  Print the source root from which LLVM was built.
 
 **--obj-root**
 
  Print the object root used to build LLVM.
 
 **--bindir**
 
  Print the installation directory for LLVM binaries.
 
 **--includedir**
 
  Print the installation directory for LLVM headers.
 
 **--libdir**
 
  Print the installation directory for LLVM libraries.
 
+**--cmakedir**
+
+ Print the installation directory for LLVM cmake modules.
+
+**--cppflags**
+
+ Print the C preprocessor flags needed to use LLVM headers.
+
+**--cflags**
+
+ Print the C compiler flags needed to use LLVM headers.
+
 **--cxxflags**
 
  Print the C++ compiler flags needed to use LLVM headers.
 
 **--ldflags**
 
  Print the flags needed to link against LLVM libraries.
 
+**--system-libs**
+
+ Print all the system libraries needed to link against the specified LLVM
+ *components*, including any dependencies.
+
 **--libs**
 
  Print all the libraries needed to link against the specified LLVM
  *components*, including any dependencies.
 
 **--libnames**
 
  Similar to **--libs**, but prints the bare filenames of the libraries

 **--components**
 
  Print all valid component names.
 
 **--targets-built**
 
  Print the component names for all targets supported by this copy of LLVM.
 
+**--host-target**
+
+ Print the target triple used to configure LLVM.
+
 **--build-mode**
 
- Print the build mode used when LLVM was built (e.g. Debug or Release)
+ Print the build mode used when LLVM was built (e.g. Debug or Release).
+
+**--assertion-mode**
+
+ Print the assertion mode used when LLVM was built (ON or OFF).
+
+**--build-system**
+
+ Print the build system used to build LLVM (always cmake).
+
+**--has-rtti**
+
+ Print whether or not LLVM was built with rtti (YES or NO).
+
+**--shared-mode**
+
+ Print how the provided components can be collectively linked (`shared` or `static`).
+
+**--link-shared**
+
+ Link the components as shared libraries.
+
+**--link-static**
+
+ Link the component libraries statically.
+
+**--ignore-libllvm**
+
+ Ignore libLLVM and link component libraries instead.
 
 
 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: