[TableGen] [Docs] Add lldb-tblgen to command guide; add 4 stubs for xxx-tblgen commands

[Paul-C-Anagnostopoulos]

Summary

This revision adds the lldb-tblgen command options to the tblgen command guide.

It also adds four stub documents, xxx-tblgen, for the four flavors of TableGen, which simply refer the reader to the primary command guide.

[lattner]

I'm not up to speed on the doc structure.

[aaronpuchert]

The comments apply similarly to the other files,

llvm/docs/CommandGuide/clang-tblgen.rst

2

I'd say "Description to C++ Code for Clang".

It can be a bunch of things like command line options, diagnostic messages, attributes, so I think it's hard to find something overarching here.

5

Should this say clang-tblgen? Not sure how this works.

23

Can we use * instead of xxx here?

[Paul-C-Anagnostopoulos]

Incorporate Aaron's comments.

[Paul-C-Anagnostopoulos]

Now let's actually include the changes.

[aaronpuchert]

I'm wondering if we should move the files to their respective subprojects, but that would probably prevent the links from working. So I guess we have to live with this for now.

[jrtc27]

llvm/docs/CommandGuide/tblgen.rst

1

This is what ends up in the mange's file name, so we now have a file called tblgen Family.1 being built, which is clearly not a good idea. Please change this.

1

*manpage's

[brooks]

This results in a manpage with the filename tblgen Family.1 which quite odd.

[jrtc27]

llvm/docs/CommandGuide/clang-tblgen.rst

20

These references are wrong; the real title doesn't have "Target" in it (since that's specifically for llvm-tblgen)

[Paul-C-Anagnostopoulos]

llvm/docs/CommandGuide/tblgen.rst

1

What do you suggest I change it to?

[jrtc27]

llvm/docs/CommandGuide/tblgen.rst

1

I'd suggest just removing the Family? Then it matches .. program:: below and the name of the rst file itself.

[Paul-C-Anagnostopoulos]

llvm/docs/CommandGuide/tblgen.rst

1

Sounds good. I will do this on Friday.

[jrtc27]

llvm/docs/CommandGuide/tblgen.rst

1

Thanks

[Paul-C-Anagnostopoulos]

Do you think it's necessary to have the change of document title reviewed in Phabricator?

[jrtc27]

In D99605#2677896, @Paul-C-Anagnostopoulos wrote:

Do you think it's necessary to have the change of document title reviewed in Phabricator?

I wouldn't bother, especially since we've discussed the exact change already

[Paul-C-Anagnostopoulos]

I pushed this patch.

[jrtc27]

In D99605#2679568, @Paul-C-Anagnostopoulos wrote:

I pushed this patch.

Great, thanks for the quick follow-up.

llvm/docs/CommandGuide/clang-tblgen.rst

+clang-tblgen - Description to C++ Code for Clang
+================================================
+
+.. program:: clang-tblgen
+
+SYNOPSIS
+--------
+
+:program:`clang-tblgen` [*options*] [*filename*]
+
+
+DESCRIPTION
+-----------
+
+:program:`clang-tblgen` is a program that translates compiler-related target
+description (``.td``) files into C++ code and other output formats. Most
+users of LLVM will not need to use this program. It is used only for writing
+parts of the compiler.
+
+Please see :doc:`tblgen Family - Target Description to C++ Code<./tblgen>`
+for a description of the *filename* argument and options, including the
+options common to all :program:`*-tblgen` programs.

llvm/docs/CommandGuide/index.rst

 Developer Tools
 ~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
 
    FileCheck
    tblgen
+   clang-tblgen
+   lldb-tblgen
+   llvm-tblgen
+   mlir-tblgen
    lit
    llvm-exegesis
    llvm-locstats
    llvm-pdbutil
    llvm-profgen

llvm/docs/CommandGuide/lldb-tblgen.rst

