qualcomm · quic-shaksuma · May 13, 2026
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -41,9 +41,28 @@ jobs:
 
       - name: Install dependencies
         run: |
+          sudo apt-get update
           sudo apt-get install -y graphviz doxygen libxml2 libxml2-dev libxslt1-dev
           pip install -r llvm-project/llvm/tools/eld/docs/userguide/requirements.txt
 
+      - name: Install D2 diagram generator
+        run: |
+          curl -fsSL https://d2lang.com/install.sh | sh -s -- --prefix "$HOME/.local"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Configure D2 PDF renderer
+        run: |
+          CHROME_BIN="$(command -v google-chrome || command -v google-chrome-stable || command -v chromium || command -v chromium-browser || true)"
+          if [ -z "$CHROME_BIN" ]; then
+            cd /tmp
+            wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+            sudo apt-get install -y ./google-chrome-stable_current_amd64.deb
+            CHROME_BIN="$(command -v google-chrome || command -v google-chrome-stable)"
+          fi
+          echo "D2_PDF_CHROME_BIN=$CHROME_BIN" >> "$GITHUB_ENV"
+          d2 --version
+          "$CHROME_BIN" --version
+
       - name: Run CMake
         run: |
           mkdir obj
@@ -57,12 +76,17 @@ jobs:
             -DELD_ENABLE_PDF_DOCS:BOOL=ON \
             ../llvm-project/llvm
 
-      - name: Generate documentation
+      - name: Generate HTML documentation with D2 diagrams
+        run: |
+          cd obj
+          ninja docs-eld-userguide-html
+
+      - name: Generate PDF documentation with D2 diagrams
         run: |
           cd obj
-          ninja eld-docs
-          mv tools/eld/docs/userguide/pdf/ELD_UserGuide.pdf \
-             tools/eld/docs/userguide/html/ELD_UserGuide.pdf
+          ninja docs-eld-userguide-pdf
+          cp tools/eld/docs/userguide/pdf/ELD_UserGuide.pdf \
+            tools/eld/docs/userguide/html/ELD_UserGuide.pdf
 
       - name: Deploy to docs branch
         run: |

diff --git a/README.md b/README.md
@@ -207,13 +207,15 @@ ninja check-eld-vim
 First install the prerequisites for building documentation:
 
 - Doxygen (>=1.8.11)
-- graphviz
+- graphviz (for Doxygen-generated diagrams)
+- D2 CLI (for Sphinx diagrams)
 - Sphinx and other python dependencies as specified in 'docs/userguide/requirements.txt'
 
 On an ubuntu machine, the prerequisites can be installed as:
 
 ```
 sudo apt install doxygen graphviz
+curl -fsSL https://d2lang.com/install.sh | sh -s --
 pip3 install -r ${ELDRoot}/docs/userguide/requirements.txt
 ```
 

diff --git a/cmake/modules/BuildSphinxTarget.cmake b/cmake/modules/BuildSphinxTarget.cmake
@@ -7,22 +7,27 @@ function (build_sphinx_target builder project target_name)
 
     set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
     set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
