From 1b999acb2fd5e44ec115d5b30c70b326a397a76e Mon Sep 17 00:00:00 2001
From: Dale Glass <dale@daleglass.net>
Date: Wed, 24 Mar 2021 22:16:42 +0100
Subject: [PATCH] Add more explanatory comments

---
 cmake/macros/SetupQt.cmake |  9 ++++++---
 hifi_qt.py                 | 25 +++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/cmake/macros/SetupQt.cmake b/cmake/macros/SetupQt.cmake
index 4676a00e97..743ac934c4 100644
--- a/cmake/macros/SetupQt.cmake
+++ b/cmake/macros/SetupQt.cmake
@@ -5,6 +5,9 @@
 #  See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
 #
 
+# For understanding the execution flow followed by the Qt setup,
+# please look at the comment on top of hifi_qt.py
+
 function(get_sub_directories result curdir)
   file(GLOB children RELATIVE ${curdir} ${curdir}/*)
   set(dirlist "")
@@ -55,7 +58,9 @@ macro(setup_qt)
         # then use it,
         # otherwise, use the vcpkg'ed version
         if(NOT DEFINED QT_CMAKE_PREFIX_PATH)
-            message(FATAL_ERROR "QT_CMAKE_PREFIX_PATH should have been set by hifi_qt.py")
+            # Note: This comes from qt.cmake generated by hifi_qt.py
+            # See the comment on top of hifi_qt.py for details.
+            message(FATAL_ERROR "QT_CMAKE_PREFIX_PATH should have been set by hifi_qt.py through qt.cmake")
         endif()
         if (DEV_BUILD)
           if (DEFINED ENV{QT_CMAKE_PREFIX_PATH})
@@ -63,8 +68,6 @@ macro(setup_qt)
           endif()
         endif()
 
-        message("QT_CMAKE_PREFIX_PATH = " ${QT_CMAKE_PREFIX_PATH})
-
         # figure out where the qt dir is
         get_filename_component(QT_DIR "${QT_CMAKE_PREFIX_PATH}/../../" ABSOLUTE)
         set(QT_VERSION "unknown")
diff --git a/hifi_qt.py b/hifi_qt.py
index 530aaff8ec..56fb3a0ec1 100644
--- a/hifi_qt.py
+++ b/hifi_qt.py
@@ -10,6 +10,31 @@ import json
 import xml.etree.ElementTree as ET
 import functools
 
+# The way Qt is handled is a bit complicated, so I'm documenting it here.
+#
+# 1. User runs cmake
+# 2. cmake calls prebuild.py, which is referenced in /CMakeLists.txt
+# 3. prebuild.py calls this code.
+# 4. hifi_qt.py determines how to handle cmake: do we need to download a package, and which?
+# 4.a - Using system Qt
+#       No download, most special paths are turned off.
+#       We build in the same way a normal Qt program would.
+# 4.b - Using an user-provided Qt build in a custom directory.
+#       We just need to set the cmakePath to the right dir (qt5-install/lib/cmake)
+# 4.c - Using a premade package.
+#       We check the OS and distro and set qtUrl to the URL to download.
+#       After this, it works on the same pathway as 4.b.
+# 5. We write /qt.cmake, which contains paths that are passed down to SetupQt.cmake
+#    The template for this file is in CMAKE_TEMPLATE just below this comment
+#    and it sets the QT_CMAKE_PREFIX_PATH variable used by SetupQt.cmake.
+# 6. cmake includes /qt.cmake receiving our information
+#    In the case of system Qt, this step is skipped.
+# 7. cmake runs SetupQt.cmake which takes care of the cmake parts of the Qt configuration.
+#    In the case of system Qt, SetupQt.cmake is a no-op. It runs but exits immediately.
+#
+# The format for a prebuilt qt is a package containing a top-level directory named
+# 'qt5-install', which contains the result of a "make install" from a build of the Qt source.
+
 print = functools.partial(print, flush=True)
 
 # Encapsulates the vcpkg system