[Mlir-commits] [clang] [clang-tools-extra] [flang] [lldb] [llvm] [mlir] [openmp] [polly] [docs] update CI to use modern (currently pre-release) version of doxygen (PR #191501)

Jameson Nash llvmlistbot at llvm.org
Thu Apr 30 21:06:05 PDT 2026 

https://github.com/vtjnash updated https://github.com/llvm/llvm-project/pull/191501

>From 07b6b7d1fb491043b9773db7895d87bad5fdb62e Mon Sep 17 00:00:00 2001
From: Jameson Nash <vtjnash at gmail.com>
Date: Fri, 10 Apr 2026 19:30:24 +0000
Subject: [PATCH 1/2] [docs] update CI to use modern (currently pre-release)
 version of doxygen

Previously this was likely 1.9.8, with the Ubuntu 24.04 worker. Now this
is 1.17.0-dev.

Fixes 3 significant issues for LLVM:

- `dot` execution performance is very slow (cuts this half hour step
  down to mere seconds).
  https://github.com/doxygen/doxygen/pull/12037
- multi-thread performance is very slow (worse than single threading),
  and now uses all cores for ncpu times speedup (when using version with
  fix, autodetected by cmake).
  https://github.com/doxygen/doxygen/pull/12027
- file links for IR.cpp and similar files were wrong
  https://github.com/doxygen/doxygen/pull/11944

Assisted-by: Claude Code
---
 .github/workflows/release-doxygen.yml | 10 ++++++++--
 bolt/docs/CMakeLists.txt              |  4 ++--
 bolt/docs/doxygen.cfg.in              |  2 ++
 clang-tools-extra/docs/CMakeLists.txt |  4 ++--
 clang-tools-extra/docs/doxygen.cfg.in |  2 ++
 clang/docs/CMakeLists.txt             |  4 ++--
 clang/docs/doxygen.cfg.in             |  2 ++
 cmake/Modules/HandleDoxygen.cmake     | 18 +++++++++++++++++-
 flang/docs/CMakeLists.txt             |  4 ++--
 flang/docs/doxygen.cfg.in             |  2 ++
 lldb/docs/CMakeLists.txt              |  4 ++--
 lldb/docs/doxygen.cfg.in              |  2 ++
 llvm/docs/CMakeLists.txt              |  4 ++--
 llvm/docs/doxygen.cfg.in              |  2 ++
 mlir/docs/CMakeLists.txt              |  4 ++--
 mlir/docs/doxygen.cfg.in              |  2 ++
 openmp/docs/CMakeLists.txt            |  4 ++--
 openmp/docs/doxygen.cfg.in            |  2 ++
 polly/docs/CMakeLists.txt             |  4 ++--
 polly/docs/doxygen.cfg.in             |  2 ++
 20 files changed, 61 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/release-doxygen.yml b/.github/workflows/release-doxygen.yml
index 4301a4712b8fc..9e2f06c1ede08 100644
--- a/.github/workflows/release-doxygen.yml
+++ b/.github/workflows/release-doxygen.yml
@@ -54,13 +54,19 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y \
-              doxygen \
               graphviz \
               python3-github \
               ninja-build \
-              texlive-font-utils
+              texlive-font-utils \
+              unzip
           pip3 install --user -r ./llvm/docs/requirements.txt
 
+      - name: Install Doxygen
+        run: |
+          curl -L https://github.com/vtjnash/doxygen/releases/download/Dev_1_17_0/Ubuntu.Latest.GCC.Release.Intel.build.artifacts.zip -o doxygen.zip
+          unzip doxygen.zip -d doxygen-install
+          sudo install -m 755 doxygen-install/doxygen /usr/local/bin/doxygen
+
       - name: Build Doxygen
         run: |
           ./llvm/utils/release/build-docs.sh -release "${{ inputs.release-version }}" -no-sphinx
diff --git a/bolt/docs/CMakeLists.txt b/bolt/docs/CMakeLists.txt
index 897a0ae043259..92c3c964acb77 100644
--- a/bolt/docs/CMakeLists.txt
+++ b/bolt/docs/CMakeLists.txt
@@ -48,8 +48,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(bolt_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/bolt/docs/doxygen.cfg.in b/bolt/docs/doxygen.cfg.in
index de8b1f7bd6b3d..79ccde79d55e0 100644
--- a/bolt/docs/doxygen.cfg.in
+++ b/bolt/docs/doxygen.cfg.in
@@ -392,6 +392,8 @@ LOOKUP_CACHE_SIZE      = 0
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/clang-tools-extra/docs/CMakeLists.txt b/clang-tools-extra/docs/CMakeLists.txt
index 1eb9dc294f225..1492f25a0197f 100644
--- a/clang-tools-extra/docs/CMakeLists.txt
+++ b/clang-tools-extra/docs/CMakeLists.txt
@@ -46,8 +46,8 @@ if (DOXYGEN_FOUND)
       set(clang_tools_doxygen_qhp_cust_filter_attrs "")
     endif()
 
-    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-      ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+    include(HandleDoxygen)
+    llvm_configure_doxygen()
 
     set(abs_top_srcdir)
     set(abs_top_builddir)
diff --git a/clang-tools-extra/docs/doxygen.cfg.in b/clang-tools-extra/docs/doxygen.cfg.in
index d33094f099acf..854c548b7a3d0 100644
--- a/clang-tools-extra/docs/doxygen.cfg.in
+++ b/clang-tools-extra/docs/doxygen.cfg.in
@@ -390,6 +390,8 @@ LOOKUP_CACHE_SIZE      = 2
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt
index e69d4750aeb4c..1393284bae025 100644
--- a/clang/docs/CMakeLists.txt
+++ b/clang/docs/CMakeLists.txt
@@ -47,8 +47,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(clang_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/clang/docs/doxygen.cfg.in b/clang/docs/doxygen.cfg.in
index 09764efc2261e..5f7dd22fc77f4 100644
--- a/clang/docs/doxygen.cfg.in
+++ b/clang/docs/doxygen.cfg.in
@@ -390,6 +390,8 @@ LOOKUP_CACHE_SIZE      = 3
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/cmake/Modules/HandleDoxygen.cmake b/cmake/Modules/HandleDoxygen.cmake
index 23015ffcaa85c..bb89a8f3302cb 100644
--- a/cmake/Modules/HandleDoxygen.cmake
+++ b/cmake/Modules/HandleDoxygen.cmake
@@ -17,9 +17,9 @@ function(llvm_find_program name)
 endfunction()
 
 if (LLVM_ENABLE_DOXYGEN)
-  message(STATUS "Doxygen enabled.")
   llvm_find_program(dot)
   find_package(Doxygen REQUIRED)
+  message(STATUS "Doxygen enabled (${DOXYGEN_VERSION}).")
 
   if (DOXYGEN_FOUND)
     # If we find doxygen and we want to enable doxygen by default create a
@@ -35,6 +35,22 @@ if (LLVM_ENABLE_DOXYGEN)
       set(LLVM_DOXYGEN_SEARCH_MAPPINGS "" CACHE STRING "Doxygen Search Mappings")
     endif()
   endif()
+
+  # Uses all CPUs for doxygen >= 1.17 where multi-threading is fast, and
+  # single-threaded (1) for older versions where multi-threading is slower than
+  # single-threaded.
+  if (DOXYGEN_VERSION VERSION_GREATER_EQUAL "1.17")
+    set(DOXYGEN_NUM_PROC_THREADS 0)
+  else()
+    set(DOXYGEN_NUM_PROC_THREADS 1)
+  endif()
 else()
   message(STATUS "Doxygen disabled.")
 endif()
+
+# Configure doxygen.cfg.in -> doxygen.cfg, using a macro here to ensure that
+# DOXYGEN_NUM_PROC_THREADS has been set.
+macro(llvm_configure_doxygen)
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
+    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+endmacro()
diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt
index 09219b2bad811..5f2fb2fadd067 100644
--- a/flang/docs/CMakeLists.txt
+++ b/flang/docs/CMakeLists.txt
@@ -48,8 +48,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(flang_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/flang/docs/doxygen.cfg.in b/flang/docs/doxygen.cfg.in
index cbbe87d92dc90..78c3cdf57f343 100644
--- a/flang/docs/doxygen.cfg.in
+++ b/flang/docs/doxygen.cfg.in
@@ -392,6 +392,8 @@ LOOKUP_CACHE_SIZE      = 0
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt
index bbecf606f1f8f..39642e4590ad4 100644
--- a/lldb/docs/CMakeLists.txt
+++ b/lldb/docs/CMakeLists.txt
@@ -5,8 +5,8 @@ if(DOXYGEN_FOUND)
   set(DOT dot)
   set(PACKAGE_VERSION mainline)
   set(abs_top_builddir ..)
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-  ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   add_custom_target(lldb-cpp-doc
     ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
diff --git a/lldb/docs/doxygen.cfg.in b/lldb/docs/doxygen.cfg.in
index 2bb7abbde47ab..045660ce4f281 100644
--- a/lldb/docs/doxygen.cfg.in
+++ b/lldb/docs/doxygen.cfg.in
@@ -293,6 +293,8 @@ SYMBOL_CACHE_SIZE      = 0
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available.
 # Private class members and static file members will be hidden unless
diff --git a/llvm/docs/CMakeLists.txt b/llvm/docs/CMakeLists.txt
index fc37c6d97ddfa..5c8a24c0d6516 100644
--- a/llvm/docs/CMakeLists.txt
+++ b/llvm/docs/CMakeLists.txt
@@ -56,8 +56,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(llvm_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/llvm/docs/doxygen.cfg.in b/llvm/docs/doxygen.cfg.in
index 82b281ad103ba..d884d92053f6a 100644
--- a/llvm/docs/doxygen.cfg.in
+++ b/llvm/docs/doxygen.cfg.in
@@ -391,6 +391,8 @@ LOOKUP_CACHE_SIZE      = 4
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/mlir/docs/CMakeLists.txt b/mlir/docs/CMakeLists.txt
index b32b9427adb5e..53d9f73f912f6 100644
--- a/mlir/docs/CMakeLists.txt
+++ b/mlir/docs/CMakeLists.txt
@@ -47,8 +47,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(mlir_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/mlir/docs/doxygen.cfg.in b/mlir/docs/doxygen.cfg.in
index 255041b6817a9..382ea8faaedce 100644
--- a/mlir/docs/doxygen.cfg.in
+++ b/mlir/docs/doxygen.cfg.in
@@ -391,6 +391,8 @@ LOOKUP_CACHE_SIZE      = 4
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/openmp/docs/CMakeLists.txt b/openmp/docs/CMakeLists.txt
index 018942cf0e9dc..491237677374b 100644
--- a/openmp/docs/CMakeLists.txt
+++ b/openmp/docs/CMakeLists.txt
@@ -47,8 +47,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(openmp_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/openmp/docs/doxygen.cfg.in b/openmp/docs/doxygen.cfg.in
index 07964e90c8eaf..2b4fd0b5c5ee1 100644
--- a/openmp/docs/doxygen.cfg.in
+++ b/openmp/docs/doxygen.cfg.in
@@ -390,6 +390,8 @@ LOOKUP_CACHE_SIZE      = 3
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the
diff --git a/polly/docs/CMakeLists.txt b/polly/docs/CMakeLists.txt
index 8b801339962ce..b034b00ce9829 100644
--- a/polly/docs/CMakeLists.txt
+++ b/polly/docs/CMakeLists.txt
@@ -46,8 +46,8 @@ if (LLVM_ENABLE_DOXYGEN)
     set(polly_doxygen_qhp_cust_filter_attrs "")
   endif()
 
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
-    ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
+  include(HandleDoxygen)
+  llvm_configure_doxygen()
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
diff --git a/polly/docs/doxygen.cfg.in b/polly/docs/doxygen.cfg.in
index 5c4e8a6372820..277f86eef83cd 100644
--- a/polly/docs/doxygen.cfg.in
+++ b/polly/docs/doxygen.cfg.in
@@ -390,6 +390,8 @@ LOOKUP_CACHE_SIZE      = 2
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+NUM_PROC_THREADS       = @DOXYGEN_NUM_PROC_THREADS@
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available. Private
 # class members and static file members will be hidden unless the

>From eed0545978661e36d44ca0989352eebad7853c8b Mon Sep 17 00:00:00 2001
From: Jameson Nash <vtjnash at gmail.com>
Date: Fri, 1 May 2026 00:05:55 -0400
Subject: [PATCH 2/2] Update Doxygen installation method in workflow

---
 .github/workflows/release-doxygen.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release-doxygen.yml b/.github/workflows/release-doxygen.yml
index 9e2f06c1ede08..dc05d9cc6e673 100644
--- a/.github/workflows/release-doxygen.yml
+++ b/.github/workflows/release-doxygen.yml
@@ -63,9 +63,9 @@ jobs:
 
       - name: Install Doxygen
         run: |
-          curl -L https://github.com/vtjnash/doxygen/releases/download/Dev_1_17_0/Ubuntu.Latest.GCC.Release.Intel.build.artifacts.zip -o doxygen.zip
-          unzip doxygen.zip -d doxygen-install
-          sudo install -m 755 doxygen-install/doxygen /usr/local/bin/doxygen
+          curl -L https://github.com/doxygen/doxygen/releases/download/Release_1_17_0/doxygen-1.17.0.linux.bin.tar.gz -o doxygen.tar.gz
+          tar -xf doxygen.tar.gz
+          sudo install -m 755 doxygen-1.17.0/bin/doxygen /usr/local/bin/doxygen
 
       - name: Build Doxygen
         run: |

More information about the Mlir-commits mailing list