https://github.com/Nerixyz updated https://github.com/llvm/llvm-project/pull/168245
>From de2ea6d8d33b4c790a1d8f99c9bcdf9a254a7fbd Mon Sep 17 00:00:00 2001 From: Nerixyz <[email protected]> Date: Tue, 3 Feb 2026 17:15:21 +0100 Subject: [PATCH] [LLDB][Docs] Generate documentation for settings --- lldb/cmake/modules/AddLLDB.cmake | 3 + lldb/docs/CMakeLists.txt | 18 ++- lldb/docs/_ext/lldb_setting.py | 73 ++++++++++++ .../_scripts/gen-property-docs-from-json.py | 106 ++++++++++++++++++ lldb/docs/_static/lldb-setting.css | 86 ++++++++++++++ lldb/docs/conf.py | 16 ++- lldb/docs/index.rst | 1 + lldb/docs/use/.gitignore | 2 + lldb/source/Core/CMakeLists.txt | 4 + lldb/source/Interpreter/CMakeLists.txt | 4 + .../Darwin-Kernel/CMakeLists.txt | 4 + .../Plugins/JITLoader/GDB/CMakeLists.txt | 4 + .../Plugins/Language/CPlusPlus/CMakeLists.txt | 4 + .../Plugins/ObjectFile/PECOFF/CMakeLists.txt | 4 + .../Plugins/Platform/Android/CMakeLists.txt | 4 + .../Plugins/Platform/MacOSX/CMakeLists.txt | 4 + .../Plugins/Platform/QemuUser/CMakeLists.txt | 4 + .../Platform/WebAssembly/CMakeLists.txt | 4 + lldb/source/Plugins/Process/CMakeLists.txt | 4 +- .../Process/MacOSX-Kernel/CMakeLists.txt | 8 ++ .../Plugins/Process/gdb-remote/CMakeLists.txt | 4 + .../StructuredData/DarwinLog/CMakeLists.txt | 4 + .../Plugins/SymbolFile/DWARF/CMakeLists.txt | 4 + .../Plugins/SymbolFile/PDB/CMakeLists.txt | 4 + .../SymbolLocator/Debuginfod/CMakeLists.txt | 4 + lldb/source/Plugins/Trace/CMakeLists.txt | 5 +- .../Plugins/Trace/intel-pt/CMakeLists.txt | 30 +++-- lldb/source/Target/CMakeLists.txt | 4 + lldb/utils/TableGen/CMakeLists.txt | 1 + .../TableGen/LLDBPropertyDocsEmitter.cpp | 73 ++++++++++++ lldb/utils/TableGen/LLDBTableGen.cpp | 8 +- lldb/utils/TableGen/LLDBTableGenBackends.h | 1 + 32 files changed, 478 insertions(+), 21 deletions(-) create mode 100644 lldb/docs/_ext/lldb_setting.py create mode 100644 lldb/docs/_scripts/gen-property-docs-from-json.py create mode 100644 lldb/docs/_static/lldb-setting.css create mode 100644 lldb/docs/use/.gitignore create mode 100644 lldb/utils/TableGen/LLDBPropertyDocsEmitter.cpp diff --git a/lldb/cmake/modules/AddLLDB.cmake b/lldb/cmake/modules/AddLLDB.cmake index 6493df27f38db..b535250cb1758 100644 --- a/lldb/cmake/modules/AddLLDB.cmake +++ b/lldb/cmake/modules/AddLLDB.cmake @@ -31,6 +31,9 @@ function(lldb_tablegen) add_public_tablegen_target(${LTG_TARGET}) set_property(GLOBAL APPEND PROPERTY LLDB_TABLEGEN_TARGETS ${LTG_TARGET}) endif() + if("-gen-lldb-property-docs-json" IN_LIST ARGN) + set_property(GLOBAL APPEND PROPERTY LLDB_DOCS_JSON_OUTPUTS "${TABLEGEN_OUTPUT}") + endif() endfunction(lldb_tablegen) function(add_lldb_library name) diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt index bbecf606f1f8f..920628f5da79a 100644 --- a/lldb/docs/CMakeLists.txt +++ b/lldb/docs/CMakeLists.txt @@ -37,6 +37,22 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND) add_dependencies(lldb-python-doc-package swig_wrapper_python) + get_property(LLDB_ALL_DOC_JSON_FILES GLOBAL PROPERTY LLDB_DOCS_JSON_OUTPUTS) + add_custom_command( + OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/use/settings.md" + COMMAND + "${Python3_EXECUTABLE}" + "${CMAKE_CURRENT_SOURCE_DIR}/_scripts/gen-property-docs-from-json.py" + -o + "${CMAKE_CURRENT_SOURCE_DIR}/use/settings.md" + -- + ${LLDB_ALL_DOC_JSON_FILES} + DEPENDS + ${LLDB_ALL_DOC_JSON_FILES} + "${CMAKE_CURRENT_SOURCE_DIR}/_scripts/gen-property-docs-from-json.py" + ) + add_custom_target(LLDBDocsSettingsMd DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/use/settings.md") + # FIXME: Don't treat Sphinx warnings as errors. The files generated by # automodapi are full of warnings (partly caused by SWIG, our documentation # and probably also automodapi itself), so those warnings need to be fixed @@ -52,7 +68,7 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND) add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html) add_dependencies(docs-lldb-html swig_wrapper_python - lldb-python-doc-package clean-lldb-html) + lldb-python-doc-package clean-lldb-html LLDBDocsSettingsMd) endif() if (${SPHINX_OUTPUT_MAN}) diff --git a/lldb/docs/_ext/lldb_setting.py b/lldb/docs/_ext/lldb_setting.py new file mode 100644 index 0000000000000..331789633e9da --- /dev/null +++ b/lldb/docs/_ext/lldb_setting.py @@ -0,0 +1,73 @@ +from docutils.parsers.rst import directives +from docutils import nodes + +from sphinx import addnodes +from sphinx.application import Sphinx +from sphinx.directives import ObjectDescription +from sphinx.util.docfields import Field, GroupedField +import llvm_slug + + +class LiteralField(Field): + """A field that wraps the content in <code></code>""" + + def make_field(self, types, domain, item, env=None, inliner=None, location=None): + fieldarg, content = item + fieldname = nodes.field_name("", self.label) + if fieldarg: + fieldname += nodes.Text(" ") + fieldname += nodes.Text(fieldarg) + + fieldbody = nodes.field_body("", nodes.literal("", "", *content)) + return nodes.field("", fieldname, fieldbody) + + +# Example: +# ```{lldbsetting} dwim-print-verbosity +# :type: "enum" +# +# The verbosity level used by dwim-print. +# +# :enum none: Use no verbosity when running dwim-print. +# :enum expression: Use partial verbosity when running dwim-print - display a message when `expression` evaluation is used. +# :enum full: Use full verbosity when running dwim-print. +# :default: none +# ``` +class LLDBSetting(ObjectDescription): + option_spec = { + "type": directives.unchanged, + } + doc_field_types = [ + LiteralField( + "default", + label="Default", + has_arg=False, + names=("default",), + ), + GroupedField("enum", label="Enumerations", names=("enum",)), + ] + + def handle_signature(self, sig: str, signode: addnodes.desc_signature): + typ = self.options.get("type", None) + + desc = addnodes.desc_name(text=sig) + desc += nodes.inline( + "", + typ, + classes=[ + "lldb-setting-type", + f"lldb-setting-type-{llvm_slug.make_slug(typ)}", + ], + ) + signode["ids"].append(sig) + signode += desc + + +def setup(app: Sphinx): + app.add_directive("lldbsetting", LLDBSetting) + + return { + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/lldb/docs/_scripts/gen-property-docs-from-json.py b/lldb/docs/_scripts/gen-property-docs-from-json.py new file mode 100644 index 0000000000000..fa034f6245c61 --- /dev/null +++ b/lldb/docs/_scripts/gen-property-docs-from-json.py @@ -0,0 +1,106 @@ +import argparse +from typing import TypedDict, Union, Optional, TextIO, NotRequired +from dataclasses import dataclass +import json + + +class Property(TypedDict): + name: str + type: str + default: NotRequired[str] + description: NotRequired[str] + + +class PropertyGroup(TypedDict): + path: str + """The full path to this group separated by dots""" + properties: list[Property] + + +@dataclass +class PropertyTree: + items: dict[str, Union["PropertyTree", Property]] + + +def append_group(tree: PropertyTree, group: PropertyGroup): + segments = group["path"].split(".") if group["path"] else [] + + subtree = tree + for segment in segments: + if segment not in subtree.items: + subtree.items[segment] = PropertyTree(items={}) + subtree = subtree.items[segment] + assert isinstance(subtree, PropertyTree) + + for property in group["properties"]: + subtree.items[property["name"]] = property + + +def print_property(f: TextIO, path: str, property: Property): + f.write(f"```{{lldbsetting}} {path}\n") + f.write(f":type: \"{property['type']}\"\n\n") + f.write(property.get("description", "").strip()) + f.write("\n\n") + if "default" in property and property["default"]: + f.write(f":default: {property['default']}\n") + # FIXME: add enumerations (":enum {name}: {description}") + f.write("```\n") + + +def print_tree(f: TextIO, level: int, prefix: str, name: str, tree: PropertyTree): + if level > 0: + f.write(f"{'#' * (level + 2)} {name}\n\n") + + leafs = sorted( + filter(lambda it: isinstance(it[1], dict), tree.items.items()), + key=lambda it: it[0], + ) + for key, prop in leafs: + assert isinstance(prop, dict) # only needed for typing + path = f"{prefix}.{key}" if prefix else key + print_property(f, path, prop) + + groups = sorted( + filter(lambda it: isinstance(it[1], PropertyTree), tree.items.items()), + key=lambda it: it[0], + ) + for key, subtree in groups: + assert isinstance(subtree, PropertyTree) # only needed for typing + prefix = f"{name}.{key}" if name else key + print_tree(f, level + 1, prefix, key, subtree) + + +HEADER = """ +# Settings + +This page lists all available settings in LLDB. +Settings can be set using `settings set <name> <value>`. +Values can be added to arrays and dictionaries with `settings append -- <name> <value>`. + +## Root +""" + + +def main(): + parser = argparse.ArgumentParser( + prog="gen-property-docs-from-json", + description="Generate Markdown from multiple property docs", + ) + parser.add_argument("-o", "--output", help="Path to output file") + parser.add_argument("inputs", nargs="*") + args = parser.parse_args() + + root = PropertyTree(items={}) + for input in args.inputs: + with open(input) as f: + groups: list[PropertyGroup] = json.load(f) + for group in groups: + append_group(root, group) + + with open(args.output, "w") as f: + f.write(HEADER) + print_tree(f, 0, "", "", root) + + +if __name__ == "__main__": + main() diff --git a/lldb/docs/_static/lldb-setting.css b/lldb/docs/_static/lldb-setting.css new file mode 100644 index 0000000000000..a0c5af557563a --- /dev/null +++ b/lldb/docs/_static/lldb-setting.css @@ -0,0 +1,86 @@ +/* + Terms use normal weight and upper case by default. + For settings, the term should be bold and use the original case. +*/ +dl[class]:not( + .option-list, + .field-list, + .footnote, + .glossary, + .simple + ).lldbsetting + .field-list + > dt { + text-transform: none; + font-weight: bold; +} + +.lldb-setting-type { + --setting-color: var(--light-color); + --background-opacity: 0.1; +} + +.lldb-setting-type { + float: right; + text-align: right; + text-indent: 0; + line-height: 1.4; + background-color: rgba(var(--setting-color), var(--background-opacity)); + padding: 0px 8px; + border-radius: 99999px; + border: rgba(var(--setting-color), 1) 1px solid; + font-size: 0.9em; + color: rgba(var(--setting-color), 1); +} + +body[data-theme="dark"] .lldb-setting-type { + --setting-color: var(--dark-color); + --background-opacity: 0.2; +} +@media (prefers-color-scheme: dark) { + body[data-theme="auto"] .lldb-setting-type { + --setting-color: var(--dark-color); + --background-opacity: 0.2; + } +} + +/* anything string-like (default) */ +.lldb-setting-type-string, +.lldb-setting-type /* fallback */ { + --dark-color: 255, 177, 38; + --light-color: 125, 98, 1; +} + +/* array-like */ +.lldb-setting-type-arguments, +.lldb-setting-type-array, +.lldb-setting-type-file-list { + --dark-color: 211, 131, 255; + --light-color: 64, 33, 242; +} + +/* map-like */ +.lldb-setting-type-dictionary, +.lldb-setting-type-path-map { + --dark-color: 243, 0, 255; + --light-color: 157, 0, 183; +} + +/* boolean */ +.lldb-setting-type-boolean { + --dark-color: 29, 180, 8; + --light-color: 0, 123, 33; +} + +/* numbers */ +.lldb-setting-type-int, +.lldb-setting-type-unsigned { + --dark-color: 80, 164, 198; + --light-color: 1, 108, 140; +} + +/* enum */ +.lldb-setting-type-enum { + --dark-color: 255, 87, 73; + --light-color: 191, 3, 10; +} diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py index 79cc37c8c4557..e5342be5fa283 100644 --- a/lldb/docs/conf.py +++ b/lldb/docs/conf.py @@ -12,6 +12,7 @@ # serve to show the default. import sys, os, re, shutil from datetime import date +from pathlib import Path # Add path for llvm_slug module. sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "llvm", "docs"))) @@ -41,9 +42,16 @@ # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' +sys.path.append(str(Path("_ext").resolve())) + # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["sphinx.ext.todo", "sphinx.ext.mathjax", "sphinx.ext.intersphinx"] +extensions = [ + "sphinx.ext.todo", + "sphinx.ext.mathjax", + "sphinx.ext.intersphinx", + "lldb_setting", +] # When building man pages, we do not use the markdown pages, # So, we can continue without the myst_parser dependencies. @@ -59,6 +67,7 @@ # Automatic anchors for markdown titles myst_heading_anchors = 6 myst_heading_slug_func = "llvm_slug.make_slug" +myst_enable_extensions = ["fieldlist"] autodoc_default_options = {"special-members": True} @@ -192,7 +201,10 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ["_static"] +html_static_path = ["_static"] +html_css_files = [ + "lldb-setting.css", +] html_extra_path = [".htaccess"] diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst index 10683c7593b01..e6b39e537baad 100644 --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -139,6 +139,7 @@ interesting areas to contribute to lldb. use/symbolfilejson use/lldbdap use/mcp + use/settings use/troubleshooting use/links Man Page <man/lldb> diff --git a/lldb/docs/use/.gitignore b/lldb/docs/use/.gitignore new file mode 100644 index 0000000000000..e9c6c7212fad2 --- /dev/null +++ b/lldb/docs/use/.gitignore @@ -0,0 +1,2 @@ +# autogenerated +/settings.md diff --git a/lldb/source/Core/CMakeLists.txt b/lldb/source/Core/CMakeLists.txt index df35bd5c025f3..269d647fb56fc 100644 --- a/lldb/source/Core/CMakeLists.txt +++ b/lldb/source/Core/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(CorePropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE CoreProperties.td TARGET LLDBCorePropertiesEnumGen) +lldb_tablegen(CoreProperties.json -gen-lldb-property-docs-json + SOURCE CoreProperties.td + TARGET LLDBCorePropertiesJsonGen) + set(LLDB_CURSES_LIBS) set(LLDB_LIBEDIT_LIBS) diff --git a/lldb/source/Interpreter/CMakeLists.txt b/lldb/source/Interpreter/CMakeLists.txt index 8af7373702c38..0caae7a0f1adc 100644 --- a/lldb/source/Interpreter/CMakeLists.txt +++ b/lldb/source/Interpreter/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(InterpreterPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE InterpreterProperties.td TARGET LLDBInterpreterPropertiesEnumGen) +lldb_tablegen(InterpreterProperties.json -gen-lldb-property-docs-json + SOURCE InterpreterProperties.td + TARGET LLDBInterpreterPropertiesJsonGen) + add_subdirectory(Interfaces) add_lldb_library(lldbInterpreter NO_PLUGIN_DEPENDENCIES diff --git a/lldb/source/Plugins/DynamicLoader/Darwin-Kernel/CMakeLists.txt b/lldb/source/Plugins/DynamicLoader/Darwin-Kernel/CMakeLists.txt index a22a83363ffea..b4ad53ee301c4 100644 --- a/lldb/source/Plugins/DynamicLoader/Darwin-Kernel/CMakeLists.txt +++ b/lldb/source/Plugins/DynamicLoader/Darwin-Kernel/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(DynamicLoaderDarwinKernelPropertiesEnum.inc -gen-lldb-property-enu SOURCE DynamicLoaderDarwinKernelProperties.td TARGET LLDBPluginDynamicLoaderDarwinKernelPropertiesEnumGen) +lldb_tablegen(DynamicLoaderDarwinKernelProperties.json -gen-lldb-property-docs-json + SOURCE DynamicLoaderDarwinKernelProperties.td + TARGET LLDBPluginDynamicLoaderDarwinKernelPropertiesJsonGen) + add_lldb_library(lldbPluginDynamicLoaderDarwinKernel PLUGIN DynamicLoaderDarwinKernel.cpp diff --git a/lldb/source/Plugins/JITLoader/GDB/CMakeLists.txt b/lldb/source/Plugins/JITLoader/GDB/CMakeLists.txt index b66be412a10dd..d7b3285bd53d2 100644 --- a/lldb/source/Plugins/JITLoader/GDB/CMakeLists.txt +++ b/lldb/source/Plugins/JITLoader/GDB/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(JITLoaderGDBPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE JITLoaderGDBProperties.td TARGET LLDBPluginJITLoaderGDBPropertiesEnumGen) +lldb_tablegen(JITLoaderGDBProperties.json -gen-lldb-property-docs-json + SOURCE JITLoaderGDBProperties.td + TARGET LLDBPluginJITLoaderGDBPropertiesJsonGen) + add_lldb_library(lldbPluginJITLoaderGDB PLUGIN JITLoaderGDB.cpp diff --git a/lldb/source/Plugins/Language/CPlusPlus/CMakeLists.txt b/lldb/source/Plugins/Language/CPlusPlus/CMakeLists.txt index 79c0cc14ec644..fc74d60f962c4 100644 --- a/lldb/source/Plugins/Language/CPlusPlus/CMakeLists.txt +++ b/lldb/source/Plugins/Language/CPlusPlus/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(LanguageCPlusPlusPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE LanguageCPlusPlusProperties.td TARGET LLDBPluginLanguageCPlusPlusPropertiesEnumGen) +lldb_tablegen(LanguageCPlusPlusProperties.json -gen-lldb-property-docs-json + SOURCE LanguageCPlusPlusProperties.td + TARGET LLDBPluginLanguageCPlusPlusPropertiesJsonGen) + add_lldb_library(lldbPluginCPlusPlusLanguage PLUGIN BlockPointer.cpp Coroutines.cpp diff --git a/lldb/source/Plugins/ObjectFile/PECOFF/CMakeLists.txt b/lldb/source/Plugins/ObjectFile/PECOFF/CMakeLists.txt index 97ba4032e2713..d982fa0a2c98a 100644 --- a/lldb/source/Plugins/ObjectFile/PECOFF/CMakeLists.txt +++ b/lldb/source/Plugins/ObjectFile/PECOFF/CMakeLists.txt @@ -13,6 +13,10 @@ lldb_tablegen(ObjectFilePECOFFPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE ObjectFilePECOFFProperties.td TARGET LLDBPluginObjectFilePECOFFPropertiesEnumGen) +lldb_tablegen(ObjectFilePECOFFProperties.json -gen-lldb-property-docs-json + SOURCE ObjectFilePECOFFProperties.td + TARGET LLDBPluginObjectFilePECOFFPropertiesJsonGen) + add_lldb_library(lldbPluginObjectFilePECOFF PLUGIN ObjectFilePECOFF.cpp PECallFrameInfo.cpp diff --git a/lldb/source/Plugins/Platform/Android/CMakeLists.txt b/lldb/source/Plugins/Platform/Android/CMakeLists.txt index 71108371daf09..a6b3f3b0a4849 100644 --- a/lldb/source/Plugins/Platform/Android/CMakeLists.txt +++ b/lldb/source/Plugins/Platform/Android/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(PlatformAndroidPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE PlatformAndroidProperties.td TARGET LLDBPluginPlatformAndroidPropertiesEnumGen) +lldb_tablegen(PlatformAndroidProperties.json -gen-lldb-property-docs-json + SOURCE PlatformAndroidProperties.td + TARGET LLDBPluginPlatformAndroidPropertiesJsonGen) + add_lldb_library(lldbPluginPlatformAndroid PLUGIN AdbClient.cpp PlatformAndroid.cpp diff --git a/lldb/source/Plugins/Platform/MacOSX/CMakeLists.txt b/lldb/source/Plugins/Platform/MacOSX/CMakeLists.txt index 598472430a9e8..044418620b270 100644 --- a/lldb/source/Plugins/Platform/MacOSX/CMakeLists.txt +++ b/lldb/source/Plugins/Platform/MacOSX/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(PlatformMacOSXPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE PlatformMacOSXProperties.td TARGET LLDBPluginPlatformMacOSXPropertiesEnumGen) +lldb_tablegen(PlatformMacOSXProperties.json -gen-lldb-property-docs-json + SOURCE PlatformMacOSXProperties.td + TARGET LLDBPluginPlatformMacOSXPropertiesJsonGen) + list(APPEND PLUGIN_PLATFORM_MACOSX_SOURCES PlatformDarwin.cpp PlatformDarwinDevice.cpp diff --git a/lldb/source/Plugins/Platform/QemuUser/CMakeLists.txt b/lldb/source/Plugins/Platform/QemuUser/CMakeLists.txt index dc3ff75079cc3..d9667fc72d19f 100644 --- a/lldb/source/Plugins/Platform/QemuUser/CMakeLists.txt +++ b/lldb/source/Plugins/Platform/QemuUser/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(PlatformQemuUserPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE PlatformQemuUserProperties.td TARGET LLDBPluginPlatformQemuUserPropertiesEnumGen) +lldb_tablegen(PlatformQemuUserProperties.json -gen-lldb-property-docs-json + SOURCE PlatformQemuUserProperties.td + TARGET LLDBPluginPlatformQemuUserPropertiesJsonGen) + add_lldb_library(lldbPluginPlatformQemuUser PLUGIN PlatformQemuUser.cpp diff --git a/lldb/source/Plugins/Platform/WebAssembly/CMakeLists.txt b/lldb/source/Plugins/Platform/WebAssembly/CMakeLists.txt index e049937dffd47..3220d44c3b143 100644 --- a/lldb/source/Plugins/Platform/WebAssembly/CMakeLists.txt +++ b/lldb/source/Plugins/Platform/WebAssembly/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(PlatformWasmPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE PlatformWasmProperties.td TARGET LLDBPluginPlatformWasmPropertiesEnumGen) +lldb_tablegen(PlatformWasmProperties.json -gen-lldb-property-docs-json + SOURCE PlatformWasmProperties.td + TARGET LLDBPluginPlatformWasmPropertiesJsonGen) + add_lldb_library(lldbPluginPlatformWasm PLUGIN PlatformWasm.cpp PlatformWasmRemoteGDBServer.cpp diff --git a/lldb/source/Plugins/Process/CMakeLists.txt b/lldb/source/Plugins/Process/CMakeLists.txt index 3413360e975fb..16ebb13054d4f 100644 --- a/lldb/source/Plugins/Process/CMakeLists.txt +++ b/lldb/source/Plugins/Process/CMakeLists.txt @@ -19,9 +19,9 @@ elseif (CMAKE_SYSTEM_NAME MATCHES "OpenBSD") add_subdirectory(POSIX) elseif (CMAKE_SYSTEM_NAME MATCHES "Windows") add_subdirectory(Windows/Common) -elseif (CMAKE_SYSTEM_NAME MATCHES "Darwin") - add_subdirectory(MacOSX-Kernel) endif() + +add_subdirectory(MacOSX-Kernel) add_subdirectory(scripted) add_subdirectory(gdb-remote) add_subdirectory(Utility) diff --git a/lldb/source/Plugins/Process/MacOSX-Kernel/CMakeLists.txt b/lldb/source/Plugins/Process/MacOSX-Kernel/CMakeLists.txt index f26e14f580cb7..16124a382a417 100644 --- a/lldb/source/Plugins/Process/MacOSX-Kernel/CMakeLists.txt +++ b/lldb/source/Plugins/Process/MacOSX-Kernel/CMakeLists.txt @@ -6,6 +6,14 @@ lldb_tablegen(ProcessKDPPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE ProcessKDPProperties.td TARGET LLDBPluginProcessMacOSXKernelPropertiesEnumGen) +lldb_tablegen(ProcessKDPProperties.json -gen-lldb-property-docs-json + SOURCE ProcessKDPProperties.td + TARGET LLDBPluginProcessMacOSXKernelPropertiesJsonGen) + +if (NOT CMAKE_SYSTEM_NAME MATCHES "Darwin") + return() +endif() + add_lldb_library(lldbPluginProcessMacOSXKernel PLUGIN CommunicationKDP.cpp ProcessKDP.cpp diff --git a/lldb/source/Plugins/Process/gdb-remote/CMakeLists.txt b/lldb/source/Plugins/Process/gdb-remote/CMakeLists.txt index 5c39384fa31b9..6bd93028e1802 100644 --- a/lldb/source/Plugins/Process/gdb-remote/CMakeLists.txt +++ b/lldb/source/Plugins/Process/gdb-remote/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(ProcessGDBRemotePropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE ProcessGDBRemoteProperties.td TARGET LLDBPluginProcessGDBRemotePropertiesEnumGen) +lldb_tablegen(ProcessGDBRemoteProperties.json -gen-lldb-property-docs-json + SOURCE ProcessGDBRemoteProperties.td + TARGET LLDBPluginProcessGDBRemotePropertiesJsonGen) + set(LLDB_PLUGINS lldbPluginProcessUtility ) diff --git a/lldb/source/Plugins/StructuredData/DarwinLog/CMakeLists.txt b/lldb/source/Plugins/StructuredData/DarwinLog/CMakeLists.txt index 7d1d03fe908fa..7830e53eecfb0 100644 --- a/lldb/source/Plugins/StructuredData/DarwinLog/CMakeLists.txt +++ b/lldb/source/Plugins/StructuredData/DarwinLog/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(StructuredDataDarwinLogPropertiesEnum.inc -gen-lldb-property-enum- SOURCE StructuredDataDarwinLogProperties.td TARGET LLDBPluginStructuredDataDarwinLogPropertiesEnumGen) +lldb_tablegen(StructuredDataDarwinLogProperties.json -gen-lldb-property-docs-json + SOURCE StructuredDataDarwinLogProperties.td + TARGET LLDBPluginStructuredDataDarwinLogPropertiesJsonGen) + add_lldb_library(lldbPluginStructuredDataDarwinLog PLUGIN StructuredDataDarwinLog.cpp diff --git a/lldb/source/Plugins/SymbolFile/DWARF/CMakeLists.txt b/lldb/source/Plugins/SymbolFile/DWARF/CMakeLists.txt index c3f1bb55e03be..910bf92320916 100644 --- a/lldb/source/Plugins/SymbolFile/DWARF/CMakeLists.txt +++ b/lldb/source/Plugins/SymbolFile/DWARF/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(SymbolFileDWARFPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE SymbolFileDWARFProperties.td TARGET LLDBPluginSymbolFileDWARFPropertiesEnumGen) +lldb_tablegen(SymbolFileDWARFProperties.json -gen-lldb-property-docs-json + SOURCE SymbolFileDWARFProperties.td + TARGET LLDBPluginSymbolFileDWARFPropertiesJsonGen) + add_lldb_library(lldbPluginSymbolFileDWARF PLUGIN AppleDWARFIndex.cpp DebugNamesDWARFIndex.cpp diff --git a/lldb/source/Plugins/SymbolFile/PDB/CMakeLists.txt b/lldb/source/Plugins/SymbolFile/PDB/CMakeLists.txt index c1cc3cd13a96f..310a300b7da90 100644 --- a/lldb/source/Plugins/SymbolFile/PDB/CMakeLists.txt +++ b/lldb/source/Plugins/SymbolFile/PDB/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(SymbolFilePDBPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE SymbolFilePDBProperties.td TARGET LLDBPluginSymbolFilePDBPropertiesEnumGen) +lldb_tablegen(SymbolFilePDBProperties.json -gen-lldb-property-docs-json + SOURCE SymbolFilePDBProperties.td + TARGET LLDBPluginSymbolFilePDBPropertiesJsonGen) + add_lldb_library(lldbPluginSymbolFilePDB PLUGIN PDBASTParser.cpp PDBLocationToDWARFExpression.cpp diff --git a/lldb/source/Plugins/SymbolLocator/Debuginfod/CMakeLists.txt b/lldb/source/Plugins/SymbolLocator/Debuginfod/CMakeLists.txt index f07e93e131376..4f7b9095c1f09 100644 --- a/lldb/source/Plugins/SymbolLocator/Debuginfod/CMakeLists.txt +++ b/lldb/source/Plugins/SymbolLocator/Debuginfod/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(SymbolLocatorDebuginfodPropertiesEnum.inc -gen-lldb-property-enum- SOURCE SymbolLocatorDebuginfodProperties.td TARGET LLDBPluginSymbolLocatorDebuginfodPropertiesEnumGen) +lldb_tablegen(SymbolLocatorDebuginfodProperties.json -gen-lldb-property-docs-json + SOURCE SymbolLocatorDebuginfodProperties.td + TARGET LLDBPluginSymbolLocatorDebuginfodPropertiesJsonGen) + add_lldb_library(lldbPluginSymbolLocatorDebuginfod PLUGIN SymbolLocatorDebuginfod.cpp diff --git a/lldb/source/Plugins/Trace/CMakeLists.txt b/lldb/source/Plugins/Trace/CMakeLists.txt index 331b48f95f1a4..122674e02e246 100644 --- a/lldb/source/Plugins/Trace/CMakeLists.txt +++ b/lldb/source/Plugins/Trace/CMakeLists.txt @@ -3,7 +3,4 @@ set_property(DIRECTORY PROPERTY LLDB_PLUGIN_KIND Trace) option(LLDB_BUILD_INTEL_PT "Enable Building of Intel(R) Processor Trace Tool" OFF) add_subdirectory(common) - -if (LLDB_BUILD_INTEL_PT) - add_subdirectory(intel-pt) -endif() +add_subdirectory(intel-pt) diff --git a/lldb/source/Plugins/Trace/intel-pt/CMakeLists.txt b/lldb/source/Plugins/Trace/intel-pt/CMakeLists.txt index ddb2f384d1848..8a92aa6441087 100644 --- a/lldb/source/Plugins/Trace/intel-pt/CMakeLists.txt +++ b/lldb/source/Plugins/Trace/intel-pt/CMakeLists.txt @@ -1,14 +1,3 @@ -if (NOT LIBIPT_INCLUDE_PATH) - message (FATAL_ERROR "libipt include path not provided") -endif() - -if (NOT EXISTS "${LIBIPT_INCLUDE_PATH}") - message (FATAL_ERROR "invalid libipt include path provided") -endif() -include_directories(${LIBIPT_INCLUDE_PATH}) - -find_library(LIBIPT_LIBRARY ipt PATHS ${LIBIPT_LIBRARY_PATH} REQUIRED) - lldb_tablegen(TraceIntelPTCommandOptions.inc -gen-lldb-option-defs SOURCE TraceIntelPTOptions.td TARGET TraceIntelPTOptionsGen) @@ -21,6 +10,25 @@ lldb_tablegen(TraceIntelPTPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE TraceIntelPTProperties.td TARGET TraceIntelPTPropertiesEnumGen) +lldb_tablegen(TraceIntelPTProperties.json -gen-lldb-property-docs-json + SOURCE TraceIntelPTProperties.td + TARGET TraceIntelPTPropertiesJsonGen) + +if (NOT LLDB_BUILD_INTEL_PT) + return() +endif() + +if (NOT LIBIPT_INCLUDE_PATH) + message (FATAL_ERROR "libipt include path not provided") +endif() + +if (NOT EXISTS "${LIBIPT_INCLUDE_PATH}") + message (FATAL_ERROR "invalid libipt include path provided") +endif() +include_directories(${LIBIPT_INCLUDE_PATH}) + +find_library(LIBIPT_LIBRARY ipt PATHS ${LIBIPT_LIBRARY_PATH} REQUIRED) + add_lldb_library(lldbPluginTraceIntelPT PLUGIN CommandObjectTraceStartIntelPT.cpp DecodedThread.cpp diff --git a/lldb/source/Target/CMakeLists.txt b/lldb/source/Target/CMakeLists.txt index df2ee03860ac0..d1e7a521f99dc 100644 --- a/lldb/source/Target/CMakeLists.txt +++ b/lldb/source/Target/CMakeLists.txt @@ -6,6 +6,10 @@ lldb_tablegen(TargetPropertiesEnum.inc -gen-lldb-property-enum-defs SOURCE TargetProperties.td TARGET LLDBTargetPropertiesEnumGen) +lldb_tablegen(TargetProperties.json -gen-lldb-property-docs-json + SOURCE TargetProperties.td + TARGET LLDBTargetPropertiesJsonGen) + # TODO: Add property `NO_PLUGIN_DEPENDENCIES` to lldbTarget add_lldb_library(lldbTarget ABI.cpp diff --git a/lldb/utils/TableGen/CMakeLists.txt b/lldb/utils/TableGen/CMakeLists.txt index ce96dddd44201..7dd941baf2d2f 100644 --- a/lldb/utils/TableGen/CMakeLists.txt +++ b/lldb/utils/TableGen/CMakeLists.txt @@ -11,6 +11,7 @@ if (NOT DEFINED LLDB_TABLEGEN_EXE) DESTINATION "${CMAKE_INSTALL_BINDIR}" LLDBOptionDefEmitter.cpp LLDBPropertyDefEmitter.cpp + LLDBPropertyDocsEmitter.cpp LLDBTableGen.cpp LLDBTableGenUtils.cpp ) diff --git a/lldb/utils/TableGen/LLDBPropertyDocsEmitter.cpp b/lldb/utils/TableGen/LLDBPropertyDocsEmitter.cpp new file mode 100644 index 0000000000000..75cde9f6ec94b --- /dev/null +++ b/lldb/utils/TableGen/LLDBPropertyDocsEmitter.cpp @@ -0,0 +1,73 @@ +//===----------------------------------------------------------------------===// +// +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +//===----------------------------------------------------------------------===// +// +// This tablegen backend emits JSON describing each property grouped by path. +// +//===----------------------------------------------------------------------===// + +#include "LLDBTableGenBackends.h" +#include "LLDBTableGenUtils.h" +#include "llvm/Support/JSON.h" +#include "llvm/TableGen/Record.h" +#include <vector> + +using namespace llvm; +using namespace lldb_private; + +static void emitProperty(const Record *Property, json::OStream &OS) { + OS.attribute("name", Property->getValueAsString("Name")); + OS.attribute("type", Property->getValueAsString("Type")); + + bool hasDefaultUnsignedValue = Property->getValue("HasDefaultUnsignedValue"); + bool hasDefaultBooleanValue = Property->getValue("HasDefaultBooleanValue"); + bool hasDefaultStringValue = Property->getValue("HasDefaultStringValue"); + + // Emit the default uint value. + if (hasDefaultBooleanValue) { + assert(hasDefaultUnsignedValue); + bool value = Property->getValueAsInt("DefaultUnsignedValue") != 0; + OS.attribute("default", value ? "true" : "false"); + } else if (hasDefaultUnsignedValue) { + OS.attribute("default", std::to_string(Property->getValueAsInt( + "DefaultUnsignedValue"))); + } else if (hasDefaultStringValue) { + if (auto *D = Property->getValue("DefaultStringValue")) + OS.attribute("default", D->getValue()->getAsUnquotedString()); + } + + // FIXME: Get enum values. This requires the enum values to be declared in + // tablegen as well. + + if (auto *D = Property->getValue("Description")) + OS.attribute("description", D->getValue()->getAsUnquotedString()); +} + +/// Emits all property initializers to the raw_ostream. +static void emityProperties(const std::vector<const Record *> &PropertyRecords, + json::OStream &OS) { + + for (const Record *R : PropertyRecords) + OS.object([&] { emitProperty(R, OS); }); +} + +void lldb_private::EmitPropertyDocsJson(const RecordKeeper &Records, + raw_ostream &OS) { + json::OStream JsonOS(OS); + JsonOS.array([&] { + ArrayRef<const Record *> Properties = + Records.getAllDerivedDefinitions("Property"); + for (auto &Rec : getRecordsByName(Properties, "Path")) { + JsonOS.object([&] { + JsonOS.attribute("path", Rec.first); + JsonOS.attributeBegin("properties"); + JsonOS.array([&] { emityProperties(Rec.second, JsonOS); }); + JsonOS.attributeEnd(); // properties + }); + } + }); +} diff --git a/lldb/utils/TableGen/LLDBTableGen.cpp b/lldb/utils/TableGen/LLDBTableGen.cpp index 0c06c93fbdc3d..5fcb2038ba1cb 100644 --- a/lldb/utils/TableGen/LLDBTableGen.cpp +++ b/lldb/utils/TableGen/LLDBTableGen.cpp @@ -28,6 +28,7 @@ enum ActionType { GenOptionDefs, GenPropertyDefs, GenPropertyEnumDefs, + GenPropertyDocsJson, }; static cl::opt<ActionType> Action( @@ -41,7 +42,9 @@ static cl::opt<ActionType> Action( clEnumValN(GenPropertyDefs, "gen-lldb-property-defs", "Generate lldb property definitions"), clEnumValN(GenPropertyEnumDefs, "gen-lldb-property-enum-defs", - "Generate lldb property enum definitions"))); + "Generate lldb property enum definitions"), + clEnumValN(GenPropertyDocsJson, "gen-lldb-property-docs-json", + "Generate lldb property documentation"))); static bool LLDBTableGenMain(raw_ostream &OS, const RecordKeeper &Records) { switch (Action) { @@ -60,6 +63,9 @@ static bool LLDBTableGenMain(raw_ostream &OS, const RecordKeeper &Records) { case GenPropertyEnumDefs: EmitPropertyEnumDefs(Records, OS); break; + case GenPropertyDocsJson: + EmitPropertyDocsJson(Records, OS); + break; } return false; } diff --git a/lldb/utils/TableGen/LLDBTableGenBackends.h b/lldb/utils/TableGen/LLDBTableGenBackends.h index a51b7bf7b60d0..d3a51559b29ae 100644 --- a/lldb/utils/TableGen/LLDBTableGenBackends.h +++ b/lldb/utils/TableGen/LLDBTableGenBackends.h @@ -32,6 +32,7 @@ namespace lldb_private { void EmitOptionDefs(const RecordKeeper &RK, raw_ostream &OS); void EmitPropertyDefs(const RecordKeeper &RK, raw_ostream &OS); void EmitPropertyEnumDefs(const RecordKeeper &RK, raw_ostream &OS); +void EmitPropertyDocsJson(const RecordKeeper &RK, raw_ostream &OS); int EmitSBAPIDWARFEnum(int argc, char **argv); } // namespace lldb_private _______________________________________________ lldb-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
