documentation: Rename of poky-ref-manual folder to ref-manual.

Changing the folder that holds the YP Reference Manual to be
"ref-manual".  This will help with confustion over the manual's
intended purpose.

(From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 606 insertions, 0 deletions

diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
new file mode 100644
index 0000000000..176573de28
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,606 @@
+<!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 "Poky" 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 BitBake.
+                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.
+                For a fuller description of the term "Poky", see the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project
+                Development Manual.
+            </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 BSP layer for it.
+                For more information on how to create a BSP layer, see 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 the same set of recipes can be used to create output of various formats, the
+                output of an OpenEmbedded build depends on how it was started.
+                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'>Adding a Package</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
+                <filename>ipk</filename> for <filename>opkg</filename>,
+                Debian package (<filename>.deb</filename>), or RPM.
+                The packages can then be upgraded using the package tools on the device, much like
+                on a desktop distribution such as Ubuntu or Fedora.
+            </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>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I see lots of 404 responses for files on
+                <filename>http://www.yoctoproject.org/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 in the case that needs it.
+                The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>.
+            </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.
+                Example settings in that file would be
+                <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 that either the hardware you're running the
+                build on has some problem, or, if you are running the build under virtualisation,
+                the virtualisation probably has bugs.
+                The OpenEmbedded build system processes a massive amount of data causing 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 virtualisation 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 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>
+        </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 Recipe Files</ulink>"
+                section and 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 Recipe Files</ulink>"
+                section 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>
+                Images are created to be 1.2 times the size of the populated root filesystem.
+                To modify this ratio so that there is more free space available, you need to
+                set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.
+                For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets
+                the image size ratio to one and a half times the size of the populated
+                root filesystem.
+                <literallayout class='monospaced'>
+     IMAGE_OVERHEAD_FACTOR = "1.5"
+                </literallayout>
+            </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>
+        </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 PREMIRRORS, the upstream source,
+                and then MIRRORS in that order.
+            </para>
+            <para>
+                By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
+                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 Poky 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 Poky 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 throw 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 Poky to pulling source from the PREMIRRORS 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 Poky 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 PREMIRROR server is up to date:
+                 <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 Poky to successfully fetch source over HTTP and
+                 any network accesses to anything other than the PREMIRROR 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 <filename>oe-init-build-env</filename>
+                setup file.
+                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
+-->