1 files changed, 106 insertions, 0 deletions

diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
index bc147ce70a..72ff0d6fda 100644
--- a/documentation/ref-manual/faq.xml
+++ b/documentation/ref-manual/faq.xml
@@ -682,6 +682,112 @@
         </answer>
     </qandaentry>
 
+    <qandaentry>
+        <question>
+            <para>
+                Why do <filename>${bindir}</filename> and <filename>${libdir}</filename> have strange values for <filename>-native</filename> recipes?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Executables and libraries might need to be used from a
+                directory other than the directory into which they were
+                initially installed.
+                Complicating this situation is the fact that sometimes these
+                executables and libraries are compiled with the expectation
+                of being run from that initial installation target directory.
+                If this is the case, moving them causes problems.
+            </para>
+
+            <para>
+                This scenario is a fundamental problem for package maintainers
+                of mainstream Linux distributions as well as for the
+                OpenEmbedded build system.
+                As such, a well-established solution exists.
+                Makefiles, Autotools configuration scripts, and other build
+                systems are expected to respect environment variables such as
+                <filename>bindir</filename>, <filename>libdir</filename>,
+                and <filename>sysconfdir</filename> that indicate where
+                executables, libraries, and data reside when a program is
+                actually run.
+                And, they are also expected to respect a
+                <filename>DESTDIR</filename> environment variable, which is
+                prepended to all the other variables when the build system
+                actually installs the files.
+                It is understood that the program does not actually run from
+                within <filename>DESTDIR</filename>.
+            </para>
+
+            <para>
+                When the OpenEmbedded build system uses a recipe to build a
+                target-architecture program (i.e. one that is intended for
+                inclusion on the image being built), that program eventually
+                runs from the root file system of that image.
+                Thus, the build system provides a value of "/usr/bin" for
+                <filename>bindir</filename>, a value of "/usr/lib" for
+                <filename>libdir</filename>, and so forth.
+            </para>
+
+            <para>
+                Meanwhile, <filename>DESTDIR</filename> is a path within the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                However, when the recipe builds a native program (i.e. one
+                that is intended to run on the build machine), that program
+                is never installed directly to the build machine's root
+                file system.
+                Consequently, the build system uses paths within the Build
+                Directory for <filename>DESTDIR</filename>,
+                <filename>bindir</filename> and related variables.
+                To better understand this, consider the following two paths
+                where the first is relatively normal and the second is not:
+                <note>
+                    Due to these lengthy examples, the paths are artificially
+                    broke across lines for readability.
+                </note>
+                <literallayout class='monospaced'>
+     /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
+        1.2.8-r0/sysroot-destdir/usr/bin
+
+     /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
+        zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
+        build/tmp/sysroots/x86_64-linux/usr/bin
+                </literallayout>
+                The standard <filename>DESTDIR</filename> mechanism leaves no
+                other choice.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                The files provided by my <filename>-native</filename> recipe do
+                not appear to be available to other recipes.
+                Files are missing from the native sysroot, my recipe is
+                installing to the wrong place, or I am getting permissions
+                errors during the do_install task in my recipe! What is wrong?
+            </para>
+        </question>
+        <answer>
+            <para>
+                This situation results when the OpenEmbedded build system does
+                not recognize the environment variables supplied to it by
+                <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+                The incident that prompted this FAQ entry involved a Makefile
+                that used an environment variable named
+                <filename>BINDIR</filename> instead of the more standard
+                variable <filename>bindir</filename>.
+                The makefile's hardcoded default value of "/usr/bin" worked
+                most of the time, but not for the recipe's
+                <filename>-native</filename> variant.
+                Consequently, permissions errors might be caused by a Makefile
+                that ignores <filename>DESTDIR</filename> or uses a different
+                name for that environment variable.
+                Check the OpenEmbedded build system to see if these kinds of
+                issues exist.
+            </para>
+        </answer>
+    </qandaentry>
 
 </qandaset>
 </chapter>