summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/ref-tasks.xml9
-rw-r--r--documentation/ref-manual/ref-variables.xml5
-rw-r--r--documentation/ref-manual/technical-details.xml72
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 @@
260 This task runs with the current working directory set to 260 This task runs with the current working directory set to
261 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>, 261 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>,
262 which is the compilation directory. 262 which is the compilation directory.
263 The <filename>do_install</filename> task, as well as other tasks
264 that either directly or indirectly depend on the installed files
265 (e.g.
266 <link linkend='ref-tasks-package'><filename>do_package</filename></link>,
267 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>,
268 and
269 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>),
270 run under
271 <link linkend='fakeroot-and-pseudo'>fakeroot</link>.
263 <note> 272 <note>
264 <title>Caution</title> 273 <title>Caution</title>
265 274
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 @@
2599 <literallayout class='monospaced'> 2599 <literallayout class='monospaced'>
2600 ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image 2600 ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image
2601 </literallayout> 2601 </literallayout>
2602 <note><title>Caution</title>
2603 Tasks that read from or write to this directory should
2604 run under
2605 <link linkend='fakeroot-and-pseudo'>fakeroot</link>.
2606 </note>
2602 </para> 2607 </para>
2603 </glossdef> 2608 </glossdef>
2604 </glossentry> 2609 </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 @@
1020 </section> 1020 </section>
1021</section> 1021</section>
1022 1022
1023<section id='fakeroot-and-pseudo'>
1024 <title>Fakeroot and Pseudo</title>
1025
1026 <para>
1027 Some tasks are easier to implement when allowed to perform certain
1028 operations that are normally reserved for the root user.
1029 For example, the
1030 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1031 task benefits from being able to set the UID and GID of installed files
1032 to arbitrary values.
1033 </para>
1034
1035 <para>
1036 One approach to allowing tasks to perform root-only operations
1037 would be to require BitBake to run as root.
1038 However, this method is cumbersome and has security issues.
1039 The approach that is actually used is to run tasks that benefit from
1040 root privileges in a "fake" root environment.
1041 Within this environment, the task and its child processes believe that
1042 they are running as the root user, and see an internally consistent
1043 view of the filesystem.
1044 As long as generating the final output (e.g. a package or an image)
1045 does not require root privileges, the fact that some earlier steps ran
1046 in a fake root environment does not cause problems.
1047 </para>
1048
1049 <para>
1050 The capability to run tasks in a fake root environment is known as
1051 "fakeroot", which is derived from the BitBake keyword/variable
1052 flag that requests a fake root environment for a task.
1053 In current versions of the OpenEmbedded build system,
1054 the program that implements fakeroot is known as Pseudo.
1055 </para>
1056
1057 <para>
1058 Pseudo overrides system calls through the
1059 <filename>LD_PRELOAD</filename> mechanism to give the
1060 illusion of running as root.
1061 To keep track of "fake" file ownership and permissions resulting from
1062 operations that require root permissions, an sqlite3
1063 database is used.
1064 This database is stored in
1065 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename>
1066 for individual recipes.
1067 Storing the database in a file as opposed to in memory
1068 gives persistence between tasks, and even between builds.
1069 <note><title>Caution</title>
1070 If you add your own task that manipulates the same files or
1071 directories as a fakeroot task, then that task should also run
1072 under fakeroot.
1073 Otherwise, the task will not be able to run root-only operations,
1074 and will not see the fake file ownership and permissions set by the
1075 other task.
1076 You should also add a dependency on
1077 <filename>virtual/fakeroot-native:do_populate_sysroot</filename>,
1078 giving the following:
1079 <literallayout class='monospaced'>
1080 fakeroot do_mytask () {
1081 ...
1082 }
1083 do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
1084 </literallayout>
1085 </note>
1086 For more information, see the
1087 <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink>
1088 variables in the BitBake User Manual.
1089 You can also reference this
1090 <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>
1091 article.
1092 </para>
1093</section>
1094
1023<section id='x32'> 1095<section id='x32'>
1024 <title>x32</title> 1096 <title>x32</title>
1025 1097