+lldb-tblgen - Description to C++ Code for LLDB
+==============================================
+
+.. program:: lldb-tblgen
+
+SYNOPSIS
+--------
+
+:program:`lldb-tblgen` [*options*] [*filename*]
+
+
+DESCRIPTION
+-----------
+
+:program:`lldb-tblgen` is a program that translates compiler-related target
+description (``.td``) files into C++ code and other output formats. Most
+users of LLVM will not need to use this program. It is used only for writing
+parts of the compiler.
+
+Please see :doc:`tblgen Family - Target Description to C++ Code<./tblgen>`
+for a description of the *filename* argument and options, including the
+options common to all :program:`*-tblgen` programs.

llvm/docs/CommandGuide/llvm-tblgen.rst

+llvm-tblgen - Target Description to C++ Code for LLVM
+=====================================================
+
+.. program:: llvm-tblgen
+
+SYNOPSIS
+--------
+
+:program:`llvm-tblgen` [*options*] [*filename*]
+
+
+DESCRIPTION
+-----------
+
+:program:`llvm-tblgen` is a program that translates compiler-related target
+description (``.td``) files into C++ code and other output formats. Most
+users of LLVM will not need to use this program. It is used only for writing
+parts of the compiler.
+
+Please see :doc:`tblgen Family - Target Description to C++ Code<./tblgen>`
+for a description of the *filename* argument and options, including the
+options common to all :program:`*-tblgen` programs.

llvm/docs/CommandGuide/mlir-tblgen.rst

+mlir-tblgen - Description to C++ Code for MLIR
+==============================================
+
+.. program:: mlir-tblgen
+
+SYNOPSIS
+--------
+
+:program:`mlir-tblgen` [*options*] [*filename*]
+
+
+DESCRIPTION
+-----------
+
+:program:`mlir-tblgen` is a program that translates compiler-related target
+description (``.td``) files into C++ code and other output formats. Most
+users of LLVM will not need to use this program. It is used only for writing
+parts of the compiler.
+
+Please see :doc:`tblgen Family - Target Description to C++ Code<./tblgen>`
+for a description of the *filename* argument and options, including the
+options common to all :program:`*-tblgen` programs.

llvm/docs/CommandGuide/tblgen.rst

-xxx-tblgen - Target Description to C++ Code
-===========================================
+tblgen Family - Description to C++ Code
+=======================================
 
 .. program:: tblgen
 
 SYNOPSIS
 --------
 
-:program:`xxx-tblgen` [*options*] [*filename*]
+:program:`clang-tblgen` [*options*] [*filename*]
+
+:program:`lldb-tblgen` [*options*] [*filename*]
+
+:program:`llvm-tblgen` [*options*] [*filename*]
+
+:program:`mlir-tblgen` [*options*] [*filename*]
 
 DESCRIPTION
 -----------
 
-:program:`xxx-tblgen` is a family of programs that translates target
+:program:`*-tblgen` is a family of programs that translates target
 description (``.td``) files into C++ code and other output formats. Most
 users of LLVM will not need to use this program. It is used only for
-writing parts of the compiler or LLVM target backends.
+writing parts of the compiler, debugger, and LLVM target backends.
 
-The details of the input and output of :program:`xxx-tblgen` is beyond the
+The details of the input and output of :program:`*-tblgen` is beyond the
 scope of this short introduction; please see the :doc:`TableGen Overview
 <../TableGen/index>` for an introduction and for references to additional
 TableGen documents.
 
 The *filename* argument specifies the name of the Target Description (``.td``)
 file that TableGen processes.
 
 OPTIONS

 .. option:: -null-backend
 
   Parse the source files and build the records, but do not run any
   backend. This is useful for timing the frontend.
 
 .. option:: -o filename
 
  Specify the output file name.  If ``filename`` is ``-``, then
- :program:`xxx-tblgen` sends its output to standard output.
+ :program:`*-tblgen` sends its output to standard output.
 
 .. option:: -print-records
 
  Print all classes and records to standard output (default backend option).
 
 .. option:: -print-detailed-records
 
   Print a detailed report of all global variables, classes, and records

 .. option:: -version
 
  Show the version number of the program.
 
 .. option:: -write-if-changed
 
   Write the output file only if it is new or has changed.
 
