https://github.com/ilovepi updated
https://github.com/llvm/llvm-project/pull/138062
>From 3d870717fdc1a35f3fc28e7fa74b763362f98c19 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Wed, 30 Apr 2025 08:10:20 -0700
Subject: [PATCH] [clang-doc] Add helpers for Template config
This patch adds or fills in some helper functions related to template
setup when initializing the mustache backend. It was split from #133161.
Co-authored-by: Peter Chou <peter.c...@mail.utoronto.ca>
---
.../clang-doc/HTMLMustacheGenerator.cpp | 45 ++++++++++++++
.../clang-doc/support/CMakeLists.txt | 4 +-
clang-tools-extra/clang-doc/support/Utils.cpp | 61 +++++++++++++++++++
clang-tools-extra/clang-doc/support/Utils.h | 26 ++++++++
.../unittests/clang-doc/CMakeLists.txt | 12 ++++
.../clang-doc/HTMLMustacheGeneratorTest.cpp | 11 +++-
.../unittests/clang-doc/config.h.cmake | 6 ++
7 files changed, 162 insertions(+), 3 deletions(-)
create mode 100644 clang-tools-extra/clang-doc/support/Utils.cpp
create mode 100644 clang-tools-extra/clang-doc/support/Utils.h
create mode 100644 clang-tools-extra/unittests/clang-doc/config.h.cmake
diff --git a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
index 366deb55b77b9..f7e53fc64196a 100644
--- a/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLMustacheGenerator.cpp
@@ -18,6 +18,7 @@
#include "llvm/Support/Error.h"
#include "llvm/Support/MemoryBuffer.h"
#include "llvm/Support/Mustache.h"
+#include "llvm/Support/Path.h"
using namespace llvm;
using namespace llvm::json;
@@ -74,7 +75,51 @@ static std::unique_ptr<MustacheTemplateFile>
NamespaceTemplate = nullptr;
static std::unique_ptr<MustacheTemplateFile> RecordTemplate = nullptr;
+static Error
+setupTemplate(std::unique_ptr<MustacheTemplateFile> &Template,
+ StringRef TemplatePath,
+ std::vector<std::pair<StringRef, StringRef>> Partials) {
+ auto T = MustacheTemplateFile::createMustacheFile(TemplatePath);
+ if (Error Err = T.takeError())
+ return Err;
+ Template = std::move(T.get());
+ for (const auto [Name, FileName] : Partials) {
+ if (auto Err = Template->registerPartialFile(Name, FileName))
+ return Err;
+ }
+ return Error::success();
+}
+
static Error setupTemplateFiles(const clang::doc::ClangDocContext &CDCtx) {
+ // Template files need to use the native path when they're opened,
+ // but have to be used in Posix style when used in HTML.
+ auto ConvertToNative = [](std::string &&Path) -> std::string {
+ SmallString<128> PathBuf(Path);
+ llvm::sys::path::native(PathBuf);
+ return PathBuf.str().str();
+ };
+
+ std::string NamespaceFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("namespace-template"));
+ std::string ClassFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("class-template"));
+ std::string CommentFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("comments-template"));
+ std::string FunctionFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("function-template"));
+ std::string EnumFilePath =
+ ConvertToNative(CDCtx.MustacheTemplates.lookup("enum-template"));
+ std::vector<std::pair<StringRef, StringRef>> Partials = {
+ {"Comments", CommentFilePath},
+ {"FunctionPartial", FunctionFilePath},
+ {"EnumPartial", EnumFilePath}};
+
+ if (Error Err = setupTemplate(NamespaceTemplate, NamespaceFilePath,
Partials))
+ return Err;
+
+ if (Error Err = setupTemplate(RecordTemplate, ClassFilePath, Partials))
+ return Err;
+
return Error::success();
}
diff --git a/clang-tools-extra/clang-doc/support/CMakeLists.txt
b/clang-tools-extra/clang-doc/support/CMakeLists.txt
index a4f7993d5c9d8..f470a613b95d9 100644
--- a/clang-tools-extra/clang-doc/support/CMakeLists.txt
+++ b/clang-tools-extra/clang-doc/support/CMakeLists.txt
@@ -6,4 +6,6 @@ set(LLVM_LINK_COMPONENTS
add_clang_library(clangDocSupport STATIC
File.cpp
- )
\ No newline at end of file
+ Utils.cpp
+ )
+
diff --git a/clang-tools-extra/clang-doc/support/Utils.cpp
b/clang-tools-extra/clang-doc/support/Utils.cpp
new file mode 100644
index 0000000000000..f1d193379afa6
--- /dev/null
+++ b/clang-tools-extra/clang-doc/support/Utils.cpp
@@ -0,0 +1,61 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "Utils.h"
+#include "llvm/ADT/SmallString.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/FileSystem.h"
+#include "llvm/Support/Path.h"
+
+using namespace llvm;
+
+SmallString<128> appendPathNative(StringRef Base, StringRef Path) {
+ SmallString<128> Default;
+ sys::path::native(Base, Default);
+ sys::path::append(Default, Path);
+ return Default;
+}
+
+SmallString<128> appendPathPosix(StringRef Base, StringRef Path) {
+ SmallString<128> Default;
+ sys::path::native(Base, Default, sys::path::Style::posix);
+ sys::path::append(Default, Path);
+ return Default;
+}
+
+void getMustacheHtmlFiles(StringRef AssetsPath,
+ clang::doc::ClangDocContext &CDCtx) {
+ assert(!AssetsPath.empty());
+ assert(sys::fs::is_directory(AssetsPath));
+
+ SmallString<128> DefaultStylesheet =
+ appendPathPosix(AssetsPath, "clang-doc-mustache.css");
+ SmallString<128> NamespaceTemplate =
+ appendPathPosix(AssetsPath, "namespace-template.mustache");
+ SmallString<128> ClassTemplate =
+ appendPathPosix(AssetsPath, "class-template.mustache");
+ SmallString<128> EnumTemplate =
+ appendPathPosix(AssetsPath, "enum-template.mustache");
+ SmallString<128> FunctionTemplate =
+ appendPathPosix(AssetsPath, "function-template.mustache");
+ SmallString<128> CommentTemplate =
+ appendPathPosix(AssetsPath, "comments-template.mustache");
+ SmallString<128> IndexJS = appendPathPosix(AssetsPath, "mustache-index.js");
+
+ CDCtx.JsScripts.insert(CDCtx.JsScripts.begin(), IndexJS.c_str());
+ CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
+ DefaultStylesheet.str().str());
+ CDCtx.MustacheTemplates.insert(
+ {"namespace-template", NamespaceTemplate.c_str()});
+ CDCtx.MustacheTemplates.insert({"class-template", ClassTemplate.c_str()});
+ CDCtx.MustacheTemplates.insert({"enum-template", EnumTemplate.c_str()});
+ CDCtx.MustacheTemplates.insert(
+ {"function-template", FunctionTemplate.c_str()});
+ CDCtx.MustacheTemplates.insert(
+ {"comments-template", CommentTemplate.c_str()});
+}
diff --git a/clang-tools-extra/clang-doc/support/Utils.h
b/clang-tools-extra/clang-doc/support/Utils.h
new file mode 100644
index 0000000000000..8161c37503f81
--- /dev/null
+++ b/clang-tools-extra/clang-doc/support/Utils.h
@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
+
+#include "../Representation.h"
+#include "llvm/ADT/SmallString.h"
+#include "llvm/ADT/StringRef.h"
+
+/// Appends \p Path to \p Base and returns the appended path.
+llvm::SmallString<128> appendPathNative(llvm::StringRef Base,
+ llvm::StringRef Path);
+
+/// Appends \p Path to \p Base and returns the appended path in posix style.
+llvm::SmallString<128> appendPathPosix(llvm::StringRef Base,
+ llvm::StringRef Path);
+
+void getMustacheHtmlFiles(llvm::StringRef AssetsPath,
+ clang::doc::ClangDocContext &CDCtx);
+
+#endif
diff --git a/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
b/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
index fd14d85c63485..1c5ab32b66154 100644
--- a/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
+++ b/clang-tools-extra/unittests/clang-doc/CMakeLists.txt
@@ -4,10 +4,21 @@ set(LLVM_LINK_COMPONENTS
FrontendOpenMP
)
+# Unittests need access to mustache template files, so we use a config file to
+# inject those into a config.h header that can provide it to the unittests.
+set(CLANG_DOC_TEST_ASSET_DIR
"${LLVM_RUNTIME_OUTPUT_INTDIR}/../share/clang-doc")
+configure_file(
+ "${CMAKE_CURRENT_SOURCE_DIR}/config.h.cmake"
+ "${CMAKE_CURRENT_BINARY_DIR}/config.h"
+)
+
+# The config.h file is in ${CMAKE_CURRENT_BINARY_DIR}, so add it to
+# include_directories.
get_filename_component(CLANG_DOC_SOURCE_DIR
${CMAKE_CURRENT_SOURCE_DIR}/../../clang-doc REALPATH)
include_directories(
${CLANG_DOC_SOURCE_DIR}
+ ${CMAKE_CURRENT_BINARY_DIR}
)
add_extra_unittest(ClangDocTests
@@ -40,3 +51,4 @@ target_link_libraries(ClangDocTests
clangDoc
LLVMTestingSupport
)
+
diff --git
a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
index c0ff3f0bbaa74..70491f0754b3d 100644
--- a/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
+++ b/clang-tools-extra/unittests/clang-doc/HTMLMustacheGeneratorTest.cpp
@@ -9,6 +9,8 @@
#include "ClangDocTest.h"
#include "Generators.h"
#include "Representation.h"
+#include "config.h"
+#include "support/Utils.h"
#include "clang/Basic/Version.h"
#include "llvm/Support/Path.h"
#include "llvm/Testing/Support/Error.h"
@@ -86,8 +88,13 @@ TEST(HTMLMustacheGeneratorTest, generateDocs) {
assert(G && "Could not find HTMLMustacheGenerator");
ClangDocContext CDCtx = getClangDocContext();
- StringRef RootDir = "";
- EXPECT_THAT_ERROR(G->generateDocs(RootDir, {}, CDCtx), Succeeded())
+ unittest::TempDir RootTestDirectory("generateDocsTest", /*Unique=*/true);
+ CDCtx.OutDirectory = RootTestDirectory.path();
+
+ getMustacheHtmlFiles(CLANG_DOC_TEST_ASSET_DIR, CDCtx);
+
+ EXPECT_THAT_ERROR(G->generateDocs(RootTestDirectory.path(), {}, CDCtx),
+ Succeeded())
<< "Failed to generate docs.";
}
diff --git a/clang-tools-extra/unittests/clang-doc/config.h.cmake
b/clang-tools-extra/unittests/clang-doc/config.h.cmake
new file mode 100644
index 0000000000000..38edb3530e994
--- /dev/null
+++ b/clang-tools-extra/unittests/clang-doc/config.h.cmake
@@ -0,0 +1,6 @@
+#ifndef CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H
+#define CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H
+
+#define CLANG_DOC_TEST_ASSET_DIR "${CLANG_DOC_TEST_ASSET_DIR}"
+
+#endif // CLANG_TOOLS_EXTRA_UNITTESTS_CLANG_DOC_CONFIG_H
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
