ref-manual: New "Fakeroot and Pseudo" section.

Fixes [YOCTO #10060]

I provided a new section in the Technical Details chapter.  Also
some extra explanation was added to both the do_install task and to
the D variable.

(From yocto-docs rev: 565fb11d72bf8c585469bcf65f92b6738e344813)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 86 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index d6f0051f16..b0a65a989b 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -260,6 +260,15 @@
             This task runs with the current working directory set to
             <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>,
             which is the compilation directory.
+            The <filename>do_install</filename> task, as well as other tasks
+            that either directly or indirectly depend on the installed files
+            (e.g.
+            <link linkend='ref-tasks-package'><filename>do_package</filename></link>,
+            <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>,
+            and
+            <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>),
+            run under
+            <link linkend='fakeroot-and-pseudo'>fakeroot</link>.
             <note>
                 <title>Caution</title>
 
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 3fe5cc3c2d..2507d4b520 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2599,6 +2599,11 @@
                     <literallayout class='monospaced'>
      ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image
                     </literallayout>
+                    <note><title>Caution</title>
+                        Tasks that read from or write to this directory should
+                        run under
+                        <link linkend='fakeroot-and-pseudo'>fakeroot</link>.
+                    </note>
                 </para>
             </glossdef>
         </glossentry>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 8535d2c6e8..5ef764c8e0 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -1020,6 +1020,78 @@
     </section>
 </section>
 
+<section id='fakeroot-and-pseudo'>
+    <title>Fakeroot and Pseudo</title>
+
+    <para>
+        Some tasks are easier to implement when allowed to perform certain
+        operations that are normally reserved for the root user.
+        For example, the
+        <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+        task benefits from being able to set the UID and GID of installed files
+        to arbitrary values.
+    </para>
+
+    <para>
+        One approach to allowing tasks to perform root-only operations
+        would be to require BitBake to run as root.
+        However, this method is cumbersome and has security issues.
+        The approach that is actually used is to run tasks that benefit from
+        root privileges in a "fake" root environment.
+        Within this environment, the task and its child processes believe that
+        they are running as the root user, and see an internally consistent
+        view of the filesystem.
+        As long as generating the final output (e.g. a package or an image)
+        does not require root privileges, the fact that some earlier steps ran
+        in a fake root environment does not cause problems.
+    </para>
+
+    <para>
+        The capability to run tasks in a fake root environment is known as
+        "fakeroot", which is derived from the BitBake keyword/variable
+        flag that requests a fake root environment for a task.
+        In current versions of the OpenEmbedded build system,
+        the program that implements fakeroot is known as Pseudo.
+    </para>
+
+    <para>
+        Pseudo overrides system calls through the
+        <filename>LD_PRELOAD</filename> mechanism to give the
+        illusion of running as root.
+        To keep track of "fake" file ownership and permissions resulting from
+        operations that require root permissions, an sqlite3
+        database is used.
+        This database is stored in
+        <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename>
+        for individual recipes.
+        Storing the database in a file as opposed to in memory
+        gives persistence between tasks, and even between builds.
+        <note><title>Caution</title>
+            If you add your own task that manipulates the same files or
+            directories as a fakeroot task, then that task should also run
+            under fakeroot.
+            Otherwise, the task will not be able to run root-only operations,
+            and will not see the fake file ownership and permissions set by the
+            other task.
+            You should also add a dependency on
+            <filename>virtual/fakeroot-native:do_populate_sysroot</filename>,
+            giving the following:
+            <literallayout class='monospaced'>
+       fakeroot do_mytask () {
+           ...
+       }
+       do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
+            </literallayout>
+        </note>
+        For more information, see the
+        <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink>
+        variables in the BitBake User Manual.
+        You can also reference this
+        <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>
+        article.
+    </para>
+</section>
+
 <section id='x32'>
     <title>x32</title>