-llvm-tblgen Options
-~~~~~~~~~~~~~~~~~~~
-
-.. option:: -gen-asm-matcher
-
- Generate assembly instruction matcher.
-
-.. option:: -match-prefix=prefix
-
-  Make -gen-asm-matcher match only instructions with the given *prefix*.
-
-.. option:: -gen-asm-parser
-
- Generate assembly instruction parser.
-
-.. option:: -asmparsernum=n
-
- Make -gen-asm-parser emit assembly parser number *n*.
-
-.. option:: -gen-asm-writer
-
- Generate assembly writer.
-
-.. option:: -asmwriternum=n
-
- Make -gen-asm-writer emit assembly writer number *n*.
-
-.. option:: -gen-attrs
-
-  Generate attributes.
-
-.. option:: -gen-automata
-
-  Generate generic automata.
-
-.. option:: -gen-callingconv
-
-  Generate calling convention descriptions.
-
-.. option:: -gen-compress-inst-emitter
-
-  Generate RISC-V compressed instructions.
-
-.. option:: -gen-ctags
-
-  Generate ctags-compatible index.
-
-.. option:: -gen-dag-isel
-
- Generate a DAG (directed acyclic graph) instruction selector.
-
-.. option:: -instrument-coverage
-
-  Make -gen-dag-isel generate tables to help identify the patterns matched.
-
-.. option:: -omit-comments
-
-  Make -gen-dag-isel omit comments. The default is false.
-
-.. option:: -gen-dfa-packetizer
-
- Generate DFA Packetizer for VLIW targets.
-
-.. option:: -gen-directive-decl
-
-  Generate directive related declaration code (header file).
-
-.. option:: -gen-directive-gen
-
-  Generate directive related implementation code part.
-
-.. option:: -gen-directive-impl
-
-  Generate directive related implementation code.
-
-.. option:: -gen-disassembler
-
-  Generate disassembler.
-
-.. option:: -gen-emitter
-
- Generate machine code emitter.
-
-.. option:: -gen-exegesis
-
-  Generate llvm-exegesis tables.
-
-.. option:: -gen-fast-isel
-
-  Generate a "fast" instruction selector.
-
-.. option:: -gen-global-isel
-
-  Generate GlobalISel selector.
-
-.. option:: -gisel-coverage-file=filename
-
-  Specify the file from which to retrieve coverage information.
-
-.. option:: -instrument-gisel-coverage
-
-  Make -gen-global-isel generate coverage instrumentation.
-
-.. option:: -optimize-match-table
-
-  Make -gen-global-isel generate an optimized version of the match table.
-
-.. option:: -warn-on-skipped-patterns
-
-  Make -gen-global-isel explain why a pattern was skipped for inclusion.
-
-.. option:: -gen-global-isel-combiner
-
-  Generate GlobalISel combiner.
-
-.. option:: -combiners=list
-
-  Make -gen-global-isel-combiner emit the specified combiners.
-
-.. option:: -gicombiner-show-expansions
-
-  Make -gen-global-isel-combiner use C++ comments to indicate occurrences
-  of code expansion.
-
-.. option:: -gicombiner-stop-after-build
-
-  Make -gen-global-isel-combiner stop processing after building the match tree.
-
-.. option:: -gicombiner-stop-after-parse
-
-  Make -gen-global-isel-combiner stop processing after parsing rules
-  and dump state.
-
-.. option:: -gen-instr-info
-
- Generate instruction descriptions.
-
-.. option:: -gen-instr-docs
-
- Generate instruction documentation.
-
-.. option:: -gen-intrinsic-enums
-
- Generate intrinsic enums.
-
-.. option:: -intrinsic-prefix=prefix
-
-  Make -gen-intrinsic-enums generate intrinsics with this target *prefix*.
-
-.. option:: -gen-intrinsic-impl
-
- Generate intrinsic information.
-
-.. option:: -gen-opt-parser-defs
-
-  Generate options definitions.
-
-.. option:: -gen-opt-rst
-
-  Generate option RST.
-
-.. option:: -gen-pseudo-lowering
-
- Generate pseudo instruction lowering.
-
-.. option:: -gen-register-bank
-
-  Generate register bank descriptions.
-
-.. option:: -gen-register-info
-
-  Generate registers and register classes info.
-
-.. option:: -register-info-debug
-
-  Make -gen-register-info dump register information for debugging.
-
-.. option:: -gen-searchable-tables
-
-  Generate generic searchable tables. See :doc:`TableGen BackEnds <../TableGen/BackEnds>`
-  for a detailed description.
-
-.. option:: -gen-subtarget
-
- Generate subtarget enumerations.
-
-.. option:: -gen-x86-EVEX2VEX-tables
-
-  Generate X86 EVEX to VEX compress tables.
-
-.. option:: -gen-x86-fold-tables
-
-  Generate X86 fold tables.
-
-.. option:: -long-string-literals
-
-  When emitting large string tables, prefer string literals over
-  comma-separated char literals. This can be a readability and
-  compile-time performance win, but upsets some compilers.
-
-.. option:: -print-enums
-
- Print enumeration values for a class.
-
-.. option:: -class=classname
-
- Make -print-enums print the enumeration list for the specified class.
-
-.. option:: -print-sets
-
- Print expanded sets for testing DAG exprs.
 
 clang-tblgen Options
 ~~~~~~~~~~~~~~~~~~~~
 
 .. option:: -gen-clang-attr-classes
 
   Generate Clang attribute clases.
 
