Add docs for new way of defining properties in QtGPHEADdev

Document the new way of defining properties in gradle.properties file
and add deprecation warnings for the old method.

Fixes: QTTA-359
Pick-to: 1.3
Change-Id: Ifd596e49abf8bf90c4780b1d60edf6f7945fa909
Reviewed-by: Nicholas Bennett <[email protected]>

1 files changed, 101 insertions, 24 deletions

diff --git a/src/doc/src/qt-gradle-plugin-topics.qdoc b/src/doc/src/qt-gradle-plugin-topics.qdoc
index 8fab443..45bf1dd 100644
--- a/src/doc/src/qt-gradle-plugin-topics.qdoc
+++ b/src/doc/src/qt-gradle-plugin-topics.qdoc
@@ -138,7 +138,11 @@
     \title Configuring Qt Gradle Plugin
 
     The plugin needs to know where certain parts of the Qt toolchain are.
-    In the \c <yourappname>/app/build.gradle(.kts) file, you need to define paths for the plugin.
+    In the \c <yourappname>/gradle.properties file, you need to define paths
+    for the plugin.
+    \note You can also define them in the \c <yourappname>/app/build.gradle(.kts)
+    file inside a QtBuild block, but this has been deprecated and will be removed
+    in the future.
 
     \section1 Plugins path
     Inside the \b plugins block, include the plugin ID and version.
@@ -160,29 +164,38 @@
     \endcode
     \endtabcontent
 
-    Create a QtBuild block:
-    \badcode
-    QtBuild{
-
-    }
-    \endcode
-
-    Inside the \b QtBuild block, define the following paths.
+    Define the properties as shown.
 
     \section1 QtPath
 
     Qt path for version \minqtpatchversion or newer where the Qt version you want to build against is installed:
 
-    \tab {qtgradle-snippets-qtpath}{tab-kotlin-qtpath}{Kotlin}{checked}
+    \tab {qtgradle-snippets-qtpath}{tab-properties-qtpath}{gradle.properties}{checked}
+    \tab {qtgradle-snippets-qtpath}{tab-kotlin-qtpath}{Kotlin}{}
     \tab {qtgradle-snippets-qtpath}{tab-groovy-qtpath}{Groovy}{}
+    \tabcontent {tab-properties-qtpath}
+    \badcode \minqtpatchversion
+        qt.path=/home/username/Qt/
+    \endcode
+    \endtabcontent
     \tabcontent {tab-kotlin-qtpath}
     \badcode \minqtpatchversion
-        qtPath = file("/home/username/Qt/\1")
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            qtPath = file("/home/username/Qt/\1")
+            ...
+        }
     \endcode
     \endtabcontent
     \tabcontent {tab-groovy-qtpath}
         \badcode \minqtpatchversion
-        qtPath file('/home/username/Qt/\1')
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            qtPath file('/home/username/Qt/\1')
+            ...
+        }
     \endcode
     \endtabcontent
 
@@ -190,16 +203,32 @@
 
     Add the path to the QML project directory:
 
-    \tab {qtgradle-snippets-projectpath}{tab-kotlin-projectpath}{Kotlin}{checked}
+    \tab {qtgradle-snippets-projectpath}{tab-properties-projectpath}{gradle.properties}{checked}
+    \tab {qtgradle-snippets-projectpath}{tab-kotlin-projectpath}{Kotlin}{}
     \tab {qtgradle-snippets-projectpath}{tab-groovy-projectpath}{Groovy}{}
+    \tabcontent {tab-properties-projectpath}
+    \badcode \minqtpatchversion
+        qt.projectPath=../qmlapp
+    \endcode
+    \endtabcontent
     \tabcontent {tab-kotlin-projectpath}
     \badcode
-        projectPath = file("../qmlapp")
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            projectPath = file("../qmlapp")
+            ...
+        }
     \endcode
     \endtabcontent
     \tabcontent {tab-groovy-projectpath}
     \badcode
-        projectPath = file('../qmlapp')
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            projectPath = file('../qmlapp')
+            ...
+        }
     \endcode
     \endtabcontent
 
@@ -210,16 +239,32 @@
     By default, this is not defined, and Multi-ABIs will be built. If this path is defined,
     then a build will be done for that kit ABI only.
 
