llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clangir @llvm/pr-subscribers-clang Author: Sirui Mu (Lancern) <details> <summary>Changes</summary> 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](https://github.com/llvm/clangir) 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. --- Full diff: https://github.com/llvm/llvm-project/pull/190354.diff 11 Files Affected: - (renamed) clang/docs/CIR/ClangIRABILowering.md () - (renamed) clang/docs/CIR/ClangIRCleanupAndEHDesign.md () - (renamed) clang/docs/CIR/ClangIRCodeDuplication.rst () - (added) clang/docs/CIR/_raw/CIRLangRef_Template.md (+24) - (added) clang/docs/CIR/_raw/CreateCIRLangRef.py (+38) - (added) clang/docs/CIR/index.rst (+32) - (modified) clang/docs/CMakeLists.txt (+16) - (modified) clang/docs/conf.py (+3-1) - (modified) clang/docs/index.rst (+1-3) - (modified) clang/include/clang/CIR/Dialect/CMakeLists.txt (+22) - (modified) clang/include/clang/CIR/Dialect/IR/CMakeLists.txt (+5) ``````````diff diff --git a/clang/docs/ClangIRABILowering.md b/clang/docs/CIR/ClangIRABILowering.md similarity index 100% rename from clang/docs/ClangIRABILowering.md rename to clang/docs/CIR/ClangIRABILowering.md diff --git a/clang/docs/ClangIRCleanupAndEHDesign.md b/clang/docs/CIR/ClangIRCleanupAndEHDesign.md similarity index 100% rename from clang/docs/ClangIRCleanupAndEHDesign.md rename to clang/docs/CIR/ClangIRCleanupAndEHDesign.md diff --git a/clang/docs/ClangIRCodeDuplication.rst b/clang/docs/CIR/ClangIRCodeDuplication.rst similarity index 100% rename from clang/docs/ClangIRCodeDuplication.rst rename to clang/docs/CIR/ClangIRCodeDuplication.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..60e60e0af6929 --- /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 + +@@CIRAttributes@@ + +## Passes + +@@CIRPasses@@ diff --git a/clang/docs/CIR/_raw/CreateCIRLangRef.py b/clang/docs/CIR/_raw/CreateCIRLangRef.py new file mode 100644 index 0000000000000..ca13c947e23dd --- /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..de9b2812f1a75 --- /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 + + ClangIRCodeDuplication + ClangIRABILowering + ClangIRCleanupAndEHDesign + +ClangIR Language Reference +========================== + +.. toctree:: + :numbered: + :maxdepth: 1 + + CIRLangRef diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt index e69d4750aeb4c..774c8071f0458 100644 --- a/clang/docs/CMakeLists.txt +++ b/clang/docs/CMakeLists.txt @@ -112,6 +112,22 @@ if (LLVM_ENABLE_SPHINX) "${CMAKE_CURRENT_BINARY_DIR}" ) + set(generated_cir_pages ${CMAKE_CURRENT_BINARY_DIR}/CIR/index.rst) + if (CLANG_ENABLE_CIR) + list(APPEND generated_cir_pages + ${CMAKE_CURRENT_BINARY_DIR}/CIR/Dialect/attrs.md + ${CMAKE_CURRENT_BINARY_DIR}/CIR/Dialect/ops.md + ${CMAKE_CURRENT_BINARY_DIR}/CIR/Dialect/types.md + ${CMAKE_CURRENT_BINARY_DIR}/CIR/passes.md + ) + add_dependencies(copy-clang-rst-docs clang-cir-doc) + endif() + 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 + ) + 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) `````````` </details> https://github.com/llvm/llvm-project/pull/190354 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
