<!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>
                I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
                Can I still use the Yocto Project?
            </para>
        </question>
        <answer>
            <para>
                You can use a stand-alone tarball to provide Python 2.6.
                You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
                <itemizedlist>
                    <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
                    <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
                </itemizedlist>
            </para>
            <para>
                These tarballs are self-contained with all required libraries and should work
                on most Linux systems.
                To use the tarballs extract them into the root
                directory and run the appropriate command:
                <literallayout class='monospaced'>
     $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
     $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
                </literallayout>
            </para>
            <para>
                Once you run the command, BitBake uses Python 2.6.
            </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 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 add a package, see the section
                "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Writing a Recipe to Add a Package to Your Image</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>
                What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
            </para>
        </question>
        <answer>
            <para>
                GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
                platform targeted at mobile and embedded devices.
                The the main difference between GNOME Mobile and standard GNOME is that
                desktop-orientated libraries have been removed, along with deprecated libraries,
                creating a much smaller footprint.
            </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 <filename>foo</filename> and <filename>foo-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>
                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"
                (i.e. <filename>tcmode-default.inc</filename>).
                However, other patterns are accepted.
                In particular, "external-*" refers to external toolchains of 
                which there are some basic examples included in the 
                OpenEmbedded Core (<filename>meta</filename>).
                You can use your own custom toolchain definition in your own 
                layer (or as defined in the <filename>local.conf</filename> 
                file) at the location
                <filename>conf/distro/include/tcmode-*.inc</filename>.
            </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>.
                An example is the 
                <filename>external-sourcery-toolchain.bb</filename>, which is 
                located in <filename>meta/recipes-core/meta/</filename> within 
                the Source Directory.
            </para>

            <para>
                For information on installing and using cross-development 
                toolchains, see the 
                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
                section in the Yocto Project Application Developer's Guide.
            </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>
        </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 source the 
                <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
                setup script.
                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>


</qandaset>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->
