[clang-doc][NFC] refactor out file helpers #134298

PeterChou1 · 2025-04-03T20:02:45Z

Split from #133161

refactor the code to extract file helpers used in HTML generators for use in other generators for clang-doc

llvmbot · 2025-04-03T20:03:23Z

@llvm/pr-subscribers-clang-tools-extra

Author: None (PeterChou1)

Changes

Split from #133161

refactor the code to extract file helpers used in HTML generators for use in other generators for clang-doc

Full diff: https://github.com/llvm/llvm-project/pull/134298.diff

5 Files Affected:

(modified) clang-tools-extra/clang-doc/CMakeLists.txt (+2)
(modified) clang-tools-extra/clang-doc/HTMLGenerator.cpp (+1-58)
(added) clang-tools-extra/clang-doc/support/CMakeLists.txt (+9)
(added) clang-tools-extra/clang-doc/support/File.cpp (+74)
(added) clang-tools-extra/clang-doc/support/File.h (+26)

diff --git a/clang-tools-extra/clang-doc/CMakeLists.txt b/clang-tools-extra/clang-doc/CMakeLists.txt
index 520fe58cbe68e..f4f62c74d6592 100644
--- a/clang-tools-extra/clang-doc/CMakeLists.txt
+++ b/clang-tools-extra/clang-doc/CMakeLists.txt
@@ -3,6 +3,7 @@ set(LLVM_LINK_COMPONENTS
   BitstreamReader
   FrontendOpenMP
   )