+    set(SPHINX_STAMP_FILE "${SPHINX_BUILD_DIR}/.${project}-${builder}.stamp")
     set(SPHINX_TARGET_NAME docs-${project}-${builder})
     set(${target_name} ${SPHINX_TARGET_NAME} PARENT_SCOPE)
     if (NOT ARG_SOURCE_DIR)
         set(ARG_SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/source")
     endif()
 
-    add_custom_target(${SPHINX_TARGET_NAME}
+    add_custom_command(
+            OUTPUT "${SPHINX_STAMP_FILE}"
+            COMMAND ${CMAKE_COMMAND} -E make_directory "${SPHINX_BUILD_DIR}"
             COMMAND ${SPHINX_EXECUTABLE}
             -b ${builder}
             -Dbreathe_projects.ELD="${ARG_DOXYGEN_XML_DIR}" # This is needed to hook sphinx up with the information generated by doxygen
             -d "${SPHINX_DOC_TREE_DIR}"
             -q # Quiet: no output other than errors and warnings.
             "${ARG_SOURCE_DIR}" # Source
             "${SPHINX_BUILD_DIR}" # Output
-            DEPENDS eld-api-docs
+            COMMAND ${CMAKE_COMMAND} -E touch "${SPHINX_STAMP_FILE}"
+            DEPENDS ${ARG_DEPENDS}
             COMMENT
-            "Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
-    add_dependencies(${SPHINX_TARGET_NAME} eld-api-docs ${ARG_DEPENDS})
-endfunction()
+            "Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\""
+            VERBATIM)
+    add_custom_target(${SPHINX_TARGET_NAME} DEPENDS "${SPHINX_STAMP_FILE}")
+endfunction()
diff --git a/docs/userguide/CMakeLists.txt b/docs/userguide/CMakeLists.txt
@@ -3,67 +3,129 @@ add_subdirectory(api_docs)
 if(LLVM_ENABLE_SPHINX)
   include(${ELD_SOURCE_DIR}/cmake/modules/BuildSphinxTarget.cmake)
   set(EXHALE_OUTPUT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/api")
+  if(NOT ELD_D2_BIN)
+    if(DEFINED ENV{D2_BIN})
+      set(ELD_D2_BIN
+          "$ENV{D2_BIN}"
+          CACHE FILEPATH "Path to the D2 executable used for ELD diagrams")
+    else()
+      find_program(ELD_D2_BIN NAMES d2 DOC "Path to the D2 executable used for ELD diagrams")
+    endif()
+  endif()
+  if(NOT ELD_D2_BIN)
+    message(FATAL_ERROR "D2 executable is required to build ELD userguide diagrams. Set ELD_D2_BIN or D2_BIN.")
+  endif()
   configure_file(conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/source/conf.py)
   file(MAKE_DIRECTORY ${EXHALE_OUTPUT_DIR})
 
   set(DOCS_BUILD_SOURCE ${CMAKE_CURRENT_BINARY_DIR}/source)
+  set(ELD_COPY_USERGUIDE_SOURCE_STAMP
+      ${DOCS_BUILD_SOURCE}/.copy-userguide-source.stamp)
+  file(GLOB_RECURSE ELD_USERGUIDE_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*)
+  list(FILTER ELD_USERGUIDE_SOURCE_FILES EXCLUDE REGEX "/(__pycache__|api)(/|$)")
   # Copy the documentation sources to the build directory. We need to copy the
   # documentation sources to the build directory so that we have both
   # handwritten and automatically generated documentation sources in the same
   # directory. This is required because sphinx support only a single source
   # directory.
-  add_custom_target(
-    eld-copy-userguide-source
+  add_custom_command(
+    OUTPUT ${ELD_COPY_USERGUIDE_SOURCE_STAMP}
     COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}
             ${DOCS_BUILD_SOURCE}
-    WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+    COMMAND ${CMAKE_COMMAND} -E touch ${ELD_COPY_USERGUIDE_SOURCE_STAMP}
+    DEPENDS ${ELD_USERGUIDE_SOURCE_FILES}
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+    COMMENT "Copying ELD userguide sources"
+    VERBATIM)
+  add_custom_target(eld-copy-userguide-source
+                    DEPENDS ${ELD_COPY_USERGUIDE_SOURCE_STAMP})
 
-  add_custom_target(eld-linkeroptions-docs)
   set(LINKER_OPTS_DUMP_DIR ${DOCS_BUILD_SOURCE}/LinkerOptionsDump)
+  set(ELD_LINKEROPTIONS_DUMP_DIR_STAMP ${LINKER_OPTS_DUMP_DIR}/.dir.stamp)
   set(OPTIONS_SUPPLEMENTS_DIR
       ${CMAKE_CURRENT_SOURCE_DIR}/CommandLineOptionsSupplements)
-  add_custom_target(
-    eld-linkeroptions-create-json-dump-dir
-    COMMAND ${CMAKE_COMMAND} -E make_directory ${LINKER_OPTS_DUMP_DIR})
+  file(GLOB ELD_LINKEROPTIONS_SUPPLEMENTS ${OPTIONS_SUPPLEMENTS_DIR}/*)
+  add_custom_command(
+    OUTPUT ${ELD_LINKEROPTIONS_DUMP_DIR_STAMP}
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${LINKER_OPTS_DUMP_DIR}
+    COMMAND ${CMAKE_COMMAND} -E touch ${ELD_LINKEROPTIONS_DUMP_DIR_STAMP}
+    COMMENT "Creating ELD linker options dump directory"
+    VERBATIM)
+  add_custom_target(eld-linkeroptions-create-json-dump-dir
+                    DEPENDS ${ELD_LINKEROPTIONS_DUMP_DIR_STAMP})
+
+  set(ELD_LINKEROPTIONS_DOC_OUTPUTS)
+  set(ELD_API_DOC_OUTPUTS ${DOXYGEN_OUTPUT_DIR}/xml/index.xml
+                          ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+  set(ELD_GNU_LINKEROPTIONS_JSON_DUMP
+      ${LINKER_OPTS_DUMP_DIR}/GnuLinkerOptionsTblGenDump.json)
 
   foreach(target Gnu ARM Hexagon RISCV)
     string(TOLOWER ${target} targetLC)
     # Generate JSON dump file of ${target}LinkerOptions.td
-    add_custom_target(
-      eld-${targetLC}linkeroptions-json-dump
+    set(LINKER_OPTIONS_TD
+        ${ELD_SOURCE_DIR}/include/eld/Driver/${target}LinkerOptions.td)
+    set(LINKER_OPTIONS_JSON_DUMP
+        ${LINKER_OPTS_DUMP_DIR}/${target}LinkerOptionsTblGenDump.json)
+    set(LINKER_OPTIONS_JSON_DEPENDS
+        llvm-tblgen
+        ${ELD_LINKEROPTIONS_DUMP_DIR_STAMP}
+        ${LINKER_OPTIONS_TD}
+        ${LLVM_MAIN_INCLUDE_DIR}/llvm/Option/OptParser.td)
+    if(NOT target MATCHES "Gnu")
+      list(APPEND LINKER_OPTIONS_JSON_DEPENDS
+           ${ELD_SOURCE_DIR}/include/eld/Driver/GnuLinkerOptions.td)
+    endif()
+    add_custom_command(
+      OUTPUT ${LINKER_OPTIONS_JSON_DUMP}
       COMMAND
         llvm-tblgen
-        ${ELD_SOURCE_DIR}/include/eld/Driver/${target}LinkerOptions.td
+        ${LINKER_OPTIONS_TD}
         -dump-json -I${LLVM_MAIN_INCLUDE_DIR}
         -I${ELD_SOURCE_DIR}/include/eld/Driver -o
-        ${LINKER_OPTS_DUMP_DIR}/${target}LinkerOptionsTblGenDump.json
-      DEPENDS eld-linkeroptions-create-json-dump-dir)
+        ${LINKER_OPTIONS_JSON_DUMP}
+      DEPENDS ${LINKER_OPTIONS_JSON_DEPENDS}
+      COMMENT "Generating ${target} linker options JSON dump"
+      VERBATIM)
+    add_custom_target(eld-${targetLC}linkeroptions-json-dump
+                      DEPENDS ${LINKER_OPTIONS_JSON_DUMP})
 
     # Generates ${target}LinkerOptions restructureText documentation from the
     # ${target}LinkerOptions JSON dump file.
     set(SKIP_OPTION "")
+    set(LINKER_OPTIONS_DOC_DEPENDS
+        ${LINKER_OPTIONS_JSON_DUMP}
+        ${ELD_COPY_USERGUIDE_SOURCE_STAMP}
+        ${CMAKE_CURRENT_SOURCE_DIR}/GenerateOptionsDocsFromTblGen.py
+        ${ELD_LINKEROPTIONS_SUPPLEMENTS})
     if(NOT target MATCHES "Gnu")
       set(SKIP_OPTION -s
-                      ${LINKER_OPTS_DUMP_DIR}/GnuLinkerOptionsTblGenDump.json)
+                      ${ELD_GNU_LINKEROPTIONS_JSON_DUMP})
+      list(APPEND LINKER_OPTIONS_DOC_DEPENDS ${ELD_GNU_LINKEROPTIONS_JSON_DUMP})
     endif()
-    add_custom_target(
-      eld-${targetLC}linkeroptions-docs
+    set(LINKER_OPTIONS_DOC
+        ${DOCS_BUILD_SOURCE}/documentation/options/${target}LinkerOptions.rst)
+    add_custom_command(
+      OUTPUT ${LINKER_OPTIONS_DOC}
+      COMMAND ${CMAKE_COMMAND} -E make_directory
+              ${DOCS_BUILD_SOURCE}/documentation/options
       COMMAND
         python3 ${CMAKE_CURRENT_SOURCE_DIR}/GenerateOptionsDocsFromTblGen.py
-        ${LINKER_OPTS_DUMP_DIR}/${target}LinkerOptionsTblGenDump.json -o
-        ${DOCS_BUILD_SOURCE}/documentation/options/${target}LinkerOptions.rst
+        ${LINKER_OPTIONS_JSON_DUMP} -o
+        ${LINKER_OPTIONS_DOC}
         ${SKIP_OPTION}
-        -S ${OPTIONS_SUPPLEMENTS_DIR})
-
-    add_dependencies(eld-${targetLC}linkeroptions-docs
-                     eld-${targetLC}linkeroptions-json-dump)
-    add_dependencies(eld-linkeroptions-docs eld-${targetLC}linkeroptions-docs)
-    if(NOT target MATCHES "Gnu")
-      add_dependencies(eld-${targetLC}linkeroptions-docs
-                       eld-gnulinkeroptions-json-dump)
-    endif()
+        -S ${OPTIONS_SUPPLEMENTS_DIR}
+      DEPENDS ${LINKER_OPTIONS_DOC_DEPENDS}
+      COMMENT "Generating ${target} linker options documentation"
+      VERBATIM)
+    add_custom_target(eld-${targetLC}linkeroptions-docs
+                      DEPENDS ${LINKER_OPTIONS_DOC})
+    list(APPEND ELD_LINKEROPTIONS_DOC_OUTPUTS ${LINKER_OPTIONS_DOC})
   endforeach()
 
+  add_custom_target(eld-linkeroptions-docs
+                    DEPENDS ${ELD_LINKEROPTIONS_DOC_OUTPUTS})
+
   # HTML user guide
   build_sphinx_target(
     html
@@ -72,8 +134,9 @@ if(LLVM_ENABLE_SPHINX)
     DOXYGEN_XML_DIR
     ${DOXYGEN_OUTPUT_DIR}/xml
     DEPENDS
-    eld-copy-userguide-source
-    eld-linkeroptions-docs)
+    ${ELD_API_DOC_OUTPUTS}
+    ${ELD_COPY_USERGUIDE_SOURCE_STAMP}
+    ${ELD_LINKEROPTIONS_DOC_OUTPUTS})
 
   add_custom_target(eld-docs DEPENDS ${html_target_name})
 
@@ -86,8 +149,9 @@ if(LLVM_ENABLE_SPHINX)
       DOXYGEN_XML_DIR
       ${DOXYGEN_OUTPUT_DIR}/xml
       DEPENDS
-      eld-copy-userguide-source
-      eld-linkeroptions-docs)
+      ${ELD_API_DOC_OUTPUTS}
+      ${ELD_COPY_USERGUIDE_SOURCE_STAMP}
+      ${ELD_LINKEROPTIONS_DOC_OUTPUTS})
 
     add_dependencies(eld-docs ${pdf_target_name})
   endif()