https://github.com/Lancern updated https://github.com/llvm/llvm-project/pull/190354
>From d9ea8aab3e1e64bfdde759c45c720fc67bff5385 Mon Sep 17 00:00:00 2001 From: Sirui Mu <[email protected]> Date: Fri, 3 Apr 2026 23:27:56 +0800 Subject: [PATCH] [clang][doc] Add auto-generated ClangIR documentation ClangIR has a collection of documentation pages that we want to upstream as part of the main clang documentation. These pages are originally available at https://clangir.org/, maintained in the incubator repository which has been archived a few months ago. This patch makes a first step towards the upstreaming of ClangIR documentation. The pages included in this patch are those automatically generated from MLIR TableGen. Specifically, this patch mades the following changes to the main clang documentation tree: - It adds a new subdirectory `CIR` under `clang/docs` to hold all ClangIR documentation. There are already 3 ClangIR design documents put under `clang/docs`, and I moved all of them to this new subdirectory. - It touches the necessary CMake files and Python scripts to: - Generate ClangIR language reference automatically from MLIR TableGen when building the clang documentation with `CLANG_ENABLE_CIR=ON`. - Incorporate these automatically generated documents (if any) into the main clang documentation build tree. --- .../ABILowering.md} | 0 .../CleanupAndEHDesign.md} | 0 .../CodeDuplication.rst} | 0 clang/docs/CIR/_raw/CIRLangRef_Template.md | 24 ++++++++++++ clang/docs/CIR/_raw/CreateCIRLangRef.py | 38 +++++++++++++++++++ clang/docs/CIR/index.rst | 32 ++++++++++++++++ clang/docs/CMakeLists.txt | 9 +++++ clang/docs/conf.py | 4 +- clang/docs/index.rst | 4 +- .../include/clang/CIR/Dialect/CMakeLists.txt | 22 +++++++++++ .../clang/CIR/Dialect/IR/CMakeLists.txt | 5 +++ 11 files changed, 134 insertions(+), 4 deletions(-) rename clang/docs/{ClangIRABILowering.md => CIR/ABILowering.md} (100%) rename clang/docs/{ClangIRCleanupAndEHDesign.md => CIR/CleanupAndEHDesign.md} (100%) rename clang/docs/{ClangIRCodeDuplication.rst => CIR/CodeDuplication.rst} (100%) create mode 100644 clang/docs/CIR/_raw/CIRLangRef_Template.md create mode 100644 clang/docs/CIR/_raw/CreateCIRLangRef.py create mode 100644 clang/docs/CIR/index.rst diff --git a/clang/docs/ClangIRABILowering.md b/clang/docs/CIR/ABILowering.md similarity index 100% rename from clang/docs/ClangIRABILowering.md rename to clang/docs/CIR/ABILowering.md diff --git a/clang/docs/ClangIRCleanupAndEHDesign.md b/clang/docs/CIR/CleanupAndEHDesign.md similarity index 100% rename from clang/docs/ClangIRCleanupAndEHDesign.md rename to clang/docs/CIR/CleanupAndEHDesign.md diff --git a/clang/docs/ClangIRCodeDuplication.rst b/clang/docs/CIR/CodeDuplication.rst similarity index 100% rename from clang/docs/ClangIRCodeDuplication.rst rename to clang/docs/CIR/CodeDuplication.rst diff --git a/clang/docs/CIR/_raw/CIRLangRef_Template.md b/clang/docs/CIR/_raw/CIRLangRef_Template.md new file mode 100644 index 0000000000000..224c933e90916 --- /dev/null +++ b/clang/docs/CIR/_raw/CIRLangRef_Template.md @@ -0,0 +1,24 @@ +# ClangIR Language Reference + +```{contents} +--- +local: +depth: 2 +--- +``` + +## Operations + +@@CIROps@@ + +## Types + +@@CIRTypes@@ + +## Attributes + +@@CIRAttrs@@ + +## Passes + +@@CIRPasses@@ diff --git a/clang/docs/CIR/_raw/CreateCIRLangRef.py b/clang/docs/CIR/_raw/CreateCIRLangRef.py new file mode 100644 index 0000000000000..47b1abb7189c9 --- /dev/null +++ b/clang/docs/CIR/_raw/CreateCIRLangRef.py @@ -0,0 +1,38 @@ +# This script embeds MLIR generated documentations (in Markdown format) into +# CIRLangRef_Template.md to generate CIRLangRef.md + +import os + + +def load_mlir_doc(name, path): + global docs_catalog + + if not os.path.exists(path): + docs_catalog[name] = "(not generated)" + return + + with open(path, encoding="utf-8") as doc: + docs_catalog[name] = doc.read() + + +# Note that the working directory of this script will be clang/docs under the +# build directory. All paths are relative to that directory. +TEMPLATE_PATH = os.path.join("CIR", "_raw", "CIRLangRef_Template.md") +OUTPUT_PATH = os.path.join("CIR", "CIRLangRef.md") + +with open(TEMPLATE_PATH, encoding="utf-8") as template: + output_doc = template.read() + +docs_catalog = {} +load_mlir_doc("CIRAttrs", os.path.join("CIR", "_raw", "Dialect", "CIRAttrs.md")) +load_mlir_doc("CIROps", os.path.join("CIR", "_raw", "Dialect", "CIROps.md")) +load_mlir_doc("CIRTypes", os.path.join("CIR", "_raw", "Dialect", "CIRTypes.md")) +load_mlir_doc("CIRPasses", os.path.join("CIR", "_raw", "CIRPasses.md")) + +output_doc = output_doc.replace("@@CIRAttrs@@", docs_catalog["CIRAttrs"]) +output_doc = output_doc.replace("@@CIROps@@", docs_catalog["CIROps"]) +output_doc = output_doc.replace("@@CIRTypes@@", docs_catalog["CIRTypes"]) +output_doc = output_doc.replace("@@CIRPasses@@", docs_catalog["CIRPasses"]) + +with open(OUTPUT_PATH, "w", encoding="utf-8") as output: + output.write(output_doc) diff --git a/clang/docs/CIR/index.rst b/clang/docs/CIR/index.rst new file mode 100644 index 0000000000000..f3cdf47ab9a33 --- /dev/null +++ b/clang/docs/CIR/index.rst @@ -0,0 +1,32 @@ +======= +ClangIR +======= + +.. warning:: + The project of upstreaming ClangIR support from the incubator repository is + still in progress, and ClangIR is not included in a default clang build. The + documentation may be incomplete and out-of-date. + +ClangIR is a high-level representation in Clang that reflects aspects of the +C/C++ languages and their extensions. It is implemented using MLIR and occupies +a position between Clang's AST and LLVM IR. + +ClangIR Design Documents +======================== + +.. toctree:: + :numbered: + :maxdepth: 1 + + ABILowering + CleanupAndEHDesign + CodeDuplication + +ClangIR Language Reference +========================== + +.. toctree:: + :numbered: + :maxdepth: 1 + + CIRLangRef diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt index e69d4750aeb4c..9530e121fa996 100644 --- a/clang/docs/CMakeLists.txt +++ b/clang/docs/CMakeLists.txt @@ -112,6 +112,15 @@ if (LLVM_ENABLE_SPHINX) "${CMAKE_CURRENT_BINARY_DIR}" ) + add_custom_command(TARGET copy-clang-rst-docs POST_BUILD + COMMAND "${Python3_EXECUTABLE}" + ARGS "${CMAKE_CURRENT_BINARY_DIR}/CIR/_raw/CreateCIRLangRef.py" + BYPRODUCTS ${CMAKE_CURRENT_BINARY_DIR}/CIR/CIRLangRef.md + ) + if (CLANG_ENABLE_CIR) + add_dependencies(copy-clang-rst-docs clang-cir-doc) + endif() + set(docs_targets "") if (${SPHINX_OUTPUT_HTML}) diff --git a/clang/docs/conf.py b/clang/docs/conf.py index 4cee382a718fa..f0e3b151c9736 100644 --- a/clang/docs/conf.py +++ b/clang/docs/conf.py @@ -69,7 +69,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ["_build"] +exclude_patterns = ["_build", "CIR/_raw/*"] # The reST default role (used for this markup: `text`) to use for all documents. # default_role = None @@ -94,6 +94,8 @@ .. |ReleaseNotesTitle| replace:: {in_progress_title} Release Notes """ +suppress_warnings = ["misc.highlighting_failure"] + # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/clang/docs/index.rst b/clang/docs/index.rst index 89ca6d73d9d8d..898667e36011d 100644 --- a/clang/docs/index.rst +++ b/clang/docs/index.rst @@ -69,6 +69,7 @@ Using Clang as a Compiler DebuggingCoroutines AMDGPUSupport CXXTypeAwareAllocators + CIR/index CommandGuide/index FAQ @@ -127,9 +128,6 @@ Design Documents HardwareAssistedAddressSanitizerDesign.rst ConstantInterpreter LLVMExceptionHandlingCodeGen - ClangIRCodeDuplication - ClangIRABILowering - ClangIRCleanupAndEHDesign Indices and tables ================== diff --git a/clang/include/clang/CIR/Dialect/CMakeLists.txt b/clang/include/clang/CIR/Dialect/CMakeLists.txt index 3d4e6586e1c62..0b80e49984c05 100644 --- a/clang/include/clang/CIR/Dialect/CMakeLists.txt +++ b/clang/include/clang/CIR/Dialect/CMakeLists.txt @@ -1,3 +1,23 @@ +add_custom_target(clang-cir-doc) + +# This replicates part of the add_mlir_doc cmake function from MLIR that cannot +# be used here. This happens because it expects to be run inside MLIR directory +# which is not the case for CIR (and also FIR, both have similar workarounds). +function(add_clang_mlir_doc doc_filename output_file output_directory command) + set(LLVM_TARGET_DEFINITIONS ${doc_filename}.td) + tablegen(MLIR ${output_file}.md ${command} ${ARGN} + "-I${MLIR_MAIN_SRC_DIR}" "-I${MLIR_INCLUDE_DIR}") + set(GEN_DOC_FILE ${CLANG_BINARY_DIR}/docs/CIR/_raw/${output_directory}${output_file}.md) + add_custom_command( + OUTPUT ${GEN_DOC_FILE} + COMMAND ${CMAKE_COMMAND} -E copy + ${CMAKE_CURRENT_BINARY_DIR}/${output_file}.md + ${GEN_DOC_FILE} + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${output_file}.md) + add_custom_target(${output_file}DocGen DEPENDS ${GEN_DOC_FILE}) + add_dependencies(clang-cir-doc ${output_file}DocGen) +endfunction() + add_subdirectory(IR) set(LLVM_TARGET_DEFINITIONS Passes.td) @@ -5,3 +25,5 @@ mlir_tablegen(Passes.h.inc -gen-pass-decls -name CIR) mlir_tablegen(Passes.capi.h.inc -gen-pass-capi-header --prefix CIR) mlir_tablegen(Passes.capi.cpp.inc -gen-pass-capi-impl --prefix CIR) add_public_tablegen_target(MLIRCIRPassIncGen) + +add_clang_mlir_doc(Passes CIRPasses ./ -gen-pass-doc) diff --git a/clang/include/clang/CIR/Dialect/IR/CMakeLists.txt b/clang/include/clang/CIR/Dialect/IR/CMakeLists.txt index 870f9e3f5d052..a2618a48b7003 100644 --- a/clang/include/clang/CIR/Dialect/IR/CMakeLists.txt +++ b/clang/include/clang/CIR/Dialect/IR/CMakeLists.txt @@ -14,6 +14,11 @@ mlir_tablegen(CIROpsDialect.cpp.inc -gen-dialect-defs) add_public_tablegen_target(MLIRCIROpsIncGen) add_dependencies(mlir-headers MLIRCIROpsIncGen) +# Equivalent to add_mlir_doc +add_clang_mlir_doc(CIROps CIROps Dialect/ -gen-op-doc) +add_clang_mlir_doc(CIRAttrs CIRAttrs Dialect/ -gen-attrdef-doc) +add_clang_mlir_doc(CIRTypes CIRTypes Dialect/ -gen-typedef-doc) + mlir_tablegen(CIROpsEnums.h.inc -gen-enum-decls) mlir_tablegen(CIROpsEnums.cpp.inc -gen-enum-defs) mlir_tablegen(CIROpsAttributes.h.inc -gen-attrdef-decls) _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