+add_subdirectory(support)
 
 add_clang_library(clangDoc STATIC
   BitcodeReader.cpp
@@ -23,6 +24,7 @@ add_clang_library(clangDoc STATIC
 
 clang_target_link_libraries(clangDoc
   PRIVATE
+  clangDocSupport        
   clangAnalysis
   clangAST
   clangASTMatchers
diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index 18a0de826630c..edcaf27094661 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -8,6 +8,7 @@
 
 #include "Generators.h"
 #include "Representation.h"
+#include "support/File.h"
 #include "clang/Basic/Version.h"
 #include "llvm/ADT/StringExtras.h"
 #include "llvm/ADT/StringRef.h"
@@ -251,47 +252,6 @@ static void appendVector(std::vector<Derived> &&New,
   std::move(New.begin(), New.end(), std::back_inserter(Original));
 }
 
-// Compute the relative path from an Origin directory to a Destination directory
-static SmallString<128> computeRelativePath(StringRef Destination,
-                                            StringRef Origin) {
-  // If Origin is empty, the relative path to the Destination is its complete
-  // path.
-  if (Origin.empty())
-    return Destination;
-
-  // The relative path is an empty path if both directories are the same.
-  if (Destination == Origin)
-    return {};
-
-  // These iterators iterate through each of their parent directories
-  llvm::sys::path::const_iterator FileI = llvm::sys::path::begin(Destination);
-  llvm::sys::path::const_iterator FileE = llvm::sys::path::end(Destination);
-  llvm::sys::path::const_iterator DirI = llvm::sys::path::begin(Origin);
-  llvm::sys::path::const_iterator DirE = llvm::sys::path::end(Origin);
-  // Advance both iterators until the paths differ. Example:
-  //    Destination = A/B/C/D
-  //    Origin      = A/B/E/F
-  // FileI will point to C and DirI to E. The directories behind them is the
-  // directory they share (A/B).
-  while (FileI != FileE && DirI != DirE && *FileI == *DirI) {
-    ++FileI;
-    ++DirI;
-  }
-  SmallString<128> Result; // This will hold the resulting path.
-  // Result has to go up one directory for each of the remaining directories in
-  // Origin
-  while (DirI != DirE) {
-    llvm::sys::path::append(Result, "..");
-    ++DirI;
-  }
-  // Result has to append each of the remaining directories in Destination
-  while (FileI != FileE) {
-    llvm::sys::path::append(Result, *FileI);
-    ++FileI;
-  }
-  return Result;
-}
-
 // HTML generation
 
 static std::vector<std::unique_ptr<TagNode>>
@@ -1146,23 +1106,6 @@ static llvm::Error genIndex(const ClangDocContext &CDCtx) {
   return llvm::Error::success();
 }
 
-static llvm::Error copyFile(StringRef FilePath, StringRef OutDirectory) {
-  llvm::SmallString<128> PathWrite;
-  llvm::sys::path::native(OutDirectory, PathWrite);
-  llvm::sys::path::append(PathWrite, llvm::sys::path::filename(FilePath));
-  llvm::SmallString<128> PathRead;
-  llvm::sys::path::native(FilePath, PathRead);
-  std::error_code OK;
-  std::error_code FileErr = llvm::sys::fs::copy_file(PathRead, PathWrite);
-  if (FileErr != OK) {
-    return llvm::createStringError(llvm::inconvertibleErrorCode(),
-                                   "error creating file " +
-                                       llvm::sys::path::filename(FilePath) +
-                                       ": " + FileErr.message() + "\n");
-  }
-  return llvm::Error::success();
-}
-
 llvm::Error HTMLGenerator::createResources(ClangDocContext &CDCtx) {
   auto Err = serializeIndex(CDCtx);
   if (Err)
diff --git a/clang-tools-extra/clang-doc/support/CMakeLists.txt b/clang-tools-extra/clang-doc/support/CMakeLists.txt
new file mode 100644
index 0000000000000..a4f7993d5c9d8
--- /dev/null
+++ b/clang-tools-extra/clang-doc/support/CMakeLists.txt
@@ -0,0 +1,9 @@
+# clang-doc/support contains support libraries that do not depend
+# on clang either programmatically or conceptually.
+set(LLVM_LINK_COMPONENTS
+  Support
+  )
+
+add_clang_library(clangDocSupport STATIC
+  File.cpp
+  )
\ No newline at end of file
diff --git a/clang-tools-extra/clang-doc/support/File.cpp b/clang-tools-extra/clang-doc/support/File.cpp
new file mode 100644
index 0000000000000..a9162bee8cd70
--- /dev/null
+++ b/clang-tools-extra/clang-doc/support/File.cpp
@@ -0,0 +1,74 @@
+//===-- FileHelpersClangDoc.cpp - File Helpers -------------------*- C++-*-===//
+//
+// 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 "File.h"
+#include "llvm/Support/FileSystem.h"
+#include "llvm/Support/Path.h"
+
+namespace clang {
+namespace doc {
+
+llvm::Error
+copyFile(llvm::StringRef FilePath, llvm::StringRef OutDirectory) {
+  llvm::SmallString<128> PathWrite;
+  llvm::sys::path::native(OutDirectory, PathWrite);
+  llvm::sys::path::append(PathWrite, llvm::sys::path::filename(FilePath));
+  llvm::SmallString<128> PathRead;
+  llvm::sys::path::native(FilePath, PathRead);
+  std::error_code FileErr = llvm::sys::fs::copy_file(PathRead, PathWrite);
+  if (FileErr) {
+    return llvm::createStringError(llvm::inconvertibleErrorCode(),
+                                   "error creating file " +
+                                       llvm::sys::path::filename(FilePath) +
+                                       ": " + FileErr.message() + "\n");
+  }
+  return llvm::Error::success();
+}
+
+
+llvm::SmallString<128> computeRelativePath(llvm::StringRef Destination,
+                                           llvm::StringRef Origin) {
+  // If Origin is empty, the relative path to the Destination is its complete
+  // path.
+  if (Origin.empty())
+    return Destination;
+  
+  // The relative path is an empty path if both directories are the same.
+  if (Destination == Origin)
+    return {};
+
+  // These iterators iterate through each of their parent directories
+  llvm::sys::path::const_iterator FileI = llvm::sys::path::begin(Destination);
+  llvm::sys::path::const_iterator FileE = llvm::sys::path::end(Destination);
+  llvm::sys::path::const_iterator DirI = llvm::sys::path::begin(Origin);
+  llvm::sys::path::const_iterator DirE = llvm::sys::path::end(Origin);
+  // Advance both iterators until the paths differ. Example:
+  //    Destination = A/B/C/D
+  //    Origin      = A/B/E/F
+  // FileI will point to C and DirI to E. The directories behind them is the
+  // directory they share (A/B).
+  while (FileI != FileE && DirI != DirE && *FileI == *DirI) {
+    ++FileI;
+    ++DirI;
+  }
+  llvm::SmallString<128> Result; // This will hold the resulting path.
+  // Result has to go up one directory for each of the remaining directories in
+  // Origin
+  while (DirI != DirE) {
+    llvm::sys::path::append(Result, "..");
+    ++DirI;
+  }
+  // Result has to append each of the remaining directories in Destination
+  while (FileI != FileE) {
+    llvm::sys::path::append(Result, *FileI);
+    ++FileI;
+  }
+  return Result;
+}
+
+} // namespace doc
+} // namespace clang
\ No newline at end of file
diff --git a/clang-tools-extra/clang-doc/support/File.h b/clang-tools-extra/clang-doc/support/File.h
new file mode 100644
index 0000000000000..fc52d185a5093
--- /dev/null
+++ b/clang-tools-extra/clang-doc/support/File.h
@@ -0,0 +1,26 @@
+//===-- File.h --- File Helpers -------------------*- C++-*-===//
+//
+// 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_FILEHELPER_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILEHELPER_H
+
+#include "llvm/ADT/StringExtras.h"
+#include "llvm/Support/Error.h"
+
+namespace clang {
+namespace doc {
+
+llvm::Error 
+copyFile(llvm::StringRef FilePath, llvm::StringRef OutDirectory);
+
+llvm::SmallString<128> 
+computeRelativePath(llvm::StringRef Destination,llvm::StringRef Origin);
+
+} // namespace doc
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILEHELPER_H
\ No newline at end of file

github-actions · 2025-04-03T20:05:33Z

✅ With the latest revision this PR passed the C/C++ code formatter.

ilovepi

Since this just moves common code I think this is fine for now. We should revisit some of the interfaces though, especially the ones that return SmallString<128>. I think there is also a Path API that handles relative paths, so we can perhaps drop that entirely?

Also I know I suggested File.cpp, but maybe FileUtils.cpp is a more apt name now that I look at the content again?

clang-tools-extra/clang-doc/support/File.h

clang-tools-extra/clang-doc/support/File.cpp

llvm-ci · 2025-04-10T00:15:29Z

LLVM Buildbot has detected a new failure on builder llvm-x86_64-debian-dylib running on gribozavr4 while building clang-tools-extra at step 5 "build-unified-tree".

Full details are available at: https://lab.llvm.org/buildbot/#/builders/60/builds/24310

Here is the relevant piece of the build log for the reference

Step 5 (build-unified-tree) failure: build (failure)
...
61.955 [8/2/7272] Linking CXX shared library lib/liblldb.so.21.0.0git
61.957 [7/2/7273] Creating library symlink lib/liblldb.so.21.0git lib/liblldb.so
61.961 [4/4/7274] Linking CXX static library lib/liblldbIntelMPX.a
62.083 [3/4/7275] Linking CXX shared library lib/liblldbIntelFeatures.so.21.0git
62.084 [2/4/7276] Linking CXX executable bin/lldb
62.084 [2/3/7277] Creating library symlink lib/liblldbIntelFeatures.so
62.107 [2/2/7278] Linking CXX executable bin/lldb-dap
63.114 [2/1/7279] Building CXX object tools/clang/tools/extra/clang-doc/CMakeFiles/obj.clangDoc.dir/HTMLGenerator.cpp.o
63.127 [1/1/7280] Linking CXX static library lib/libclangDoc.a
63.265 [0/1/7281] Linking CXX executable bin/clang-doc
FAILED: bin/clang-doc 
: && /usr/bin/clang++ -fPIC -fvisibility-inlines-hidden -Werror=date-time -Werror=unguarded-availability-new -Wall -Wextra -Wno-unused-parameter -Wwrite-strings -Wcast-qual -Wmissing-field-initializers -pedantic -Wno-long-long -Wc++98-compat-extra-semi -Wimplicit-fallthrough -Wcovered-switch-default -Wno-noexcept-type -Wnon-virtual-dtor -Wdelete-non-virtual-dtor -Wsuggest-override -Wstring-conversion -Wmisleading-indentation -Wctad-maybe-unsupported -fdiagnostics-color -ffunction-sections -fdata-sections -fno-common -Woverloaded-virtual -Wno-nested-anon-types -O3 -DNDEBUG -Wl,--gc-sections tools/clang/tools/extra/clang-doc/tool/CMakeFiles/clang-doc.dir/ClangDocMain.cpp.o -o bin/clang-doc  -Wl,-rpath,"\$ORIGIN/../lib:/b/1/llvm-x86_64-debian-dylib/build/lib:"  -lpthread  lib/libclangDoc.a  lib/libclang-cpp.so.21.0git  lib/libLLVM.so.21.0git && :
lib/libclangDoc.a(HTMLGenerator.cpp.o):HTMLGenerator.cpp:function clang::doc::HTMLGenerator::createResources(clang::doc::ClangDocContext&): error: undefined reference to 'clang::doc::copyFile(llvm::StringRef, llvm::StringRef)'
lib/libclangDoc.a(HTMLGenerator.cpp.o):HTMLGenerator.cpp:function clang::doc::HTMLGenerator::createResources(clang::doc::ClangDocContext&): error: undefined reference to 'clang::doc::copyFile(llvm::StringRef, llvm::StringRef)'
lib/libclangDoc.a(HTMLGenerator.cpp.o):HTMLGenerator.cpp:function clang::doc::genFileHeadNodes(llvm::StringRef, llvm::StringRef, clang::doc::ClangDocContext const&): error: undefined reference to 'clang::doc::computeRelativePath(llvm::StringRef, llvm::StringRef)'
lib/libclangDoc.a(HTMLGenerator.cpp.o):HTMLGenerator.cpp:function clang::doc::genFileHeadNodes(llvm::StringRef, llvm::StringRef, clang::doc::ClangDocContext const&): error: undefined reference to 'clang::doc::computeRelativePath(llvm::StringRef, llvm::StringRef)'
lib/libclangDoc.a(HTMLGenerator.cpp.o):HTMLGenerator.cpp:function clang::doc::genFileHeadNodes(llvm::StringRef, llvm::StringRef, clang::doc::ClangDocContext const&): error: undefined reference to 'clang::doc::computeRelativePath(llvm::StringRef, llvm::StringRef)'
clang: error: linker command failed with exit code 1 (use -v to see invocation)
ninja: build stopped: subcommand failed.

Split from llvm#133161 refactor the code to extract file helpers used in HTML generators for use in other generators for clang-doc

mstorsjo · 2025-04-10T07:22:20Z

This change broke compiling with -DLLVM_LINK_LLVM_DYLIB=ON, as seen in the buildbot log above. Will revert later today if we don't have a fix.

This reverts commit e10f67a.

Split from llvm#133161 refactor the code to extract file helpers used in HTML generators for use in other generators for clang-doc

PeterChou1 added 2 commits April 3, 2025 15:59

factor out file helpers

fa35468

remove redundant code

870f17b

llvmbot added the clang-tools-extra label Apr 3, 2025

PeterChou1 requested a review from ilovepi April 3, 2025 20:04

PeterChou1 added 3 commits April 3, 2025 16:07

clang-format

0c59710

commit file

75fb16e

clang-format

73bf517

PeterChou1 requested a review from mysterymath April 3, 2025 22:19

ilovepi approved these changes Apr 3, 2025

View reviewed changes

clang-tools-extra/clang-doc/support/File.h Outdated Show resolved Hide resolved

clang-tools-extra/clang-doc/support/File.h Outdated Show resolved Hide resolved

mysterymath approved these changes Apr 7, 2025

View reviewed changes

clang-tools-extra/clang-doc/support/File.cpp Outdated Show resolved Hide resolved

address comment

db9c5a6

PeterChou1 merged commit e10f67a into llvm:main Apr 9, 2025
7 of 10 checks passed

pranavk added a commit to pranavk/llvm-project that referenced this pull request Apr 10, 2025

[bazel] Fix for llvm#134298

e061d3c

pranavk added a commit that referenced this pull request Apr 10, 2025

[bazel] Fix for #134298 (#135114)

02fde3a

AllinLeeYL pushed a commit to AllinLeeYL/llvm-project that referenced this pull request Apr 10, 2025

[bazel] Fix for llvm#134298 (llvm#135114)

6257d7f

searlmc1 pushed a commit to ROCm/llvm-project that referenced this pull request Apr 10, 2025

Revert "[clang-doc][NFC] refactor out file helpers (llvm#134298)"

2251aef

This reverts commit e10f67a.

searlmc1 pushed a commit to ROCm/llvm-project that referenced this pull request Apr 10, 2025

[clang-doc][NFC] refactor out file helpers (llvm#134298)

bd441cb

Split from llvm#133161 refactor the code to extract file helpers used in HTML generators for use in other generators for clang-doc

var-const pushed a commit to ldionne/llvm-project that referenced this pull request Apr 17, 2025

[clang-doc][NFC] refactor out file helpers (llvm#134298)

3c9aae3

Split from llvm#133161 refactor the code to extract file helpers used in HTML generators for use in other generators for clang-doc

var-const pushed a commit to ldionne/llvm-project that referenced this pull request Apr 17, 2025

[bazel] Fix for llvm#134298 (llvm#135114)

e74bc52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[clang-doc][NFC] refactor out file helpers #134298

[clang-doc][NFC] refactor out file helpers #134298

Uh oh!

PeterChou1 commented Apr 3, 2025

Uh oh!

llvmbot commented Apr 3, 2025

Uh oh!

github-actions bot commented Apr 3, 2025 •

edited

Loading

Uh oh!

ilovepi left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

llvm-ci commented Apr 10, 2025

Uh oh!

mstorsjo commented Apr 10, 2025

Uh oh!

Uh oh!

[clang-doc][NFC] refactor out file helpers #134298

[clang-doc][NFC] refactor out file helpers #134298

Uh oh!

Conversation

PeterChou1 commented Apr 3, 2025

Uh oh!

llvmbot commented Apr 3, 2025

Uh oh!

github-actions bot commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ilovepi left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

llvm-ci commented Apr 10, 2025

Uh oh!

mstorsjo commented Apr 10, 2025

Uh oh!

Uh oh!

github-actions bot commented Apr 3, 2025 •

edited

Loading

ilovepi left a comment •

edited

Loading