[gnome-continuous-yocto/gnomeostree-3.28-rocko: 5631/8267] dev-manual, ref-manual: Added PACKAGE_WRITE_DEPS and concept support

[Emmanuele Bassi <ebassi src gnome org>]

commit e2232e6813d503db33bb2fc29b57fbb7a0f7bca0
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Mon Apr 3 11:58:29 2017 -0700

    dev-manual, ref-manual: Added PACKAGE_WRITE_DEPS and concept support
    
    Fixes [YOCTO #11274]
    
    When a post-installation or pre-installation script uses tools that
    have dependencies, you need to specify the tools using the new
    PACKAGE_WRITE_DEPS variable.  I added this information at the end
    of the "Post Installtion Scripts" section in the dev-manual.
    
    I also added a new variable entry for the PACKAGE_WRITE_DEPS variable
    in the glossary.
    
    (From yocto-docs rev: 4d130b63cba5ebabd4af52b62421d387a4b54353)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 .../dev-manual/dev-manual-common-tasks.xml         |   24 +++++++++++++++----
 documentation/ref-manual/ref-variables.xml         |   25 ++++++++++++++++++++
 2 files changed, 44 insertions(+), 5 deletions(-)
---
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml 
b/documentation/dev-manual/dev-manual-common-tasks.xml
index bdf9cfc..f9b2910 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3207,21 +3207,21 @@
                 a package on the target or during image creation when a
                 package is included in an image.
                 To add a post-installation script to a package, add a
-                <filename>pkg_postinst_PACKAGENAME()</filename> function to
+                
<filename>pkg_postinst_</filename><replaceable>PACKAGENAME</replaceable><filename>()</filename> function to
                 the recipe file (<filename>.bb</filename>) and replace
-                <filename>PACKAGENAME</filename> with the name of the package
+                <replaceable>PACKAGENAME</replaceable> with the name of the package
                 you want to attach to the <filename>postinst</filename>
                 script.
                 To apply the post-installation script to the main package
                 for the recipe, which is usually what is required, specify
                 <filename>${</filename><ulink 
url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
-                in place of <filename>PACKAGENAME</filename>.
+                in place of <replaceable>PACKAGENAME</replaceable>.
             </para>
 
             <para>
                 A post-installation function has the following structure:
                 <literallayout class='monospaced'>
-     pkg_postinst_PACKAGENAME() {
+     pkg_postinst_<replaceable>PACKAGENAME</replaceable>() {
      # Commands to carry out
      }
                 </literallayout>
@@ -3250,7 +3250,7 @@
                 To delay script execution until boot time, use the following
                 structure in the post-installation script:
                 <literallayout class='monospaced'>
-     pkg_postinst_PACKAGENAME() {
+     pkg_postinst_<replaceable>PACKAGENAME</replaceable>() {
      if [ x"$D" = "x" ]; then
           # Actions to carry out on the device go here
      else
@@ -3268,6 +3268,20 @@
                 when executed on the first boot.
             </para>
 
+            <para>
+                If you have recipes that use <filename>pkg_postinst</filename>
+                scripts and they require the use of non-standard native
+                tools that have dependencies during rootfs construction, you
+                need to use the
+                <ulink 
url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></ulink>
+                variable in your recipe to list these tools.
+                If you do not use this variable, the tools might be missing and
+                execution of the post-installation script is deferred until
+                first boot.
+                Deferring the script to first boot is undesirable and for
+                read-only rootfs impossible.
+            </para>
+
             <note>
                 Equivalent support for pre-install, pre-uninstall, and
                 post-uninstall scripts exist by way of
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 758de36..ae2abde 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9318,6 +9318,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
+            <info>
+                PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script 
dependencies on native/cross tools."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Specifies a list of dependencies for post-installation and
+                    pre-installation scripts on native/cross tools.
+                    If your post-installation or pre-installation script can
+                    execute at rootfs creation time rather than on the
+                    target but depends on a native tool in order to execute,
+                    you need to list the tools in
+                    <filename>PACKAGE_WRITE_DEPENDS</filename>.
+                </para>
+
+                <para>
+                    For information on running post-installation scripts, see
+                    the
+                    "<ulink 
url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
             <info>
                 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a 
recipe on a per-recipe basis."