Squashed 'yocto-poky/' content from commit ea562de
git-subtree-dir: yocto-poky
git-subtree-split: ea562de57590c966cd5a75fda8defecd397e6436
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
new file mode 100644
index 0000000..197d490
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,817 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='faq'>
+<title>FAQ</title>
+<qandaset>
+ <qandaentry>
+ <question>
+ <para>
+ How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The term "<ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>"
+ refers to the specific reference build system that
+ the Yocto Project provides.
+ Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
+ and <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+ Thus, the generic term used here for the build system is
+ the "OpenEmbedded build system."
+ Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
+ changes always being merged to OE-Core or BitBake first before being pulled back
+ into Poky.
+ This practice benefits both projects immediately.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para id='faq-not-meeting-requirements'>
+ My development system does not meet the
+ required Git, tar, and Python versions.
+ In particular, I do not have Python 2.7.3 or greater, or
+ I do have Python 3.x, which is specifically not supported by
+ the Yocto Project.
+ Can I still use the Yocto Project?
+ </para>
+ </question>
+ <answer>
+ <para>
+ You can get the required tools on your host development
+ system a couple different ways (i.e. building a tarball or
+ downloading a tarball).
+ See the
+ "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
+ section for steps on how to update your build tools.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How can you claim Poky / OpenEmbedded-Core is stable?
+ </para>
+ </question>
+ <answer>
+ <para>
+ There are three areas that help with stability;
+ <itemizedlist>
+ <listitem><para>The Yocto Project team keeps
+ <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
+ and focused, containing around 830 recipes as opposed to the thousands
+ available in other OpenEmbedded community layers.
+ Keeping it small makes it easy to test and maintain.</para></listitem>
+ <listitem><para>The Yocto Project team runs manual and automated tests
+ using a small, fixed set of reference hardware as well as emulated
+ targets.</para></listitem>
+ <listitem><para>The Yocto Project uses an autobuilder,
+ which provides continuous build and integration tests.</para></listitem>
+ </itemizedlist>
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How do I get support for my board added to the Yocto Project?
+ </para>
+ </question>
+ <answer>
+ <para>
+ Support for an additional board is added by creating a
+ Board Support Package (BSP) layer for it.
+ For more information on how to create a BSP layer, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Manual and the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+ </para>
+ <para>
+ Usually, if the board is not completely exotic, adding support in
+ the Yocto Project is fairly straightforward.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ Are there any products built using the OpenEmbedded build system?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
+ is built using the OpenEmbedded build system.
+ See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
+ website for more information.
+ There are a number of pre-production devices using the OpenEmbedded build system
+ and the Yocto Project team
+ announces them as soon as they are released.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ What does the OpenEmbedded build system produce as output?
+ </para>
+ </question>
+ <answer>
+ <para>
+ Because you can use the same set of recipes to create output of
+ various formats, the output of an OpenEmbedded build depends on
+ how you start it.
+ Usually, the output is a flashable image ready for the target
+ device.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How do I add my package to the Yocto Project?
+ </para>
+ </question>
+ <answer>
+ <para>
+ To add a package, you need to create a BitBake recipe.
+ For information on how to create a BitBake recipe, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
+ in the Yocto Project Development Manual.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ Do I have to reflash my entire board with a new Yocto Project image when recompiling
+ a package?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The OpenEmbedded build system can build packages in various
+ formats such as IPK for OPKG, Debian package
+ (<filename>.deb</filename>), or RPM.
+ You can then upgrade the packages using the package tools on
+ the device, much like on a desktop distribution such as
+ Ubuntu or Fedora.
+ However, package management on the target is entirely optional.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
+ What is wrong?
+ </para>
+ </question>
+ <answer>
+ <para>
+ You are probably running the build on an NTFS filesystem.
+ Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
+ </para>
+ </answer>
+ </qandaentry>
+
+<!-- <qandaentry>
+ <question>
+ <para>
+ How do I make the Yocto Project work in RHEL/CentOS?
+ </para>
+ </question>
+ <answer>
+ <para>
+ To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
+ install some required packages.
+ The standard CentOS packages needed are:
+ <itemizedlist>
+ <listitem><para>"Development tools" (selected during installation)</para></listitem>
+ <listitem><para><filename>texi2html</filename></para></listitem>
+ <listitem><para><filename>compat-gcc-34</filename></para></listitem>
+ </itemizedlist>
+ On top of these, you need the following external packages:
+ <itemizedlist>
+ <listitem><para><filename>python-sqlite2</filename> from
+ <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
+ </para></listitem>
+ <listitem><para><filename>help2man</filename> from
+ <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Once these packages are installed, the OpenEmbedded build system will be able
+ to build standard images.
+ However, there might be a problem with the QEMU emulator segfaulting.
+ You can either disable the generation of binary locales by setting
+ <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
+ </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
+ from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
+ </para>
+
+ <note>
+ <para>For information on distributions that the Yocto Project
+ uses during validation, see the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
+ Wiki page.</para>
+ <para>For notes about using the Yocto Project on a RHEL 4-based
+ host, see the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
+ Wiki page.</para>
+ </note>
+ </answer>
+ </qandaentry> -->
+
+ <qandaentry>
+ <question>
+ <para>
+ I see lots of 404 responses for files on
+ <filename>&YOCTO_HOME_URL;/sources/*</filename>. Is something wrong?
+ </para>
+ </question>
+ <answer>
+ <para>
+ Nothing is wrong.
+ The OpenEmbedded build system checks any configured source mirrors before downloading
+ from the upstream sources.
+ The build system does this searching for both source archives and
+ pre-checked out versions of SCM-managed software.
+ These checks help in large installations because it can reduce load on the SCM servers
+ themselves.
+ The address above is one of the default mirrors configured into the
+ build system.
+ Consequently, if an upstream source disappears, the team
+ can place sources there so builds continue to work.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ I have machine-specific data in a package for one machine only but the package is
+ being marked as machine-specific in all cases, how do I prevent this?
+ </para>
+ </question>
+ <answer>
+ <para>
+ Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
+ </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
+ manually marked as
+ machine-specific for the case that needs it.
+ The code that handles
+ <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
+ the <filename>meta/classes/base.bbclass</filename> file.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ I'm behind a firewall and need to use a proxy server. How do I do that?
+ </para>
+ </question>
+ <answer>
+ <para>
+ Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
+ and you therefore need to specify the proxy settings in a
+ <filename>.wgetrc</filename> file in your home directory.
+ Here are some example settings:
+ <literallayout class='monospaced'>
+ http_proxy = http://proxy.yoyodyne.com:18023/
+ ftp_proxy = http://proxy.yoyodyne.com:18023/
+ </literallayout>
+ The Yocto Project also includes a
+ <filename>site.conf.sample</filename> file that shows how to
+ configure CVS and Git proxy servers if needed.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The <filename>*-native</filename> targets are designed to run on the system
+ being used for the build.
+ These are usually tools that are needed to assist the build in some way such as
+ <filename>quilt-native</filename>, which is used to apply patches.
+ The non-native version is the one that runs on the target device.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ I'm seeing random build failures. Help?!
+ </para>
+ </question>
+ <answer>
+ <para>
+ If the same build is failing in totally different and random
+ ways, the most likely explanation is:
+ <itemizedlist>
+ <listitem><para>The hardware you are running the build on
+ has some problem.</para></listitem>
+ <listitem><para>You are running the build under
+ virtualization, in which case the virtualization
+ probably has bugs.</para></listitem>
+ </itemizedlist>
+ The OpenEmbedded build system processes a massive amount of
+ data that causes lots of network, disk and CPU activity and
+ is sensitive to even single-bit failures in any of these areas.
+ True random failures have always been traced back to hardware
+ or virtualization issues.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ When I try to build a native recipe, the build fails with <filename>iconv.h</filename> problems.
+ </para>
+ </question>
+ <answer>
+ <para>
+ If you get an error message that indicates GNU
+ <filename>libiconv</filename> is not in use but
+ <filename>iconv.h</filename> has been included from
+ <filename>libiconv</filename>, you need to check to see if
+ you have a previously installed version of the header file
+ in <filename>/usr/local/include</filename>.
+ <literallayout class='monospaced'>
+ #error GNU libiconv not in use but included iconv.h is from libiconv
+ </literallayout>
+ If you find a previously installed file, you should either
+ uninstall it or temporarily rename it and try the build again.
+ </para>
+
+ <para>
+ This issue is just a single manifestation of "system
+ leakage" issues caused when the OpenEbedded build system
+ finds and uses previously installed files during a native
+ build.
+ This type of issue might not be limited to
+ <filename>iconv.h</filename>.
+ Be sure that leakage cannot occur from
+ <filename>/usr/local/include</filename> and
+ <filename>/opt</filename> locations.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ What do we need to ship for license compliance?
+ </para>
+ </question>
+ <answer>
+ <para>
+ This is a difficult question and you need to consult your lawyer
+ for the answer for your specific case.
+ It is worth bearing in mind that for GPL compliance, there needs
+ to be enough information shipped to allow someone else to
+ rebuild and produce the same end result you are shipping.
+ This means sharing the source code, any patches applied to it,
+ and also any configuration information about how that package
+ was configured and built.
+ </para>
+
+ <para>
+ You can find more information on licensing in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#licensing'>Licensing</ulink>"
+ and "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+ sections, both of which are in the Yocto Project Development
+ Manual.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How do I disable the cursor on my touchscreen device?
+ </para>
+ </question>
+ <answer>
+ <para>
+ You need to create a form factor file as described in the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
+ section in the Yocto Project Board Support Packages (BSP)
+ Developer's Guide.
+ Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
+ one as follows:
+ <literallayout class='monospaced'>
+ HAVE_TOUCHSCREEN=1
+ </literallayout>
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How do I make sure connected network interfaces are brought up by default?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The default interfaces file provided by the netbase recipe does not
+ automatically bring up network interfaces.
+ Therefore, you will need to add a BSP-specific netbase that includes an interfaces
+ file.
+ See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
+ section in the Yocto Project Board Support Packages (BSP)
+ Developer's Guide for information on creating these types of
+ miscellaneous recipe files.
+ </para>
+ <para>
+ For example, add the following files to your layer:
+ <literallayout class='monospaced'>
+ meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
+ meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
+ </literallayout>
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How do I create images with more free space?
+ </para>
+ </question>
+ <answer>
+ <para>
+ By default, the OpenEmbedded build system creates images
+ that are 1.3 times the size of the populated root filesystem.
+ To affect the image size, you need to set various
+ configurations:
+ <itemizedlist>
+ <listitem><para><emphasis>Image Size:</emphasis>
+ The OpenEmbedded build system uses the
+ <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
+ variable to define the size of the image in Kbytes.
+ The build system determines the size by taking into
+ account the initial root filesystem size before any
+ modifications such as requested size for the image and
+ any requested additional free disk space to be
+ added to the image.</para></listitem>
+ <listitem><para><emphasis>Overhead:</emphasis>
+ Use the
+ <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
+ variable to define the multiplier that the build system
+ applies to the initial image size, which is 1.3 by
+ default.</para></listitem>
+ <listitem><para><emphasis>Additional Free Space:</emphasis>
+ Use the
+ <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
+ variable to add additional free space to the image.
+ The build system adds this space to the image after
+ it determines its
+ <filename>IMAGE_ROOTFS_SIZE</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ Why don't you support directories with spaces in the pathnames?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The Yocto Project team has tried to do this before but too
+ many of the tools the OpenEmbedded build system depends on,
+ such as <filename>autoconf</filename>, break when they find
+ spaces in pathnames.
+ Until that situation changes, the team will not support spaces
+ in pathnames.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ How do I use an external toolchain?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The toolchain configuration is very flexible and customizable.
+ It is primarily controlled with the
+ <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
+ variable.
+ This variable controls which <filename>tcmode-*.inc</filename>
+ file to include from the
+ <filename>meta/conf/distro/include</filename> directory within
+ the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+ </para>
+
+ <para>
+ The default value of <filename>TCMODE</filename> is "default",
+ which tells the OpenEmbedded build system to use its internally
+ built toolchain (i.e. <filename>tcmode-default.inc</filename>).
+ However, other patterns are accepted.
+ In particular, "external-*" refers to external toolchains.
+ One example is the Sourcery G++ Toolchain.
+ The support for this toolchain resides in the separate
+ <filename>meta-sourcery</filename> layer at
+ <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
+ </para>
+
+ <para>
+ In addition to the toolchain configuration, you also need a
+ corresponding toolchain recipe file.
+ This recipe file needs to package up any pre-built objects in
+ the toolchain such as <filename>libgcc</filename>,
+ <filename>libstdcc++</filename>, any locales, and
+ <filename>libc</filename>.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
+ How does the OpenEmbedded build system obtain source code and
+ will it work behind my firewall or proxy server?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The way the build system obtains source code is highly
+ configurable.
+ You can setup the build system to get source code in most
+ environments if HTTP transport is available.
+ </para>
+ <para>
+ When the build system searches for source code, it first
+ tries the local download directory.
+ If that location fails, Poky tries
+ <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
+ the upstream source, and then
+ <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+ in that order.
+ </para>
+ <para>
+ Assuming your distribution is "poky", the OpenEmbedded build
+ system uses the Yocto Project source
+ <filename>PREMIRRORS</filename> by default for SCM-based
+ sources, upstreams for normal tarballs, and then falls back
+ to a number of other mirrors including the Yocto Project
+ source mirror if those fail.
+ </para>
+ <para>
+ As an example, you could add a specific server for the
+ build system to attempt before any others by adding something
+ like the following to the <filename>local.conf</filename>
+ configuration file:
+ <literallayout class='monospaced'>
+ PREMIRRORS_prepend = "\
+ git://.*/.* http://www.yoctoproject.org/sources/ \n \
+ ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+ http://.*/.* http://www.yoctoproject.org/sources/ \n \
+ https://.*/.* http://www.yoctoproject.org/sources/ \n"
+ </literallayout>
+ </para>
+ <para>
+ These changes cause the build system to intercept Git, FTP,
+ HTTP, and HTTPS requests and direct them to the
+ <filename>http://</filename> sources mirror.
+ You can use <filename>file://</filename> URLs to point to
+ local directories or network shares as well.
+ </para>
+ <para>
+ Aside from the previous technique, these options also exist:
+ <literallayout class='monospaced'>
+ BB_NO_NETWORK = "1"
+ </literallayout>
+ This statement tells BitBake to issue an error instead of
+ trying to access the Internet.
+ This technique is useful if you want to ensure code builds
+ only from local sources.
+ </para>
+ <para>
+ Here is another technique:
+ <literallayout class='monospaced'>
+ BB_FETCH_PREMIRRORONLY = "1"
+ </literallayout>
+ This statement limits the build system to pulling source
+ from the <filename>PREMIRRORS</filename> only.
+ Again, this technique is useful for reproducing builds.
+ </para>
+ <para>
+ Here is another technique:
+ <literallayout class='monospaced'>
+ BB_GENERATE_MIRROR_TARBALLS = "1"
+ </literallayout>
+ This statement tells the build system to generate mirror
+ tarballs.
+ This technique is useful if you want to create a mirror server.
+ If not, however, the technique can simply waste time during
+ the build.
+ </para>
+ <para>
+ Finally, consider an example where you are behind an
+ HTTP-only firewall.
+ You could make the following changes to the
+ <filename>local.conf</filename> configuration file as long as
+ the <filename>PREMIRRORS</filename> server is current:
+ <literallayout class='monospaced'>
+ PREMIRRORS_prepend = "\
+ ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+ http://.*/.* http://www.yoctoproject.org/sources/ \n \
+ https://.*/.* http://www.yoctoproject.org/sources/ \n"
+ BB_FETCH_PREMIRRORONLY = "1"
+ </literallayout>
+ These changes would cause the build system to successfully
+ fetch source over HTTP and any network accesses to anything
+ other than the <filename>PREMIRRORS</filename> would fail.
+ </para>
+ <para>
+ The build system also honors the standard shell environment
+ variables <filename>http_proxy</filename>,
+ <filename>ftp_proxy</filename>,
+ <filename>https_proxy</filename>, and
+ <filename>all_proxy</filename> to redirect requests through
+ proxy servers.
+ </para>
+ <note>
+ You can find more information on the
+ "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
+ Wiki page.
+ </note>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>
+ Can I get rid of build output so I can start over?
+ </para>
+ </question>
+ <answer>
+ <para>
+ Yes - you can easily do this.
+ When you use BitBake to build an image, all the build output
+ goes into the directory created when you run the
+ build environment setup script (i.e.
+ <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+ or
+ <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+ By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ is named <filename>build</filename> but can be named
+ anything you want.
+ </para>
+
+ <para>
+ Within the Build Directory, is the <filename>tmp</filename>
+ directory.
+ To remove all the build output yet preserve any source code or
+ downloaded files from previous builds, simply remove the
+ <filename>tmp</filename> directory.
+ </para>
+ </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.
+ 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
+ broken 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>
+ Even if the paths look unusual, they both are correct -
+ the first for a target and the second for a native recipe.
+ These paths are a consequence of the
+ <filename>DESTDIR</filename> mechanism and while they
+ appear strange, they are correct and in practice very effective.
+ </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 a 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.
+ For another example, permissions errors might be caused
+ by a Makefile that ignores <filename>DESTDIR</filename> or uses
+ a different name for that environment variable.
+ Check the the build system to see if these kinds of
+ issues exist.
+ </para>
+ </answer>
+ </qandaentry>
+
+</qandaset>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->