dev-manual: Changes to the read-only root filesystem section.

Applied the review comments from Paul Eggleton to augment this
section with more information.

Performed a spell check on the entire chapter.

Made the term "postinstall" consistent by defining its first
use in sections a "post-installation (postinstall) script".

(From yocto-docs rev: 179f478777fd02e3fa56d80951ce3eab350fc189)

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

1 files changed, 118 insertions, 30 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 70ecc2276a..f8b41bf54d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1022,10 +1022,11 @@
         </section>
 
         <section id='usingpoky-extend-addpkg-postinstalls'>
-            <title>Post Install Scripts</title>
+            <title>Post-Installation Scripts</title>
 
             <para>
-                To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME()
+                To add a post-installation (postinstall) script to a package,
+                add a <filename>pkg_postinst_PACKAGENAME()
                 </filename> function to the <filename>.bb</filename> file and use
                 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
                 <filename>postinst</filename> script.
@@ -1488,7 +1489,7 @@
                 These situations almost always exist when a library API
                 changes and you have multiple pieces of software that
                 depend on the separate versions of the library.
-                To accomodate these situations, you can install multiple
+                To accommodate these situations, you can install multiple
                 versions of the same library in parallel on the same system.
             </para>
 
@@ -2297,7 +2298,7 @@
                 your own distribution.
                 You can use the Yocto Project out-of-the-box to create the
                 <filename>poky-tiny</filename> distribution.
-                Ulitmately, you will want to make changes in your own
+                Ultimately, you will want to make changes in your own
                 distribution that are likely modeled after
                 <filename>poky-tiny</filename>.
                 <note>
@@ -2870,7 +2871,7 @@
             <para>
                 If you have more than one distribution alias, separate them with a space.
                 Note that the build system currently automatically checks the
-                Fedora, OpenSuSE, Debian, Ubuntu,
+                Fedora, OpenSUSE, Debian, Ubuntu,
                 and Mandriva distributions for source package recipes without having to specify them
                 using the <filename>DISTRO_PN_ALIAS</filename> variable.
                 For example, the following command generates a report that lists the Linux distributions
@@ -3447,8 +3448,8 @@
         <title>Creating a Read-Only Root Filesystem</title>
 
         <para>
-            Suppose, for security reasons, you need to disable the
-            your target device's root filesystem's write permisions
+            Suppose, for security reasons, you need to disable
+            your target device's root filesystem's write permissions
             (i.e. you need a read-only root filesystem).
             Or, perhaps you are running the device's operating system
             from a read-only storage device.
@@ -3456,34 +3457,121 @@
             that behavior.
         </para>
 
-        <para>
-            To create a read-only root filesystem, simply add the
-            "read-only-rootfs" feature to your image.
-            Using either of the following statements in your
-            image recipe or from within the
-            <filename>local.conf</filename> file found in the Build
-            Directory causes the build system to create a
-            read-only root filesystem:
-            <literallayout class='monospaced'>
+        <note>
+            Supporting a read-only root filesystem requires that the system and
+            applications do not try to write to the root filesystem.
+            If writes are attempted, they need to gracefully fail.
+        </note>
+
+        <section id='post-installation-scripts'>
+            <title>Post-Installation Scripts</title>
+
+            <para>
+                It is very important that you make sure all
+                Post-Installation (postinstall) scripts
+                for packages that are installed into the image can be run
+                at the time when the root filesystem is created during the
+                build on the host system.
+                These scripts cannot attempt to run during first-boot on the
+                target device.
+                With the read-only root filesystem feature enabled,
+                the build system checks during root filesystem creation to make
+                sure all postinstall scripts succeed.
+                If any of these scripts still need to be run after the root
+                filesystem is created, the build immediately fails.
+                These checks during build time ensure that the build fails
+                rather than the target device fails later during its
+                initial boot operation.
+            </para>
+
+            <para>
+                Most of the common postinstall scripts generated by the build
+                system for the out-of-the-box Yocto Project are engineered
+                so that they can run during root filesystem creation
+                (e.g. postinstall scripts for caching fonts).
+                However, if you create and add custom scripts, you need
+                to be sure they can be run during file system creation.
+            </para>
+
+            <para>
+                Here are some common problems that prevent postinstall
+                scripts from running during root filesystem creation:
+                <itemizedlist>
+                    <listitem><para>Not using
+                        <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
+                        in front of absolute paths.
+                        The build system defines <filename>$D</filename>, and
+                        it is blank when run on the target device.
+                        This implies two purposes for <filename>$D</filename>:
+                        ensuring paths are valid in both the host and target
+                        environments, and checking to determine which
+                        environment is being used as a method for taking
+                        appropriate actions.
+                        </para></listitem>
+                    <listitem><para>Attempting to run processes that are
+                        specific to or dependent on the target
+                        architecture.
+                        You can work around these attempts by using native
+                        tools to accomplish the same processes (tasks), or
+                        by alternatively running the processes under QEMU,
+                        which has the <filename>qemu_run_binary</filename>
+                        function.
+                        For more information, see the
+                        <filename>meta/classes/qemu.bbclass</filename>
+                        class in the
+                        <link linkend='source-directory'>Source Directory</link>.
+                        </para></listitem>
+                    <listitem><para>Using hardware features specific to the machine.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='areas-with-write-access'>
+            <title>Areas With Write Access</title>
+
+            <para>
+                With the read-only root filesystem feature enabled, any
+                attempt by the target to write to the root filesystem at
+                runtime fails.
+                Consequently, you must make sure that you configure processes
+                and applications that attempt these types of writes do so
+                to directories with write access (i.e.
+                <filename>/tmp</filename> or <filename>/var/run</filename>).
+            </para>
+        </section>
+
+        <section id='creating-the-root-filesystem'>
+            <title>Creating the Root Filesystem</title>
+
+            <para>
+                To create the read-only root filesystem, simply add the
+                "read-only-rootfs" feature to your image.
+                Using either of the following statements in your
+                image recipe or from within the
+                <filename>local.conf</filename> file found in the
+                <link linkend='build-directory'>Build Directory</link>
+                causes the build system to create a read-only root filesystem:
+                <literallayout class='monospaced'>
      IMAGE_FEATURES = "read-only-rootfs"
-            </literallayout>
-            or
-            <literallayout class='monospaced'>
+                </literallayout>
+                or
+                <literallayout class='monospaced'>
      EXTRA_IMAGE_FEATURES = "read-only-rootfs"
-            </literallayout>
-        </para>
+                </literallayout>
+            </para>
 
-        <para>
-            For more information on how to use these variables, see the
-            "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
-            section.
-            For information on the variables, see
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
-            and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
-        </para>
+            <para>
+                For more information on how to use these variables, see the
+                "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
+                section.
+                For information on the variables, see
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
+            </para>
+        </section>
     </section>
 
-
     <section id="platdev-gdb-remotedebug">
         <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>