.. option:: -gen-clang-data-collectors
   Generate data collectors for AST nodes.
 
 .. option:: -gen-clang-test-pragma-attribute-supported-attributes
 
   Generate a list of attributes supported by ``#pragma`` Clang attribute for
   testing purposes.
 
 
+lldb-tblgen Options
+~~~~~~~~~~~~~~~~~~~
+
+.. option:: gen-lldb-option-defs
+
+  Generate lldb OptionDefinition values.
+
+.. option:: gen-lldb-property-defs
+
+  Generate lldb PropertyDefinition values.
+
+.. option:: gen-lldb-property-enum-defs
+
+  Generate lldb PropertyDefinition enum values.
+
+
+llvm-tblgen Options
+~~~~~~~~~~~~~~~~~~~
+
+.. option:: -gen-asm-matcher
+
+ Generate assembly instruction matcher.
+
+.. option:: -match-prefix=prefix
+
+  Make -gen-asm-matcher match only instructions with the given *prefix*.
+
+.. option:: -gen-asm-parser
+
+ Generate assembly instruction parser.
+
+.. option:: -asmparsernum=n
+
+ Make -gen-asm-parser emit assembly parser number *n*.
+
+.. option:: -gen-asm-writer
+
+ Generate assembly writer.
+
+.. option:: -asmwriternum=n
+
+ Make -gen-asm-writer emit assembly writer number *n*.
+
+.. option:: -gen-attrs
+
+  Generate attributes.
+
+.. option:: -gen-automata
+
+  Generate generic automata.
+
+.. option:: -gen-callingconv
+
+  Generate calling convention descriptions.
+
+.. option:: -gen-compress-inst-emitter
+
+  Generate RISC-V compressed instructions.
+
+.. option:: -gen-ctags
+
+  Generate ctags-compatible index.
+
+.. option:: -gen-dag-isel
+
+ Generate a DAG (directed acyclic graph) instruction selector.
+
+.. option:: -instrument-coverage
+
+  Make -gen-dag-isel generate tables to help identify the patterns matched.
+
+.. option:: -omit-comments
+
+  Make -gen-dag-isel omit comments. The default is false.
+
+.. option:: -gen-dfa-packetizer
+
+ Generate DFA Packetizer for VLIW targets.
+
+.. option:: -gen-directive-decl
+
+  Generate directive related declaration code (header file).
+
+.. option:: -gen-directive-gen
+
+  Generate directive related implementation code part.
+
+.. option:: -gen-directive-impl
+
+  Generate directive related implementation code.
+
+.. option:: -gen-disassembler
+
+  Generate disassembler.
+
+.. option:: -gen-emitter
+
+ Generate machine code emitter.
+
+.. option:: -gen-exegesis
+
+  Generate llvm-exegesis tables.
+
+.. option:: -gen-fast-isel
+
+  Generate a "fast" instruction selector.
+
+.. option:: -gen-global-isel
+
+  Generate GlobalISel selector.
+
+.. option:: -gisel-coverage-file=filename
+
+  Specify the file from which to retrieve coverage information.
+
+.. option:: -instrument-gisel-coverage
+
+  Make -gen-global-isel generate coverage instrumentation.
+
+.. option:: -optimize-match-table
+
+  Make -gen-global-isel generate an optimized version of the match table.
+
+.. option:: -warn-on-skipped-patterns
+
+  Make -gen-global-isel explain why a pattern was skipped for inclusion.
+
+.. option:: -gen-global-isel-combiner
+
+  Generate GlobalISel combiner.
+
+.. option:: -combiners=list
+
+  Make -gen-global-isel-combiner emit the specified combiners.
+
+.. option:: -gicombiner-show-expansions
+
+  Make -gen-global-isel-combiner use C++ comments to indicate occurrences
+  of code expansion.
+
+.. option:: -gicombiner-stop-after-build
+
+  Make -gen-global-isel-combiner stop processing after building the match tree.
+
+.. option:: -gicombiner-stop-after-parse
+
+  Make -gen-global-isel-combiner stop processing after parsing rules
+  and dump state.
+
+.. option:: -gen-instr-info
+
+ Generate instruction descriptions.
+
+.. option:: -gen-instr-docs
+
+ Generate instruction documentation.
+
+.. option:: -gen-intrinsic-enums
+
+ Generate intrinsic enums.
+
+.. option:: -intrinsic-prefix=prefix
+
+  Make -gen-intrinsic-enums generate intrinsics with this target *prefix*.
+
+.. option:: -gen-intrinsic-impl
+
+ Generate intrinsic information.
+
+.. option:: -gen-opt-parser-defs
+
+  Generate options definitions.
+
+.. option:: -gen-opt-rst
+
+  Generate option RST.
+
+.. option:: -gen-pseudo-lowering
+
+ Generate pseudo instruction lowering.
+
+.. option:: -gen-register-bank
+
+  Generate register bank descriptions.
+
+.. option:: -gen-register-info
+
+  Generate registers and register classes info.
+
+.. option:: -register-info-debug
+
+  Make -gen-register-info dump register information for debugging.
+
+.. option:: -gen-searchable-tables
+
+  Generate generic searchable tables. See :doc:`TableGen BackEnds <../TableGen/BackEnds>`
+  for a detailed description.
+
+.. option:: -gen-subtarget
+
+ Generate subtarget enumerations.
+
+.. option:: -gen-x86-EVEX2VEX-tables
+
+  Generate X86 EVEX to VEX compress tables.
+
+.. option:: -gen-x86-fold-tables
+
+  Generate X86 fold tables.
+
+.. option:: -long-string-literals
+
+  When emitting large string tables, prefer string literals over
+  comma-separated char literals. This can be a readability and
+  compile-time performance win, but upsets some compilers.
+
+.. option:: -print-enums
+
+ Print enumeration values for a class.
+
+.. option:: -class=classname
+
+ Make -print-enums print the enumeration list for the specified class.
+
+.. option:: -print-sets
+
+ Print expanded sets for testing DAG exprs.
+
 
 mlir-tblgen Options
 ~~~~~~~~~~~~~~~~~~~
 
 .. option:: -gen-avail-interface-decls
 
   Generate availability interface declarations.
 

 
 .. option:: -typedefs-dialect name
 
   Generate types for this dialect.
 
 EXIT STATUS
 -----------
 
-If :program:`xxx-tblgen` succeeds, it will exit with 0.  Otherwise, if an error
+If :program:`*-tblgen` succeeds, it will exit with 0.  Otherwise, if an error
 occurs, it will exit with a non-zero value.