-    \tab {qtgradle-snippets-qtKitDir}{tab-kotlin-qtKitDir}{Kotlin}{checked}
+    \tab {qtgradle-snippets-qtKitDir}{tab-properties-qtKitDir}{gradle.properties}{checked}
+    \tab {qtgradle-snippets-qtKitDir}{tab-kotlin-qtKitDir}{Kotlin}{}
     \tab {qtgradle-snippets-qtKitDir}{tab-groovy-qtKitDir}{Groovy}{}
+    \tabcontent {tab-properties-qtKitDir}
+    \badcode \minqtpatchversion
+        qt.kitDir=/home/username/qt/build/your-qt-kit
+    \endcode
+    \endtabcontent
     \tabcontent {tab-kotlin-qtKitDir}
     \badcode
-        qtKitDir = file("/home/username/qt/build/your-qt-kit")
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            qtKitDir = file("/home/username/qt/build/your-qt-kit")
+            ...
+        }
     \endcode
     \endtabcontent
     \tabcontent {tab-groovy-qtKitDir}
     \badcode
-        qtKitDir = file('/home/username/qt/build/your-qt-kit')
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            qtKitDir = file('/home/username/qt/build/your-qt-kit')
+            ...
+        }
     \endcode
     \endtabcontent
 
@@ -227,16 +272,32 @@
 
     For example:
 
-    \tab {qtgradle-snippets-cmakearg}{tab-kotlin-cmakearg}{Kotlin}{checked}
+    \tab {qtgradle-snippets-cmakearg}{tab-properties-cmakearg}{gradle.properties}{checked}
+    \tab {qtgradle-snippets-cmakearg}{tab-kotlin-cmakearg}{Kotlin}{}
     \tab {qtgradle-snippets-cmakearg}{tab-groovy-cmakearg}{Groovy}{}
+    \tabcontent {tab-properties-cmakearg}
+    \badcode \minqtpatchversion
+        qt.extraCMakeArguments=-DCMAKE_BUILD_TYPE=Release,-DANDROID_NDK_ROOT=/opt/android/ndk/26.1.10909125
+    \endcode
+    \endtabcontent
     \tabcontent {tab-kotlin-cmakearg}
     \badcode
-        setExtraCMakeArguments("-DCMAKE_BUILD_TYPE=Release", "-DANDROID_NDK_ROOT=/opt/android/ndk/26.1.10909125")
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            setExtraCMakeArguments("-DCMAKE_BUILD_TYPE=Release", "-DANDROID_NDK_ROOT=/opt/android/ndk/26.1.10909125")
+            ...
+        }
     \endcode
     \endtabcontent
     \tabcontent {tab-groovy-cmakearg}
     \badcode
-        extraCMakeArguments = ['-DCMAKE_BUILD_TYPE=Release', '-DANDROID_NDK_ROOT=/opt/android/ndk/26.1.10909125']
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            extraCMakeArguments = ['-DCMAKE_BUILD_TYPE=Release', '-DANDROID_NDK_ROOT=/opt/android/ndk/26.1.10909125']
+            ...
+        }
     \endcode
     \endtabcontent
 
@@ -245,16 +306,32 @@
     If you haven't installed Ninja from the Qt Maintenance Tool and its location is
     not defined in your system path, you can provide the path as follows:
 
-    \tab {qtgradle-snippets-ninja}{tab-kotlin-ninja}{Kotlin}{checked}
+    \tab {qtgradle-snippets-ninja}{tab-properties-ninja}{gradle.properties}{checked}
+    \tab {qtgradle-snippets-ninja}{tab-kotlin-ninja}{Kotlin}{}
     \tab {qtgradle-snippets-ninja}{tab-groovy-ninja}{Groovy}{}
+    \tabcontent {tab-properties-ninja}
+    \badcode \minqtpatchversion
+        qt.ninjaPath=C:\Qt\Tools\Ninja
+    \endcode
+    \endtabcontent
     \tabcontent {tab-kotlin-ninja}
     \badcode
-        ninjaPath = "C:\Qt\Tools\Ninja"
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            ninjaPath = "C:\Qt\Tools\Ninja"
+            ...
+        }
     \endcode
     \endtabcontent
     \tabcontent {tab-groovy-ninja}
     \badcode
-        ninjaPath = 'C:\Qt\Tools\Ninja'
+        // Deprecated. Use gradle.properties instead
+        QtBuild {
+            ...
+            ninjaPath = 'C:\Qt\Tools\Ninja'
+            ...
+        }
     \endcode
     \endtabcontent
 */