diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-12-11 12:07:58 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-07 14:43:25 +0000 |
commit | ed0a240e1632682ec4c33341f3e24ad71773cdfc (patch) | |
tree | 201557f498b77b9f51fad7e12a6009f74aca4c65 /documentation/ref-manual/faq.xml | |
parent | af19d889ef320f9625aae42eed6688b5cc739793 (diff) | |
download | ast2050-yocto-poky-ed0a240e1632682ec4c33341f3e24ad71773cdfc.zip ast2050-yocto-poky-ed0a240e1632682ec4c33341f3e24ad71773cdfc.tar.gz |
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>
Diffstat (limited to 'documentation/ref-manual/faq.xml')
-rw-r--r-- | documentation/ref-manual/faq.xml | 606 |
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 0000000..176573d --- /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 +--> |