Doc: Add information about postLoad usage in scripts

Task-number: QTIFW-2860
Change-Id: Icadb39c13279d3614179f8e16d33be696198a74c
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Arttu Tarkiainen <arttu.tarkiainen@qt.io>

2 files changed, 28 insertions, 5 deletions

diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc
index 6e403dc6b..476234f80 100644
--- a/doc/installerfw.qdoc
+++ b/doc/installerfw.qdoc
@@ -945,16 +945,15 @@
         \row
             \li Script
             \li File name of a script being loaded. Optional.
-                Specifying the \c {postLoad="True"} attribute will cause the script
+                Specifying the \c {postLoad="true"} attribute will cause the script
                 to be loaded only to the component that is selected for update or
                 install. With the attribute, the script is loaded right before the
                 component installation starts. This will speed up the installer
                 if there are large amounts of components with install scripts in the
                 repository. Make sure the script does not contain anything that needs
-                to be evaluated before the install tree is shown, like setting \c
-                <Default> to \c true. Both \c <Script postLoad="True"> and
-                \c <Script> tags can be used at the same time.
-                For more information, see \l{Adding Operations}.
+                to be evaluated before the install tree view is shown.
+                For more information, see \l{Adding Operations} and
+                \l{Using postLoad in component script}.
         \row
             \li UserInterfaces
             \li List of pages to load. To add several pages, add several
diff --git a/doc/scripting.qdoc b/doc/scripting.qdoc
index bb547a0d6..8854442fa 100644
--- a/doc/scripting.qdoc
+++ b/doc/scripting.qdoc
@@ -375,4 +375,28 @@
             \li ApplicationsDirX64
             \li \c {C:\Program Files}
     \endtable
+
+    \section1 Using postLoad in Component Script
+    By default, component scripts are evaluated before the install tree view
+    is shown. This can have performance cost if there is a huge amount of
+    components with component scripts. The \c postLoad attribute introduces a way
+    to evaluate the component script right before installation starts, only for
+    the components that are selected for installation or update:
+    \code
+    <Script postLoad="true">my_install_script.qs</Script>
+    \endcode
+    Whether \c postLoad can be set to \c true must be considered case by case,
+    depending on the contents of the script. For example, if the script contents
+    affect the install tree view, like setting \c <Default> to \c true, setting
+    new dependencies, or adding new wizard pages, \c postLoad must not be used or
+    it must be set to \c false. If the script contains only methods
+    that are run during the installation, \c postLoad can be set to \c true. For
+    example, all overridden \c operation functions are run during installation.
+    For more information, see \l {Adding Operations to Components}. If you are not
+    sure when to use \c postLoad, then don't use it. The performance cost is
+    huge only when there are thousands of scripts to be evaluated.
+
+    Both \c <Script postLoad="true"> and \c <Script> tags can be used at the same time.
+    This means that one component can have one script that is evaluated when the installation
+    starts and another script that is evaluated before the install tree view is shown.
 */