From a31ae7708783ae045b38bdfd5cfbfe5983b0ac1d Mon Sep 17 00:00:00 2001
From: Copilot <copilot@example.com>
Date: Mon, 20 Jul 2026 13:10:36 +0200
Subject: [PATCH] migration: add install_bgviewer.sh; make FindBgViewer search
 ./external/BgViewer and respect BGVIEWER_DIR

---
 app/install_bgviewer.sh  | 41 ++++++++++++++++++++++++++++++++++++++++
 cmake/FindBgViewer.cmake | 37 ++++++++++++++++++++++++------------
 2 files changed, 66 insertions(+), 12 deletions(-)
 create mode 100644 app/install_bgviewer.sh

diff --git a/app/install_bgviewer.sh b/app/install_bgviewer.sh
new file mode 100644
index 000000000..19a5b9da7
--- /dev/null
+++ b/app/install_bgviewer.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# install_bgviewer.sh
+# Extract or copy a BgViewer/dtEntity vendor archive or directory into ./external/BgViewer
+# Usage: ./install_bgviewer.sh /path/to/bgviewer.tar.gz_or_dir [target_dir]
+
+SRC="$1"
+TARGET_DIR="${2:-./external/BgViewer}"
+
+if [[ -z "$SRC" ]]; then
+  echo "Usage: $0 /path/to/bgviewer.tar.gz_or_dir [target_dir]"
+  exit 1
+fi
+
+# Create target dir (prefer non-root)
+if ! mkdir -p "$TARGET_DIR" 2>/dev/null; then
+  sudo mkdir -p "$TARGET_DIR"
+fi
+if ! chown $(id -u):$(id -g) "$TARGET_DIR" 2>/dev/null; then
+  sudo chown $(id -u):$(id -g) "$TARGET_DIR" || true
+fi
+
+if [[ -d "$SRC" ]]; then
+  echo "Copying BgViewer directory $SRC -> $TARGET_DIR"
+  rsync -a --delete "$SRC/" "$TARGET_DIR/"
+elif [[ -f "$SRC" ]]; then
+  echo "Extracting archive $SRC -> $TARGET_DIR"
+  case "$SRC" in
+    *.tar.gz|*.tgz) tar xzf "$SRC" -C "$TARGET_DIR" --strip-components=1 ;;
+    *.tar.bz2) tar xjf "$SRC" -C "$TARGET_DIR" --strip-components=1 ;;
+    *.zip) unzip -q "$SRC" -d "$TARGET_DIR" ;;
+    *) echo "Unknown archive format: $SRC"; exit 1 ;;
+  esac
+else
+  echo "Source $SRC not found" >&2
+  exit 1
+fi
+
+echo "BgViewer installed to $TARGET_DIR"
+echo "You may set -DBGVIEWER_DIR=$TARGET_DIR or ensure CMAKE_PREFIX_PATH includes $TARGET_DIR when configuring CMake."
diff --git a/cmake/FindBgViewer.cmake b/cmake/FindBgViewer.cmake
index 624930cd9..e6d1d74d8 100755
--- a/cmake/FindBgViewer.cmake
+++ b/cmake/FindBgViewer.cmake
@@ -21,16 +21,29 @@
 
 
 
-INCLUDE(FindPackageHandleStandardArgs)
-INCLUDE(FindLibraryWithDebug)
-
-FIND_LIBRARY_WITH_DEBUG(BGVIEWER_DTENTITY_LIBRARY WIN32_DEBUG_POSTFIX d dtEntity)
-FIND_LIBRARY_WITH_DEBUG(BGVIEWER_DTENTITYOSG_LIBRARY WIN32_DEBUG_POSTFIX d dtEntityOSG)
-FIND_PATH(BGVIEWER_INCLUDE_DIR dtEntity/export.h)
-
-FIND_PACKAGE_HANDLE_STANDARD_ARGS(BgViewer DEFAULT_MSG
-                                  BGVIEWER_DTENTITY_LIBRARY
-                                  BGVIEWER_DTENTITYOSG_LIBRARY
-                                  BGVIEWER_INCLUDE_DIR)
-SET(BGVIEWER_LIBRARIES ${BGVIEWER_DTENTITYOSG_LIBRARY}
+INCLUDE(FindPackageHandleStandardArgs)
+INCLUDE(FindLibraryWithDebug)
+
+# Allow user to supply BGVIEWER_DIR or check ./external/BgViewer by default
+if(NOT DEFINED BGVIEWER_DIR)
+  if(DEFINED ENV{EXTERNAL_DIR})
+    set(_external_hint "$ENV{EXTERNAL_DIR}")
+  else()
+    set(_external_hint "${CMAKE_SOURCE_DIR}/external")
+  endif()
+  set(BGVIEWER_DIR "${_external_hint}/BgViewer" CACHE PATH "BgViewer root directory (optional)")
+endif()
+
+# Search in common system locations and in BGVIEWER_DIR
+set(_hints "${BGVIEWER_DIR}/lib" "${BGVIEWER_DIR}/lib/*" "${BGVIEWER_DIR}/lib/*/*")
+
+FIND_LIBRARY_WITH_DEBUG(BGVIEWER_DTENTITY_LIBRARY WIN32_DEBUG_POSTFIX d dtEntity HINTS ${_hints})
+FIND_LIBRARY_WITH_DEBUG(BGVIEWER_DTENTITYOSG_LIBRARY WIN32_DEBUG_POSTFIX d dtEntityOSG HINTS ${_hints})
+FIND_PATH(BGVIEWER_INCLUDE_DIR dtEntity/export.h HINTS "${BGVIEWER_DIR}/include" "${BGVIEWER_DIR}/include/dtEntity" ${_hints} )
+
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(BgViewer DEFAULT_MSG
+                                  BGVIEWER_DTENTITY_LIBRARY
+                                  BGVIEWER_DTENTITYOSG_LIBRARY
+                                  BGVIEWER_INCLUDE_DIR)
+SET(BGVIEWER_LIBRARIES ${BGVIEWER_DTENTITYOSG_LIBRARY}
                        ${BGVIEWER_DTENTITY_LIBRARY})