ref-manual: Added and updated variables to support calling functions

Fixed [YOCTO #7632]

Looked for, updated, and added (if necessary) the following
variables:

 * ROOTFS_PREPROCESS_COMMAND
 * ROOTFS_POSTPROCESS_COMMAND
 * SDK_POSTPROCESS_COMMAND
 * POPULATE_SDK_POST_TARGET_COMMAND
 * POPULATE_SDK_POST_HOST_COMMAND,
 * IMAGE_POSTPROCESS_COMMAND
 * IMAGE_PREPROCESS_COMMAND
 * ROOTFS_POSTUNINSTALL_COMMAND
 * ROOTFS_POSTINSTALL_COMMAND

Each of these variables no longer accepts arbitrary shell commands but
rather functions.  The wordings now support that behavior.

Also, updated the migration section for going to 1.6 release to note
this change.

(From yocto-docs rev: e1ab48f7def9d1eb080e007b88f75172470b8007)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 243 insertions, 15 deletions

diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 7c78c9dd50..984485ede2 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1413,6 +1413,35 @@
                 it encounters the variable.
             </para>
         </section>
+
+        <section id='migration-1.6-variable-changes-variable-entry-behavior'>
+            <title>Preprocess and Post Process Command Variable Behavior</title>
+
+            <para>
+                The following variables now expect a semicolon separated
+                list of functions to call and not arbitrary shell commands:
+                <literallayout class='monospaced'>
+     <link linkend='var-ROOTFS_PREPROCESS_COMMAND'>ROOTFS_PREPROCESS_COMMAND</link>
+     <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'>ROOTFS_POSTPROCESS_COMMAND</link>
+     <link linkend='var-SDK_POSTPROCESS_COMMAND'>SDK_POSTPROCESS_COMMAND</link>
+     <link linkend='var-POPULATE_SDK_POST_TARGET_COMMAND'>POPULATE_SDK_POST_TARGET_COMMAND</link>
+     <link linkend='var-POPULATE_SDK_POST_HOST_COMMAND'>POPULATE_SDK_POST_HOST_COMMAND</link>
+     <link linkend='var-IMAGE_POSTPROCESS_COMMAND'>IMAGE_POSTPROCESS_COMMAND</link>
+     <link linkend='var-IMAGE_PREPROCESS_COMMAND'>IMAGE_PREPROCESS_COMMAND</link>
+     <link linkend='var-ROOTFS_POSTUNINSTALL_COMMAND'>ROOTFS_POSTUNINSTALL_COMMAND</link>
+     <link linkend='var-ROOTFS_POSTINSTALL_COMMAND'>ROOTFS_POSTINSTALL_COMMAND</link>
+                </literallayout>
+                For migration purposes, you can simply wrap shell commands in
+                a shell function and then call the function.
+                Here is an example:
+                <literallayout class='monospaced'>
+     my_postprocess_function() {
+        echo "hello" > ${IMAGE_ROOTFS}/hello.txt
+     }
+     ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
+                </literallayout>
+            </para>
+        </section>
     </section>
 
     <section id='migration-1.6-directory-layout-changes'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index dfe775b23f..e70445762f 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -5433,24 +5433,50 @@
 
         <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
             <info>
-                IMAGE_POSTPROCESS_COMMAND[doc] = "Added by classes to run post processing commands once the OpenEmbedded build system has created the image."
+                IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the final image output files."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    Added by classes to run post processing commands once the
-                    OpenEmbedded build system has created the image.
-                    You can specify shell commands separated by semicolons:
+                    Specifies a list of functions to call once the
+                    OpenEmbedded build system has created the final image
+                    output files.
+                    You can specify functions separated by semicolons:
                     <literallayout class='monospaced'>
-     IMAGE_POSTPROCESS_COMMAND += "<replaceable>shell_command</replaceable>; ... "
+     IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
                     </literallayout>
                 </para>
 
                 <para>
-                    If you need to pass the path to the root filesystem within
-                    the command, you can use
+                    If you need to pass the root filesystem path to a command
+                    within the function, you can use
                     <filename>${IMAGE_ROOTFS}</filename>, which points to
-                    the root filesystem image.
+                    the directory that becomes the root filesystem image.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
+            <info>
+                IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the final image output files."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call before the
+                    OpenEmbedded build system has created the final image
+                    output files.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass the root filesystem path to a command
+                    within the function, you can use
+                    <filename>${IMAGE_ROOTFS}</filename>, which points to
+                    the directory that becomes the root filesystem image.
                 </para>
             </glossdef>
         </glossentry>
@@ -8948,6 +8974,64 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
+            <info>
+                POPULATE_SDK_POST_HOST_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created host part of the SDK."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call once the
+                    OpenEmbedded build system has created the host part of
+                    the SDK.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass the SDK path to a command
+                    within a function, you can use
+                    <filename>${SDK_DIR}</filename>, which points to
+                    the parent directory used by the OpenEmbedded build
+                    system when creating SDK output.
+                    See the
+                    <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
+                    variable for more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
+            <info>
+                POPULATE_SDK_POST_TARGET_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created target part of the SDK."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call once the
+                    OpenEmbedded build system has created the target part of
+                    the SDK.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass the SDK path to a command
+                    within a function, you can use
+                    <filename>${SDK_DIR}</filename>, which points to
+                    the parent directory used by the OpenEmbedded build
+                    system when creating SDK output.
+                    See the
+                    <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
+                    variable for more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PR'><glossterm>PR</glossterm>
             <info>
                 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
@@ -9691,26 +9775,113 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
+            <info>
+                ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call after the
+                    OpenEmbedded build system has installed packages.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass the root filesystem path to a command
+                    within a function, you can use
+                    <filename>${IMAGE_ROOTFS}</filename>, which points to
+                    the directory that becomes the root filesystem image.
+                    See the
+                    <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
+                    variable for more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
             <info>
-                ROOTFS_POSTPROCESS_COMMAND[doc] = "Added by classes to run post processing commands once the OpenEmbedded build system has created the root filesystem."
+                ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call once the
+                    OpenEmbedded build system has created the root filesystem.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass the root filesystem path to a command
+                    within a function, you can use
+                    <filename>${IMAGE_ROOTFS}</filename>, which points to
+                    the directory that becomes the root filesystem image.
+                    See the
+                    <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
+                    variable for more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
+            <info>
+                ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call after the
+                    OpenEmbedded build system has removed unnecessary
+                    packages.
+                    When runtime package management is disabled in the
+                    image, several packages are removed including
+                    <filename>base-passwd</filename>,
+                    <filename>shadow</filename>, and
+                    <filename>update-alternatives</filename>.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass the root filesystem path to a command
+                    within a function, you can use
+                    <filename>${IMAGE_ROOTFS}</filename>, which points to
+                    the directory that becomes the root filesystem image.
+                    See the
+                    <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
+                    variable for more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
+            <info>
+                ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    Added by classes to run post processing commands once the
+                    Specifies a list of functions to call before the
                     OpenEmbedded build system has created the root filesystem.
-                    You can specify shell commands separated by semicolons:
+                    You can specify functions separated by semicolons:
                     <literallayout class='monospaced'>
-     ROOTFS_POSTPROCESS_COMMAND += "<replaceable>shell_command</replaceable>; ... "
+     ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
                     </literallayout>
                 </para>
 
                 <para>
-                    If you need to pass the path to the root filesystem within
-                    the command, you can use
+                    If you need to pass the root filesystem path to a command
+                    within a function, you can use
                     <filename>${IMAGE_ROOTFS}</filename>, which points to
-                    the root filesystem image.
+                    the directory that becomes the root filesystem image.
                     See the
                     <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
                     variable for more information.
@@ -10182,6 +10353,34 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
+            <info>
+                SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the SDK."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of functions to call once the
+                    OpenEmbedded build system has created the SDK.
+                    You can specify functions separated by semicolons:
+                    <literallayout class='monospaced'>
+     SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you need to pass an SDK path to a command within a
+                    function, you can use
+                    <filename>${SDK_DIR}</filename>, which points to
+                    the parent directory used by the OpenEmbedded build system
+                    when creating SDK output.
+                    See the
+                    <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
+                    variable for more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
             <info>
                 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."