From 3e20d23fa34a9a852e8d351a5c726caae8c77de4 Mon Sep 17 00:00:00 2001
From: Enrico Seiler <enrico.seiler@hotmail.de>
Date: Mon, 24 Jul 2023 17:29:57 +0200
Subject: [PATCH] [INFRA] Add option to configure tag file

https://salsa.debian.org/med-team/seqan3/-/blob/40f5a781a90f31c0fd7df199405e4f9bb3989a0a/debian/patches/debian_cppreference
---
 test/documentation/seqan3-doxygen.cmake | 48 +++++++++++++++++--------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/test/documentation/seqan3-doxygen.cmake b/test/documentation/seqan3-doxygen.cmake
index 5ee9642746..8e95656079 100644
--- a/test/documentation/seqan3-doxygen.cmake
+++ b/test/documentation/seqan3-doxygen.cmake
@@ -47,20 +47,40 @@ if (SEQAN3_VERCEL_PREVIEW_DOC)
 endif ()
 
 ### Download and extract cppreference-doxygen-web.tag.xml for std:: documentation links
-set (SEQAN3_DOXYGEN_STD_TAGFILE "${PROJECT_BINARY_DIR}/cppreference-doxygen-web.tag.xml")
-include (ExternalProject)
-ExternalProject_Add (
-    download-cppreference-doxygen-web-tag
-    URL "https://github.com/PeterFeicht/cppreference-doc/releases/download/v20220730/html-book-20220730.tar.xz"
-    URL_HASH SHA256=71f15003c168b8dc5a00cbaf19b6480a9b3e87ab7e462aa39edb63d7511c028b
-    TLS_VERIFY ON
-    DOWNLOAD_DIR "${PROJECT_BINARY_DIR}"
-    DOWNLOAD_NAME "html-book.tar.xz"
-    DOWNLOAD_NO_EXTRACT YES
-    BINARY_DIR "${PROJECT_BINARY_DIR}"
-    CONFIGURE_COMMAND /bin/sh -c "xzcat html-book.tar.xz | tar -xf - cppreference-doxygen-web.tag.xml"
-    BUILD_COMMAND rm "html-book.tar.xz"
-    INSTALL_COMMAND "")
+# SEQAN3_DOXYGEN_STD_TAGFILE can be used to point to an existing tag file (cppreference-doxygen-web.tag.xml).
+# If SEQAN3_DOXYGEN_STD_TAGFILE is set by the user and the file exists, it will be copied.
+# If SEQAN3_DOXYGEN_STD_TAGFILE is not set by the user, or it is set by the user, but the file does not exist,
+# the tag file will be downloaded.
+set (SEQAN3_DEFAULT_DOXYGEN_STD_TAGFILE "${PROJECT_BINARY_DIR}/cppreference-doxygen-web.tag.xml")
+set (SEQAN3_DOXYGEN_STD_TAGFILE
+     "${SEQAN3_DEFAULT_DOXYGEN_STD_TAGFILE}"
+     CACHE STRING "Path to cppreference-doxygen-web.tag.xml")
+if (NOT EXISTS "${SEQAN3_DOXYGEN_STD_TAGFILE}" OR SEQAN3_DOXYGEN_STD_TAGFILE STREQUAL
+                                                  "${SEQAN3_DEFAULT_DOXYGEN_STD_TAGFILE}")
+    message (STATUS "Tag file will be fetched.")
+    # Reset path in case it was set from the outside, but does not exist.
+    set (SEQAN3_DOXYGEN_STD_TAGFILE "${SEQAN3_DEFAULT_DOXYGEN_STD_TAGFILE}")
+    include (ExternalProject)
+    ExternalProject_Add (
+        download-cppreference-doxygen-web-tag
+        URL "https://github.com/PeterFeicht/cppreference-doc/releases/download/v20220730/html-book-20220730.tar.xz"
+        URL_HASH SHA256=71f15003c168b8dc5a00cbaf19b6480a9b3e87ab7e462aa39edb63d7511c028b
+        TLS_VERIFY ON
+        DOWNLOAD_DIR "${PROJECT_BINARY_DIR}"
+        DOWNLOAD_NAME "html-book.tar.xz"
+        DOWNLOAD_NO_EXTRACT YES
+        BINARY_DIR "${PROJECT_BINARY_DIR}"
+        BUILD_BYPRODUCTS "${SEQAN3_DOXYGEN_STD_TAGFILE}"
+        CONFIGURE_COMMAND /bin/sh -c "xzcat html-book.tar.xz | tar -xf - cppreference-doxygen-web.tag.xml"
+        BUILD_COMMAND rm "html-book.tar.xz"
+        INSTALL_COMMAND "")
+else ()
+    message (STATUS "Copying existing tag file: ${SEQAN3_DOXYGEN_STD_TAGFILE}")
+    # Copy tag file such that it is present in the built documentation. This is useful if the documentation is
+    # subsequently deployed to a server.
+    configure_file ("${SEQAN3_DOXYGEN_STD_TAGFILE}" "${SEQAN3_DEFAULT_DOXYGEN_STD_TAGFILE}" COPYONLY)
+    set (SEQAN3_DOXYGEN_STD_TAGFILE "${SEQAN3_DEFAULT_DOXYGEN_STD_TAGFILE}")
+endif ()
 
 ### TEST HELPER