diff options
Diffstat (limited to 'documentation/mega-manual')
27 files changed, 13681 insertions, 0 deletions
diff --git a/documentation/mega-manual/figures/adt-title.png b/documentation/mega-manual/figures/adt-title.png new file mode 100644 index 0000000000..6e71e41f1a --- /dev/null +++ b/documentation/mega-manual/figures/adt-title.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/app-dev-flow.png b/documentation/mega-manual/figures/app-dev-flow.png new file mode 100644 index 0000000000..4927b93d67 --- /dev/null +++ b/documentation/mega-manual/figures/app-dev-flow.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/bsp-dev-flow.png b/documentation/mega-manual/figures/bsp-dev-flow.png new file mode 100644 index 0000000000..b20ee19223 --- /dev/null +++ b/documentation/mega-manual/figures/bsp-dev-flow.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/bsp-title.png b/documentation/mega-manual/figures/bsp-title.png new file mode 100644 index 0000000000..f624dd4f94 --- /dev/null +++ b/documentation/mega-manual/figures/bsp-title.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/building-an-image.png b/documentation/mega-manual/figures/building-an-image.png new file mode 100755 index 0000000000..1fbea5ab00 --- /dev/null +++ b/documentation/mega-manual/figures/building-an-image.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/dev-title.png b/documentation/mega-manual/figures/dev-title.png new file mode 100644 index 0000000000..d3cac4a7e5 --- /dev/null +++ b/documentation/mega-manual/figures/dev-title.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/git-workflow.png b/documentation/mega-manual/figures/git-workflow.png new file mode 100644 index 0000000000..4fdf42f89c --- /dev/null +++ b/documentation/mega-manual/figures/git-workflow.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/index-downloads.png b/documentation/mega-manual/figures/index-downloads.png new file mode 100644 index 0000000000..c907997db2 --- /dev/null +++ b/documentation/mega-manual/figures/index-downloads.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-architecture-overview.png b/documentation/mega-manual/figures/kernel-architecture-overview.png new file mode 100755 index 0000000000..2aad172db3 --- /dev/null +++ b/documentation/mega-manual/figures/kernel-architecture-overview.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-dev-flow.png b/documentation/mega-manual/figures/kernel-dev-flow.png new file mode 100644 index 0000000000..f200af6338 --- /dev/null +++ b/documentation/mega-manual/figures/kernel-dev-flow.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-example-repos-denzil.png b/documentation/mega-manual/figures/kernel-example-repos-denzil.png new file mode 100644 index 0000000000..79fc60698b --- /dev/null +++ b/documentation/mega-manual/figures/kernel-example-repos-denzil.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-overview-1.png b/documentation/mega-manual/figures/kernel-overview-1.png new file mode 100644 index 0000000000..116c0b9bd4 --- /dev/null +++ b/documentation/mega-manual/figures/kernel-overview-1.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-overview-2.png b/documentation/mega-manual/figures/kernel-overview-2.png new file mode 100644 index 0000000000..5fee847c66 --- /dev/null +++ b/documentation/mega-manual/figures/kernel-overview-2.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-overview-3-denzil.png b/documentation/mega-manual/figures/kernel-overview-3-denzil.png new file mode 100644 index 0000000000..5f2ea05789 --- /dev/null +++ b/documentation/mega-manual/figures/kernel-overview-3-denzil.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/kernel-title.png b/documentation/mega-manual/figures/kernel-title.png new file mode 100644 index 0000000000..59d86c00dc --- /dev/null +++ b/documentation/mega-manual/figures/kernel-title.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/poky-title.png b/documentation/mega-manual/figures/poky-title.png new file mode 100644 index 0000000000..2893d84620 --- /dev/null +++ b/documentation/mega-manual/figures/poky-title.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/source-repos.png b/documentation/mega-manual/figures/source-repos.png new file mode 100644 index 0000000000..65c5f29a43 --- /dev/null +++ b/documentation/mega-manual/figures/source-repos.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/using-a-pre-built-image.png b/documentation/mega-manual/figures/using-a-pre-built-image.png new file mode 100644 index 0000000000..b03130d123 --- /dev/null +++ b/documentation/mega-manual/figures/using-a-pre-built-image.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/wip.png b/documentation/mega-manual/figures/wip.png new file mode 100644 index 0000000000..88116374a1 --- /dev/null +++ b/documentation/mega-manual/figures/wip.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/yocto-environment.png b/documentation/mega-manual/figures/yocto-environment.png new file mode 100644 index 0000000000..82b7a55a35 --- /dev/null +++ b/documentation/mega-manual/figures/yocto-environment.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/yocto-project-transp.png b/documentation/mega-manual/figures/yocto-project-transp.png new file mode 100755 index 0000000000..31d2b147fd --- /dev/null +++ b/documentation/mega-manual/figures/yocto-project-transp.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/figures/yp-download.png b/documentation/mega-manual/figures/yp-download.png new file mode 100644 index 0000000000..a10b2e2b20 --- /dev/null +++ b/documentation/mega-manual/figures/yp-download.png | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/mega-manual-customization.xsl b/documentation/mega-manual/mega-manual-customization.xsl new file mode 100644 index 0000000000..3be182d6c2 --- /dev/null +++ b/documentation/mega-manual/mega-manual-customization.xsl | |||
| @@ -0,0 +1,8 @@ | |||
| 1 | <?xml version='1.0'?> | ||
| 2 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> | ||
| 3 | |||
| 4 | <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> | ||
| 5 | |||
| 6 | <xsl:param name="generate.toc" select="'chapter toc'"></xsl:param> | ||
| 7 | |||
| 8 | </xsl:stylesheet> | ||
diff --git a/documentation/mega-manual/mega-manual.html b/documentation/mega-manual/mega-manual.html new file mode 100644 index 0000000000..1b4419f3b9 --- /dev/null +++ b/documentation/mega-manual/mega-manual.html | |||
| @@ -0,0 +1,12646 @@ | |||
| 1 | <?xml version="1.0" encoding="UTF-8"?> | ||
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | ||
| 3 | <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title></title><link rel="stylesheet" href="mega-style.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><hr /></div> | ||
| 4 | |||
| 5 | <div class="article"><div class="titlepage"><hr /></div><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 90px"><td align="right"><img src="figures/yocto-project-transp.png" align="right" width="135" /></td></tr></table><div class="section" title="1. The Yocto Project Quick Start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="fake-title"></a>1. The Yocto Project Quick Start</h2></div></div></div><p>Copyright © 2010-2012 Linux Foundation</p></div><div class="section" title="2. Welcome!"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="welcome"></a>2. Welcome!</h2></div></div></div><p> | ||
| 6 | Welcome to the Yocto Project! | ||
| 7 | The Yocto Project is an open-source collaboration project focused on embedded Linux | ||
| 8 | developers. | ||
| 9 | Among other things, the Yocto Project uses a build system based on the Poky project | ||
| 10 | to construct complete Linux images. | ||
| 11 | The Poky project, in turn, draws from and contributes back to the OpenEmbedded project. | ||
| 12 | </p><p> | ||
| 13 | If you don't have a system that runs Linux and you want to give the Yocto Project a test run, | ||
| 14 | you might consider using the Yocto Project Build Appliance. | ||
| 15 | The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto | ||
| 16 | Project using a non-Linux development system. | ||
| 17 | See the <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Yocto | ||
| 18 | Project Build Appliance</a> for more information. | ||
| 19 | </p><p> | ||
| 20 | On the other hand, if you know all about open-source development, Linux development environments, | ||
| 21 | Git source repositories and the like and you just want some quick information that lets you try out | ||
| 22 | the Yocto Project on your Linux system, skip right to the | ||
| 23 | "<a class="link" href="#super-user" title="6. Super User">Super User</a>" section at the end of this quick start. | ||
| 24 | </p><p> | ||
| 25 | For the rest of you, this short document will give you some basic information about the environment and | ||
| 26 | let you experience it in its simplest form. | ||
| 27 | After reading this document, you will have a basic understanding of what the Yocto Project is | ||
| 28 | and how to use some of its core components. | ||
| 29 | This document steps you through a simple example showing you how to build a small image | ||
| 30 | and run it using the Quick EMUlator (QEMU emulator). | ||
| 31 | </p><p> | ||
| 32 | For more detailed information on the Yocto Project, you should check out these resources: | ||
| 33 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Website:</em></span> The <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a> | ||
| 34 | provides the latest builds, breaking news, full development documentation, and a rich Yocto | ||
| 35 | Project Development Community into which you can tap. | ||
| 36 | </p></li><li class="listitem"><p><span class="emphasis"><em>FAQs:</em></span> Lists commonly asked Yocto Project questions and answers. | ||
| 37 | You can find two FAQs: <a class="ulink" href="https://wiki.yoctoproject.org/wiki/FAQ" target="_top">Yocto Project FAQ</a> on | ||
| 38 | a wiki, and the | ||
| 39 | <a class="link" href="#faq" target="_top">FAQ</a> chapter in | ||
| 40 | the Yocto Project Reference Manual. | ||
| 41 | </p></li><li class="listitem"><p><span class="emphasis"><em>Developer Screencast:</em></span> The | ||
| 42 | <a class="ulink" href="http://vimeo.com/36450321" target="_top">Getting Started with the Yocto Project - New | ||
| 43 | Developer Screencast Tutorial</a> provides a 30-minute video for the user | ||
| 44 | new to the Yocto Project but familiar with Linux build systems.</p></li></ul></div><p> | ||
| 45 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 46 | Due to production processes, there could be differences between the Yocto Project | ||
| 47 | documentation bundled in a released tarball and the | ||
| 48 | Yocto Project Quick Start on | ||
| 49 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 50 | For the latest version of this manual, see the manual on the website. | ||
| 51 | </div></div><div class="section" title="3. Introducing the Yocto Project Development Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yp-intro"></a>3. Introducing the Yocto Project Development Environment</h2></div></div></div><p> | ||
| 52 | The Yocto Project through the OpenEmbedded build system provides an open source development | ||
| 53 | environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of | ||
| 54 | platforms including x86-64 and emulated ones. | ||
| 55 | You can use components from the Yocto Project to design, develop, build, debug, simulate, | ||
| 56 | and test the complete software stack using Linux, the X Window System, GNOME Mobile-based | ||
| 57 | application frameworks, and Qt frameworks. | ||
| 58 | </p><div class="mediaobject" align="center"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="center"><img src="figures/yocto-environment.png" align="middle" width="100%" /></td></tr></table><div class="caption"><p>The Yocto Project Development Environment</p></div></div><p> | ||
| 59 | Here are some highlights for the Yocto Project: | ||
| 60 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Provides a recent Linux kernel along with a set of system commands and libraries suitable for the embedded environment.</p></li><li class="listitem"><p>Makes available system components such as X11, Matchbox, GTK+, Pimlico, Clutter, | ||
| 61 | GuPNP and Qt (among others) so you can create a richer user interface experience on | ||
| 62 | devices that use displays or have a GUI. | ||
| 63 | For devices that don't have a GUI or display, you simply would not employ these | ||
| 64 | components.</p></li><li class="listitem"><p>Creates a focused and stable core compatible with the OpenEmbedded | ||
| 65 | project with which you can easily and reliably build and develop.</p></li><li class="listitem"><p>Fully supports a wide range of hardware and device emulation through the QEMU | ||
| 66 | Emulator.</p></li></ul></div><p> | ||
| 67 | The Yocto Project can generate images for many kinds of devices. | ||
| 68 | However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS, | ||
| 69 | and PPC-based architectures as well as specific hardware such as the | ||
| 70 | <span class="trademark">Intel</span>® Desktop Board DH55TC. | ||
| 71 | Because an image developed with the Yocto Project can boot inside a QEMU emulator, the | ||
| 72 | development environment works nicely as a test platform for developing embedded software. | ||
| 73 | </p><p> | ||
| 74 | Another important Yocto Project feature is the Sato reference User Interface. | ||
| 75 | This optional GNOME mobile-based UI, which is intended for devices with | ||
| 76 | restricted screen sizes, sits neatly on top of a device using the | ||
| 77 | GNOME Mobile Stack and provides a well-defined user experience. | ||
| 78 | Implemented in its own layer, it makes it clear to developers how they can implement | ||
| 79 | their own user interface on top of a Linux image created with the Yocto Project. | ||
| 80 | </p></div><div class="section" title="4. What You Need and How You Get It"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yp-resources"></a>4. What You Need and How You Get It</h2></div></div></div><p> | ||
| 81 | You need these things to develop in the Yocto Project environment: | ||
| 82 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A host system running a supported Linux distribution (i.e. recent releases of | ||
| 83 | Fedora, openSUSE, CentOS, and Ubuntu). | ||
| 84 | If the host system supports multiple cores and threads, you can configure the | ||
| 85 | Yocto Project build system to decrease the time needed to build images | ||
| 86 | significantly. | ||
| 87 | </p></li><li class="listitem"><p>The right packages.</p></li><li class="listitem"><p>A release of the Yocto Project.</p></li></ul></div><div class="section" title="4.1. The Linux Distribution"><div class="titlepage"><div><div><h3 class="title"><a id="the-linux-distro"></a>4.1. The Linux Distribution</h3></div></div></div><p> | ||
| 88 | The Yocto Project team is continually verifying more and more Linux | ||
| 89 | distributions with each release. | ||
| 90 | In general, if you have the current release minus one of the following | ||
| 91 | distributions you should have no problems. | ||
| 92 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Ubuntu</p></li><li class="listitem"><p>Fedora</p></li><li class="listitem"><p>openSUSE</p></li><li class="listitem"><p>CentOS</p></li></ul></div><p> | ||
| 93 | For a list of the distributions under validation and their status, see the | ||
| 94 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_top">Distribution | ||
| 95 | Support</a> wiki page. | ||
| 96 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 97 | For notes about using the Yocto Project on a RHEL 4-based host, see the | ||
| 98 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/BuildingOnRHEL4" target="_top">BuildingOnRHEL4</a> | ||
| 99 | wiki page. | ||
| 100 | </div><p> | ||
| 101 | </p><p> | ||
| 102 | The OpenEmbedded build system should be able to run on any modern distribution with Python 2.6 or 2.7. | ||
| 103 | Earlier releases of Python are known to not work and the system does not support Python 3 at this time. | ||
| 104 | This document assumes you are running one of the previously noted distributions on your Linux-based | ||
| 105 | host systems. | ||
| 106 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 107 | If you attempt to use a distribution not in the above list, you may or may not have success - you | ||
| 108 | are venturing into untested territory. | ||
| 109 | Refer to | ||
| 110 | <a class="ulink" href="http://www.openembedded.org/index.php?title=OEandYourDistro&action=historysubmit&diff=4309&okdid=4225" target="_top">OE and Your Distro</a> and | ||
| 111 | <a class="ulink" href="http://www.openembedded.org/index.php?title=Required_software&action=historysubmit&diff=4311&oldid=4251" target="_top">Required Software</a> | ||
| 112 | for information for other distributions used with the OpenEmbedded project, which might be | ||
| 113 | a starting point for exploration. | ||
| 114 | If you go down this path, you should expect problems. | ||
| 115 | When you do, please go to <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">Yocto Project Bugzilla</a> | ||
| 116 | and submit a bug. | ||
| 117 | We are interested in hearing about your experience. | ||
| 118 | </p></div></div><div class="section" title="4.2. The Packages"><div class="titlepage"><div><div><h3 class="title"><a id="packages"></a>4.2. The Packages</h3></div></div></div><p> | ||
| 119 | Packages and package installation vary depending on your development system. | ||
| 120 | In general, you need to have root access and then install the required packages. | ||
| 121 | The next few sections show you how to get set up with the right packages for | ||
| 122 | Ubuntu, Fedora, openSUSE, and CentOS. | ||
| 123 | </p><div class="section" title="4.2.1. Ubuntu"><div class="titlepage"><div><div><h4 class="title"><a id="ubuntu"></a>4.2.1. Ubuntu</h4></div></div></div><p> | ||
| 124 | The packages you need for a supported Ubuntu distribution are shown in the following command: | ||
| 125 | </p><pre class="literallayout"> | ||
| 126 | $ sudo apt-get install sed wget subversion git-core coreutils \ | ||
| 127 | unzip texi2html texinfo libsdl1.2-dev docbook-utils fop gawk \ | ||
| 128 | python-pysqlite2 diffstat make gcc build-essential xsltproc \ | ||
| 129 | g++ desktop-file-utils chrpath libgl1-mesa-dev libglu1-mesa-dev \ | ||
| 130 | autoconf automake groff libtool xterm libxml-parser-perl dblatex | ||
| 131 | </pre></div><div class="section" title="4.2.2. Fedora"><div class="titlepage"><div><div><h4 class="title"><a id="fedora"></a>4.2.2. Fedora</h4></div></div></div><p> | ||
| 132 | The packages you need for a supported Fedora distribution are shown in the following | ||
| 133 | commands: | ||
| 134 | </p><pre class="literallayout"> | ||
| 135 | $ sudo yum groupinstall "development tools" | ||
| 136 | $ sudo yum install python m4 make wget curl ftp tar bzip2 gzip \ | ||
| 137 | unzip perl texinfo texi2html diffstat openjade \ | ||
| 138 | docbook-style-dsssl sed docbook-style-xsl docbook-dtds fop libxslt \ | ||
| 139 | docbook-utils sed bc eglibc-devel ccache pcre pcre-devel quilt \ | ||
| 140 | groff linuxdoc-tools patch cmake \ | ||
| 141 | perl-ExtUtils-MakeMaker tcl-devel gettext chrpath ncurses apr \ | ||
| 142 | SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \ | ||
| 143 | autoconf automake libtool xterm dblatex | ||
| 144 | </pre></div><div class="section" title="4.2.3. openSUSE"><div class="titlepage"><div><div><h4 class="title"><a id="opensuse"></a>4.2.3. openSUSE</h4></div></div></div><p> | ||
| 145 | The packages you need for a supported openSUSE distribution are shown in the following | ||
| 146 | command: | ||
| 147 | </p><pre class="literallayout"> | ||
| 148 | $ sudo zypper install python gcc gcc-c++ libtool fop \ | ||
| 149 | subversion git chrpath automake make wget xsltproc \ | ||
| 150 | diffstat texinfo freeglut-devel libSDL-devel dblatex | ||
| 151 | </pre></div><div class="section" title="4.2.4. CentOS"><div class="titlepage"><div><div><h4 class="title"><a id="centos"></a>4.2.4. CentOS</h4></div></div></div><p> | ||
| 152 | The packages you need for a supported CentOS distribution are shown in the following | ||
| 153 | commands: | ||
| 154 | </p><pre class="literallayout"> | ||
| 155 | $ sudo yum -y groupinstall "development tools" | ||
| 156 | $ sudo yum -y install tetex gawk sqlite-devel vim-common redhat-lsb xz \ | ||
| 157 | m4 make wget curl ftp tar bzip2 gzip python-devel \ | ||
| 158 | unzip perl texinfo texi2html diffstat openjade zlib-devel \ | ||
| 159 | docbook-style-dsssl sed docbook-style-xsl docbook-dtds \ | ||
| 160 | docbook-utils bc glibc-devel pcre pcre-devel \ | ||
| 161 | groff linuxdoc-tools patch cmake \ | ||
| 162 | tcl-devel gettext ncurses apr \ | ||
| 163 | SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \ | ||
| 164 | autoconf automake libtool xterm dblatex | ||
| 165 | </pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 166 | Depending on the CentOS version you are using, other requirements and dependencies | ||
| 167 | might exist. | ||
| 168 | For details, you should look at the CentOS sections on the | ||
| 169 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_top">Poky/GettingStarted/Dependencies</a> | ||
| 170 | wiki page. | ||
| 171 | </p></div></div></div><div class="section" title="4.3. Yocto Project Release"><div class="titlepage"><div><div><h3 class="title"><a id="releases"></a>4.3. Yocto Project Release</h3></div></div></div><p> | ||
| 172 | You can download the latest Yocto Project release by going to the | ||
| 173 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Yocto Project Download page</a>. | ||
| 174 | Just go to the page and click the "Yocto Downloads" link found in the "Download" | ||
| 175 | navigation pane to the right to view all available Yocto Project releases. | ||
| 176 | Then, click the "Yocto Release" link for the release you want from the list to | ||
| 177 | begin the download. | ||
| 178 | Nightly and developmental builds are also maintained at | ||
| 179 | <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly/" target="_top">http://autobuilder.yoctoproject.org/nightly/</a>. | ||
| 180 | However, for this document a released version of Yocto Project is used. | ||
| 181 | </p><p> | ||
| 182 | You can also get the Yocto Project files you need by setting up (cloning in Git terms) | ||
| 183 | a local copy of the <code class="filename">poky</code> Git repository on your host development | ||
| 184 | system. | ||
| 185 | Doing so allows you to contribute back to the Yocto Project project. | ||
| 186 | For information on how to get set up using this method, see the | ||
| 187 | "<a class="link" href="#local-yp-release" target="_top">Yocto | ||
| 188 | Project Release</a>" item in the Yocto Project Development Manual. | ||
| 189 | </p></div></div><div class="section" title="5. A Quick Test Run"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="test-run"></a>5. A Quick Test Run</h2></div></div></div><p> | ||
| 190 | Now that you have your system requirements in order, you can give the Yocto Project a try. | ||
| 191 | This section presents some steps that let you do the following: | ||
| 192 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Build an image and run it in the QEMU emulator</p></li><li class="listitem"><p>Use a pre-built image and run it in the QEMU emulator</p></li></ul></div><div class="section" title="5.1. Building an Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-image"></a>5.1. Building an Image</h3></div></div></div><p> | ||
| 193 | In the development environment you will need to build an image whenever you change hardware | ||
| 194 | support, add or change system libraries, or add or change services that have dependencies. | ||
| 195 | </p><div class="mediaobject" align="center"><img src="figures/building-an-image.png" align="middle" /><div class="caption"><p>Building an Image</p></div></div><p> | ||
| 196 | Use the following commands to build your image. | ||
| 197 | The OpenEmbedded build process creates an entire Linux distribution, including the toolchain, | ||
| 198 | from source. | ||
| 199 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 200 | The build process using Sato currently consumes about 50GB of disk space. | ||
| 201 | To allow for variations in the build process and for future package expansion, we | ||
| 202 | recommend having at least 100GB of free disk space. | ||
| 203 | </p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 204 | By default, the build process searches for source code using a pre-determined order | ||
| 205 | through a set of locations. | ||
| 206 | If you encounter problems with the build process finding and downloading source code, see the | ||
| 207 | "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server" target="_top">How does the OpenEmbedded build system obtain source code and will it work behind my | ||
| 208 | firewall or proxy server?</a>" in the Yocto Project Reference Manual. | ||
| 209 | </p></div><p> | ||
| 210 | </p><pre class="literallayout"> | ||
| 211 | $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-1.2+snapshot-8.0.tar.bz2 | ||
| 212 | $ tar xjf poky-1.2+snapshot-8.0.tar.bz2 | ||
| 213 | $ source poky-1.2+snapshot-8.0/oe-init-build-env poky-1.2+snapshot-8.0-build | ||
| 214 | </pre><p> | ||
| 215 | </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p> | ||
| 216 | To help conserve disk space during builds, you can add the following statement | ||
| 217 | to your project's configuration file, which for this example | ||
| 218 | is <code class="filename">poky-1.2+snapshot-8.0-build/conf/local.conf</code>. | ||
| 219 | Adding this statement deletes the work directory used for building a package | ||
| 220 | once the package is built. | ||
| 221 | </p><pre class="literallayout"> | ||
| 222 | INHERIT += "rm_work" | ||
| 223 | </pre><p> | ||
| 224 | </p></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>In the previous example, the first command retrieves the Yocto Project | ||
| 225 | release tarball from the source repositories using the | ||
| 226 | <code class="filename">wget</code> command. | ||
| 227 | Alternatively, you can go to the | ||
| 228 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Yocto Project website's Downloads page</a> | ||
| 229 | to retrieve the tarball.</p></li><li class="listitem"><p>The second command extracts the files from the tarball and places | ||
| 230 | them into a directory named <code class="filename">poky-1.2+snapshot-8.0</code> in the current | ||
| 231 | directory.</p></li><li class="listitem"><p>The third command runs the Yocto Project environment setup script. | ||
| 232 | Running this script defines OpenEmbedded build environment settings needed to | ||
| 233 | complete the build. | ||
| 234 | The script also creates the | ||
| 235 | <a class="link" href="#build-directory" target="_top">build directory</a>, | ||
| 236 | which is <code class="filename">poky-1.2+snapshot-8.0-build</code> in this case. | ||
| 237 | After the script runs, your current working directory is set | ||
| 238 | to the build directory. | ||
| 239 | Later, when the build completes, the build directory contains all the files | ||
| 240 | created during the build. | ||
| 241 | </p></li></ul></div><p> | ||
| 242 | Take some time to examine your <code class="filename">local.conf</code> file | ||
| 243 | in your project's configuration directory. | ||
| 244 | The defaults in that file should work fine. | ||
| 245 | However, there are some variables of interest at which you might look. | ||
| 246 | </p><p> | ||
| 247 | By default, the target architecture for the build is <code class="filename">qemux86</code>, | ||
| 248 | which produces an image that can be used in the QEMU emulator and is targeted at an | ||
| 249 | <span class="trademark">Intel</span>® 32-bit based architecture. | ||
| 250 | To change this default, edit the value of the <code class="filename">MACHINE</code> variable | ||
| 251 | in the configuration file before launching the build. | ||
| 252 | </p><p> | ||
| 253 | Another couple of variables of interest are the | ||
| 254 | <a class="link" href="#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a> and the | ||
| 255 | <a class="link" href="#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a> variables. | ||
| 256 | By default, these variables are commented out. | ||
| 257 | However, if you have a multi-core CPU you might want to uncomment | ||
| 258 | the lines and set both variables equal to twice the number of your | ||
| 259 | host's processor cores. | ||
| 260 | Setting these variables can significantly shorten your build time. | ||
| 261 | </p><p> | ||
| 262 | Another consideration before you build is the package manager used when creating | ||
| 263 | the image. | ||
| 264 | By default, the OpenEmbedded build system uses the RPM package manager. | ||
| 265 | You can control this configuration by using the | ||
| 266 | <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a></code> variable. | ||
| 267 | For additional package manager selection information, see | ||
| 268 | "<a class="link" href="#ref-classes-package" target="_top">Packaging - <code class="filename">package*.bbclass</code></a>" | ||
| 269 | in the Yocto Project Reference Manual. | ||
| 270 | </p><p> | ||
| 271 | Continue with the following command to build an OS image for the target, which is | ||
| 272 | <code class="filename">core-image-sato</code> in this example. | ||
| 273 | For information on the <code class="filename">-k</code> option use the | ||
| 274 | <code class="filename">bitbake --help</code> command or see the | ||
| 275 | "<a class="link" href="#usingpoky-components-bitbake" target="_top">BitBake</a>" section in | ||
| 276 | the Yocto Project Reference Manual. | ||
| 277 | </p><pre class="literallayout"> | ||
| 278 | $ bitbake -k core-image-sato | ||
| 279 | </pre><p> | ||
| 280 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 281 | BitBake requires Python 2.6 or 2.7. For more information on this requirement, | ||
| 282 | see the | ||
| 283 | <a class="link" href="#faq" target="_top">FAQ</a> in the Yocto Project Reference | ||
| 284 | Manual. | ||
| 285 | </p></div><p> | ||
| 286 | The final command runs the image: | ||
| 287 | </p><pre class="literallayout"> | ||
| 288 | $ runqemu qemux86 | ||
| 289 | </pre><p> | ||
| 290 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 291 | Depending on the number of processors and cores, the amount or RAM, the speed of your | ||
| 292 | Internet connection and other factors, the build process could take several hours the first | ||
| 293 | time you run it. | ||
| 294 | Subsequent builds run much faster since parts of the build are cached. | ||
| 295 | </p></div><p> | ||
| 296 | </p></div><div class="section" title="5.2. Using Pre-Built Binaries and QEMU"><div class="titlepage"><div><div><h3 class="title"><a id="using-pre-built"></a>5.2. Using Pre-Built Binaries and QEMU</h3></div></div></div><p> | ||
| 297 | If hardware, libraries and services are stable, you can get started by using a pre-built binary | ||
| 298 | of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. | ||
| 299 | This scenario is useful for developing application software. | ||
| 300 | </p><div class="mediaobject" align="center"><img src="figures/using-a-pre-built-image.png" align="middle" /><div class="caption"><p>Using a Pre-Built Image</p></div></div><p> | ||
| 301 | For this scenario, you need to do several things: | ||
| 302 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Install the appropriate stand-alone toolchain tarball.</p></li><li class="listitem"><p>Download the pre-built image that will boot with QEMU. | ||
| 303 | You need to be sure to get the QEMU image that matches your target machine’s | ||
| 304 | architecture (e.g. x86, ARM, etc.).</p></li><li class="listitem"><p>Download the filesystem image for your target machine's architecture. | ||
| 305 | </p></li><li class="listitem"><p>Set up the environment to emulate the hardware and then start the QEMU emulator. | ||
| 306 | </p></li></ul></div><div class="section" title="5.2.1. Installing the Toolchain"><div class="titlepage"><div><div><h4 class="title"><a id="installing-the-toolchain"></a>5.2.1. Installing the Toolchain</h4></div></div></div><p> | ||
| 307 | You can download a tarball with the pre-built toolchain, which includes the | ||
| 308 | <code class="filename">runqemu</code> | ||
| 309 | script and support files, from the appropriate directory under | ||
| 310 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/</a>. | ||
| 311 | Toolchains are available for 32-bit and 64-bit development systems from the | ||
| 312 | <code class="filename">i686</code> and <code class="filename">x86-64</code> directories, respectively. | ||
| 313 | Each type of development system supports five target architectures. | ||
| 314 | The names of the tarballs are such that a string representing the host system appears | ||
| 315 | first in the filename and then is immediately followed by a string representing | ||
| 316 | the target architecture. | ||
| 317 | </p><pre class="literallayout"> | ||
| 318 | poky-eglibc-<<span class="emphasis"><em>host_system</em></span>>-<<span class="emphasis"><em>arch</em></span>>-toolchain-gmae-<<span class="emphasis"><em>release</em></span>>.tar.bz2 | ||
| 319 | |||
| 320 | Where: | ||
| 321 | <<span class="emphasis"><em>host_system</em></span>> is a string representing your development system: | ||
| 322 | i686 or x86_64. | ||
| 323 | |||
| 324 | <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: | ||
| 325 | i586, x86_64, powerpc, mips, or arm. | ||
| 326 | |||
| 327 | <<span class="emphasis"><em>release</em></span>> is the version of Yocto Project. | ||
| 328 | </pre><p> | ||
| 329 | For example, the following toolchain tarball is for a 64-bit development | ||
| 330 | host system and a 32-bit target architecture: | ||
| 331 | </p><pre class="literallayout"> | ||
| 332 | poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2 | ||
| 333 | </pre><p> | ||
| 334 | The toolchain tarballs are self-contained and must be installed into <code class="filename">/opt/poky</code>. | ||
| 335 | The following commands show how you install the toolchain tarball given a 64-bit development | ||
| 336 | host system and a 32-bit target architecture. | ||
| 337 | The example assumes the toolchain tarball is located in <code class="filename">~/toolchains/</code>. | ||
| 338 | You must have your working directory set to root before unpacking the tarball: | ||
| 339 | </p><p> | ||
| 340 | </p><pre class="literallayout"> | ||
| 341 | $ cd / | ||
| 342 | $ sudo tar -xvjf ~/toolchains/poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2 | ||
| 343 | </pre><p> | ||
| 344 | </p><p> | ||
| 345 | For more information on how to install tarballs, see the | ||
| 346 | "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" and | ||
| 347 | "<a class="link" href="#using-the-toolchain-from-within-the-build-tree" target="_top">Using BitBake and the Build Directory</a>" sections in the Yocto Project Application Developer's Guide. | ||
| 348 | </p></div><div class="section" title="5.2.2. Downloading the Pre-Built Linux Kernel"><div class="titlepage"><div><div><h4 class="title"><a id="downloading-the-pre-built-linux-kernel"></a>5.2.2. Downloading the Pre-Built Linux Kernel</h4></div></div></div><p> | ||
| 349 | You can download the pre-built Linux kernel suitable for running in the QEMU emulator from | ||
| 350 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu</a>. | ||
| 351 | Be sure to use the kernel that matches the architecture you want to simulate. | ||
| 352 | Download areas exist for the five supported machine architectures: | ||
| 353 | <code class="filename">qemuarm</code>, <code class="filename">qemumips</code>, <code class="filename">qemuppc</code>, | ||
| 354 | <code class="filename">qemux86</code>, and <code class="filename">qemux86-64</code>. | ||
| 355 | </p><p> | ||
| 356 | Most kernel files have one of the following forms: | ||
| 357 | </p><pre class="literallayout"> | ||
| 358 | *zImage-qemu<<span class="emphasis"><em>arch</em></span>>.bin | ||
| 359 | vmlinux-qemu<<span class="emphasis"><em>arch</em></span>>.bin | ||
| 360 | |||
| 361 | Where: | ||
| 362 | <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: | ||
| 363 | x86, x86-64, ppc, mips, or arm. | ||
| 364 | </pre><p> | ||
| 365 | </p><p> | ||
| 366 | You can learn more about downloading a Yocto Project kernel in the | ||
| 367 | "<a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a>" | ||
| 368 | bulleted item in the Yocto Project Development Manual. | ||
| 369 | </p></div><div class="section" title="5.2.3. Downloading the Filesystem"><div class="titlepage"><div><div><h4 class="title"><a id="downloading-the-filesystem"></a>5.2.3. Downloading the Filesystem</h4></div></div></div><p> | ||
| 370 | You can also download the filesystem image suitable for your target architecture from | ||
| 371 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu</a>. | ||
| 372 | Again, be sure to use the filesystem that matches the architecture you want | ||
| 373 | to simulate. | ||
| 374 | </p><p> | ||
| 375 | The filesystem image has two tarball forms: <code class="filename">ext3</code> and | ||
| 376 | <code class="filename">tar</code>. | ||
| 377 | You must use the <code class="filename">ext3</code> form when booting an image using the | ||
| 378 | QEMU emulator. | ||
| 379 | The <code class="filename">tar</code> form can be flattened out in your host development system | ||
| 380 | and used for build purposes with the Yocto Project. | ||
| 381 | </p><pre class="literallayout"> | ||
| 382 | core-image-<<span class="emphasis"><em>profile</em></span>>-qemu<<span class="emphasis"><em>arch</em></span>>.ext3 | ||
| 383 | core-image-<<span class="emphasis"><em>profile</em></span>>-qemu<<span class="emphasis"><em>arch</em></span>>.tar.bz2 | ||
| 384 | |||
| 385 | Where: | ||
| 386 | <<span class="emphasis"><em>profile</em></span>> is the filesystem image's profile: | ||
| 387 | lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, sato-dev, or sato-sdk. | ||
| 388 | For information on these types of image profiles, see the | ||
| 389 | "<a class="link" href="#ref-images" target="_top">Images</a>" chapter | ||
| 390 | in the Yocto Project Reference Manual. | ||
| 391 | |||
| 392 | <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: | ||
| 393 | x86, x86-64, ppc, mips, or arm. | ||
| 394 | </pre><p> | ||
| 395 | </p></div><div class="section" title="5.2.4. Setting Up the Environment and Starting the QEMU Emulator"><div class="titlepage"><div><div><h4 class="title"><a id="setting-up-the-environment-and-starting-the-qemu-emulator"></a>5.2.4. Setting Up the Environment and Starting the QEMU Emulator</h4></div></div></div><p> | ||
| 396 | Before you start the QEMU emulator, you need to set up the emulation environment. | ||
| 397 | The following command form sets up the emulation environment. | ||
| 398 | </p><pre class="literallayout"> | ||
| 399 | $ source /opt/poky/1.3/environment-setup-<<span class="emphasis"><em>arch</em></span>>-poky-linux-<<span class="emphasis"><em>if</em></span>> | ||
| 400 | |||
| 401 | Where: | ||
| 402 | <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: | ||
| 403 | i586, x86_64, ppc603e, mips, or armv5te. | ||
| 404 | |||
| 405 | <<span class="emphasis"><em>if</em></span>> is a string representing an embedded application binary interface. | ||
| 406 | Not all setup scripts include this string. | ||
| 407 | </pre><p> | ||
| 408 | </p><p> | ||
| 409 | Finally, this command form invokes the QEMU emulator | ||
| 410 | </p><pre class="literallayout"> | ||
| 411 | $ runqemu <<span class="emphasis"><em>qemuarch</em></span>> <<span class="emphasis"><em>kernel-image</em></span>> <<span class="emphasis"><em>filesystem-image</em></span>> | ||
| 412 | |||
| 413 | Where: | ||
| 414 | <<span class="emphasis"><em>qemuarch</em></span>> is a string representing the target architecture: qemux86, qemux86-64, | ||
| 415 | qemuppc, qemumips, or qemuarm. | ||
| 416 | |||
| 417 | <<span class="emphasis"><em>kernel-image</em></span>> is the architecture-specific kernel image. | ||
| 418 | |||
| 419 | <<span class="emphasis"><em>filesystem-image</em></span>> is the .ext3 filesystem image. | ||
| 420 | |||
| 421 | </pre><p> | ||
| 422 | </p><p> | ||
| 423 | Continuing with the example, the following two commands setup the emulation | ||
| 424 | environment and launch QEMU. | ||
| 425 | This example assumes the root filesystem (<code class="filename">.ext3</code> file) and | ||
| 426 | the pre-built kernel image file both reside in your home directory. | ||
| 427 | The kernel and filesystem are for a 32-bit target architecture. | ||
| 428 | </p><pre class="literallayout"> | ||
| 429 | $ cd $HOME | ||
| 430 | $ source /opt/poky/1.3/environment-setup-i586-poky-linux | ||
| 431 | $ runqemu qemux86 bzImage-qemux86.bin \ | ||
| 432 | core-image-sato-qemux86.ext3 | ||
| 433 | </pre><p> | ||
| 434 | </p><p> | ||
| 435 | The environment in which QEMU launches varies depending on the filesystem image and on the | ||
| 436 | target architecture. | ||
| 437 | For example, if you source the environment for the ARM target | ||
| 438 | architecture and then boot the minimal QEMU image, the emulator comes up in a new | ||
| 439 | shell in command-line mode. | ||
| 440 | However, if you boot the SDK image, QEMU comes up with a GUI. | ||
| 441 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Booting the PPC image results in QEMU launching in the same shell in | ||
| 442 | command-line mode.</div><p> | ||
| 443 | </p></div></div></div><div class="section" title="6. Super User"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="super-user"></a>6. Super User | ||
| 444 | </h2></div></div></div><p> | ||
| 445 | This section | ||
| 446 | <sup>[<a id="id1482592" href="#ftn.id1482592" class="footnote">1</a>]</sup> | ||
| 447 | gives you a very fast description of how to use the Yocto Project to build images | ||
| 448 | for a BeagleBoard xM starting from scratch. | ||
| 449 | The steps were performed on a 64-bit Ubuntu 10.04 system. | ||
| 450 | </p><div class="section" title="6.1. Getting the Yocto Project"><div class="titlepage"><div><div><h3 class="title"><a id="getting-yocto"></a>6.1. Getting the Yocto Project</h3></div></div></div><p> | ||
| 451 | Set up your <a class="link" href="#source-directory" target="_top">source directory</a> | ||
| 452 | one of two ways: | ||
| 453 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Tarball:</em></span> | ||
| 454 | Use if you want the latest stable release: | ||
| 455 | </p><pre class="literallayout"> | ||
| 456 | $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-1.2+snapshot-8.0.tar.bz2 | ||
| 457 | $ tar xvjf poky-1.2+snapshot-8.0.tar.bz2 | ||
| 458 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Git Repository:</em></span> | ||
| 459 | Use if you want to work with cutting edge development content: | ||
| 460 | </p><pre class="literallayout"> | ||
| 461 | $ git clone git://git.yoctoproject.org/poky | ||
| 462 | </pre></li></ul></div><p> | ||
| 463 | The remainder of the section assumes the Git repository method. | ||
| 464 | </p></div><div class="section" title="6.2. Setting Up Your Host"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-your-host"></a>6.2. Setting Up Your Host</h3></div></div></div><p> | ||
| 465 | You need some packages for everything to work. | ||
| 466 | Rather than duplicate them here, look at the "<a class="link" href="#packages" title="4.2. The Packages">The Packages</a>" | ||
| 467 | section earlier in this quick start. | ||
| 468 | </p></div><div class="section" title="6.3. Initializing the Build Environment"><div class="titlepage"><div><div><h3 class="title"><a id="initializing-the-build-environment"></a>6.3. Initializing the Build Environment</h3></div></div></div><p> | ||
| 469 | From the parent directory of local source directory, initialize your environment | ||
| 470 | and provide a meaningful | ||
| 471 | <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 472 | name: | ||
| 473 | </p><pre class="literallayout"> | ||
| 474 | $ source poky/oe-init-build-env mybuilds | ||
| 475 | </pre><p> | ||
| 476 | At this point, the <code class="filename">mybuilds</code> directory has been created for you | ||
| 477 | and it is now your current working directory. | ||
| 478 | If you don't provide your own directory name it defaults to <code class="filename">build</code>. | ||
| 479 | </p></div><div class="section" title="6.4. Configuring the local.conf File"><div class="titlepage"><div><div><h3 class="title"><a id="configuring-the-local.conf-file"></a>6.4. Configuring the local.conf File</h3></div></div></div><p> | ||
| 480 | Initializing the build environment creates a <code class="filename">conf/local.conf</code> configuration file | ||
| 481 | in the build directory. | ||
| 482 | You need to manually edit this file to specify the machine you are building and to optimize | ||
| 483 | your build time. | ||
| 484 | Here are the minimal changes to make: | ||
| 485 | </p><pre class="literallayout"> | ||
| 486 | BB_NUMBER_THREADS = "8" | ||
| 487 | PARALLEL_MAKE = "-j 8" | ||
| 488 | MACHINE ?= "beagleboard" | ||
| 489 | </pre><p> | ||
| 490 | Briefly, set <a class="link" href="#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a> | ||
| 491 | and <a class="link" href="#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a> to | ||
| 492 | twice your host processor's number of cores. | ||
| 493 | </p><p> | ||
| 494 | A good deal that goes into a Yocto Project build is simply downloading all of the source | ||
| 495 | tarballs. | ||
| 496 | Maybe you have been working with another build system (OpenEmbedded, Angstrom, etc) for which | ||
| 497 | you've built up a sizable directory of source tarballs. | ||
| 498 | Or perhaps someone else has such a directory for which you have read access. | ||
| 499 | If so, you can save time by adding the <code class="filename">PREMIRRORS</code> | ||
| 500 | statement to your configuration file so that local directories are first checked for existing | ||
| 501 | tarballs before running out to the net: | ||
| 502 | </p><pre class="literallayout"> | ||
| 503 | PREMIRRORS_prepend = "\ | ||
| 504 | git://.*/.* file:///home/you/dl/ \n \ | ||
| 505 | svn://.*/.* file:///home/you/dl/ \n \ | ||
| 506 | cvs://.*/.* file:///home/you/dl/ \n \ | ||
| 507 | ftp://.*/.* file:///home/you/dl/ \n \ | ||
| 508 | http://.*/.* file:///home/you/dl/ \n \ | ||
| 509 | https://.*/.* file:///home/you/dl/ \n" | ||
| 510 | </pre><p> | ||
| 511 | </p></div><div class="section" title="6.5. Building the Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-the-image"></a>6.5. Building the Image</h3></div></div></div><p> | ||
| 512 | At this point, you need to select an image to build for the BeagleBoard xM. | ||
| 513 | If this is your first build using the Yocto Project, you should try the smallest and simplest | ||
| 514 | image: | ||
| 515 | </p><pre class="literallayout"> | ||
| 516 | $ bitbake core-image-minimal | ||
| 517 | </pre><p> | ||
| 518 | Now you just wait for the build to finish. | ||
| 519 | </p><p> | ||
| 520 | Here are some variations on the build process that could be helpful: | ||
| 521 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Fetch all the necessary sources without starting the build: | ||
| 522 | </p><pre class="literallayout"> | ||
| 523 | $ bitbake -c fetchall core-image-minimal | ||
| 524 | </pre><p> | ||
| 525 | This variation guarantees that you have all the sources for that BitBake target | ||
| 526 | should you to disconnect from the net and want to do the build later offline. | ||
| 527 | </p></li><li class="listitem"><p>Specify to continue the build even if BitBake encounters an error. | ||
| 528 | By default, BitBake aborts the build when it encounters an error. | ||
| 529 | This command keeps a faulty build going: | ||
| 530 | </p><pre class="literallayout"> | ||
| 531 | $ bitbake -k core-image-minimal | ||
| 532 | </pre></li></ul></div><p> | ||
| 533 | </p><p> | ||
| 534 | Once you have your image, you can take steps to load and boot it on the target hardware. | ||
| 535 | </p></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id1482592" href="#id1482592" class="para">1</a>] </sup> | ||
| 536 | Kudos and thanks to Robert P. J. Day of | ||
| 537 | <a class="ulink" href="http://www.crashcourse.ca" target="_top">CrashCourse</a> for providing the basis | ||
| 538 | for this "expert" section with information from one of his | ||
| 539 | <a class="ulink" href="http://www.crashcourse.ca/wiki/index.php/Yocto_Project_Quick_Start" target="_top">wiki</a> | ||
| 540 | pages. | ||
| 541 | </p></div></div></div> | ||
| 542 | |||
| 543 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/dev-title.png" align="left" width="100%" /></td></tr></table> | ||
| 544 | |||
| 545 | <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="dev-manual"></a></h1></div><div><div class="authorgroup"> | ||
| 546 | <div class="author"><h3 class="author"><span class="firstname">Scott</span> <span class="surname">Rifenbark</span></h3><div class="affiliation"> | ||
| 547 | <span class="orgname">Intel Corporation<br /></span> | ||
| 548 | </div><code class="email"><<a class="email" href="mailto:scott.m.rifenbark@intel.com">scott.m.rifenbark@intel.com</a>></code></div> | ||
| 549 | </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1482939"></a> | ||
| 550 | <p> | ||
| 551 | Permission is granted to copy, distribute and/or modify this document under | ||
| 552 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top"> | ||
| 553 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by | ||
| 554 | Creative Commons. | ||
| 555 | </p> | ||
| 556 | |||
| 557 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 558 | Due to production processes, there could be differences between the Yocto Project | ||
| 559 | documentation bundled in the release tarball and the | ||
| 560 | Yocto Project Development Manual on | ||
| 561 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 562 | For the latest version of this manual, see the manual on the website. | ||
| 563 | </div> | ||
| 564 | </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> | ||
| 565 | <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">The initial document released with the Yocto Project 1.1 Release.</td></tr> | ||
| 566 | <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> | ||
| 567 | <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> | ||
| 568 | </table></div></div></div><hr /></div> | ||
| 569 | |||
| 570 | |||
| 571 | <div class="chapter" title="Chapter 1. The Yocto Project Development Manual"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-intro"></a>Chapter 1. The Yocto Project Development Manual</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#intro">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#what-this-manual-provides">1.2. What this Manual Provides</a></span></dt><dt><span class="section"><a href="#what-this-manual-does-not-provide">1.3. What this Manual Does Not Provide</a></span></dt><dt><span class="section"><a href="#other-information">1.4. Other Information</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro"></a>1.1. Introduction</h2></div></div></div><p> | ||
| 572 | Welcome to the Yocto Project Development Manual! | ||
| 573 | This manual gives you an idea of how to use the Yocto Project to develop embedded Linux | ||
| 574 | images and user-space applications to run on targeted devices. | ||
| 575 | Reading this manual gives you an overview of image, kernel, and user-space application development | ||
| 576 | using the Yocto Project. | ||
| 577 | Because much of the information in this manual is general, it contains many references to other | ||
| 578 | sources where you can find more detail. | ||
| 579 | For example, detailed information on Git, repositories and open source in general | ||
| 580 | can be found in many places. | ||
| 581 | Another example is how to get set up to use the Yocto Project, which our Yocto Project | ||
| 582 | Quick Start covers. | ||
| 583 | </p><p> | ||
| 584 | The Yocto Project Development Manual, however, does provide detailed examples on how to create a | ||
| 585 | Board Support Package (BSP), change the kernel source code, and reconfigure the kernel. | ||
| 586 | You can find this information in the appendices of the manual. | ||
| 587 | </p></div><div class="section" title="1.2. What this Manual Provides"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="what-this-manual-provides"></a>1.2. What this Manual Provides</h2></div></div></div><p> | ||
| 588 | The following list describes what you can get from this guide: | ||
| 589 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Information that lets you get set | ||
| 590 | up to develop using the Yocto Project.</p></li><li class="listitem"><p>Information to help developers who are new to the open source environment | ||
| 591 | and to the distributed revision control system Git, which the Yocto Project | ||
| 592 | uses.</p></li><li class="listitem"><p>An understanding of common end-to-end development models and tasks.</p></li><li class="listitem"><p>Development case overviews for both system development and user-space | ||
| 593 | applications.</p></li><li class="listitem"><p>An overview and understanding of the emulation environment used with | ||
| 594 | the Yocto Project (QEMU).</p></li><li class="listitem"><p>An understanding of basic kernel architecture and concepts.</p></li><li class="listitem"><p>Many references to other sources of related information.</p></li></ul></div><p> | ||
| 595 | </p></div><div class="section" title="1.3. What this Manual Does Not Provide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="what-this-manual-does-not-provide"></a>1.3. What this Manual Does Not Provide</h2></div></div></div><p> | ||
| 596 | This manual will not give you the following: | ||
| 597 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Step-by-step instructions if those instructions exist in other Yocto | ||
| 598 | Project documentation. | ||
| 599 | For example, the Yocto Project Development Manual contains detailed | ||
| 600 | instruction on how to obtain and configure the | ||
| 601 | <span class="trademark">Eclipse</span>™ Yocto Plug-in.</p></li><li class="listitem"><p>Reference material. | ||
| 602 | This type of material resides in an appropriate reference manual. | ||
| 603 | For example, system variables are documented in the | ||
| 604 | Yocto Project Reference Manual.</p></li><li class="listitem"><p>Detailed public information that is not specific to the Yocto Project. | ||
| 605 | For example, exhaustive information on how to use Git is covered better through the | ||
| 606 | Internet than in this manual.</p></li></ul></div><p> | ||
| 607 | </p></div><div class="section" title="1.4. Other Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="other-information"></a>1.4. Other Information</h2></div></div></div><p> | ||
| 608 | Because this manual presents overview information for many different topics, you will | ||
| 609 | need to supplement it with other information. | ||
| 610 | The following list presents other sources of information you might find helpful: | ||
| 611 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a>: | ||
| 612 | </em></span> The home page for the Yocto Project provides lots of information on the project | ||
| 613 | as well as links to software and documentation.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 614 | Yocto Project Quick Start:</em></span> This short document lets you get started | ||
| 615 | with the Yocto Project quickly and start building an image.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 616 | Yocto Project Reference Manual:</em></span> This manual is a reference | ||
| 617 | guide to the OpenEmbedded build system known as "Poky." | ||
| 618 | The manual also contains a reference chapter on Board Support Package (BSP) | ||
| 619 | layout.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 620 | Yocto Project Application Developer's Guide:</em></span> | ||
| 621 | This guide provides information that lets you get going with the Application | ||
| 622 | Development Toolkit (ADT) and stand-alone cross-development toolchains to | ||
| 623 | develop projects using the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 624 | Yocto Project Board Support Package (BSP) Developer's Guide:</em></span> | ||
| 625 | This guide defines the structure for BSP components. | ||
| 626 | Having a commonly understood structure encourages standardization.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 627 | Yocto Project Kernel Architecture and Use Manual:</em></span> | ||
| 628 | This manual describes the architecture of the Yocto Project kernel and provides | ||
| 629 | some work flow examples.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 630 | <a class="ulink" href="http://www.youtube.com/watch?v=3ZlOu-gLsh0" target="_top"> | ||
| 631 | Eclipse IDE Yocto Plug-in</a>:</em></span> A step-by-step instructional video that | ||
| 632 | demonstrates how an application developer uses Yocto Plug-in features within | ||
| 633 | the Eclipse IDE.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 634 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/FAQ" target="_top">FAQ</a>:</em></span> | ||
| 635 | A list of commonly asked questions and their answers.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 636 | <a class="ulink" href="http://www.yoctoproject.org/download/yocto/yocto-project-1.1-release-notes-poky-8.0" target="_top"> | ||
| 637 | Release Notes</a>:</em></span> Features, updates and known issues for the current | ||
| 638 | release of the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 639 | <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top"> | ||
| 640 | Hob</a>:</em></span> A graphical user interface for BitBake. | ||
| 641 | Hob's primary goal is to enable a user to perform common tasks more easily.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 642 | <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top"> | ||
| 643 | Build Appliance</a>:</em></span> A bootable custom embedded Linux image you can | ||
| 644 | either build using a non-Linux development system (VMware applications) or download | ||
| 645 | from the Yocto Project website. | ||
| 646 | See the <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> | ||
| 647 | page for more information.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 648 | <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">Bugzilla</a>:</em></span> | ||
| 649 | The bug tracking application the Yocto Project uses. | ||
| 650 | If you find problems with the Yocto Project, you should report them using this | ||
| 651 | application.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 652 | Yocto Project Mailing Lists:</em></span> To subscribe to the Yocto Project mailing | ||
| 653 | lists, click on the following URLs and follow the instructions: | ||
| 654 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> for a | ||
| 655 | Yocto Project Discussions mailing list.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> for a | ||
| 656 | Yocto Project Discussions mailing list about the Poky build system.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> | ||
| 657 | for a mailing list to receive official Yocto Project announcements for developments and | ||
| 658 | as well as Yocto Project milestones.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em>Internet Relay Chat (IRC):</em></span> | ||
| 659 | Two IRC channels on freenode are available | ||
| 660 | for Yocto Project and Poky discussions: <code class="filename">#yocto</code> and | ||
| 661 | <code class="filename">#poky</code>, respectively.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 662 | <a class="ulink" href="http://o-hand.com" target="_top">OpenedHand</a>:</em></span> | ||
| 663 | The company that initially developed the Poky project, which is the basis | ||
| 664 | for the OpenEmbedded build system used by the Yocto Project. | ||
| 665 | OpenedHand was acquired by Intel Corporation in 2008.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 666 | <a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span> | ||
| 667 | A multinational semiconductor chip manufacturer company whose Software and | ||
| 668 | Services Group created and supports the Yocto Project. | ||
| 669 | Intel acquired OpenedHand in 2008.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 670 | <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span> | ||
| 671 | The build system used by the Yocto Project. | ||
| 672 | This project is the upstream, generic, embedded distribution from which the Yocto | ||
| 673 | Project derives its build system (Poky) from and to which it contributes.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 674 | <a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top"> | ||
| 675 | BitBake</a>:</em></span> The tool used by the OpenEmbedded build system | ||
| 676 | to process project metadata.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 677 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top"> | ||
| 678 | BitBake User Manual</a>:</em></span> A comprehensive guide to the BitBake tool. | ||
| 679 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 680 | <a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>: | ||
| 681 | </em></span> An open-source machine emulator and virtualizer.</p></li></ul></div><p> | ||
| 682 | </p></div></div> | ||
| 683 | |||
| 684 | <div class="chapter" title="Chapter 2. Getting Started with the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-start"></a>Chapter 2. Getting Started with the Yocto Project</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#introducing-the-yocto-project">2.1. Introducing the Yocto Project</a></span></dt><dt><span class="section"><a href="#getting-setup">2.2. Getting Set Up</a></span></dt><dt><span class="section"><a href="#building-images">2.3. Building Images</a></span></dt><dt><span class="section"><a href="#using-pre-built-binaries-and-qemu">2.4. Using Pre-Built Binaries and QEMU</a></span></dt></dl></div><p> | ||
| 685 | This chapter introduces the Yocto Project and gives you an idea of what you need to get started. | ||
| 686 | You can find enough information to set up your development host and build or use images for | ||
| 687 | hardware supported by the Yocto Project by reading the | ||
| 688 | Yocto Project Quick Start. | ||
| 689 | </p><p> | ||
| 690 | The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides | ||
| 691 | some higher-level concepts you might want to consider. | ||
| 692 | </p><div class="section" title="2.1. Introducing the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introducing-the-yocto-project"></a>2.1. Introducing the Yocto Project</h2></div></div></div><p> | ||
| 693 | The Yocto Project is an open-source collaboration project focused on embedded Linux development. | ||
| 694 | The project currently provides a build system, which is | ||
| 695 | referred to as the OpenEmbedded build system in the Yocto Project documentation. | ||
| 696 | The Yocto Project provides various ancillary tools suitable for the embedded developer | ||
| 697 | and also features the Sato reference User Interface, which is optimized for | ||
| 698 | stylus driven, low-resolution screens. | ||
| 699 | </p><p> | ||
| 700 | You can use the OpenEmbedded build system, which uses | ||
| 701 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">BitBake</a>, to develop complete Linux | ||
| 702 | images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, | ||
| 703 | x86 and x86-64. | ||
| 704 | While the Yocto Project does not provide a strict testing framework, | ||
| 705 | it does provide or generate for you artifacts that let you perform target-level and | ||
| 706 | emulated testing and debugging. | ||
| 707 | Additionally, if you are an <span class="trademark">Eclipse</span>™ | ||
| 708 | IDE user, you can install an Eclipse Yocto Plug-in to allow you to | ||
| 709 | develop within that familiar environment. | ||
| 710 | </p></div><div class="section" title="2.2. Getting Set Up"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="getting-setup"></a>2.2. Getting Set Up</h2></div></div></div><p> | ||
| 711 | Here is what you need to get set up to use the Yocto Project: | ||
| 712 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Host System:</em></span> You should have a reasonably current | ||
| 713 | Linux-based host system. | ||
| 714 | You will have the best results with a recent release of Fedora, | ||
| 715 | OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project | ||
| 716 | and officially supported. | ||
| 717 | You should also have about 100 gigabytes of free disk space for building images. | ||
| 718 | </p></li><li class="listitem"><p><span class="emphasis"><em>Packages:</em></span> The OpenEmbedded build system | ||
| 719 | requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). | ||
| 720 | See "<a class="link" href="#packages" target="_top">The Packages</a>" | ||
| 721 | section in the Yocto Project Quick Start for the exact package | ||
| 722 | requirements and the installation commands to install them | ||
| 723 | for the supported distributions.</p></li><li class="listitem"><p><a id="local-yp-release"></a><span class="emphasis"><em>Yocto Project Release:</em></span> | ||
| 724 | You need a release of the Yocto Project. | ||
| 725 | You set up a with local <a class="link" href="#source-directory">source directory</a> | ||
| 726 | one of two ways depending on whether you | ||
| 727 | are going to contribute back into the Yocto Project or not. | ||
| 728 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 729 | Regardless of the method you use, this manual refers to the resulting local | ||
| 730 | hierarchical set of files as the "source directory." | ||
| 731 | </div><p> | ||
| 732 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em>Tarball Extraction:</em></span> If you are not going to contribute | ||
| 733 | back into the Yocto Project, you can simply download a Yocto Project release you want | ||
| 734 | from the website’s <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">download page</a>. | ||
| 735 | Once you have the tarball, just extract it into a directory of your choice.</p><p>For example, the following command extracts the Yocto Project 1.3 | ||
| 736 | release tarball | ||
| 737 | into the current working directory and sets up the local source directory | ||
| 738 | with a top-level folder named <code class="filename">poky-1.2+snapshot-8.0</code>: | ||
| 739 | </p><pre class="literallayout"> | ||
| 740 | $ tar xfj poky-1.2+snapshot-8.0.tar.bz2 | ||
| 741 | </pre><p>This method does not produce a local Git repository. | ||
| 742 | Instead, you simply end up with a snapshot of the release.</p></li><li class="listitem"><p><span class="emphasis"><em>Git Repository Method:</em></span> If you are going to be contributing | ||
| 743 | back into the Yocto Project or you simply want to keep up | ||
| 744 | with the latest developments, you should use Git commands to set up a local | ||
| 745 | Git repository of the upstream <code class="filename">poky</code> source repository. | ||
| 746 | Doing so creates a repository with a complete history of changes and allows | ||
| 747 | you to easily submit your changes upstream to the project. | ||
| 748 | Because you cloned the repository, you have access to all the Yocto Project development | ||
| 749 | branches and tag names used in the upstream repository.</p><p>The following transcript shows how to clone the <code class="filename">poky</code> | ||
| 750 | Git repository into the current working directory. | ||
| 751 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>You can view the Yocto Project Source Repositories at | ||
| 752 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a></div><p> | ||
| 753 | The command creates the local repository in a directory named <code class="filename">poky</code>. | ||
| 754 | For information on Git used within the Yocto Project, see the | ||
| 755 | "<a class="link" href="#git" title="3.6. Git">Git</a>" section. | ||
| 756 | </p><pre class="literallayout"> | ||
| 757 | $ git clone git://git.yoctoproject.org/poky | ||
| 758 | Initialized empty Git repository in /home/scottrif/poky/.git/ | ||
| 759 | remote: Counting objects: 141863, done. | ||
| 760 | remote: Compressing objects: 100% (38624/38624), done. | ||
| 761 | remote: Total 141863 (delta 99661), reused 141816 (delta 99614) | ||
| 762 | Receiving objects: 100% (141863/141863), 76.64 MiB | 126 KiB/s, done. | ||
| 763 | Resolving deltas: 100% (99661/99661), done. | ||
| 764 | </pre><p>For another example of how to set up your own local Git repositories, see this | ||
| 765 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP" target="_top"> | ||
| 766 | wiki page</a>, which describes how to create both <code class="filename">poky</code> | ||
| 767 | and <code class="filename">meta-intel</code> Git repositories.</p></li></ul></div></li><li class="listitem"><p><a id="local-kernel-files"></a><span class="emphasis"><em>Yocto Project Kernel:</em></span> | ||
| 768 | If you are going to be making modifications to a supported Yocto Project kernel, you | ||
| 769 | need to establish local copies of the source. | ||
| 770 | You can find Git repositories of supported Yocto Project Kernels organized under | ||
| 771 | "Yocto Project Linux Kernel" in the Yocto Project Source Repositories at | ||
| 772 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>.</p><p>This setup involves creating a bare clone of the Yocto Project kernel and then | ||
| 773 | copying that cloned repository. | ||
| 774 | You can create the bare clone and the copy of the bare clone anywhere you like. | ||
| 775 | For simplicity, it is recommended that you create these structures outside of the | ||
| 776 | source directory (usually <code class="filename">poky</code>).</p><p>As an example, the following transcript shows how to create the bare clone | ||
| 777 | of the <code class="filename">linux-yocto-3.2</code> kernel and then create a copy of | ||
| 778 | that clone. | ||
| 779 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>When you have a local Yocto Project kernel Git repository, you can | ||
| 780 | reference that repository rather than the upstream Git repository as | ||
| 781 | part of the <code class="filename">clone</code> command. | ||
| 782 | Doing so can speed up the process.</div><p>In the following example, the bare clone is named | ||
| 783 | <code class="filename">linux-yocto-3.2.git</code>, while the | ||
| 784 | copy is named <code class="filename">my-linux-yocto-3.2-work</code>: | ||
| 785 | </p><pre class="literallayout"> | ||
| 786 | $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.2 linux-yocto-3.2.git | ||
| 787 | Initialized empty Git repository in /home/scottrif/linux-yocto-3.2.git/ | ||
| 788 | remote: Counting objects: 2468027, done. | ||
| 789 | remote: Compressing objects: 100% (392255/392255), done. | ||
| 790 | remote: Total 2468027 (delta 2071693), reused 2448773 (delta 2052498) | ||
| 791 | Receiving objects: 100% (2468027/2468027), 530.46 MiB | 129 KiB/s, done. | ||
| 792 | Resolving deltas: 100% (2071693/2071693), done. | ||
| 793 | </pre><p>Now create a clone of the bare clone just created: | ||
| 794 | </p><pre class="literallayout"> | ||
| 795 | $ git clone linux-yocto-3.2.git my-linux-yocto-3.2-work | ||
| 796 | Initialized empty Git repository in /home/scottrif/my-linux-yocto-3.2-work/.git/ | ||
| 797 | Checking out files: 100% (37619/37619), done. | ||
| 798 | </pre></li><li class="listitem"><p><a id="poky-extras-repo"></a><span class="emphasis"><em> | ||
| 799 | The <code class="filename">poky-extras</code> Git Repository</em></span>: | ||
| 800 | The <code class="filename">poky-extras</code> Git repository contains metadata needed | ||
| 801 | only if you are modifying and building the kernel image. | ||
| 802 | In particular, it contains the kernel BitBake append (<code class="filename">.bbappend</code>) | ||
| 803 | files that you | ||
| 804 | edit to point to your locally modified kernel source files and to build the kernel | ||
| 805 | image. | ||
| 806 | Pointing to these local files is much more efficient than requiring a download of the | ||
| 807 | kernel's source files from upstream each time you make changes to the kernel.</p><p>You can find the <code class="filename">poky-extras</code> Git Repository in the | ||
| 808 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at | ||
| 809 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. | ||
| 810 | It is good practice to create this Git repository inside the source directory.</p><p>Following is an example that creates the <code class="filename">poky-extras</code> Git | ||
| 811 | repository inside the source directory, which is named <code class="filename">poky</code> | ||
| 812 | in this case: | ||
| 813 | </p><pre class="literallayout"> | ||
| 814 | $ git clone git://git.yoctoproject.org/poky-extras poky-extras | ||
| 815 | Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ | ||
| 816 | remote: Counting objects: 618, done. | ||
| 817 | remote: Compressing objects: 100% (558/558), done. | ||
| 818 | remote: Total 618 (delta 192), reused 307 (delta 39) | ||
| 819 | Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done. | ||
| 820 | Resolving deltas: 100% (192/192), done. | ||
| 821 | </pre></li><li class="listitem"><p><a id="supported-board-support-packages-(bsps)"></a><span class="emphasis"><em>Supported Board | ||
| 822 | Support Packages (BSPs):</em></span> | ||
| 823 | The Yocto Project provides a layer called <code class="filename">meta-intel</code> and | ||
| 824 | it is maintained in its own separate Git repository. | ||
| 825 | The <code class="filename">meta-intel</code> layer contains many supported | ||
| 826 | <a class="link" href="#bsp-layers" target="_top">BSP Layers</a>.</p><p>Similar considerations exist for setting up the <code class="filename">meta-intel</code> | ||
| 827 | layer. | ||
| 828 | You can get set up for BSP development one of two ways: tarball extraction or | ||
| 829 | with a local Git repository. | ||
| 830 | It is a good idea to use the same method that you used to set up the source directory. | ||
| 831 | Regardless of the method you use, the Yocto Project uses the following BSP layer | ||
| 832 | naming scheme: | ||
| 833 | </p><pre class="literallayout"> | ||
| 834 | meta-<BSP_name> | ||
| 835 | </pre><p> | ||
| 836 | where <BSP_name> is the recognized BSP name. | ||
| 837 | Here are some examples: | ||
| 838 | </p><pre class="literallayout"> | ||
| 839 | meta-crownbay | ||
| 840 | meta-emenlow | ||
| 841 | meta-n450 | ||
| 842 | </pre><p> | ||
| 843 | See the | ||
| 844 | "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" | ||
| 845 | section in the Yocto Project Board Support Package (BSP) Developer's Guide for more | ||
| 846 | information on BSP Layers. | ||
| 847 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em>Tarball Extraction:</em></span> You can download any released | ||
| 848 | BSP tarball from the same | ||
| 849 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">download site</a> used | ||
| 850 | to get the Yocto Project release. | ||
| 851 | Once you have the tarball, just extract it into a directory of your choice. | ||
| 852 | Again, this method just produces a snapshot of the BSP layer in the form | ||
| 853 | of a hierarchical directory structure.</p></li><li class="listitem"><p><span class="emphasis"><em>Git Repository Method:</em></span> If you are working | ||
| 854 | with a local Git repository for your source directory, you should also use this method | ||
| 855 | to set up the <code class="filename">meta-intel</code> Git repository. | ||
| 856 | You can locate the <code class="filename">meta-intel</code> Git repository in the | ||
| 857 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at | ||
| 858 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>.</p><p>Typically, you set up the <code class="filename">meta-intel</code> Git repository inside | ||
| 859 | the source directory. | ||
| 860 | For example, the following transcript shows the steps to clone the | ||
| 861 | <code class="filename">meta-intel</code> | ||
| 862 | Git repository inside the local <code class="filename">poky</code> Git repository. | ||
| 863 | </p><pre class="literallayout"> | ||
| 864 | $ git clone git://git.yoctoproject.org/meta-intel.git | ||
| 865 | Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ | ||
| 866 | remote: Counting objects: 3380, done. | ||
| 867 | remote: Compressing objects: 100% (2750/2750), done. | ||
| 868 | remote: Total 3380 (delta 1689), reused 227 (delta 113) | ||
| 869 | Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. | ||
| 870 | Resolving deltas: 100% (1689/1689), done. | ||
| 871 | </pre><p>The same | ||
| 872 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP" target="_top"> | ||
| 873 | wiki page</a> referenced earlier covers how to | ||
| 874 | set up the <code class="filename">meta-intel</code> Git repository.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em>Eclipse Yocto Plug-in:</em></span> If you are developing | ||
| 875 | applications using the Eclipse Integrated Development Environment (IDE), | ||
| 876 | you will need this plug-in. | ||
| 877 | See the | ||
| 878 | "<a class="link" href="#setting-up-the-eclipse-ide" title="5.2.2.1. Setting Up the Eclipse IDE">Setting up the Eclipse IDE</a>" | ||
| 879 | section for more information.</p></li></ul></div><p> | ||
| 880 | </p></div><div class="section" title="2.3. Building Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-images"></a>2.3. Building Images</h2></div></div></div><p> | ||
| 881 | The build process creates an entire Linux distribution, including the toolchain, from source. | ||
| 882 | For more information on this topic, see the | ||
| 883 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" | ||
| 884 | section in the Yocto Project Quick Start. | ||
| 885 | </p><p> | ||
| 886 | The build process is as follows: | ||
| 887 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Make sure you have set up the source directory described in the | ||
| 888 | previous section.</p></li><li class="listitem"><p>Initialize the build environment by sourcing a build environment | ||
| 889 | script.</p></li><li class="listitem"><p>Optionally ensure the <code class="filename">conf/local.conf</code> configuration file, | ||
| 890 | which is found in the | ||
| 891 | <a class="link" href="#build-directory">build directory</a>, | ||
| 892 | is set up how you want it. | ||
| 893 | This file defines many aspects of the build environment including | ||
| 894 | the target machine architecture through the | ||
| 895 | <code class="filename"><a class="link" href="#var-MACHINE" target="_top">MACHINE</a></code> variable, | ||
| 896 | the development machine's processor use through the | ||
| 897 | <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" target="_top">BB_NUMBER_THREADS</a></code> and | ||
| 898 | <code class="filename"><a class="link" href="#var-PARALLEL_MAKE" target="_top">PARALLEL_MAKE</a></code> variables, and | ||
| 899 | a centralized tarball download directory through the | ||
| 900 | <code class="filename"><a class="link" href="#var-DL_DIR" target="_top">DL_DIR</a></code> variable.</p></li><li class="listitem"><p>Build the image using the <code class="filename">bitbake</code> command. | ||
| 901 | If you want information on BitBake, see the user manual at | ||
| 902 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html" target="_top">http://docs.openembedded.org/bitbake/html</a>.</p></li><li class="listitem"><p>Run the image either on the actual hardware or using the QEMU | ||
| 903 | emulator.</p></li></ol></div><p> | ||
| 904 | </p></div><div class="section" title="2.4. Using Pre-Built Binaries and QEMU"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-pre-built-binaries-and-qemu"></a>2.4. Using Pre-Built Binaries and QEMU</h2></div></div></div><p> | ||
| 905 | Another option you have to get started is to use pre-built binaries. | ||
| 906 | The Yocto Project provides many types of binaries with each release. | ||
| 907 | See the <a class="link" href="#ref-images" target="_top">Images</a> | ||
| 908 | chapter in the Yocto Project Reference Manual | ||
| 909 | for descriptions of the types of binaries that ship with a Yocto Project | ||
| 910 | release. | ||
| 911 | </p><p> | ||
| 912 | Using a pre-built binary is ideal for developing software applications to run on your | ||
| 913 | target hardware. | ||
| 914 | To do this, you need to be able to access the appropriate cross-toolchain tarball for | ||
| 915 | the architecture on which you are developing. | ||
| 916 | If you are using an SDK type image, the image ships with the complete toolchain native to | ||
| 917 | the architecture. | ||
| 918 | If you are not using an SDK type image, you need to separately download and | ||
| 919 | install the stand-alone Yocto Project cross-toolchain tarball. | ||
| 920 | </p><p> | ||
| 921 | Regardless of the type of image you are using, you need to download the pre-built kernel | ||
| 922 | that you will boot in the QEMU emulator and then download and extract the target root | ||
| 923 | filesystem for your target machine’s architecture. | ||
| 924 | You can get architecture-specific binaries and filesystem from | ||
| 925 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top">machines</a>. | ||
| 926 | You can get stand-alone toolchains from | ||
| 927 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/" target="_top">toolchains</a>. | ||
| 928 | Once you have all your files, you set up the environment to emulate the hardware | ||
| 929 | by sourcing an environment setup script. | ||
| 930 | Finally, you start the QEMU emulator. | ||
| 931 | You can find details on all these steps in the | ||
| 932 | "<a class="link" href="#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>" | ||
| 933 | section of the Yocto Project Quick Start. | ||
| 934 | </p><p> | ||
| 935 | Using QEMU to emulate your hardware can result in speed issues | ||
| 936 | depending on the target and host architecture mix. | ||
| 937 | For example, using the <code class="filename">qemux86</code> image in the emulator | ||
| 938 | on an Intel-based 32-bit (x86) host machine is fast because the target and | ||
| 939 | host architectures match. | ||
| 940 | On the other hand, using the <code class="filename">qemuarm</code> image on the same Intel-based | ||
| 941 | host can be slower. | ||
| 942 | But, you still achieve faithful emulation of ARM-specific issues. | ||
| 943 | </p><p> | ||
| 944 | To speed things up, the QEMU images support using <code class="filename">distcc</code> | ||
| 945 | to call a cross-compiler outside the emulated system. | ||
| 946 | If you used <code class="filename">runqemu</code> to start QEMU, and the | ||
| 947 | <code class="filename">distccd</code> application is present on the host system, any | ||
| 948 | BitBake cross-compiling toolchain available from the build system is automatically | ||
| 949 | used from within QEMU simply by calling <code class="filename">distcc</code>. | ||
| 950 | You can accomplish this by defining the cross-compiler variable | ||
| 951 | (e.g. <code class="filename">export CC="distcc"</code>). | ||
| 952 | Alternatively, if you are using a suitable SDK image or the appropriate | ||
| 953 | stand-alone toolchain is present in <code class="filename">/opt/poky</code>, | ||
| 954 | the toolchain is also automatically used. | ||
| 955 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 956 | Several mechanisms exist that let you connect to the system running on the | ||
| 957 | QEMU emulator: | ||
| 958 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>QEMU provides a framebuffer interface that makes standard | ||
| 959 | consoles available.</p></li><li class="listitem"><p>Generally, headless embedded devices have a serial port. | ||
| 960 | If so, you can configure the operating system of the running image | ||
| 961 | to use that port to run a console. | ||
| 962 | The connection uses standard IP networking.</p></li><li class="listitem"><p>SSH servers exist in some QEMU images. | ||
| 963 | The <code class="filename">core-image-sato</code> QEMU image has a Dropbear secure | ||
| 964 | shell (ssh) server that runs with the root password disabled. | ||
| 965 | The <code class="filename">core-image-basic</code> and <code class="filename">core-image-lsb</code> QEMU images | ||
| 966 | have OpenSSH instead of Dropbear. | ||
| 967 | Including these SSH servers allow you to use standard <code class="filename">ssh</code> and | ||
| 968 | <code class="filename">scp</code> commands. | ||
| 969 | The <code class="filename">core-image-minimal</code> QEMU image, however, contains no ssh | ||
| 970 | server.</p></li><li class="listitem"><p>You can use a provided, user-space NFS server to boot the QEMU session | ||
| 971 | using a local copy of the root filesystem on the host. | ||
| 972 | In order to make this connection, you must extract a root filesystem tarball by using the | ||
| 973 | <code class="filename">runqemu-extract-sdk</code> command. | ||
| 974 | After running the command, you must then point the <code class="filename">runqemu</code> | ||
| 975 | script to the extracted directory instead of a root filesystem image file.</p></li></ul></div></div></div></div> | ||
| 976 | |||
| 977 | <div class="chapter" title="Chapter 3. The Yocto Project Open Source Development Environment"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-newbie"></a>Chapter 3. The Yocto Project Open Source Development Environment</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#open-source-philosophy">3.1. Open Source Philosophy</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-collaborate">3.2. Using the Yocto Project in a Team Environment</a></span></dt><dt><span class="section"><a href="#yocto-project-repositories">3.3. Yocto Project Source Repositories</a></span></dt><dt><span class="section"><a href="#yocto-project-terms">3.4. Yocto Project Terms</a></span></dt><dt><span class="section"><a href="#licensing">3.5. Licensing</a></span></dt><dt><span class="section"><a href="#git">3.6. Git</a></span></dt><dd><dl><dt><span class="section"><a href="#repositories-tags-and-branches">3.6.1. Repositories, Tags, and Branches</a></span></dt><dt><span class="section"><a href="#basic-commands">3.6.2. Basic Commands</a></span></dt></dl></dd><dt><span class="section"><a href="#workflows">3.7. Workflows</a></span></dt><dt><span class="section"><a href="#tracking-bugs">3.8. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#how-to-submit-a-change">3.9. How to Submit a Change</a></span></dt><dd><dl><dt><span class="section"><a href="#pushing-a-change-upstream">3.9.1. Using Scripts to Push a Change Upstream and Request a Pull</a></span></dt><dt><span class="section"><a href="#submitting-a-patch">3.9.2. Using Email to Submit a Patch</a></span></dt></dl></dd></dl></div><p> | ||
| 978 | This chapter helps you understand the Yocto Project as an open source development project. | ||
| 979 | In general, working in an open source environment is very different from working in a | ||
| 980 | closed, proprietary environment. | ||
| 981 | Additionally, the Yocto Project uses specific tools and constructs as part of its development | ||
| 982 | environment. | ||
| 983 | This chapter specifically addresses open source philosophy, licensing issues, code repositories, | ||
| 984 | the open source distributed version control system Git, and best practices using the Yocto Project. | ||
| 985 | </p><div class="section" title="3.1. Open Source Philosophy"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="open-source-philosophy"></a>3.1. Open Source Philosophy</h2></div></div></div><p> | ||
| 986 | Open source philosophy is characterized by software development directed by peer production | ||
| 987 | and collaboration through an active community of developers. | ||
| 988 | Contrast this to the more standard centralized development models used by commercial software | ||
| 989 | companies where a finite set of developers produces a product for sale using a defined set | ||
| 990 | of procedures that ultimately result in an end product whose architecture and source material | ||
| 991 | are closed to the public. | ||
| 992 | </p><p> | ||
| 993 | Open source projects conceptually have differing concurrent agendas, approaches, and production. | ||
| 994 | These facets of the development process can come from anyone in the public (community) that has a | ||
| 995 | stake in the software project. | ||
| 996 | The open source environment contains new copyright, licensing, domain, and consumer issues | ||
| 997 | that differ from the more traditional development environment. | ||
| 998 | In an open source environment, the end product, source material, and documentation are | ||
| 999 | all available to the public at no cost. | ||
| 1000 | </p><p> | ||
| 1001 | A benchmark example of an open source project is the Linux Kernel, which was initially conceived | ||
| 1002 | and created by Finnish computer science student Linus Torvalds in 1991. | ||
| 1003 | Conversely, a good example of a non-open source project is the | ||
| 1004 | <span class="trademark">Windows</span>® family of operating | ||
| 1005 | systems developed by <span class="trademark">Microsoft</span>® Corporation. | ||
| 1006 | </p><p> | ||
| 1007 | Wikipedia has a good historical description of the Open Source Philosophy | ||
| 1008 | <a class="ulink" href="http://en.wikipedia.org/wiki/Open_source" target="_top">here</a>. | ||
| 1009 | You can also find helpful information on how to participate in the Linux Community | ||
| 1010 | <a class="ulink" href="http://ldn.linuxfoundation.org/book/how-participate-linux-community" target="_top">here</a>. | ||
| 1011 | </p></div><div class="section" title="3.2. Using the Yocto Project in a Team Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-changes-collaborate"></a>3.2. Using the Yocto Project in a Team Environment</h2></div></div></div><p> | ||
| 1012 | It might not be immediately clear how you can use the Yocto Project in a team environment, | ||
| 1013 | or scale it for a large team of developers. | ||
| 1014 | The specifics of any situation determine the best solution. | ||
| 1015 | Granted that the Yocto Project offers immense flexibility regarding this, practices do exist | ||
| 1016 | that experience has shown work well. | ||
| 1017 | </p><p> | ||
| 1018 | The core component of any development effort with the Yocto Project is often an | ||
| 1019 | automated build and testing framework along with an image generation process. | ||
| 1020 | You can use these core components to check that the metadata can be built, | ||
| 1021 | highlight when commits break the build, and provide up-to-date images that | ||
| 1022 | allow developers to test the end result and use it as a base platform for further | ||
| 1023 | development. | ||
| 1024 | Experience shows that buildbot is a good fit for this role. | ||
| 1025 | What works well is to configure buildbot to make two types of builds: | ||
| 1026 | incremental and full (from scratch). | ||
| 1027 | See <a class="ulink" href="http://autobuilder.yoctoproject.org:8010/" target="_top">the buildbot for the | ||
| 1028 | Yocto Project</a> for an example implementation that uses buildbot. | ||
| 1029 | </p><p> | ||
| 1030 | You can tie incremental builds to a commit hook that triggers the build | ||
| 1031 | each time a commit is made to the metadata. | ||
| 1032 | This practice results in useful acid tests that determine whether a given commit | ||
| 1033 | breaks the build in some serious way. | ||
| 1034 | Associating a build to a commit can catch a lot of simple errors. | ||
| 1035 | Furthermore, the tests are fast so developers can get quick feedback on changes. | ||
| 1036 | </p><p> | ||
| 1037 | Full builds build and test everything from the ground up. | ||
| 1038 | These types of builds usually happen at predetermined times like during the | ||
| 1039 | night when the machine load is low. | ||
| 1040 | </p><p> | ||
| 1041 | Most teams have many pieces of software undergoing active development at any given time. | ||
| 1042 | You can derive large benefits by putting these pieces under the control of a source | ||
| 1043 | control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded | ||
| 1044 | build system that the Yocto Project uses. | ||
| 1045 | You can then set the autobuilder to pull the latest revisions of the packages | ||
| 1046 | and test the latest commits by the builds. | ||
| 1047 | This practice quickly highlights issues. | ||
| 1048 | The build system easily supports testing configurations that use both a | ||
| 1049 | stable known good revision and a floating revision. | ||
| 1050 | The build system can also take just the changes from specific source control branches. | ||
| 1051 | This capability allows you to track and test specific changes. | ||
| 1052 | </p><p> | ||
| 1053 | Perhaps the hardest part of setting this up is defining the software project or | ||
| 1054 | the metadata policies that surround the different source control systems. | ||
| 1055 | Of course circumstances will be different in each case. | ||
| 1056 | However, this situation reveals one of the Yocto Project's advantages - | ||
| 1057 | the system itself does not | ||
| 1058 | force any particular policy on users, unlike a lot of build systems. | ||
| 1059 | The system allows the best policies to be chosen for the given circumstances. | ||
| 1060 | </p></div><div class="section" title="3.3. Yocto Project Source Repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yocto-project-repositories"></a>3.3. Yocto Project Source Repositories</h2></div></div></div><p> | ||
| 1061 | The Yocto Project team maintains complete source repositories for all Yocto Project files | ||
| 1062 | at <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi</a>. | ||
| 1063 | This web-based source code browser is organized into categories by function such as | ||
| 1064 | IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. | ||
| 1065 | From the interface, you can click on any particular item in the "Name" column and | ||
| 1066 | see the URL at the bottom of the page that you need to set up a Git repository for | ||
| 1067 | that particular item. | ||
| 1068 | Having a local Git repository of the source directory (poky) allows you to | ||
| 1069 | make changes, contribute to the history, and ultimately enhance the Yocto Project's | ||
| 1070 | tools, Board Support Packages, and so forth. | ||
| 1071 | </p><p> | ||
| 1072 | Conversely, if you are a developer that is not interested in contributing back to the | ||
| 1073 | Yocto Project, you have the ability to simply download and extract release tarballs | ||
| 1074 | and use them within the Yocto Project environment. | ||
| 1075 | All that is required is a particular release of the Yocto Project and | ||
| 1076 | your application source code. | ||
| 1077 | </p><p> | ||
| 1078 | For any supported release of Yocto Project, you can go to the Yocto Project website’s | ||
| 1079 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">download page</a> and get a | ||
| 1080 | tarball of the release. | ||
| 1081 | You can also go to this site to download any supported BSP tarballs. | ||
| 1082 | Unpacking the tarball gives you a hierarchical source directory that lets you develop | ||
| 1083 | using the Yocto Project. | ||
| 1084 | </p><p> | ||
| 1085 | Once you are set up through either tarball extraction or creation of Git repositories, | ||
| 1086 | you are ready to develop. | ||
| 1087 | </p><p> | ||
| 1088 | In summary, here is where you can get the project files needed for development: | ||
| 1089 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a id="source-repositories"></a><span class="emphasis"><em><a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">Source Repositories:</a></em></span> | ||
| 1090 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto | ||
| 1091 | Metadata Layers. | ||
| 1092 | You can create local copies of Git repositories for each of these areas.</p><p> | ||
| 1093 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/source-repos.png" align="middle" width="540" /></td></tr></table><p> | ||
| 1094 | </p></li><li class="listitem"><p><a id="index-downloads"></a><span class="emphasis"><em><a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a></em></span> | ||
| 1095 | This area contains index releases such as | ||
| 1096 | the <span class="trademark">Eclipse</span>™ | ||
| 1097 | Yocto Plug-in, miscellaneous support, poky, pseudo, cross-development toolchains, | ||
| 1098 | and all released versions of Yocto Project in the form of images or tarballs. | ||
| 1099 | Downloading and extracting these files does not produce a local copy of the | ||
| 1100 | Git repository but rather a snapshot of a particular release or image.</p><p> | ||
| 1101 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/index-downloads.png" align="middle" width="540" /></td></tr></table><p> | ||
| 1102 | </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Yocto Project Download Page</a></em></span> | ||
| 1103 | This page on the Yocto Project website allows you to download any Yocto Project | ||
| 1104 | release or Board Support Package (BSP) in tarball form. | ||
| 1105 | The tarballs are similar to those found in the | ||
| 1106 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a> area.</p><p> | ||
| 1107 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/yp-download.png" align="middle" width="540" /></td></tr></table><p> | ||
| 1108 | </p></li></ul></div><p> | ||
| 1109 | </p></div><div class="section" title="3.4. Yocto Project Terms"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yocto-project-terms"></a>3.4. Yocto Project Terms</h2></div></div></div><p> | ||
| 1110 | Following is a list of terms and definitions users new to the Yocto Project development | ||
| 1111 | environment might find helpful. | ||
| 1112 | While some of these terms are universal, the list includes them just in case: | ||
| 1113 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Append Files:</em></span> Files that append build information to | ||
| 1114 | a recipe file. | ||
| 1115 | Append files are known as BitBake append files and <code class="filename">.bbappend</code> files. | ||
| 1116 | The OpenEmbedded build system expects every append file to have a corresponding and | ||
| 1117 | underlying recipe (<code class="filename">.bb</code>) file. | ||
| 1118 | Furthermore, the append file and the underlying recipe must have the same root filename. | ||
| 1119 | The filenames can differ only in the file type suffix used (e.g. | ||
| 1120 | <code class="filename">formfactor_0.0.bb</code> and <code class="filename">formfactor_0.0.bbappend</code>). | ||
| 1121 | </p><p>Information in append files overrides the information in the similarly-named recipe file. | ||
| 1122 | For examples of <code class="filename">.bbappend</code> file in use, see the | ||
| 1123 | "<a class="link" href="#using-bbappend-files" title="4.1.4. Using .bbappend Files">Using .bbappend Files</a>" and | ||
| 1124 | "<a class="link" href="#changing-recipes-kernel" title="A.5.2.4. Changing recipes-kernel">Changing <code class="filename">recipes-kernel</code></a>" | ||
| 1125 | sections.</p></li><li class="listitem"><p><span class="emphasis"><em>BitBake:</em></span> The task executor and scheduler used by | ||
| 1126 | the OpenEmbedded build system to build images. | ||
| 1127 | For more information on BitBake, see the <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top"> | ||
| 1128 | BitBake documentation</a>.</p></li><li class="listitem"><p><a id="build-directory"></a><span class="emphasis"><em>Build Directory:</em></span> | ||
| 1129 | This term refers to the area used by the OpenEmbedded build system for builds. | ||
| 1130 | The area is created when you <code class="filename">source</code> the setup | ||
| 1131 | environment script that is found in the source directory | ||
| 1132 | (i.e. <code class="filename">oe-init-build-env</code>). | ||
| 1133 | The <a class="link" href="#var-TOPDIR" target="_top"><code class="filename">TOPDIR</code></a> | ||
| 1134 | variable points to the build directory.</p><p>You have a lot of flexibility when creating the build directory. | ||
| 1135 | Following are some examples that show how to create the directory: | ||
| 1136 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Create the build directory in your current working directory | ||
| 1137 | and name it <code class="filename">build</code>. | ||
| 1138 | This is the default behavior. | ||
| 1139 | </p><pre class="literallayout"> | ||
| 1140 | $ source oe-init-build-env | ||
| 1141 | </pre></li><li class="listitem"><p>Provide a directory path and specifically name the build | ||
| 1142 | directory. | ||
| 1143 | This next example creates a build directory named <code class="filename">YP-8.0</code> | ||
| 1144 | in your home directory within the directory <code class="filename">mybuilds</code>. | ||
| 1145 | If <code class="filename">mybuilds</code> does not exist, the directory is created for you: | ||
| 1146 | </p><pre class="literallayout"> | ||
| 1147 | $ source poky-1.2+snapshot-8.0/oe-init-build-env $HOME/mybuilds/YP-8.0 | ||
| 1148 | </pre></li><li class="listitem"><p>Provide an existing directory to use as the build directory. | ||
| 1149 | This example uses the existing <code class="filename">mybuilds</code> directory | ||
| 1150 | as the build directory. | ||
| 1151 | </p><pre class="literallayout"> | ||
| 1152 | $ source poky-1.2+snapshot-8.0/oe-init-build-env $HOME/mybuilds/ | ||
| 1153 | </pre></li></ul></div><p> | ||
| 1154 | </p></li><li class="listitem"><p><span class="emphasis"><em>Build System:</em></span> In the context of the Yocto Project | ||
| 1155 | this term refers to the OpenEmbedded build system used by the project. | ||
| 1156 | This build system is based on the project known as "Poky." | ||
| 1157 | For some historical information about Poky, see the | ||
| 1158 | <a class="link" href="#poky">poky</a> term further along in this section. | ||
| 1159 | </p></li><li class="listitem"><p><span class="emphasis"><em>Classes:</em></span> Files that provide for logic encapsulation | ||
| 1160 | and inheritance allowing commonly used patterns to be defined once and easily used | ||
| 1161 | in multiple recipes. | ||
| 1162 | Class files end with the <code class="filename">.bbclass</code> filename extension. | ||
| 1163 | </p></li><li class="listitem"><p><span class="emphasis"><em>Configuration File:</em></span> Configuration information in various | ||
| 1164 | <code class="filename">.conf</code> files provides global definitions of variables. | ||
| 1165 | The <code class="filename">conf/local.conf</code> configuration file in the | ||
| 1166 | <a class="link" href="#build-directory">build directory</a> | ||
| 1167 | contains user-defined variables that affect each build. | ||
| 1168 | The <code class="filename">meta-yocto/conf/distro/poky.conf</code> configuration file | ||
| 1169 | defines Yocto ‘distro’ configuration | ||
| 1170 | variables used only when building with this policy. | ||
| 1171 | Machine configuration files, which | ||
| 1172 | are located throughout the | ||
| 1173 | <a class="link" href="#source-directory">source directory</a>, define | ||
| 1174 | variables for specific hardware and are only used when building for that target | ||
| 1175 | (e.g. the <code class="filename">machine/beagleboard.conf</code> configuration file defines | ||
| 1176 | variables for the Texas Instruments ARM Cortex-A8 development board). | ||
| 1177 | Configuration files end with a <code class="filename">.conf</code> filename extension. | ||
| 1178 | </p></li><li class="listitem"><p><span class="emphasis"><em>Cross-Development Toolchain:</em></span> | ||
| 1179 | A collection of software development | ||
| 1180 | tools and utilities that allow you to develop software for targeted architectures. | ||
| 1181 | This toolchain contains cross-compilers, linkers, and debuggers that are specific to | ||
| 1182 | an architecture. | ||
| 1183 | You can use the OpenEmbedded build system to build cross-development toolchains in tarball | ||
| 1184 | form that, when | ||
| 1185 | unpacked, contain the development tools you need to cross-compile and test your software. | ||
| 1186 | The Yocto Project ships with images that contain toolchains for supported architectures | ||
| 1187 | as well. | ||
| 1188 | Sometimes this toolchain is referred to as the meta-toolchain.</p></li><li class="listitem"><p><span class="emphasis"><em>Image:</em></span> An image is the result produced when | ||
| 1189 | BitBake processes a given collection of recipes and related metadata. | ||
| 1190 | Images are the binary output that run on specific hardware and for specific | ||
| 1191 | use cases. | ||
| 1192 | For a list of the supported image types that the Yocto Project provides, see the | ||
| 1193 | "<a class="link" href="#ref-images" target="_top">Images</a>" | ||
| 1194 | chapter in the Yocto Project Reference Manual.</p></li><li class="listitem"><p><a id="layer"></a><span class="emphasis"><em>Layer:</em></span> A collection of recipes representing the core, | ||
| 1195 | a BSP, or an application stack. | ||
| 1196 | For a discussion on BSP Layers, see the | ||
| 1197 | "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" | ||
| 1198 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</p></li><li class="listitem"><p><a id="metadata"></a><span class="emphasis"><em>Metadata:</em></span> The files that BitBake parses when | ||
| 1199 | building an image. | ||
| 1200 | Metadata includes recipes, classes, and configuration files.</p></li><li class="listitem"><p><span class="emphasis"><em>OE-Core:</em></span> A core set of metadata originating | ||
| 1201 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project. | ||
| 1202 | This metadata is found in the <code class="filename">meta</code> directory of the source | ||
| 1203 | directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Package:</em></span> The packaged output from a baked recipe. | ||
| 1204 | A package is generally the compiled binaries produced from the recipe's sources. | ||
| 1205 | You ‘bake’ something by running it through BitBake.</p></li><li class="listitem"><p><a id="poky"></a><span class="emphasis"><em>Poky:</em></span> The term "poky" can mean several things. | ||
| 1206 | In its most general sence, it is an open-source project that was initially developed | ||
| 1207 | by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded | ||
| 1208 | build system becoming a build system for embedded images. | ||
| 1209 | After Intel Corporation aquired OpenedHand, the project poky became the basis for | ||
| 1210 | the Yocto Project's build system. | ||
| 1211 | Within the Yocto Project source repositories, poky exists as a separate Git repository | ||
| 1212 | that can be cloned to yield a local copy on the host system. | ||
| 1213 | Thus, "poky" can refer to the local copy of the source directory used to develop within | ||
| 1214 | the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>Recipe:</em></span> A set of instructions for building packages. | ||
| 1215 | A recipe describes where you get source code and which patches to apply. | ||
| 1216 | Recipes describe dependencies for libraries or for other recipes, and they | ||
| 1217 | also contain configuration and compilation options. | ||
| 1218 | Recipes contain the logical unit of execution, the software/images to build, and | ||
| 1219 | use the <code class="filename">.bb</code> file extension.</p></li><li class="listitem"><p><a id="source-directory"></a><span class="emphasis"><em>Source Directory:</em></span> | ||
| 1220 | This term refers to the directory structure created as a result of either downloading | ||
| 1221 | and unpacking a Yocto Project release tarball or creating a local copy of | ||
| 1222 | <code class="filename">poky</code> Git repository <code class="filename">git://git.yoctoproject.org/poky</code>. | ||
| 1223 | Sometimes you might here the term "poky directory" used to refer to this | ||
| 1224 | directory structure.</p><p>The source directory contains BitBake, Documentation, metadata and | ||
| 1225 | other files that all support the Yocto Project. | ||
| 1226 | Consequently, you must have the source directory in place on your development | ||
| 1227 | system in order to do any development using the Yocto Project.</p><p>For tarball expansion, the name of the top-level directory of the source directory | ||
| 1228 | is derived from the Yocto Project release tarball. | ||
| 1229 | For example, downloading and unpacking <code class="filename">poky-1.2+snapshot-8.0.tar.bz2</code> | ||
| 1230 | results in a source directory whose top-level folder is named | ||
| 1231 | <code class="filename">poky-1.2+snapshot-8.0</code>. | ||
| 1232 | If you create a local copy of the Git repository, then you can name the repository | ||
| 1233 | anything you like. | ||
| 1234 | Throughout much of the documentation, <code class="filename">poky</code> is used as the name of | ||
| 1235 | the top-level folder of the local copy of the poky Git repository. | ||
| 1236 | So, for example, cloning the <code class="filename">poky</code> Git repository results in a | ||
| 1237 | local Git repository whose top-level folder is also named <code class="filename">poky</code>.</p><p>It is important to understand the differences between the source directory created | ||
| 1238 | by unpacking a released tarball as compared to cloning | ||
| 1239 | <code class="filename">git://git.yoctoproject.org/poky</code>. | ||
| 1240 | When you unpack a tarball, you have an exact copy of the files based on the time of | ||
| 1241 | release - a fixed release point. | ||
| 1242 | Any changes you make to your local files in the source directory are on top of the release. | ||
| 1243 | On the other hand, when you clone the <code class="filename">poky</code> Git repository, you have an | ||
| 1244 | active development repository. | ||
| 1245 | In this case, any local changes you make to the source directory can be later applied | ||
| 1246 | to active development branches of the upstream <code class="filename">poky</code> Git | ||
| 1247 | repository.</p><p>Finally, if you want to track a set of local changes while starting from the same point | ||
| 1248 | as a release tarball, you can create a local Git branch that | ||
| 1249 | reflects the exact copy of the files at the time of their release. | ||
| 1250 | You do this using Git tags that are part of the repository.</p><p>For more information on concepts around Git repositories, branches, and tags, | ||
| 1251 | see the | ||
| 1252 | "<a class="link" href="#repositories-tags-and-branches" title="3.6.1. Repositories, Tags, and Branches">Repositories, Tags, and Branches</a>" | ||
| 1253 | section.</p></li><li class="listitem"><p><span class="emphasis"><em>Tasks:</em></span> Arbitrary groups of software Recipes. | ||
| 1254 | You simply use Tasks to hold recipes that, when built, usually accomplish a single task. | ||
| 1255 | For example, a task could contain the recipes for a company’s proprietary or value-add software. | ||
| 1256 | Or, the task could contain the recipes that enable graphics. | ||
| 1257 | A task is really just another recipe. | ||
| 1258 | Because task files are recipes, they end with the <code class="filename">.bb</code> filename | ||
| 1259 | extension.</p></li><li class="listitem"><p><span class="emphasis"><em>Upstream:</em></span> A reference to source code or repositories | ||
| 1260 | that are not local to the development system but located in a master area that is controlled | ||
| 1261 | by the maintainer of the source code. | ||
| 1262 | For example, in order for a developer to work on a particular piece of code, they need to | ||
| 1263 | first get a copy of it from an "upstream" source.</p></li></ul></div><p> | ||
| 1264 | </p></div><div class="section" title="3.5. Licensing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licensing"></a>3.5. Licensing</h2></div></div></div><p> | ||
| 1265 | Because open source projects are open to the public, they have different licensing structures in place. | ||
| 1266 | License evolution for both Open Source and Free Software has an interesting history. | ||
| 1267 | If you are interested in this history, you can find basic information here: | ||
| 1268 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://en.wikipedia.org/wiki/Open-source_license" target="_top">Open source license history</a> | ||
| 1269 | </p></li><li class="listitem"><p><a class="ulink" href="http://en.wikipedia.org/wiki/Free_software_license" target="_top">Free software license | ||
| 1270 | history</a></p></li></ul></div><p> | ||
| 1271 | </p><p> | ||
| 1272 | In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology | ||
| 1273 | (MIT) License. | ||
| 1274 | MIT licensing permits the reuse of software within proprietary software as long as the | ||
| 1275 | license is distributed with that software. | ||
| 1276 | MIT is also compatible with the GNU General Public License (GPL). | ||
| 1277 | Patches to the Yocto Project follow the upstream licensing scheme. | ||
| 1278 | You can find information on the MIT license at | ||
| 1279 | <a class="ulink" href="http://www.opensource.org/licenses/mit-license.php" target="_top">here</a>. | ||
| 1280 | You can find information on the GNU GPL <a class="ulink" href="http://www.opensource.org/licenses/LGPL-3.0" target="_top"> | ||
| 1281 | here</a>. | ||
| 1282 | </p><p> | ||
| 1283 | When you build an image using Yocto Project, the build process uses a known list of licenses to | ||
| 1284 | ensure compliance. | ||
| 1285 | You can find this list in the Yocto Project files directory at | ||
| 1286 | <code class="filename">meta/files/common-licenses</code>. | ||
| 1287 | Once the build completes, the list of all licenses found and used during that build are | ||
| 1288 | kept in the | ||
| 1289 | <a class="link" href="#build-directory">build directory</a> at | ||
| 1290 | <code class="filename">tmp/deploy/images/licenses</code>. | ||
| 1291 | </p><p> | ||
| 1292 | If a module requires a license that is not in the base list, the build process | ||
| 1293 | generates a warning during the build. | ||
| 1294 | These tools make it easier for a developer to be certain of the licenses with which | ||
| 1295 | their shipped products must comply. | ||
| 1296 | However, even with these tools it is still up to the developer to resolve potential licensing issues. | ||
| 1297 | </p><p> | ||
| 1298 | The base list of licenses used by the build process is a combination of the Software Package | ||
| 1299 | Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. | ||
| 1300 | <a class="ulink" href="http://spdx.org" target="_top">SPDX Group</a> is a working group of the Linux Foundation | ||
| 1301 | that maintains a specification | ||
| 1302 | for a standard format for communicating the components, licenses, and copyrights | ||
| 1303 | associated with a software package. | ||
| 1304 | <a class="ulink" href="http://opensource.org" target="_top">OSI</a> is a corporation dedicated to the Open Source | ||
| 1305 | Definition and the effort for reviewing and approving licenses that are OSD-conformant. | ||
| 1306 | </p><p> | ||
| 1307 | You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses | ||
| 1308 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/files/common-licenses" target="_top">here</a>. | ||
| 1309 | This wiki page discusses the license infrastructure used by the Yocto Project. | ||
| 1310 | </p></div><div class="section" title="3.6. Git"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="git"></a>3.6. Git</h2></div></div></div><p> | ||
| 1311 | The Yocto Project uses Git, which is a free, open source distributed version control system. | ||
| 1312 | Git supports distributed development, non-linear development, and can handle large projects. | ||
| 1313 | It is best that you have some fundamental understanding of how Git tracks projects and | ||
| 1314 | how to work with Git if you are going to use Yocto Project for development. | ||
| 1315 | This section provides a quick overview of how Git works and provides you with a summary | ||
| 1316 | of some essential Git commands. | ||
| 1317 | </p><p> | ||
| 1318 | For more information on Git, see | ||
| 1319 | <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. | ||
| 1320 | If you need to download Git, go to <a class="ulink" href="http://git-scm.com/download" target="_top">http://git-scm.com/download</a>. | ||
| 1321 | </p><div class="section" title="3.6.1. Repositories, Tags, and Branches"><div class="titlepage"><div><div><h3 class="title"><a id="repositories-tags-and-branches"></a>3.6.1. Repositories, Tags, and Branches</h3></div></div></div><p> | ||
| 1322 | As mentioned earlier in section | ||
| 1323 | "<a class="link" href="#yocto-project-repositories" title="3.3. Yocto Project Source Repositories">Yocto Project Source Repositories</a>", | ||
| 1324 | the Yocto Project maintains source repositories at | ||
| 1325 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. | ||
| 1326 | If you look at this web-interface of the repositories, each item is a separate | ||
| 1327 | Git repository. | ||
| 1328 | </p><p> | ||
| 1329 | Git repositories use branching techniques that track content change (not files) | ||
| 1330 | within a project (e.g. a new feature or updated documentation). | ||
| 1331 | Creating a tree-like structure based on project divergence allows for excellent historical | ||
| 1332 | information over the life of a project. | ||
| 1333 | This methodology also allows for an environment in which you can do lots of | ||
| 1334 | local experimentation on a project as you develop changes or new features. | ||
| 1335 | </p><p> | ||
| 1336 | A Git repository represents all development efforts for a given project. | ||
| 1337 | For example, the Git repository <code class="filename">poky</code> contains all changes | ||
| 1338 | and developments for Poky over the course of its entire life. | ||
| 1339 | That means that all changes that make up all releases are captured. | ||
| 1340 | The repository maintains a complete history of changes. | ||
| 1341 | </p><p> | ||
| 1342 | You can create a local copy of any repository by "cloning" it with the Git | ||
| 1343 | <code class="filename">clone</code> command. | ||
| 1344 | When you clone a Git repository, you end up with an identical copy of the | ||
| 1345 | repository on your development system. | ||
| 1346 | Once you have a local copy of a repository, you can take steps to develop locally. | ||
| 1347 | For examples on how to clone Git repositories, see the section | ||
| 1348 | "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Set Up</a>" earlier in this manual. | ||
| 1349 | </p><p> | ||
| 1350 | It is important to understand that Git tracks content change and not files. | ||
| 1351 | Git uses "branches" to organize different development efforts. | ||
| 1352 | For example, the <code class="filename">poky</code> repository has | ||
| 1353 | <code class="filename">laverne</code>, <code class="filename">bernard</code>, | ||
| 1354 | <code class="filename">edison</code>, <code class="filename">denzil</code> and | ||
| 1355 | <code class="filename">master</code> branches among | ||
| 1356 | others. | ||
| 1357 | You can see all the branches by going to | ||
| 1358 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and | ||
| 1359 | clicking on the | ||
| 1360 | <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/heads" target="_top">[...]</a></code> | ||
| 1361 | link beneath the "Branch" heading. | ||
| 1362 | </p><p> | ||
| 1363 | Each of these branches represents a specific area of development. | ||
| 1364 | The <code class="filename">master</code> branch represents the current or most recent | ||
| 1365 | development. | ||
| 1366 | All other branches represent off-shoots of the <code class="filename">master</code> | ||
| 1367 | branch. | ||
| 1368 | </p><p> | ||
| 1369 | When you create a local copy of a Git repository, the copy has the same set | ||
| 1370 | of branches as the original. | ||
| 1371 | This means you can use Git to create a local working area (also called a branch) | ||
| 1372 | that tracks a specific development branch from the source Git repository. | ||
| 1373 | in other words, you can define your local Git environment to work on any development | ||
| 1374 | branch in the repository. | ||
| 1375 | To help illustrate, here is a set of commands that creates a local copy of the | ||
| 1376 | <code class="filename">poky</code> Git repository and then creates and checks out a local | ||
| 1377 | Git branch that tracks the Yocto Project 1.3 Release (1.2+snapshot) development: | ||
| 1378 | </p><pre class="literallayout"> | ||
| 1379 | $ cd ~ | ||
| 1380 | $ git clone git://git.yoctoproject.org/poky | ||
| 1381 | $ cd poky | ||
| 1382 | $ git checkout -b 1.2+snapshot origin/1.2+snapshot | ||
| 1383 | </pre><p> | ||
| 1384 | In this example, the name of the top-level directory of your local Yocto Project | ||
| 1385 | Files Git repository is <code class="filename">poky</code>, | ||
| 1386 | and the name of the local working area (or local branch) you have created and checked | ||
| 1387 | out is <code class="filename">1.2+snapshot</code>. | ||
| 1388 | The files in your repository now reflect the same files that are in the | ||
| 1389 | <code class="filename">1.2+snapshot</code> development branch of the Yocto Project's | ||
| 1390 | <code class="filename">poky</code> repository. | ||
| 1391 | It is important to understand that when you create and checkout a | ||
| 1392 | local working branch based on a branch name, | ||
| 1393 | your local environment matches the "tip" of that development branch | ||
| 1394 | at the time you created your local branch, which could be | ||
| 1395 | different than the files at the time of a similarly named release. | ||
| 1396 | In other words, creating and checking out a local branch based on the | ||
| 1397 | <code class="filename">1.2+snapshot</code> branch name is not the same as creating and | ||
| 1398 | checking out a local branch based on the <code class="filename">1.2+snapshot-1.3</code> | ||
| 1399 | release. | ||
| 1400 | Keep reading to see how you create a local snapshot of a Yocto Project Release. | ||
| 1401 | </p><p> | ||
| 1402 | Git uses "tags" to mark specific changes in a repository. | ||
| 1403 | Typically, a tag is used to mark a special point such as the final change | ||
| 1404 | before a project is released. | ||
| 1405 | You can see the tags used with the <code class="filename">poky</code> Git repository | ||
| 1406 | by going to <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and | ||
| 1407 | clicking on the | ||
| 1408 | <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/tags" target="_top">[...]</a></code> | ||
| 1409 | link beneath the "Tag" heading. | ||
| 1410 | </p><p> | ||
| 1411 | Some key tags are <code class="filename">laverne-4.0</code>, <code class="filename">bernard-5.0</code>, | ||
| 1412 | and <code class="filename">1.2+snapshot-8.0</code>. | ||
| 1413 | These tags represent Yocto Project releases. | ||
| 1414 | </p><p> | ||
| 1415 | When you create a local copy of the Git repository, you also have access to all the | ||
| 1416 | tags. | ||
| 1417 | Similar to branches, you can create and checkout a local working Git branch based | ||
| 1418 | on a tag name. | ||
| 1419 | When you do this, you get a snapshot of the Git repository that reflects | ||
| 1420 | the state of the files when the change was made associated with that tag. | ||
| 1421 | The most common use is to checkout a working branch that matches a specific | ||
| 1422 | Yocto Project release. | ||
| 1423 | Here is an example: | ||
| 1424 | </p><pre class="literallayout"> | ||
| 1425 | $ cd ~ | ||
| 1426 | $ git clone git://git.yoctoproject.org/poky | ||
| 1427 | $ cd poky | ||
| 1428 | $ git checkout -b my-1.2+snapshot-8.0 1.2+snapshot-8.0 | ||
| 1429 | </pre><p> | ||
| 1430 | In this example, the name of the top-level directory of your local Yocto Project | ||
| 1431 | Files Git repository is <code class="filename">poky</code>. | ||
| 1432 | And, the name of the local branch you have created and checked out is | ||
| 1433 | <code class="filename">my-1.2+snapshot-8.0</code>. | ||
| 1434 | The files in your repository now exactly match the Yocto Project 1.3 | ||
| 1435 | Release tag (<code class="filename">1.2+snapshot-8.0</code>). | ||
| 1436 | It is important to understand that when you create and checkout a local | ||
| 1437 | working branch based on a tag, your environment matches a specific point | ||
| 1438 | in time and not a development branch. | ||
| 1439 | </p></div><div class="section" title="3.6.2. Basic Commands"><div class="titlepage"><div><div><h3 class="title"><a id="basic-commands"></a>3.6.2. Basic Commands</h3></div></div></div><p> | ||
| 1440 | Git has an extensive set of commands that lets you manage changes and perform | ||
| 1441 | collaboration over the life of a project. | ||
| 1442 | Conveniently though, you can manage with a small set of basic operations and workflows | ||
| 1443 | once you understand the basic philosophy behind Git. | ||
| 1444 | You do not have to be an expert in Git to be functional. | ||
| 1445 | A good place to look for instruction on a minimal set of Git commands is | ||
| 1446 | <a class="ulink" href="http://git-scm.com/documentation" target="_top">here</a>. | ||
| 1447 | If you need to download Git, you can do so | ||
| 1448 | <a class="ulink" href="http://git-scm.com/download" target="_top">here</a>. | ||
| 1449 | </p><p> | ||
| 1450 | If you don’t know much about Git, we suggest you educate | ||
| 1451 | yourself by visiting the links previously mentioned. | ||
| 1452 | </p><p> | ||
| 1453 | The following list briefly describes some basic Git operations as a way to get started. | ||
| 1454 | As with any set of commands, this list (in most cases) simply shows the base command and | ||
| 1455 | omits the many arguments they support. | ||
| 1456 | See the Git documentation for complete descriptions and strategies on how to use these commands: | ||
| 1457 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">git init</code>:</em></span> Initializes an empty Git repository. | ||
| 1458 | You cannot use Git commands unless you have a <code class="filename">.git</code> repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git clone</code>:</em></span> Creates a clone of a repository. | ||
| 1459 | During collaboration, this command allows you to create a local repository that is on | ||
| 1460 | equal footing with a fellow developer’s repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git add</code>:</em></span> Adds updated file contents | ||
| 1461 | to the index that | ||
| 1462 | Git uses to track changes. | ||
| 1463 | You must add all files that have changed before you can commit them.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git commit</code>:</em></span> Creates a “commit” that documents | ||
| 1464 | the changes you made. | ||
| 1465 | Commits are used for historical purposes, for determining if a maintainer of a project | ||
| 1466 | will allow the change, and for ultimately pushing the change from your local Git repository | ||
| 1467 | into the project’s upstream (or master) repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git status</code>:</em></span> Reports any modified files that | ||
| 1468 | possibly need to be added and committed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout <branch-name></code>:</em></span> Changes | ||
| 1469 | your working branch. | ||
| 1470 | This command is analogous to “cd”.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout –b <working-branch></code>:</em></span> Creates | ||
| 1471 | a working branch on your local machine where you can isolate work. | ||
| 1472 | It is a good idea to use local branches when adding specific features or changes. | ||
| 1473 | This way if you don’t like what you have done you can easily get rid of the work.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch</code>:</em></span> Reports existing branches and | ||
| 1474 | tells you which branch in which you are currently working.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch -D <branch-name></code>:</em></span> | ||
| 1475 | Deletes an existing branch. | ||
| 1476 | You need to be in a branch other than the one you are deleting | ||
| 1477 | in order to delete <branch-name>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git pull</code>:</em></span> Retrieves information | ||
| 1478 | from an upstream Git | ||
| 1479 | repository and places it in your local Git repository. | ||
| 1480 | You use this command to make sure you are synchronized with the repository | ||
| 1481 | from which you are basing changes (.e.g. the master repository).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git push</code>:</em></span> Sends all your local changes you | ||
| 1482 | have committed to an upstream Git repository (e.g. a contribution repository). | ||
| 1483 | The maintainer of the project draws from these repositories when adding your changes to the | ||
| 1484 | project’s master repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git merge</code>:</em></span> Combines or adds changes from one | ||
| 1485 | local branch of your repository with another branch. | ||
| 1486 | When you create a local Git repository, the default branch is named “master”. | ||
| 1487 | A typical workflow is to create a temporary branch for isolated work, make and commit your | ||
| 1488 | changes, switch to your local master branch, merge the changes from the temporary branch into the | ||
| 1489 | local master branch, and then delete the temporary branch.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git cherry-pick</code>:</em></span> Choose and apply specific | ||
| 1490 | commits from one branch into another branch. | ||
| 1491 | There are times when you might not be able to merge all the changes in one branch with | ||
| 1492 | another but need to pick out certain ones.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gitk</code>:</em></span> Provides a GUI view of the branches | ||
| 1493 | and changes in your local Git repository. | ||
| 1494 | This command is a good way to graphically see where things have diverged in your | ||
| 1495 | local repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git log</code>:</em></span> Reports a history of your changes to the | ||
| 1496 | repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git diff</code>:</em></span> Displays line-by-line differences | ||
| 1497 | between your local working files and the same files in the upstream Git repository that your | ||
| 1498 | branch currently tracks.</p></li></ul></div><p> | ||
| 1499 | </p></div></div><div class="section" title="3.7. Workflows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="workflows"></a>3.7. Workflows</h2></div></div></div><p> | ||
| 1500 | This section provides some overview on workflows using Git. | ||
| 1501 | In particular, the information covers basic practices that describe roles and actions in a | ||
| 1502 | collaborative development environment. | ||
| 1503 | Again, if you are familiar with this type of development environment, you might want to just | ||
| 1504 | skip this section. | ||
| 1505 | </p><p> | ||
| 1506 | The Yocto Project files are maintained using Git in a "master" branch whose Git history | ||
| 1507 | tracks every change and whose structure provides branches for all diverging functionality. | ||
| 1508 | Although there is no need to use Git, many open source projects do so. | ||
| 1509 | For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" | ||
| 1510 | branch of the Git repository. | ||
| 1511 | The "master" branch is the “upstream” repository where the final builds of the project occur. | ||
| 1512 | The maintainer is responsible for allowing changes in from other developers and for | ||
| 1513 | organizing the underlying branch structure to reflect release strategies and so forth. | ||
| 1514 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>You can see who is the maintainer for Yocto Project files by examining the | ||
| 1515 | <code class="filename">distro_tracking_fields.inc</code> file in the Yocto Project | ||
| 1516 | <code class="filename">meta/conf/distro/include</code> directory.</div><p> | ||
| 1517 | </p><p> | ||
| 1518 | The project also has contribution repositories known as “contrib” areas. | ||
| 1519 | These areas temporarily hold changes to the project that have been submitted or committed | ||
| 1520 | by the Yocto Project development team and by community members that contribute to the project. | ||
| 1521 | The maintainer determines if the changes are qualified to be moved from the "contrib" areas | ||
| 1522 | into the "master" branch of the Git repository. | ||
| 1523 | </p><p> | ||
| 1524 | Developers (including contributing community members) create and maintain cloned repositories | ||
| 1525 | of the upstream "master" branch. | ||
| 1526 | These repositories are local to their development platforms and are used to develop changes. | ||
| 1527 | When a developer is satisfied with a particular feature or change, they “push” the changes | ||
| 1528 | to the appropriate "contrib" repository. | ||
| 1529 | </p><p> | ||
| 1530 | Developers are responsible for keeping their local repository up-to-date with "master". | ||
| 1531 | They are also responsible for straightening out any conflicts that might arise within files | ||
| 1532 | that are being worked on simultaneously by more than one person. | ||
| 1533 | All this work is done locally on the developer’s machine before anything is pushed to a | ||
| 1534 | "contrib" area and examined at the maintainer’s level. | ||
| 1535 | </p><p> | ||
| 1536 | A somewhat formal method exists by which developers commit changes and push them into the | ||
| 1537 | "contrib" area and subsequently request that the maintainer include them into "master" | ||
| 1538 | This process is called “submitting a patch” or “submitting a change.” | ||
| 1539 | </p><p> | ||
| 1540 | To summarize the environment: we have a single point of entry for changes into the project’s | ||
| 1541 | "master" branch of the Git repository, which is controlled by the project’s maintainer. | ||
| 1542 | And, we have a set of developers who independently develop, test, and submit changes | ||
| 1543 | to "contrib" areas for the maintainer to examine. | ||
| 1544 | The maintainer then chooses which changes are going to become a permanent part of the project. | ||
| 1545 | </p><p> | ||
| 1546 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 270px"><td align="left"><img src="figures/git-workflow.png" align="left" height="270" /></td></tr></table><p> | ||
| 1547 | </p><p> | ||
| 1548 | While each development environment is unique, there are some best practices or methods | ||
| 1549 | that help development run smoothly. | ||
| 1550 | The following list describes some of these practices. | ||
| 1551 | For more information about Git workflows, see the workflow topics in the | ||
| 1552 | <a class="ulink" href="http://book.git-scm.com" target="_top">Git Community Book</a>. | ||
| 1553 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Make Small Changes:</em></span> It is best to keep the changes you commit | ||
| 1554 | small as compared to bundling many disparate changes into a single commit. | ||
| 1555 | This practice not only keeps things manageable but also allows the maintainer | ||
| 1556 | to more easily include or refuse changes.</p><p>It is also good practice to leave the repository in a state that allows you to | ||
| 1557 | still successfully build your project. In other words, do not commit half of a feature, | ||
| 1558 | then add the other half in a separate, later commit. | ||
| 1559 | Each commit should take you from one buildable project state to another | ||
| 1560 | buildable state.</p></li><li class="listitem"><p><span class="emphasis"><em>Use Branches Liberally:</em></span> It is very easy to create, use, and | ||
| 1561 | delete local branches in your working Git repository. | ||
| 1562 | You can name these branches anything you like. | ||
| 1563 | It is helpful to give them names associated with the particular feature or change | ||
| 1564 | on which you are working. | ||
| 1565 | Once you are done with a feature or change, simply discard the branch.</p></li><li class="listitem"><p><span class="emphasis"><em>Merge Changes:</em></span> The <code class="filename">git merge</code> | ||
| 1566 | command allows you to take the | ||
| 1567 | changes from one branch and fold them into another branch. | ||
| 1568 | This process is especially helpful when more than a single developer might be working | ||
| 1569 | on different parts of the same feature. | ||
| 1570 | Merging changes also automatically identifies any collisions or “conflicts” | ||
| 1571 | that might happen as a result of the same lines of code being altered by two different | ||
| 1572 | developers.</p></li><li class="listitem"><p><span class="emphasis"><em>Manage Branches:</em></span> Because branches are easy to use, you should | ||
| 1573 | use a system where branches indicate varying levels of code readiness. | ||
| 1574 | For example, you can have a “work” branch to develop in, a “test” branch where the code or | ||
| 1575 | change is tested, a “stage” branch where changes are ready to be committed, and so forth. | ||
| 1576 | As your project develops, you can merge code across the branches to reflect ever-increasing | ||
| 1577 | stable states of the development.</p></li><li class="listitem"><p><span class="emphasis"><em>Use Push and Pull:</em></span> The push-pull workflow is based on the | ||
| 1578 | concept of developers “pushing” local commits to a remote repository, which is | ||
| 1579 | usually a contribution repository. | ||
| 1580 | This workflow is also based on developers “pulling” known states of the project down into their | ||
| 1581 | local development repositories. | ||
| 1582 | The workflow easily allows you to pull changes submitted by other developers from the | ||
| 1583 | upstream repository into your work area ensuring that you have the most recent software | ||
| 1584 | on which to develop. | ||
| 1585 | The Yocto Project has two scripts named <code class="filename">create-pull-request</code> and | ||
| 1586 | <code class="filename">send-pull-request</code> that ship with the release to facilitate this | ||
| 1587 | workflow. | ||
| 1588 | You can find these scripts in the local Yocto Project files Git repository in | ||
| 1589 | the <code class="filename">scripts</code> directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Patch Workflow:</em></span> This workflow allows you to notify the | ||
| 1590 | maintainer through an email that you have a change (or patch) you would like considered | ||
| 1591 | for the "master" branch of the Git repository. | ||
| 1592 | To send this type of change you format the patch and then send the email using the Git commands | ||
| 1593 | <code class="filename">git format-patch</code> and <code class="filename">git send-email</code>. | ||
| 1594 | You can find information on how to submit later in this chapter.</p></li></ul></div><p> | ||
| 1595 | </p></div><div class="section" title="3.8. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="tracking-bugs"></a>3.8. Tracking Bugs</h2></div></div></div><p> | ||
| 1596 | The Yocto Project uses its own implementation of | ||
| 1597 | <a class="ulink" href="http://www.bugzilla.org/about/" target="_top">Bugzilla</a> to track bugs. | ||
| 1598 | Implementations of Bugzilla work well for group development because they track bugs and code | ||
| 1599 | changes, can be used to communicate changes and problems with developers, can be used to | ||
| 1600 | submit and review patches, and can be used to manage quality assurance. | ||
| 1601 | The home page for the Yocto Project implementation of Bugzilla is | ||
| 1602 | <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>. | ||
| 1603 | </p><p> | ||
| 1604 | Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself | ||
| 1605 | such as when discovering an issue with some component of the build system that acts contrary | ||
| 1606 | to the documentation or your expectations. | ||
| 1607 | Following is the general procedure for submitting a new bug using the Yocto Project | ||
| 1608 | Bugzilla. | ||
| 1609 | You can find more information on defect management, bug tracking, and feature request | ||
| 1610 | processes all accomplished through the Yocto Project Bugzilla on the wiki page | ||
| 1611 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Bugzilla_Configuration_and_Bug_Tracking" target="_top">here</a>. | ||
| 1612 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Always use the Yocto Project implementation of Bugzilla to submit | ||
| 1613 | a bug.</p></li><li class="listitem"><p>When submitting a new bug, be sure to choose the appropriate | ||
| 1614 | Classification, Product, and Component for which the issue was found. | ||
| 1615 | Defects for Yocto Project fall into one of four classifications: Yocto Projects, | ||
| 1616 | Infrastructure, Poky, and Yocto Metadata Layers. | ||
| 1617 | Each of these Classifications break down into multiple Products and, in some | ||
| 1618 | cases, multiple Components.</p></li><li class="listitem"><p>Use the bug form to choose the correct Hardware and Architecture | ||
| 1619 | for which the bug applies.</p></li><li class="listitem"><p>Indicate the Yocto Project version you were using when the issue | ||
| 1620 | occurred.</p></li><li class="listitem"><p>Be sure to indicate the Severity of the bug. | ||
| 1621 | Severity communicates how the bug impacted your work.</p></li><li class="listitem"><p>Provide a brief summary of the issue. | ||
| 1622 | Try to limit your summary to just a line or two and be sure to capture the | ||
| 1623 | essence of the issue.</p></li><li class="listitem"><p>Provide a detailed description of the issue. | ||
| 1624 | You should provide as much detail as you can about the context, behavior, output, | ||
| 1625 | and so forth that surround the issue. | ||
| 1626 | You can even attach supporting files for output or log by using the "Add an attachment" | ||
| 1627 | button.</p></li><li class="listitem"><p>Submit the bug by clicking the "Submit Bug" button.</p></li></ol></div><p> | ||
| 1628 | </p></div><div class="section" title="3.9. How to Submit a Change"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="how-to-submit-a-change"></a>3.9. How to Submit a Change</h2></div></div></div><p> | ||
| 1629 | Contributions to the Yocto Project and OpenEmbedded are very welcome. | ||
| 1630 | Because the system is extremely configurable and flexible, we recognize that developers | ||
| 1631 | will want to extend, configure or optimize it for their specific uses. | ||
| 1632 | You should send patches to the appropriate mailing list so that they | ||
| 1633 | can be reviewed and merged by the appropriate maintainer. | ||
| 1634 | For a list of the Yocto Project and related mailing lists, see the | ||
| 1635 | "<a class="link" href="#resources-mailinglist" target="_top">Mailing lists</a>" section in | ||
| 1636 | the Yocto Project Reference Manual. | ||
| 1637 | </p><p> | ||
| 1638 | The following is some guidance on which mailing list to use for what type of change: | ||
| 1639 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>For changes to the core metadata, send your patch to the | ||
| 1640 | <a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">openembedded-core</a> mailing list. | ||
| 1641 | For example, a change to anything under the <code class="filename">meta</code> or | ||
| 1642 | <code class="filename">scripts</code> directories | ||
| 1643 | should be sent to this mailing list.</p></li><li class="listitem"><p>For changes to BitBake (anything under the <code class="filename">bitbake</code> | ||
| 1644 | directory), send your patch to the | ||
| 1645 | <a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">bitbake-devel</a> mailing list.</p></li><li class="listitem"><p>For changes to <code class="filename">meta-yocto</code>, send your patch to the | ||
| 1646 | <a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">poky</a> mailing list.</p></li><li class="listitem"><p>For changes to other layers hosted on yoctoproject.org (unless the | ||
| 1647 | layer's documentation specifies otherwise), tools, and Yocto Project | ||
| 1648 | documentation, use the | ||
| 1649 | <a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">yocto</a> mailing list.</p></li><li class="listitem"><p>For additional recipes that do not fit into the core metadata, | ||
| 1650 | you should determine which layer the recipe should go into and submit the | ||
| 1651 | change in the manner recommended by the documentation (e.g. README) supplied | ||
| 1652 | with the layer. If in doubt, please ask on the | ||
| 1653 | <a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">yocto</a> or | ||
| 1654 | <a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">openembedded-devel</a> | ||
| 1655 | mailing lists.</p></li></ul></div><p> | ||
| 1656 | </p><p> | ||
| 1657 | When you send a patch, be sure to include a "Signed-off-by:" | ||
| 1658 | line in the same style as required by the Linux kernel. | ||
| 1659 | Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 | ||
| 1660 | as follows: | ||
| 1661 | </p><pre class="literallayout"> | ||
| 1662 | Developer's Certificate of Origin 1.1 | ||
| 1663 | |||
| 1664 | By making a contribution to this project, I certify that: | ||
| 1665 | |||
| 1666 | (a) The contribution was created in whole or in part by me and I | ||
| 1667 | have the right to submit it under the open source license | ||
| 1668 | indicated in the file; or | ||
| 1669 | |||
| 1670 | (b) The contribution is based upon previous work that, to the best | ||
| 1671 | of my knowledge, is covered under an appropriate open source | ||
| 1672 | license and I have the right under that license to submit that | ||
| 1673 | work with modifications, whether created in whole or in part | ||
| 1674 | by me, under the same open source license (unless I am | ||
| 1675 | permitted to submit under a different license), as indicated | ||
| 1676 | in the file; or | ||
| 1677 | |||
| 1678 | (c) The contribution was provided directly to me by some other | ||
| 1679 | person who certified (a), (b) or (c) and I have not modified | ||
| 1680 | it. | ||
| 1681 | |||
| 1682 | (d) I understand and agree that this project and the contribution | ||
| 1683 | are public and that a record of the contribution (including all | ||
| 1684 | personal information I submit with it, including my sign-off) is | ||
| 1685 | maintained indefinitely and may be redistributed consistent with | ||
| 1686 | this project or the open source license(s) involved. | ||
| 1687 | </pre><p> | ||
| 1688 | </p><p> | ||
| 1689 | In a collaborative environment, it is necessary to have some sort of standard | ||
| 1690 | or method through which you submit changes. | ||
| 1691 | Otherwise, things could get quite chaotic. | ||
| 1692 | One general practice to follow is to make small, controlled changes. | ||
| 1693 | Keeping changes small and isolated aids review, makes merging/rebasing easier | ||
| 1694 | and keeps the change history clean when anyone needs to refer to it in future. | ||
| 1695 | </p><p> | ||
| 1696 | When you make a commit, you must follow certain standards established by the | ||
| 1697 | OpenEmbedded and Yocto Project development teams. | ||
| 1698 | For each commit, you must provide a single-line summary of the change and you | ||
| 1699 | should almost always provide a more detailed description of what you did (i.e. | ||
| 1700 | the body of the commit message). | ||
| 1701 | The only exceptions for not providing a detailed description would be if your | ||
| 1702 | change is a simple, self-explanatory change that needs no description. | ||
| 1703 | Here are the guidelines for composing a commit message: | ||
| 1704 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Provide a single-line, short summary of the change. | ||
| 1705 | This summary is typically viewable in the "shortlist" of changes. | ||
| 1706 | Thus, providing something short and descriptive that gives the reader | ||
| 1707 | a summary of the change is useful when viewing a list of many commits. | ||
| 1708 | This should be prefixed by the recipe name (if changing a recipe), or | ||
| 1709 | else the short form path to the file being changed. | ||
| 1710 | </p></li><li class="listitem"><p>For the body of the commit message, provide detailed information | ||
| 1711 | that describes what you changed, why you made the change, and the approach | ||
| 1712 | you used. It may also be helpful if you mention how you tested the change. | ||
| 1713 | Provide as much detail as you can in the body of the commit message. | ||
| 1714 | </p></li><li class="listitem"><p>If the change addresses a specific bug or issue that is | ||
| 1715 | associated with a bug-tracking ID, include a reference to that ID in | ||
| 1716 | your detailed description. | ||
| 1717 | For example, the Yocto Project uses a specific convention for bug | ||
| 1718 | references - any commit that addresses a specific bug should include the | ||
| 1719 | bug ID in the description (typically at the beginning) as follows: | ||
| 1720 | </p><pre class="literallayout"> | ||
| 1721 | [YOCTO #<bug-id>] | ||
| 1722 | |||
| 1723 | <detailed description of change> | ||
| 1724 | </pre></li></ul></div><p> | ||
| 1725 | </p><p> | ||
| 1726 | You can find more guidance on creating well-formed commit messages at this OpenEmbedded | ||
| 1727 | wiki page: | ||
| 1728 | <a class="ulink" href="http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines" target="_top">http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines</a>. | ||
| 1729 | </p><p> | ||
| 1730 | Following are general instructions for both pushing changes upstream and for submitting | ||
| 1731 | changes as patches. | ||
| 1732 | </p><div class="section" title="3.9.1. Using Scripts to Push a Change Upstream and Request a Pull"><div class="titlepage"><div><div><h3 class="title"><a id="pushing-a-change-upstream"></a>3.9.1. Using Scripts to Push a Change Upstream and Request a Pull</h3></div></div></div><p> | ||
| 1733 | The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: | ||
| 1734 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Make your changes in your local Git repository.</p></li><li class="listitem"><p>Stage your changes by using the <code class="filename">git add</code> | ||
| 1735 | command on each file you changed.</p></li><li class="listitem"><p>Commit the change by using the <code class="filename">git commit</code> | ||
| 1736 | command and push it to the "contrib" repository. | ||
| 1737 | Be sure to provide a commit message that follows the project’s commit message standards | ||
| 1738 | as described earlier.</p></li><li class="listitem"><p>Notify the maintainer that you have pushed a change by making a pull | ||
| 1739 | request. | ||
| 1740 | The Yocto Project provides two scripts that conveniently let you generate and send | ||
| 1741 | pull requests to the Yocto Project. | ||
| 1742 | These scripts are <code class="filename">create-pull-request</code> and | ||
| 1743 | <code class="filename">send-pull-request</code>. | ||
| 1744 | You can find these scripts in the <code class="filename">scripts</code> directory of the | ||
| 1745 | Yocto Project file structure.</p><p>Using these scripts correctly formats the requests without introducing any | ||
| 1746 | whitespace or HTML formatting. | ||
| 1747 | The maintainer that receives your patches needs to be able to save and apply them | ||
| 1748 | directly from your emails. | ||
| 1749 | Using these scripts is the preferred method for sending patches.</p><p>For help on using these scripts, simply provide the | ||
| 1750 | <code class="filename">-h</code> argument as follows: | ||
| 1751 | </p><pre class="literallayout"> | ||
| 1752 | $ ~/poky/scripts/create-pull-request -h | ||
| 1753 | $ ~/poky/scripts/send-pull-request -h | ||
| 1754 | </pre></li></ul></div><p> | ||
| 1755 | </p><p> | ||
| 1756 | You can find general Git information on how to push a change upstream in the | ||
| 1757 | <a class="ulink" href="http://book.git-scm.com/3_distributed_workflows.html" target="_top">Git Community Book</a>. | ||
| 1758 | </p></div><div class="section" title="3.9.2. Using Email to Submit a Patch"><div class="titlepage"><div><div><h3 class="title"><a id="submitting-a-patch"></a>3.9.2. Using Email to Submit a Patch</h3></div></div></div><p> | ||
| 1759 | You can submit patches without using the <code class="filename">create-pull-request</code> and | ||
| 1760 | <code class="filename">send-pull-request</code> scripts described in the previous section. | ||
| 1761 | Keep in mind, the preferred method is to use the scripts, however. | ||
| 1762 | </p><p> | ||
| 1763 | Depending on the components changed, you need to submit the email to a specific | ||
| 1764 | mailing list. | ||
| 1765 | For some guidance on which mailing list to use, see the list in the | ||
| 1766 | "<a class="link" href="#how-to-submit-a-change" title="3.9. How to Submit a Change">How to Submit a Change</a>" section | ||
| 1767 | earlier in this manual. | ||
| 1768 | For a description of the available mailing lists, see | ||
| 1769 | "<a class="link" href="#resources-mailinglist" target="_top">Mailing Lists</a>" | ||
| 1770 | section in the Yocto Project Reference Manual. | ||
| 1771 | </p><p> | ||
| 1772 | Here is the general procedure on how to submit a patch through email without using the | ||
| 1773 | scripts: | ||
| 1774 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Make your changes in your local Git repository.</p></li><li class="listitem"><p>Stage your changes by using the <code class="filename">git add</code> | ||
| 1775 | command on each file you changed.</p></li><li class="listitem"><p>Commit the change by using the | ||
| 1776 | <code class="filename">git commit --signoff</code> command. | ||
| 1777 | Using the <code class="filename">--signoff</code> option identifies you as the person | ||
| 1778 | making the change and also satisfies the Developer's Certificate of | ||
| 1779 | Origin (DCO) shown earlier.</p><p>When you form a commit you must follow certain standards established by the | ||
| 1780 | Yocto Project development team. | ||
| 1781 | See the earlier section | ||
| 1782 | "<a class="link" href="#how-to-submit-a-change" title="3.9. How to Submit a Change">How to Submit a Change</a>" | ||
| 1783 | for Yocto Project commit message standards.</p></li><li class="listitem"><p>Format the commit into an email message. | ||
| 1784 | To format commits, use the <code class="filename">git format-patch</code> command. | ||
| 1785 | When you provide the command, you must include a revision list or a number of patches | ||
| 1786 | as part of the command. | ||
| 1787 | For example, these two commands each take the most recent single commit and | ||
| 1788 | format it as an email message in the current directory: | ||
| 1789 | </p><pre class="literallayout"> | ||
| 1790 | $ git format-patch -1 | ||
| 1791 | $ git format-patch HEAD~ | ||
| 1792 | </pre><p>After the command is run, the current directory contains a | ||
| 1793 | numbered <code class="filename">.patch</code> file for the commit.</p><p>If you provide several commits as part of the command, | ||
| 1794 | the <code class="filename">git format-patch</code> command produces a numbered | ||
| 1795 | series of files in the current directory – one for each commit. | ||
| 1796 | If you have more than one patch, you should also use the | ||
| 1797 | <code class="filename">--cover</code> option with the command, which generates a | ||
| 1798 | cover letter as the first "patch" in the series. | ||
| 1799 | You can then edit the cover letter to provide a description for | ||
| 1800 | the series of patches. | ||
| 1801 | For information on the <code class="filename">git format-patch</code> command, | ||
| 1802 | see <code class="filename">GIT_FORMAT_PATCH(1)</code> displayed using the | ||
| 1803 | <code class="filename">man git-format-patch</code> command.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If you are or will be a frequent contributor to the Yocto Project | ||
| 1804 | or to OpenEmbedded, you might consider requesting a contrib area and the | ||
| 1805 | necessary associated rights.</div></li><li class="listitem"><p>Import the files into your mail client by using the | ||
| 1806 | <code class="filename">git send-email</code> command. | ||
| 1807 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>In order to use <code class="filename">git send-email</code>, you must have the | ||
| 1808 | the proper Git packages installed. | ||
| 1809 | For Ubuntu and Fedora the package is <code class="filename">git-email</code>.</div><p>The <code class="filename">git send-email</code> command sends email by using a local | ||
| 1810 | or remote Mail Transport Agent (MTA) such as | ||
| 1811 | <code class="filename">msmtp</code>, <code class="filename">sendmail</code>, or through a direct | ||
| 1812 | <code class="filename">smtp</code> configuration in your Git <code class="filename">config</code> | ||
| 1813 | file. | ||
| 1814 | If you are submitting patches through email only, it is very important | ||
| 1815 | that you submit them without any whitespace or HTML formatting that | ||
| 1816 | either you or your mailer introduces. | ||
| 1817 | The maintainer that receives your patches needs to be able to save and | ||
| 1818 | apply them directly from your emails. | ||
| 1819 | A good way to verify that what you are sending will be applicable by the | ||
| 1820 | maintainer is to do a dry run and send them to yourself and then | ||
| 1821 | save and apply them as the maintainer would.</p><p>The <code class="filename">git send-email</code> command is the preferred method | ||
| 1822 | for sending your patches since there is no risk of compromising whitespace | ||
| 1823 | in the body of the message, which can occur when you use your own mail client. | ||
| 1824 | The command also has several options that let you | ||
| 1825 | specify recipients and perform further editing of the email message. | ||
| 1826 | For information on how to use the <code class="filename">git send-email</code> command, | ||
| 1827 | use the <code class="filename">man git-send-email</code> command.</p></li></ul></div><p> | ||
| 1828 | </p></div></div></div> | ||
| 1829 | |||
| 1830 | <div class="chapter" title="Chapter 4. Common Tasks"><div class="titlepage"><div><div><h2 class="title"><a id="extendpoky"></a>Chapter 4. Common Tasks</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#understanding-and-creating-layers">4.1. Understanding and Creating Layers</a></span></dt><dd><dl><dt><span class="section"><a href="#yocto-project-layers">4.1.1. Layers</a></span></dt><dt><span class="section"><a href="#creating-your-own-layer">4.1.2. Creating Your Own Layer</a></span></dt><dt><span class="section"><a href="#enabling-your-layer">4.1.3. Enabling Your Layer</a></span></dt><dt><span class="section"><a href="#using-bbappend-files">4.1.4. Using .bbappend Files</a></span></dt><dt><span class="section"><a href="#prioritizing-your-layer">4.1.5. Prioritizing Your Layer</a></span></dt><dt><span class="section"><a href="#managing-layers">4.1.6. Managing Layers</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">4.2. Customizing Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">4.2.1. Customizing Images Using Custom .bb Files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">4.2.2. Customizing Images Using Custom Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">4.2.3. Customizing Images Using Custom <code class="filename">IMAGE_FEATURES</code> and | ||
| 1831 | <code class="filename">EXTRA_IMAGE_FEATURES</code></a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">4.2.4. Customizing Images Using <code class="filename">local.conf</code></a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-addpkg">4.3. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">4.3.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">4.3.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">4.3.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#splitting-an-application-into-multiple-packages">4.3.4. Splitting an Application into Multiple Packages</a></span></dt><dt><span class="section"><a href="#including-static-library-files">4.3.5. Including Static Library Files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">4.3.6. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">4.4. Adding a New Machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">4.4.1. Adding the Machine Configuration File</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">4.4.2. Adding a Kernel for the Machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">4.4.3. Adding a Formfactor Configuration File</a></span></dt></dl></dd><dt><span class="section"><a href="#building-multiple-architecture-libraries-into-one-image">4.5. Combining Multiple Versions of Library Files into One Image</a></span></dt><dd><dl><dt><span class="section"><a href="#preparing-to-use-multilib">4.5.1. Preparing to use Multilib</a></span></dt><dt><span class="section"><a href="#using-multilib">4.5.2. Using Multilib</a></span></dt><dt><span class="section"><a href="#additional-implementation-details">4.5.3. Additional Implementation Details</a></span></dt></dl></dd><dt><span class="section"><a href="#configuring-the-kernel">4.6. Configuring the Kernel</a></span></dt><dd><dl><dt><span class="section"><a href="#using-menuconfig">4.6.1. Using <code class="filename">menuconfig</code></a></span></dt><dt><span class="section"><a href="#creating-config-fragments">4.6.2. Creating Configuration Fragments</a></span></dt><dt><span class="section"><a href="#fine-tuning-the-kernel-configuration-file">4.6.3. Fine-tuning the Kernel Configuration File</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes-updatingimages">4.7. Updating Existing Images</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.8. Incrementing a Package Revision Number</a></span></dt><dt><span class="section"><a href="#usingpoky-configuring-DISTRO_PN_ALIAS">4.9. Handling a Package Name Alias</a></span></dt><dt><span class="section"><a href="#building-software-from-an-external-source">4.10. Building Software from an External Source</a></span></dt><dt><span class="section"><a href="#excluding-recipes-from-the-build">4.11. Excluding Recipes From the Build</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">4.12. Using an External SCM</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug">4.13. Debugging With the GNU Project Debugger (GDB) Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">4.13.1. Launching Gdbserver on the Target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">4.13.2. Launching GDB on the Host Computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">4.14. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">4.14.1. Profiling on the Target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">4.14.2. Using OProfileUI</a></span></dt></dl></dd></dl></div><p> | ||
| 1832 | This chapter describes standard tasks such as adding new | ||
| 1833 | software packages, extending or customizing images, and porting work to | ||
| 1834 | new hardware (adding a new machine). | ||
| 1835 | The chapter also describes how to combine multiple | ||
| 1836 | versions of library files into a single image, how to handle a package name alias, and | ||
| 1837 | gives advice about how to make changes to the Yocto Project to achieve the best results. | ||
| 1838 | </p><div class="section" title="4.1. Understanding and Creating Layers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="understanding-and-creating-layers"></a>4.1. Understanding and Creating Layers</h2></div></div></div><p> | ||
| 1839 | The OpenEmbedded build system supports organizing <a class="link" href="#metadata">metadata</a> | ||
| 1840 | into multiple layers. | ||
| 1841 | Layers allow you to isolate different types of customizations from each other. | ||
| 1842 | You might find it tempting to keep everything in one layer when working on a single project. | ||
| 1843 | However, the more modular you organize your metadata, the easier it is to cope with future changes. | ||
| 1844 | </p><p> | ||
| 1845 | To illustrate how layers are used to keep things modular, consider machine customizations. | ||
| 1846 | These types of customizations typically reside in a BSP Layer. | ||
| 1847 | Furthermore, the machine customizations should be isolated from recipes and metadata that support | ||
| 1848 | a new GUI environment, for example. | ||
| 1849 | This situation gives you a couple a layers: one for the machine configurations, and one for the | ||
| 1850 | GUI environment. | ||
| 1851 | It is important to understand, however, that the BSP layer can still make machine-specific | ||
| 1852 | additions to recipes within the GUI environment layer without polluting the GUI layer itself | ||
| 1853 | with those machine-specific changes. | ||
| 1854 | You can accomplish this through a recipe that is a BitBake append | ||
| 1855 | (<code class="filename">.bbappend</code>) file, which is described later in this section. | ||
| 1856 | </p><p> | ||
| 1857 | </p><div class="section" title="4.1.1. Layers"><div class="titlepage"><div><div><h3 class="title"><a id="yocto-project-layers"></a>4.1.1. Layers</h3></div></div></div><p> | ||
| 1858 | The source directory contains several layers right out of the box. | ||
| 1859 | You can easily identify a layer in the source directory by its folder name. | ||
| 1860 | Folders that are layers begin with the string <code class="filename">meta</code>. | ||
| 1861 | For example, when you set up the <a class="link" href="#source-directory">source directory</a> | ||
| 1862 | structure, you will see several layers: <code class="filename">meta</code>, <code class="filename">meta-demoapps</code>, | ||
| 1863 | <code class="filename">meta-skeleton</code>, and <code class="filename">meta-yocto</code>. | ||
| 1864 | Each of these folders is a layer. | ||
| 1865 | </p><p> | ||
| 1866 | Furthermore, if you set up a local copy of the <code class="filename">meta-intel</code> Git repository | ||
| 1867 | and then explore that folder, you will discover many BSP layers within the | ||
| 1868 | <code class="filename">meta-intel</code> layer. | ||
| 1869 | For more information on BSP layers, see the | ||
| 1870 | "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" | ||
| 1871 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | ||
| 1872 | </p></div><div class="section" title="4.1.2. Creating Your Own Layer"><div class="titlepage"><div><div><h3 class="title"><a id="creating-your-own-layer"></a>4.1.2. Creating Your Own Layer</h3></div></div></div><p> | ||
| 1873 | It is very easy to create your own layer to use with the OpenEmbedded build system. | ||
| 1874 | Follow these general steps to create your layer: | ||
| 1875 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Check Existing Layers:</em></span> Before creating a new layer, | ||
| 1876 | you should be sure someone has not already created a layer containing the metadata | ||
| 1877 | you need. | ||
| 1878 | You can see the | ||
| 1879 | <a class="ulink" href="http://www.openembedded.org/wiki/LayerIndex" target="_top"><code class="filename">LayerIndex</code></a> | ||
| 1880 | for a list of layers from the OpenEmbedded community that can be used in the | ||
| 1881 | Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>Create a Directory:</em></span> Create the directory | ||
| 1882 | for your layer. | ||
| 1883 | Traditionally, prepend the name of the folder with the string | ||
| 1884 | <code class="filename">meta</code>. | ||
| 1885 | For example: | ||
| 1886 | </p><pre class="literallayout"> | ||
| 1887 | meta-mylayer | ||
| 1888 | meta-GUI_xyz | ||
| 1889 | meta-mymachine | ||
| 1890 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Create a Layer Configuration File:</em></span> Inside your new | ||
| 1891 | layer folder, you need to create a <code class="filename">conf/layer.conf</code> file. | ||
| 1892 | It is easiest to take an existing layer configuration file and copy that to your | ||
| 1893 | layer's <code class="filename">conf</code> directory and then modify the file as needed.</p><p>The <code class="filename">meta-yocto/conf/layer.conf</code> file demonstrates the | ||
| 1894 | required syntax: | ||
| 1895 | </p><pre class="literallayout"> | ||
| 1896 | # We have a conf and classes directory, add to BBPATH | ||
| 1897 | BBPATH := "${LAYERDIR}:${BBPATH}" | ||
| 1898 | |||
| 1899 | # We have recipes-* directories, add to BBFILES | ||
| 1900 | BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \ | ||
| 1901 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
| 1902 | |||
| 1903 | BBFILE_COLLECTIONS += "yocto" | ||
| 1904 | BBFILE_PATTERN_yocto := "^${LAYERDIR}/" | ||
| 1905 | BBFILE_PRIORITY_yocto = "5" | ||
| 1906 | </pre><p>In the previous example, the recipes for the layers are added to | ||
| 1907 | <code class="filename"><a class="link" href="#var-BBFILES" target="_top">BBFILES</a></code>. | ||
| 1908 | The | ||
| 1909 | <code class="filename"><a class="link" href="#var-BBFILE_COLLECTIONS" target="_top">BBFILE_COLLECTIONS</a></code> | ||
| 1910 | variable is then appended with the layer name. | ||
| 1911 | The | ||
| 1912 | <code class="filename"><a class="link" href="#var-BBFILE_PATTERN" target="_top">BBFILE_PATTERN</a></code> | ||
| 1913 | variable is set to a regular expression and is used to match files | ||
| 1914 | from <code class="filename">BBFILES</code> into a particular layer. | ||
| 1915 | In this case, immediate expansion of | ||
| 1916 | <code class="filename"><a class="link" href="#var-LAYERDIR" target="_top">LAYERDIR</a></code> | ||
| 1917 | sets <code class="filename">BBFILE_PATTERN</code> to the layer's path. | ||
| 1918 | The | ||
| 1919 | <code class="filename"><a class="link" href="#var-BBFILE_PRIORITY" target="_top">BBFILE_PRIORITY</a></code> | ||
| 1920 | variable then assigns a priority to the layer. | ||
| 1921 | Applying priorities is useful in situations where the same package might appear in multiple | ||
| 1922 | layers and allows you to choose what layer should take precedence.</p><p>Note the use of the | ||
| 1923 | <code class="filename"><a class="link" href="#var-LAYERDIR" target="_top">LAYERDIR</a></code> | ||
| 1924 | variable with the immediate expansion operator. | ||
| 1925 | The <code class="filename">LAYERDIR</code> variable expands to the directory of the current layer and | ||
| 1926 | requires the immediate expansion operator so that BitBake does not wait to expand the variable | ||
| 1927 | when it's parsing a different directory.</p><p>Through the use of the <code class="filename">BBPATH</code> variable, | ||
| 1928 | BitBake locates <code class="filename">.bbclass</code> files, configuration | ||
| 1929 | files, and files that are included with <code class="filename">include</code> | ||
| 1930 | and <code class="filename">require</code> statements. | ||
| 1931 | For these cases, BitBake uses the first file with the matching name found in | ||
| 1932 | <code class="filename">BBPATH</code>. | ||
| 1933 | This is similar to the way the <code class="filename">PATH</code> variable is used for binaries. | ||
| 1934 | We recommend, therefore, that you use unique <code class="filename">.bbclass</code> | ||
| 1935 | and configuration file names in your custom layer.</p></li><li class="listitem"><p><span class="emphasis"><em>Add Content:</em></span> Depending on the type of layer, | ||
| 1936 | add the content. | ||
| 1937 | If the layer adds support for a machine, add the machine configuration in | ||
| 1938 | a <code class="filename">conf/machine/</code> file within the layer. | ||
| 1939 | If the layer adds distro policy, add the distro configuration in a | ||
| 1940 | <code class="filename">conf/distro/</code> file with the layer. | ||
| 1941 | If the layer introduces new recipes, put the recipes you need in | ||
| 1942 | <code class="filename">recipes-*</code> subdirectories within the layer.</p></li></ol></div><p> | ||
| 1943 | </p><p> | ||
| 1944 | To create layers that are easier to maintain, you should consider the following: | ||
| 1945 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Avoid "overlaying" entire recipes from other layers in your | ||
| 1946 | configuration. | ||
| 1947 | In other words, don't copy an entire recipe into your layer and then modify it. | ||
| 1948 | Use <code class="filename">.bbappend</code> files to override the parts of the | ||
| 1949 | recipe you need to modify.</p></li><li class="listitem"><p>Avoid duplicating include files. | ||
| 1950 | Use <code class="filename">.bbappend</code> files for each recipe that uses an include | ||
| 1951 | file. | ||
| 1952 | Or, if you are introducing a new recipe that requires the included file, use the | ||
| 1953 | path relative to the original layer directory to refer to the file. | ||
| 1954 | For example, use <code class="filename">require recipes-core/somepackage/somefile.inc</code> | ||
| 1955 | instead of <code class="filename">require somefile.inc</code>. | ||
| 1956 | If you're finding you have to overlay the include file, it could indicate a | ||
| 1957 | deficiency in the include file in the layer to which it originally belongs. | ||
| 1958 | If this is the case, you need to address that deficiency instead of overlaying | ||
| 1959 | the include file. | ||
| 1960 | For example, consider how Qt 4 database support plugins are configured. | ||
| 1961 | The source directory does not have | ||
| 1962 | MySQL or PostgreSQL, however OpenEmbedded's | ||
| 1963 | layer <code class="filename">meta-oe</code> does. | ||
| 1964 | Consequently, <code class="filename">meta-oe</code> uses <code class="filename">.bbappend</code> | ||
| 1965 | files to modify the <code class="filename">QT_SQL_DRIVER_FLAGS</code> variable to enable | ||
| 1966 | the appropriate plugins. | ||
| 1967 | This variable was added to the <code class="filename">qt4.inc</code> include file in | ||
| 1968 | the source directory specifically to allow the <code class="filename">meta-oe</code> layer | ||
| 1969 | to be able to control which plugins are built.</p></li></ul></div><p> | ||
| 1970 | </p><p> | ||
| 1971 | We also recommend the following: | ||
| 1972 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Store custom layers in a Git repository that uses the | ||
| 1973 | <code class="filename">meta-<layer_name></code> format.</p></li><li class="listitem"><p>Clone the repository alongside other <code class="filename">meta</code> | ||
| 1974 | directories in the | ||
| 1975 | <a class="link" href="#source-directory">source directory</a>.</p></li></ul></div><p> | ||
| 1976 | Following these recommendations keeps your source directory and | ||
| 1977 | its configuration entirely inside the Yocto Project's core base. | ||
| 1978 | </p></div><div class="section" title="4.1.3. Enabling Your Layer"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-your-layer"></a>4.1.3. Enabling Your Layer</h3></div></div></div><p> | ||
| 1979 | Before the OpenEmbedded build system can use your new layer, you need to enable it. | ||
| 1980 | To enable your layer, simply add your layer's path to the | ||
| 1981 | <code class="filename"><a class="link" href="#var-BBLAYERS" target="_top">BBLAYERS</a></code> | ||
| 1982 | variable in your <code class="filename">conf/bblayers.conf</code> file, which is found in the | ||
| 1983 | <a class="link" href="#build-directory">build directory</a>. | ||
| 1984 | The following example shows how to enable a layer named <code class="filename">meta-mylayer</code>: | ||
| 1985 | </p><pre class="literallayout"> | ||
| 1986 | LCONF_VERSION = "1" | ||
| 1987 | |||
| 1988 | BBFILES ?= "" | ||
| 1989 | BBLAYERS = " \ | ||
| 1990 | /path/to/poky/meta \ | ||
| 1991 | /path/to/poky/meta-yocto \ | ||
| 1992 | /path/to/poky/meta-mylayer \ | ||
| 1993 | " | ||
| 1994 | </pre><p> | ||
| 1995 | </p><p> | ||
| 1996 | BitBake parses each <code class="filename">conf/layer.conf</code> file as specified in the | ||
| 1997 | <code class="filename">BBLAYERS</code> variable within the <code class="filename">conf/bblayers.conf</code> | ||
| 1998 | file. | ||
| 1999 | During the processing of each <code class="filename">conf/layer.conf</code> file, BitBake adds the | ||
| 2000 | recipes, classes and configurations contained within the particular layer to the source | ||
| 2001 | directory. | ||
| 2002 | </p></div><div class="section" title="4.1.4. Using .bbappend Files"><div class="titlepage"><div><div><h3 class="title"><a id="using-bbappend-files"></a>4.1.4. Using .bbappend Files</h3></div></div></div><p> | ||
| 2003 | Recipes used to append metadata to other recipes are called BitBake append files. | ||
| 2004 | BitBake append files use the <code class="filename">.bbappend</code> file type suffix, while | ||
| 2005 | underlying recipes to which metadata is being appended use the | ||
| 2006 | <code class="filename">.bb</code> file type suffix. | ||
| 2007 | </p><p> | ||
| 2008 | A <code class="filename">.bbappend</code> file allows your layer to make additions or | ||
| 2009 | changes to the content of another layer's recipe without having to copy the other | ||
| 2010 | recipe into your layer. | ||
| 2011 | Your <code class="filename">.bbappend</code> file resides in your layer, while the underlying | ||
| 2012 | <code class="filename">.bb</code> recipe file to which you are appending metadata | ||
| 2013 | resides in a different layer. | ||
| 2014 | </p><p> | ||
| 2015 | Append files files must have the same name as the underlying recipe. | ||
| 2016 | For example, the append file <code class="filename">someapp_1.3.bbappend</code> must | ||
| 2017 | apply to <code class="filename">someapp_1.3.bb</code>. | ||
| 2018 | This means the original recipe and append file names are version number specific. | ||
| 2019 | If the underlying recipe is renamed to update to a newer version, the | ||
| 2020 | corresponding <code class="filename">.bbappend</code> file must be renamed as well. | ||
| 2021 | During the build process, BitBake displays an error on starting if it detects a | ||
| 2022 | <code class="filename">.bbappend</code> file that does not have an underlying recipe | ||
| 2023 | with a matching name. | ||
| 2024 | </p><p> | ||
| 2025 | Being able to append information to an existing recipe not only avoids duplication, | ||
| 2026 | but also automatically applies recipe changes in a different layer to your layer. | ||
| 2027 | If you were copying recipes, you would have to manually merge changes as they occur. | ||
| 2028 | </p><p> | ||
| 2029 | As an example, consider the main formfactor recipe and a corresponding formfactor | ||
| 2030 | append file both from the | ||
| 2031 | <a class="link" href="#source-directory">source directory</a>. | ||
| 2032 | Here is the main formfactor recipe, which is named <code class="filename">formfactor_0.0.bb</code> and | ||
| 2033 | located in the meta layer at <code class="filename">meta/recipes-bsp/formfactor</code>: | ||
| 2034 | </p><pre class="literallayout"> | ||
| 2035 | DESCRIPTION = "Device formfactor information" | ||
| 2036 | SECTION = "base" | ||
| 2037 | LICENSE = "MIT" | ||
| 2038 | LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \ | ||
| 2039 | file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" | ||
| 2040 | PR = "r20" | ||
| 2041 | |||
| 2042 | SRC_URI = "file://config file://machconfig" | ||
| 2043 | S = "${WORKDIR}" | ||
| 2044 | |||
| 2045 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
| 2046 | INHIBIT_DEFAULT_DEPS = "1" | ||
| 2047 | |||
| 2048 | do_install() { | ||
| 2049 | # Only install file if it has a contents | ||
| 2050 | install -d ${D}${sysconfdir}/formfactor/ | ||
| 2051 | install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ | ||
| 2052 | if [ -s "${S}/machconfig" ]; then | ||
| 2053 | install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ | ||
| 2054 | fi | ||
| 2055 | } | ||
| 2056 | </pre><p> | ||
| 2057 | Here is the append file, which is named <code class="filename">formfactor_0.0.bbappend</code> and is from the | ||
| 2058 | Crown Bay BSP Layer named <code class="filename">meta-intel/meta-crownbay</code>. | ||
| 2059 | The file is in <code class="filename">recipes-bsp/formfactor</code>: | ||
| 2060 | </p><pre class="literallayout"> | ||
| 2061 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 2062 | |||
| 2063 | PRINC = "1" | ||
| 2064 | </pre><p> | ||
| 2065 | This example adds or overrides files in | ||
| 2066 | <a class="link" href="#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> | ||
| 2067 | within a <code class="filename">.bbappend</code> by extending the path BitBake uses to search for files. | ||
| 2068 | The most reliable way to do this is by prepending the | ||
| 2069 | <code class="filename">FILESEXTRAPATHS</code> variable. | ||
| 2070 | For example, if you have your files in a directory that is named the same as your package | ||
| 2071 | (<a class="link" href="#var-PN" target="_top"><code class="filename">PN</code></a>), | ||
| 2072 | you can add this directory by adding the following to your <code class="filename">.bbappend</code> file: | ||
| 2073 | </p><pre class="literallayout"> | ||
| 2074 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 2075 | </pre><p> | ||
| 2076 | Using the immediate expansion assignment operator <code class="filename">:=</code> is important because | ||
| 2077 | of the reference to <code class="filename">THISDIR</code>. | ||
| 2078 | The trailing colon character is important as it ensures that items in the list remain | ||
| 2079 | colon-separated. | ||
| 2080 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>BitBake automatically defines the <code class="filename">THISDIR</code> variable. | ||
| 2081 | You should never set this variable yourself. | ||
| 2082 | Using <code class="filename">_prepend</code> ensures your path will be searched prior to other | ||
| 2083 | paths in the final list. | ||
| 2084 | </div><p> | ||
| 2085 | </p><p> | ||
| 2086 | For another example on how to use a <code class="filename">.bbappend</code> file, see the | ||
| 2087 | "<a class="link" href="#changing-recipes-kernel" title="A.5.2.4. Changing recipes-kernel">Changing <code class="filename">recipes-kernel</code></a>" | ||
| 2088 | section. | ||
| 2089 | </p></div><div class="section" title="4.1.5. Prioritizing Your Layer"><div class="titlepage"><div><div><h3 class="title"><a id="prioritizing-your-layer"></a>4.1.5. Prioritizing Your Layer</h3></div></div></div><p> | ||
| 2090 | Each layer is assigned a priority value. | ||
| 2091 | Priority values control which layer takes precedence if there are recipe files with | ||
| 2092 | the same name in multiple layers. | ||
| 2093 | For these cases, the recipe file from the layer with a higher priority number taking precedence. | ||
| 2094 | Priority values also affect the order in which multiple <code class="filename">.bbappend</code> files | ||
| 2095 | for the same recipe are applied. | ||
| 2096 | You can either specify the priority manually, or allow the build system to calculate it | ||
| 2097 | based on the layer's dependencies. | ||
| 2098 | </p><p> | ||
| 2099 | To specify the layer's priority manually, use the | ||
| 2100 | <a class="link" href="#var-BBFILE_PRIORITY" target="_top"><code class="filename">BBFILE_PRIORITY</code></a> | ||
| 2101 | variable. | ||
| 2102 | For example: | ||
| 2103 | </p><pre class="literallayout"> | ||
| 2104 | BBFILE_PRIORITY := "1" | ||
| 2105 | </pre><p> | ||
| 2106 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is possible for a recipe with a lower version number | ||
| 2107 | <a class="link" href="#var-PV" target="_top"><code class="filename">PV</code></a> | ||
| 2108 | in a layer that has a higher priority to take precedence.</p><p>Also, the layer priority does not currently affect the precedence order of | ||
| 2109 | <code class="filename">.conf</code> or <code class="filename">.bbclass</code> files. | ||
| 2110 | Future versions of BitBake might address this.</p></div></div><div class="section" title="4.1.6. Managing Layers"><div class="titlepage"><div><div><h3 class="title"><a id="managing-layers"></a>4.1.6. Managing Layers</h3></div></div></div><p> | ||
| 2111 | You can use the BitBake layer management tool to provide a view into the structure of | ||
| 2112 | recipes across a multi-layer project. | ||
| 2113 | Being able to generate output that reports on configured layers with their paths and | ||
| 2114 | priorities and on <code class="filename">.bbappend</code> files and their applicable recipes | ||
| 2115 | can help to reveal potential problems. | ||
| 2116 | </p><p> | ||
| 2117 | Use the following form when running the layer management tool. | ||
| 2118 | </p><pre class="literallayout"> | ||
| 2119 | $ bitbake-layers <command> [arguments] | ||
| 2120 | </pre><p> | ||
| 2121 | The following list describes the available commands: | ||
| 2122 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><span class="emphasis"><em>help:</em></span></code> | ||
| 2123 | Displays general help or help on a specified command.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-layers:</em></span></code> | ||
| 2124 | Show the current configured layers.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-recipes:</em></span></code> | ||
| 2125 | Lists available recipes and the layers that provide them. | ||
| 2126 | </p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-overlayed:</em></span></code> | ||
| 2127 | Lists overlayed recipes. | ||
| 2128 | A recipe is overlayed when a recipe with the same name exists in another layer | ||
| 2129 | that has a higher layer priority. | ||
| 2130 | </p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-appends:</em></span></code> | ||
| 2131 | Lists <code class="filename">.bbappend</code> files and the recipe files to which | ||
| 2132 | they apply.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>flatten:</em></span></code> | ||
| 2133 | Flattens the layer configuration into a separate output directory. | ||
| 2134 | Flattening your layer configuration builds a "flattened" directory that contains | ||
| 2135 | the contents of all layers, with any overlayed recipes removed and any | ||
| 2136 | <code class="filename">.bbappend</code> files appended to the corresponding recipes. | ||
| 2137 | You might have to perform some manual cleanup of the flattened layer as follows: | ||
| 2138 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Non-recipe files (such as patches) are overwritten. | ||
| 2139 | The flatten command shows a warning for these files.</p></li><li class="listitem"><p>Anything beyond the normal layer setup has been added to | ||
| 2140 | the <code class="filename">layer.conf</code> file. | ||
| 2141 | Only the lowest priority layer's <code class="filename">layer.conf</code> is used. | ||
| 2142 | </p></li><li class="listitem"><p>Overridden and appended items from <code class="filename">.bbappend</code> | ||
| 2143 | files need to be cleaned up. | ||
| 2144 | The contents of each <code class="filename">.bbappend</code> end up in the | ||
| 2145 | flattened recipe. | ||
| 2146 | However, if there are appended or changed variable values, you need to tidy | ||
| 2147 | these up yourself. | ||
| 2148 | Consider the following example. | ||
| 2149 | Here, the <code class="filename">bitbake-layers</code> command adds the line | ||
| 2150 | <code class="filename">#### bbappended ...</code> so that you know where the following | ||
| 2151 | lines originate: | ||
| 2152 | </p><pre class="literallayout"> | ||
| 2153 | ... | ||
| 2154 | DESCRIPTION = "A useful utility" | ||
| 2155 | ... | ||
| 2156 | EXTRA_OECONF = "--enable-something" | ||
| 2157 | ... | ||
| 2158 | |||
| 2159 | #### bbappended from meta-anotherlayer #### | ||
| 2160 | |||
| 2161 | DESCRIPTION = "Customized utility" | ||
| 2162 | EXTRA_OECONF += "--enable-somethingelse" | ||
| 2163 | </pre><p> | ||
| 2164 | Ideally, you would tidy up these utilities as follows: | ||
| 2165 | </p><pre class="literallayout"> | ||
| 2166 | ... | ||
| 2167 | DESCRIPTION = "Customized utility" | ||
| 2168 | ... | ||
| 2169 | EXTRA_OECONF = "--enable-something --enable-somethingelse" | ||
| 2170 | ... | ||
| 2171 | </pre></li></ul></div></li></ul></div><p> | ||
| 2172 | </p></div></div><div class="section" title="4.2. Customizing Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-extend-customimage"></a>4.2. Customizing Images</h2></div></div></div><p> | ||
| 2173 | You can customize images to satisfy particular requirements. | ||
| 2174 | This section describes several methods and provides guidelines for each. | ||
| 2175 | </p><div class="section" title="4.2.1. Customizing Images Using Custom .bb Files"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-custombb"></a>4.2.1. Customizing Images Using Custom .bb Files</h3></div></div></div><p> | ||
| 2176 | One way to get additional software into an image is to create a custom image. | ||
| 2177 | The following example shows the form for the two lines you need: | ||
| 2178 | </p><pre class="literallayout"> | ||
| 2179 | IMAGE_INSTALL = "task-core-x11-base package1 package2" | ||
| 2180 | |||
| 2181 | inherit core-image | ||
| 2182 | </pre><p> | ||
| 2183 | </p><p> | ||
| 2184 | By creating a custom image, a developer has total control | ||
| 2185 | over the contents of the image. | ||
| 2186 | It is important to use the correct names of packages in the | ||
| 2187 | <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code> | ||
| 2188 | variable. | ||
| 2189 | You must use the OpenEmbedded notation and not the Debian notation for the names | ||
| 2190 | (e.g. <code class="filename">eglibc-dev</code> instead of <code class="filename">libc6-dev</code>). | ||
| 2191 | </p><p> | ||
| 2192 | The other method for creating a custom image is to base it on an existing image. | ||
| 2193 | For example, if you want to create an image based on <code class="filename">core-image-sato</code> | ||
| 2194 | but add the additional package <code class="filename">strace</code> to the image, | ||
| 2195 | copy the <code class="filename">meta/recipes-sato/images/core-image-sato.bb</code> to a | ||
| 2196 | new <code class="filename">.bb</code> and add the following line to the end of the copy: | ||
| 2197 | </p><pre class="literallayout"> | ||
| 2198 | IMAGE_INSTALL += "strace" | ||
| 2199 | </pre><p> | ||
| 2200 | </p></div><div class="section" title="4.2.2. Customizing Images Using Custom Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-customtasks"></a>4.2.2. Customizing Images Using Custom Tasks</h3></div></div></div><p> | ||
| 2201 | For complex custom images, the best approach is to create a custom task package | ||
| 2202 | that is used to build the image or images. | ||
| 2203 | A good example of a tasks package is | ||
| 2204 | <code class="filename">meta/recipes-core/tasks/task-core-boot.bb</code> | ||
| 2205 | The | ||
| 2206 | <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a></code> | ||
| 2207 | variable lists the task packages to build along with the complementary | ||
| 2208 | <code class="filename">-dbg</code> and <code class="filename">-dev</code> packages. | ||
| 2209 | For each package added, you can use | ||
| 2210 | <code class="filename"><a class="link" href="#var-RDEPENDS" target="_top">RDEPENDS</a></code> | ||
| 2211 | and | ||
| 2212 | <code class="filename"><a class="link" href="#var-RRECOMMENDS" target="_top">RRECOMMENDS</a></code> | ||
| 2213 | entries to provide a list of packages the parent task package should contain. | ||
| 2214 | Following is an example: | ||
| 2215 | </p><pre class="literallayout"> | ||
| 2216 | DESCRIPTION = "My Custom Tasks" | ||
| 2217 | |||
| 2218 | PACKAGES = "\ | ||
| 2219 | task-custom-apps \ | ||
| 2220 | task-custom-apps-dbg \ | ||
| 2221 | task-custom-apps-dev \ | ||
| 2222 | task-custom-tools \ | ||
| 2223 | task-custom-tools-dbg \ | ||
| 2224 | task-custom-tools-dev \ | ||
| 2225 | " | ||
| 2226 | |||
| 2227 | RDEPENDS_task-custom-apps = "\ | ||
| 2228 | dropbear \ | ||
| 2229 | portmap \ | ||
| 2230 | psplash" | ||
| 2231 | |||
| 2232 | RDEPENDS_task-custom-tools = "\ | ||
| 2233 | oprofile \ | ||
| 2234 | oprofileui-server \ | ||
| 2235 | lttng-control \ | ||
| 2236 | lttng-viewer" | ||
| 2237 | |||
| 2238 | RRECOMMENDS_task-custom-tools = "\ | ||
| 2239 | kernel-module-oprofile" | ||
| 2240 | </pre><p> | ||
| 2241 | </p><p> | ||
| 2242 | In the previous example, two task packages are created with their dependencies and their | ||
| 2243 | recommended package dependencies listed: <code class="filename">task-custom-apps</code>, and | ||
| 2244 | <code class="filename">task-custom-tools</code>. | ||
| 2245 | To build an image using these task packages, you need to add | ||
| 2246 | <code class="filename">task-custom-apps</code> and/or | ||
| 2247 | <code class="filename">task-custom-tools</code> to | ||
| 2248 | <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code>. | ||
| 2249 | For other forms of image dependencies see the other areas of this section. | ||
| 2250 | </p></div><div class="section" title="4.2.3. Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-imagefeatures"></a>4.2.3. Customizing Images Using Custom <code class="filename">IMAGE_FEATURES</code> and | ||
| 2251 | <code class="filename">EXTRA_IMAGE_FEATURES</code></h3></div></div></div><p> | ||
| 2252 | Ultimately users might want to add extra image features to the set by using the | ||
| 2253 | <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" target="_top">IMAGE_FEATURES</a></code> | ||
| 2254 | variable. | ||
| 2255 | To create these features, the best reference is | ||
| 2256 | <code class="filename">meta/classes/core-image.bbclass</code>, which shows how to achieve this. | ||
| 2257 | In summary, the file looks at the contents of the | ||
| 2258 | <code class="filename">IMAGE_FEATURES</code> | ||
| 2259 | variable and then maps that into a set of tasks or packages. | ||
| 2260 | Based on this information the | ||
| 2261 | <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top"> IMAGE_INSTALL</a></code> | ||
| 2262 | variable is generated automatically. | ||
| 2263 | Users can add extra features by extending the class or creating a custom class for use | ||
| 2264 | with specialized image <code class="filename">.bb</code> files. | ||
| 2265 | You can also add more features by configuring the | ||
| 2266 | <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" target="_top">EXTRA_IMAGE_FEATURES</a></code> | ||
| 2267 | variable in the <code class="filename">local.conf</code> file found in the source directory | ||
| 2268 | located in the build directory. | ||
| 2269 | </p><p> | ||
| 2270 | The Yocto Project ships with two SSH servers you can use in your images: | ||
| 2271 | Dropbear and OpenSSH. | ||
| 2272 | Dropbear is a minimal SSH server appropriate for resource-constrained environments, | ||
| 2273 | while OpenSSH is a well-known standard SSH server implementation. | ||
| 2274 | By default, the <code class="filename">core-image-sato</code> image is configured to use Dropbear. | ||
| 2275 | The <code class="filename">core-image-basic</code> and <code class="filename">core-image-lsb</code> | ||
| 2276 | images both include OpenSSH. | ||
| 2277 | The <code class="filename">core-image-minimal</code> image does not contain an SSH server. | ||
| 2278 | To change these defaults, edit the <code class="filename">IMAGE_FEATURES</code> variable | ||
| 2279 | so that it sets the image you are working with to include | ||
| 2280 | <code class="filename">ssh-server-dropbear</code> or <code class="filename">ssh-server-openssh</code>. | ||
| 2281 | </p></div><div class="section" title="4.2.4. Customizing Images Using local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-localconf"></a>4.2.4. Customizing Images Using <code class="filename">local.conf</code></h3></div></div></div><p> | ||
| 2282 | It is possible to customize image contents by using variables from your | ||
| 2283 | local configuration in your <code class="filename">conf/local.conf</code> file. | ||
| 2284 | Because it is limited to local use, this method generally only allows you to | ||
| 2285 | add packages and is not as flexible as creating your own customized image. | ||
| 2286 | When you add packages using local variables this way, you need to realize that | ||
| 2287 | these variable changes affect all images at the same time and might not be | ||
| 2288 | what you require. | ||
| 2289 | </p><p> | ||
| 2290 | The simplest way to add extra packages to all images is by using the | ||
| 2291 | <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code> | ||
| 2292 | variable with the <code class="filename">_append</code> operator: | ||
| 2293 | </p><pre class="literallayout"> | ||
| 2294 | IMAGE_INSTALL_append = " strace" | ||
| 2295 | </pre><p> | ||
| 2296 | Use of the syntax is important. | ||
| 2297 | Specifically, the space between the quote and the package name, which is | ||
| 2298 | <code class="filename">strace</code> in this example. | ||
| 2299 | This space is required since the <code class="filename">_append</code> | ||
| 2300 | operator does not add the space. | ||
| 2301 | </p><p> | ||
| 2302 | Furthermore, you must use <code class="filename">_append</code> instead of the <code class="filename">+=</code> | ||
| 2303 | operator if you want to avoid ordering issues. | ||
| 2304 | The reason for this is because doing so unconditionally appends to the variable and | ||
| 2305 | avoids ordering problems due to the variable being set in image recipes and | ||
| 2306 | <code class="filename">.bbclass</code> files with operators like <code class="filename">?=</code>. | ||
| 2307 | Using <code class="filename">_append</code> ensures the operation takes affect. | ||
| 2308 | </p><p> | ||
| 2309 | As shown in its simplest use, <code class="filename">IMAGE_INSTALL_append</code> affects | ||
| 2310 | all images. | ||
| 2311 | It is possible to extend the syntax so that the variable applies to a specific image only. | ||
| 2312 | Here is an example: | ||
| 2313 | </p><pre class="literallayout"> | ||
| 2314 | IMAGE_INSTALL_append_pn-core-image-minimal = " strace" | ||
| 2315 | </pre><p> | ||
| 2316 | This example adds <code class="filename">strace</code> to <code class="filename">core-image-minimal</code> | ||
| 2317 | only. | ||
| 2318 | </p><p> | ||
| 2319 | You can add packages using a similar approach through the | ||
| 2320 | <code class="filename"><a class="link" href="#var-CORE_IMAGE_EXTRA_INSTALL" target="_top">CORE_IMAGE_EXTRA_INSTALL</a></code> | ||
| 2321 | variable. | ||
| 2322 | If you use this variable, only <code class="filename">core-image-*</code> images are affected. | ||
| 2323 | </p></div></div><div class="section" title="4.3. Adding a Package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-extend-addpkg"></a>4.3. Adding a Package</h2></div></div></div><p> | ||
| 2324 | To add a package you need to write a recipe for it. | ||
| 2325 | Writing a recipe means creating a <code class="filename">.bb</code> file that sets some | ||
| 2326 | variables. | ||
| 2327 | For information on variables that are useful for recipes and for information about recipe naming | ||
| 2328 | issues, see the | ||
| 2329 | "<a class="link" href="#ref-varlocality-recipe-required" target="_top">Required</a>" | ||
| 2330 | section of the Yocto Project Reference Manual. | ||
| 2331 | </p><p> | ||
| 2332 | Before writing a recipe from scratch, it is often useful to check | ||
| 2333 | whether someone else has written one already. | ||
| 2334 | OpenEmbedded is a good place to look as it has a wider scope and range of packages. | ||
| 2335 | Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes | ||
| 2336 | you find there should work for you. | ||
| 2337 | </p><p> | ||
| 2338 | For new packages, the simplest way to add a recipe is to base it on a similar | ||
| 2339 | pre-existing recipe. | ||
| 2340 | The sections that follow provide some examples that show how to add standard | ||
| 2341 | types of packages. | ||
| 2342 | </p><div class="section" title="4.3.1. Single .c File Package (Hello World!)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-singlec"></a>4.3.1. Single .c File Package (Hello World!)</h3></div></div></div><p> | ||
| 2343 | Building an application from a single file that is stored locally (e.g. under | ||
| 2344 | <code class="filename">files/</code>) requires a recipe that has the file listed in | ||
| 2345 | the | ||
| 2346 | <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> | ||
| 2347 | variable. | ||
| 2348 | Additionally, you need to manually write the <code class="filename">do_compile</code> and | ||
| 2349 | <code class="filename">do_install</code> tasks. | ||
| 2350 | The <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> | ||
| 2351 | variable defines the | ||
| 2352 | directory containing the source code, which is set to | ||
| 2353 | <code class="filename"><a class="link" href="#var-WORKDIR" target="_top"> | ||
| 2354 | WORKDIR</a></code> in this case - the directory BitBake uses for the build. | ||
| 2355 | </p><pre class="literallayout"> | ||
| 2356 | DESCRIPTION = "Simple helloworld application" | ||
| 2357 | SECTION = "examples" | ||
| 2358 | LICENSE = "MIT" | ||
| 2359 | LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" | ||
| 2360 | PR = "r0" | ||
| 2361 | |||
| 2362 | SRC_URI = "file://helloworld.c" | ||
| 2363 | |||
| 2364 | S = "${WORKDIR}" | ||
| 2365 | |||
| 2366 | do_compile() { | ||
| 2367 | ${CC} helloworld.c -o helloworld | ||
| 2368 | } | ||
| 2369 | |||
| 2370 | do_install() { | ||
| 2371 | install -d ${D}${bindir} | ||
| 2372 | install -m 0755 helloworld ${D}${bindir} | ||
| 2373 | } | ||
| 2374 | </pre><p> | ||
| 2375 | </p><p> | ||
| 2376 | By default, the <code class="filename">helloworld</code>, <code class="filename">helloworld-dbg</code>, | ||
| 2377 | and <code class="filename">helloworld-dev</code> packages are built. | ||
| 2378 | For information on how to customize the packaging process, see the | ||
| 2379 | "<a class="link" href="#splitting-an-application-into-multiple-packages" title="4.3.4. Splitting an Application into Multiple Packages">Splitting an Application | ||
| 2380 | into Multiple Packages</a>" section. | ||
| 2381 | </p></div><div class="section" title="4.3.2. Autotooled Package"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-autotools"></a>4.3.2. Autotooled Package</h3></div></div></div><p> | ||
| 2382 | Applications that use Autotools such as <code class="filename">autoconf</code> and | ||
| 2383 | <code class="filename">automake</code> require a recipe that has a source archive listed in | ||
| 2384 | <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> and | ||
| 2385 | also inherits Autotools, which instructs BitBake to use the | ||
| 2386 | <code class="filename">autotools.bbclass</code> file, which contains the definitions of all the steps | ||
| 2387 | needed to build an Autotool-based application. | ||
| 2388 | The result of the build is automatically packaged. | ||
| 2389 | And, if the application uses NLS for localization, packages with local information are | ||
| 2390 | generated (one package per language). | ||
| 2391 | Following is one example: (<code class="filename">hello_2.3.bb</code>) | ||
| 2392 | </p><pre class="literallayout"> | ||
| 2393 | DESCRIPTION = "GNU Helloworld application" | ||
| 2394 | SECTION = "examples" | ||
| 2395 | LICENSE = "GPLv2+" | ||
| 2396 | LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" | ||
| 2397 | PR = "r0" | ||
| 2398 | |||
| 2399 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
| 2400 | |||
| 2401 | inherit autotools gettext | ||
| 2402 | </pre><p> | ||
| 2403 | </p><p> | ||
| 2404 | The variable | ||
| 2405 | <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" target="_top">LIC_FILES_CHKSUM</a></code> | ||
| 2406 | is used to track source license changes as described in the | ||
| 2407 | "<a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" target="_top">Track License Changes</a>" section. | ||
| 2408 | You can quickly create Autotool-based recipes in a manner similar to the previous example. | ||
| 2409 | </p></div><div class="section" title="4.3.3. Makefile-Based Package"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-makefile"></a>4.3.3. Makefile-Based Package</h3></div></div></div><p> | ||
| 2410 | Applications that use GNU <code class="filename">make</code> also require a recipe that has | ||
| 2411 | the source archive listed in | ||
| 2412 | <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>. | ||
| 2413 | You do not need to add a <code class="filename">do_compile</code> step since by default BitBake | ||
| 2414 | starts the <code class="filename">make</code> command to compile the application. | ||
| 2415 | If you need additional <code class="filename">make</code> options you should store them in the | ||
| 2416 | <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" target="_top">EXTRA_OEMAKE</a></code> | ||
| 2417 | variable. | ||
| 2418 | BitBake passes these options into the <code class="filename">make</code> GNU invocation. | ||
| 2419 | Note that a <code class="filename">do_install</code> task is still required. | ||
| 2420 | Otherwise BitBake runs an empty <code class="filename">do_install</code> task by default. | ||
| 2421 | </p><p> | ||
| 2422 | Some applications might require extra parameters to be passed to the compiler. | ||
| 2423 | For example, the application might need an additional header path. | ||
| 2424 | You can accomplish this by adding to the | ||
| 2425 | <code class="filename"><a class="link" href="#var-CFLAGS" target="_top">CFLAGS</a></code> variable. | ||
| 2426 | The following example shows this: | ||
| 2427 | </p><pre class="literallayout"> | ||
| 2428 | CFLAGS_prepend = "-I ${S}/include " | ||
| 2429 | </pre><p> | ||
| 2430 | </p><p> | ||
| 2431 | In the following example, <code class="filename">mtd-utils</code> is a makefile-based package: | ||
| 2432 | </p><pre class="literallayout"> | ||
| 2433 | DESCRIPTION = "Tools for managing memory technology devices." | ||
| 2434 | SECTION = "base" | ||
| 2435 | DEPENDS = "zlib lzo e2fsprogs util-linux" | ||
| 2436 | HOMEPAGE = "http://www.linux-mtd.infradead.org/" | ||
| 2437 | LICENSE = "GPLv2+" | ||
| 2438 | LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ | ||
| 2439 | file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" | ||
| 2440 | |||
| 2441 | SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \ | ||
| 2442 | file://add-exclusion-to-mkfs-jffs2-git-2.patch" | ||
| 2443 | |||
| 2444 | S = "${WORKDIR}/git/" | ||
| 2445 | |||
| 2446 | PR = "r1" | ||
| 2447 | |||
| 2448 | EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \ | ||
| 2449 | 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" | ||
| 2450 | |||
| 2451 | do_install () { | ||
| 2452 | oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \ | ||
| 2453 | INCLUDEDIR=${includedir} | ||
| 2454 | install -d ${D}${includedir}/mtd/ | ||
| 2455 | for f in ${S}/include/mtd/*.h; do | ||
| 2456 | install -m 0644 $f ${D}${includedir}/mtd/ | ||
| 2457 | done | ||
| 2458 | } | ||
| 2459 | |||
| 2460 | PARALLEL_MAKE = "" | ||
| 2461 | |||
| 2462 | BBCLASSEXTEND = "native" | ||
| 2463 | </pre><p> | ||
| 2464 | </p><p> | ||
| 2465 | If your sources are available as a tarball instead of a Git repository, you | ||
| 2466 | will need to provide the URL to the tarball as well as an | ||
| 2467 | <code class="filename">md5</code> or <code class="filename">sha256</code> sum of | ||
| 2468 | the download. | ||
| 2469 | Here is an example: | ||
| 2470 | </p><pre class="literallayout"> | ||
| 2471 | SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2" | ||
| 2472 | SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b" | ||
| 2473 | </pre><p> | ||
| 2474 | You can generate the <code class="filename">md5</code> or <code class="filename">sha256</code> sums | ||
| 2475 | by using the <code class="filename">md5sum</code> or <code class="filename">sha256sum</code> commands | ||
| 2476 | with the target file as the only argument. | ||
| 2477 | Here is an example: | ||
| 2478 | </p><pre class="literallayout"> | ||
| 2479 | $ md5sum mtd-utils-1.4.9.tar.bz2 | ||
| 2480 | 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2 | ||
| 2481 | </pre><p> | ||
| 2482 | </p></div><div class="section" title="4.3.4. Splitting an Application into Multiple Packages"><div class="titlepage"><div><div><h3 class="title"><a id="splitting-an-application-into-multiple-packages"></a>4.3.4. Splitting an Application into Multiple Packages</h3></div></div></div><p> | ||
| 2483 | You can use the variables | ||
| 2484 | <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a></code> and | ||
| 2485 | <code class="filename"><a class="link" href="#var-FILES" target="_top">FILES</a></code> | ||
| 2486 | to split an application into multiple packages. | ||
| 2487 | </p><p> | ||
| 2488 | Following is an example that uses the <code class="filename">libXpm</code> recipe. | ||
| 2489 | By default, this recipe generates a single package that contains the library along | ||
| 2490 | with a few binaries. | ||
| 2491 | You can modify the recipe to split the binaries into separate packages: | ||
| 2492 | </p><pre class="literallayout"> | ||
| 2493 | require xorg-lib-common.inc | ||
| 2494 | |||
| 2495 | DESCRIPTION = "X11 Pixmap library" | ||
| 2496 | LICENSE = "X-BSD" | ||
| 2497 | LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" | ||
| 2498 | DEPENDS += "libxext libsm libxt" | ||
| 2499 | PR = "r3" | ||
| 2500 | PE = "1" | ||
| 2501 | |||
| 2502 | XORG_PN = "libXpm" | ||
| 2503 | |||
| 2504 | PACKAGES =+ "sxpm cxpm" | ||
| 2505 | FILES_cxpm = "${bindir}/cxpm" | ||
| 2506 | FILES_sxpm = "${bindir}/sxpm" | ||
| 2507 | </pre><p> | ||
| 2508 | </p><p> | ||
| 2509 | In the previous example, we want to ship the <code class="filename">sxpm</code> | ||
| 2510 | and <code class="filename">cxpm</code> binaries in separate packages. | ||
| 2511 | Since <code class="filename">bindir</code> would be packaged into the main | ||
| 2512 | <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> | ||
| 2513 | package by default, we prepend the | ||
| 2514 | <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a> | ||
| 2515 | </code> variable so additional package names are added to the start of list. | ||
| 2516 | This results in the extra | ||
| 2517 | <code class="filename"><a class="link" href="#var-FILES" target="_top">FILES</a>_*</code> | ||
| 2518 | variables then containing information that define which files and | ||
| 2519 | directories go into which packages. | ||
| 2520 | Files included by earlier packages are skipped by latter packages. | ||
| 2521 | Thus, the main | ||
| 2522 | <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> package | ||
| 2523 | does not include the above listed files. | ||
| 2524 | </p></div><div class="section" title="4.3.5. Including Static Library Files"><div class="titlepage"><div><div><h3 class="title"><a id="including-static-library-files"></a>4.3.5. Including Static Library Files</h3></div></div></div><p> | ||
| 2525 | If you are building a library and the library offers static linking, you can control | ||
| 2526 | which static library files (<code class="filename">*.a</code> files) get included in the | ||
| 2527 | built library. | ||
| 2528 | </p><p> | ||
| 2529 | The <code class="filename">PACKAGES</code> and <code class="filename">FILES_*</code> variables in the | ||
| 2530 | <code class="filename">meta/conf/bitbake.conf</code> configuration file define how files installed | ||
| 2531 | by the <code class="filename">do_install</code> task are packaged. | ||
| 2532 | By default, the <code class="filename">PACKAGES</code> variable contains | ||
| 2533 | <code class="filename">${PN}-staticdev</code>, which includes all static library files. | ||
| 2534 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2535 | Previously released versions of the Yocto Project defined the static library files | ||
| 2536 | through <code class="filename">${PN}-dev</code>. | ||
| 2537 | </div><p> | ||
| 2538 | Following, is part of the BitBake configuration file. | ||
| 2539 | You can see where the static library files are defined: | ||
| 2540 | </p><pre class="literallayout"> | ||
| 2541 | PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale" | ||
| 2542 | PACKAGES_DYNAMIC = "${PN}-locale-*" | ||
| 2543 | FILES = "" | ||
| 2544 | |||
| 2545 | FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ | ||
| 2546 | ${sysconfdir} ${sharedstatedir} ${localstatedir} \ | ||
| 2547 | ${base_bindir}/* ${base_sbindir}/* \ | ||
| 2548 | ${base_libdir}/*${SOLIBS} \ | ||
| 2549 | ${datadir}/${BPN} ${libdir}/${BPN}/* \ | ||
| 2550 | ${datadir}/pixmaps ${datadir}/applications \ | ||
| 2551 | ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ | ||
| 2552 | ${libdir}/bonobo/servers" | ||
| 2553 | |||
| 2554 | FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ | ||
| 2555 | ${datadir}/gnome/help" | ||
| 2556 | SECTION_${PN}-doc = "doc" | ||
| 2557 | |||
| 2558 | FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \ | ||
| 2559 | ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ | ||
| 2560 | ${datadir}/aclocal ${base_libdir}/*.o" | ||
| 2561 | SECTION_${PN}-dev = "devel" | ||
| 2562 | ALLOW_EMPTY_${PN}-dev = "1" | ||
| 2563 | RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" | ||
| 2564 | |||
| 2565 | FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a" | ||
| 2566 | SECTION_${PN}-staticdev = "devel" | ||
| 2567 | RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" | ||
| 2568 | </pre><p> | ||
| 2569 | </p></div><div class="section" title="4.3.6. Post Install Scripts"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-postinstalls"></a>4.3.6. Post Install Scripts</h3></div></div></div><p> | ||
| 2570 | To add a post-installation script to a package, add a <code class="filename">pkg_postinst_PACKAGENAME() | ||
| 2571 | </code> function to the <code class="filename">.bb</code> file and use | ||
| 2572 | <code class="filename">PACKAGENAME</code> as the name of the package you want to attach to the | ||
| 2573 | <code class="filename">postinst</code> script. | ||
| 2574 | Normally | ||
| 2575 | <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> | ||
| 2576 | can be used, which automatically expands to <code class="filename">PACKAGENAME</code>. | ||
| 2577 | A post-installation function has the following structure: | ||
| 2578 | </p><pre class="literallayout"> | ||
| 2579 | pkg_postinst_PACKAGENAME () { | ||
| 2580 | #!/bin/sh -e | ||
| 2581 | # Commands to carry out | ||
| 2582 | } | ||
| 2583 | </pre><p> | ||
| 2584 | </p><p> | ||
| 2585 | The script defined in the post-installation function is called when the | ||
| 2586 | root filesystem is created. | ||
| 2587 | If the script succeeds, the package is marked as installed. | ||
| 2588 | If the script fails, the package is marked as unpacked and the script is | ||
| 2589 | executed when the image boots again. | ||
| 2590 | </p><p> | ||
| 2591 | Sometimes it is necessary for the execution of a post-installation | ||
| 2592 | script to be delayed until the first boot. | ||
| 2593 | For example, the script might need to be executed on the device itself. | ||
| 2594 | To delay script execution until boot time, use the following structure in the | ||
| 2595 | post-installation script: | ||
| 2596 | </p><pre class="literallayout"> | ||
| 2597 | pkg_postinst_PACKAGENAME () { | ||
| 2598 | #!/bin/sh -e | ||
| 2599 | if [ x"$D" = "x" ]; then | ||
| 2600 | # Actions to carry out on the device go here | ||
| 2601 | else | ||
| 2602 | exit 1 | ||
| 2603 | fi | ||
| 2604 | } | ||
| 2605 | </pre><p> | ||
| 2606 | </p><p> | ||
| 2607 | The previous example delays execution until the image boots again because the | ||
| 2608 | <code class="filename"><a class="link" href="#var-D" target="_top">D</a></code> | ||
| 2609 | variable points | ||
| 2610 | to the directory containing the image when the root filesystem is created at build time but | ||
| 2611 | is unset when executed on the first boot. | ||
| 2612 | </p></div></div><div class="section" title="4.4. Adding a New Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-newmachine"></a>4.4. Adding a New Machine</h2></div></div></div><p> | ||
| 2613 | Adding a new machine to the Yocto Project is a straightforward process. | ||
| 2614 | This section provides information that gives you an idea of the changes you must make. | ||
| 2615 | The information covers adding machines similar to those the Yocto Project already supports. | ||
| 2616 | Although well within the capabilities of the Yocto Project, adding a totally new architecture | ||
| 2617 | might require | ||
| 2618 | changes to <code class="filename">gcc/eglibc</code> and to the site information, which is | ||
| 2619 | beyond the scope of this manual. | ||
| 2620 | </p><p> | ||
| 2621 | For a complete example that shows how to add a new machine, | ||
| 2622 | see the | ||
| 2623 | "<a class="link" href="#dev-manual-bsp-appendix" target="_top">BSP Development Example</a>" | ||
| 2624 | in Appendix A. | ||
| 2625 | </p><div class="section" title="4.4.1. Adding the Machine Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-newmachine-conffile"></a>4.4.1. Adding the Machine Configuration File</h3></div></div></div><p> | ||
| 2626 | To add a machine configuration you need to add a <code class="filename">.conf</code> file | ||
| 2627 | with details of the device being added to the <code class="filename">conf/machine/</code> file. | ||
| 2628 | The name of the file determines the name the OpenEmbedded build system | ||
| 2629 | uses to reference the new machine. | ||
| 2630 | </p><p> | ||
| 2631 | The most important variables to set in this file are as follows: | ||
| 2632 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" target="_top"> | ||
| 2633 | TARGET_ARCH</a></code> (e.g. "arm")</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" target="_top"> | ||
| 2634 | PREFERRED_PROVIDER</a></code>_virtual/kernel (see below)</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" target="_top"> | ||
| 2635 | MACHINE_FEATURES</a></code> (e.g. "apm screen wifi")</p></li></ul></div><p> | ||
| 2636 | </p><p> | ||
| 2637 | You might also need these variables: | ||
| 2638 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" target="_top"> | ||
| 2639 | SERIAL_CONSOLE</a></code> (e.g. "115200 ttyS0")</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-KERNEL_IMAGETYPE" target="_top"> | ||
| 2640 | KERNEL_IMAGETYPE</a></code> (e.g. "zImage")</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" target="_top"> | ||
| 2641 | IMAGE_FSTYPES</a></code> (e.g. "tar.gz jffs2")</p></li></ul></div><p> | ||
| 2642 | </p><p> | ||
| 2643 | You can find full details on these variables in the reference section. | ||
| 2644 | You can leverage many existing machine <code class="filename">.conf</code> files from | ||
| 2645 | <code class="filename">meta/conf/machine/</code>. | ||
| 2646 | </p></div><div class="section" title="4.4.2. Adding a Kernel for the Machine"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-newmachine-kernel"></a>4.4.2. Adding a Kernel for the Machine</h3></div></div></div><p> | ||
| 2647 | The OpenEmbedded build system needs to be able to build a kernel for the machine. | ||
| 2648 | You need to either create a new kernel recipe for this machine, or extend an | ||
| 2649 | existing recipe. | ||
| 2650 | You can find several kernel examples in the | ||
| 2651 | source directory at <code class="filename">meta/recipes-kernel/linux</code> | ||
| 2652 | that you can use as references. | ||
| 2653 | </p><p> | ||
| 2654 | If you are creating a new recipe, normal recipe-writing rules apply for setting | ||
| 2655 | up a | ||
| 2656 | <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>. | ||
| 2657 | Thus, you need to specify any necessary patches and set | ||
| 2658 | <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> to point at the source code. | ||
| 2659 | You need to create a <code class="filename">configure</code> task that configures the | ||
| 2660 | unpacked kernel with a defconfig. | ||
| 2661 | You can do this by using a <code class="filename">make defconfig</code> command or, | ||
| 2662 | more commonly, by copying in a suitable <code class="filename">defconfig</code> file and and then running | ||
| 2663 | <code class="filename">make oldconfig</code>. | ||
| 2664 | By making use of <code class="filename">inherit kernel</code> and potentially some of the | ||
| 2665 | <code class="filename">linux-*.inc</code> files, most other functionality is | ||
| 2666 | centralized and the the defaults of the class normally work well. | ||
| 2667 | </p><p> | ||
| 2668 | If you are extending an existing kernel, it is usually a matter of adding a | ||
| 2669 | suitable defconfig file. | ||
| 2670 | The file needs to be added into a location similar to defconfig files | ||
| 2671 | used for other machines in a given kernel. | ||
| 2672 | A possible way to do this is by listing the file in the | ||
| 2673 | <code class="filename">SRC_URI</code> and adding the machine to the expression in | ||
| 2674 | <code class="filename"><a class="link" href="#var-COMPATIBLE_MACHINE" target="_top">COMPATIBLE_MACHINE</a></code>: | ||
| 2675 | </p><pre class="literallayout"> | ||
| 2676 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' | ||
| 2677 | </pre><p> | ||
| 2678 | </p></div><div class="section" title="4.4.3. Adding a Formfactor Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-newmachine-formfactor"></a>4.4.3. Adding a Formfactor Configuration File</h3></div></div></div><p> | ||
| 2679 | A formfactor configuration file provides information about the | ||
| 2680 | target hardware for which the image is being built and information that | ||
| 2681 | the build system cannot obtain from other sources such as the kernel. | ||
| 2682 | Some examples of information contained in a formfactor configuration file include | ||
| 2683 | framebuffer orientation, whether or not the system has a keyboard, | ||
| 2684 | the positioning of the keyboard in relation to the screen, and | ||
| 2685 | the screen resolution. | ||
| 2686 | </p><p> | ||
| 2687 | The build system uses reasonable defaults in most cases, but if customization is | ||
| 2688 | necessary you need to create a <code class="filename">machconfig</code> file | ||
| 2689 | in the <code class="filename">meta/recipes-bsp/formfactor/files</code> | ||
| 2690 | directory. | ||
| 2691 | This directory contains directories for specific machines such as | ||
| 2692 | <code class="filename">qemuarm</code> and <code class="filename">qemux86</code>. | ||
| 2693 | For information about the settings available and the defaults, see the | ||
| 2694 | <code class="filename">meta/recipes-bsp/formfactor/files/config</code> file found in the | ||
| 2695 | same area. | ||
| 2696 | Following is an example for qemuarm: | ||
| 2697 | </p><pre class="literallayout"> | ||
| 2698 | HAVE_TOUCHSCREEN=1 | ||
| 2699 | HAVE_KEYBOARD=1 | ||
| 2700 | |||
| 2701 | DISPLAY_CAN_ROTATE=0 | ||
| 2702 | DISPLAY_ORIENTATION=0 | ||
| 2703 | #DISPLAY_WIDTH_PIXELS=640 | ||
| 2704 | #DISPLAY_HEIGHT_PIXELS=480 | ||
| 2705 | #DISPLAY_BPP=16 | ||
| 2706 | DISPLAY_DPI=150 | ||
| 2707 | DISPLAY_SUBPIXEL_ORDER=vrgb | ||
| 2708 | </pre><p> | ||
| 2709 | </p></div></div><div class="section" title="4.5. Combining Multiple Versions of Library Files into One Image"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-multiple-architecture-libraries-into-one-image"></a>4.5. Combining Multiple Versions of Library Files into One Image</h2></div></div></div><p> | ||
| 2710 | The build system offers the ability to build libraries with different | ||
| 2711 | target optimizations or architecture formats and combine these together | ||
| 2712 | into one system image. | ||
| 2713 | You can link different binaries in the image | ||
| 2714 | against the different libraries as needed for specific use cases. | ||
| 2715 | This feature is called "Multilib." | ||
| 2716 | </p><p> | ||
| 2717 | An example would be where you have most of a system compiled in 32-bit | ||
| 2718 | mode using 32-bit libraries, but you have something large, like a database | ||
| 2719 | engine, that needs to be a 64-bit application and use 64-bit libraries. | ||
| 2720 | Multilib allows you to get the best of both 32-bit and 64-bit libraries. | ||
| 2721 | </p><p> | ||
| 2722 | While the Multilib feature is most commonly used for 32 and 64-bit differences, | ||
| 2723 | the approach the build system uses facilitates different target optimizations. | ||
| 2724 | You could compile some binaries to use one set of libraries and other binaries | ||
| 2725 | to use other different sets of libraries. | ||
| 2726 | The libraries could differ in architecture, compiler options, or other | ||
| 2727 | optimizations. | ||
| 2728 | </p><p> | ||
| 2729 | This section overviews the Multilib process only. | ||
| 2730 | For more details on how to implement Multilib, see the | ||
| 2731 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Multilib" target="_top">Multilib</a> wiki | ||
| 2732 | page. | ||
| 2733 | </p><div class="section" title="4.5.1. Preparing to use Multilib"><div class="titlepage"><div><div><h3 class="title"><a id="preparing-to-use-multilib"></a>4.5.1. Preparing to use Multilib</h3></div></div></div><p> | ||
| 2734 | User-specific requirements drive the Multilib feature, | ||
| 2735 | Consequently, there is no one "out-of-the-box" configuration that likely | ||
| 2736 | exists to meet your needs. | ||
| 2737 | </p><p> | ||
| 2738 | In order to enable Multilib, you first need to ensure your recipe is | ||
| 2739 | extended to support multiple libraries. | ||
| 2740 | Many standard recipes are already extended and support multiple libraries. | ||
| 2741 | You can check in the <code class="filename">meta/conf/multilib.conf</code> | ||
| 2742 | configuration file in the source directory to see how this is | ||
| 2743 | done using the <code class="filename">BBCLASSEXTEND</code> variable. | ||
| 2744 | Eventually, all recipes will be covered and this list will be unneeded. | ||
| 2745 | </p><p> | ||
| 2746 | For the most part, the Multilib class extension works automatically to | ||
| 2747 | extend the package name from <code class="filename">${PN}</code> to | ||
| 2748 | <code class="filename">${MLPREFIX}${PN}</code>, where <code class="filename">MLPREFIX</code> | ||
| 2749 | is the particular multilib (e.g. "lib32-" or "lib64-"). | ||
| 2750 | Standard variables such as <code class="filename">DEPENDS</code>, | ||
| 2751 | <code class="filename">RDEPENDS</code>, <code class="filename">RPROVIDES</code>, | ||
| 2752 | <code class="filename">RRECOMMENDS</code>, <code class="filename">PACKAGES</code>, and | ||
| 2753 | <code class="filename">PACKAGES_DYNAMIC</code> are automatically extended by the system. | ||
| 2754 | If you are extending any manual code in the recipe, you can use the | ||
| 2755 | <code class="filename">${MLPREFIX}</code> variable to ensure those names are extended | ||
| 2756 | correctly. | ||
| 2757 | This automatic extension code resides in <code class="filename">multilib.bbclass</code>. | ||
| 2758 | </p></div><div class="section" title="4.5.2. Using Multilib"><div class="titlepage"><div><div><h3 class="title"><a id="using-multilib"></a>4.5.2. Using Multilib</h3></div></div></div><p> | ||
| 2759 | After you have set up the recipes, you need to define the actual | ||
| 2760 | combination of multiple libraries you want to build. | ||
| 2761 | You accomplish this through your <code class="filename">local.conf</code> | ||
| 2762 | configuration file in the | ||
| 2763 | <a class="link" href="#build-directory">build directory</a>. | ||
| 2764 | An example configuration would be as follows: | ||
| 2765 | </p><pre class="literallayout"> | ||
| 2766 | MACHINE = "qemux86-64" | ||
| 2767 | require conf/multilib.conf | ||
| 2768 | MULTILIBS = "multilib:lib32" | ||
| 2769 | DEFAULTTUNE_virtclass-multilib-lib32 = "x86" | ||
| 2770 | IMAGE_INSTALL = "lib32-connman" | ||
| 2771 | </pre><p> | ||
| 2772 | This example enables an | ||
| 2773 | additional library named <code class="filename">lib32</code> alongside the | ||
| 2774 | normal target packages. | ||
| 2775 | When combining these "lib32" alternatives, the example uses "x86" for tuning. | ||
| 2776 | For information on this particular tuning, see | ||
| 2777 | <code class="filename">meta/conf/machine/include/ia32/arch-ia32.inc</code>. | ||
| 2778 | </p><p> | ||
| 2779 | The example then includes <code class="filename">lib32-connman</code> | ||
| 2780 | in all the images, which illustrates one method of including a | ||
| 2781 | multiple library dependency. | ||
| 2782 | You can use a normal image build to include this dependency, | ||
| 2783 | for example: | ||
| 2784 | </p><pre class="literallayout"> | ||
| 2785 | $ bitbake core-image-sato | ||
| 2786 | </pre><p> | ||
| 2787 | You can also build Multilib packages specifically with a command like this: | ||
| 2788 | </p><pre class="literallayout"> | ||
| 2789 | $ bitbake lib32-connman | ||
| 2790 | </pre><p> | ||
| 2791 | </p></div><div class="section" title="4.5.3. Additional Implementation Details"><div class="titlepage"><div><div><h3 class="title"><a id="additional-implementation-details"></a>4.5.3. Additional Implementation Details</h3></div></div></div><p> | ||
| 2792 | Different packaging systems have different levels of native Multilib | ||
| 2793 | support. | ||
| 2794 | For the RPM Package Management System, the following implementation details | ||
| 2795 | exist: | ||
| 2796 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A unique architecture is defined for the Multilib packages, | ||
| 2797 | along with creating a unique deploy folder under | ||
| 2798 | <code class="filename">tmp/deploy/rpm</code> in the | ||
| 2799 | <a class="link" href="#build-directory">build directory</a>. | ||
| 2800 | For example, consider <code class="filename">lib32</code> in a | ||
| 2801 | <code class="filename">qemux86-64</code> image. | ||
| 2802 | The possible architectures in the system are "all", "qemux86_64", | ||
| 2803 | "lib32_qemux86_64", and "lib32_x86".</p></li><li class="listitem"><p>The <code class="filename">${MLPREFIX}</code> variable is stripped from | ||
| 2804 | <code class="filename">${PN}</code> during RPM packaging. | ||
| 2805 | The naming for a normal RPM package and a Multilib RPM package in a | ||
| 2806 | <code class="filename">qemux86-64</code> system resolves to something similar to | ||
| 2807 | <code class="filename">bash-4.1-r2.x86_64.rpm</code> and | ||
| 2808 | <code class="filename">bash-4.1.r2.lib32_x86.rpm</code>, respectively. | ||
| 2809 | </p></li><li class="listitem"><p>When installing a Multilib image, the RPM backend first | ||
| 2810 | installs the base image and then installs the Multilib libraries. | ||
| 2811 | </p></li><li class="listitem"><p>The build system relies on RPM to resolve the identical files in the | ||
| 2812 | two (or more) Multilib packages.</p></li></ul></div><p> | ||
| 2813 | </p><p> | ||
| 2814 | For the IPK Package Management System, the following implementation details exist: | ||
| 2815 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">${MLPREFIX}</code> is not stripped from | ||
| 2816 | <code class="filename">${PN}</code> during IPK packaging. | ||
| 2817 | The naming for a normal RPM package and a Multilib IPK package in a | ||
| 2818 | <code class="filename">qemux86-64</code> system resolves to something like | ||
| 2819 | <code class="filename">bash_4.1-r2.x86_64.ipk</code> and | ||
| 2820 | <code class="filename">lib32-bash_4.1-rw_x86.ipk</code>, respectively. | ||
| 2821 | </p></li><li class="listitem"><p>The IPK deploy folder is not modified with | ||
| 2822 | <code class="filename">${MLPREFIX}</code> because packages with and without | ||
| 2823 | the Multilib feature can exist in the same folder due to the | ||
| 2824 | <code class="filename">${PN}</code> differences.</p></li><li class="listitem"><p>IPK defines a sanity check for Multilib installation | ||
| 2825 | using certain rules for file comparison, overridden, etc. | ||
| 2826 | </p></li></ul></div><p> | ||
| 2827 | </p></div></div><div class="section" title="4.6. Configuring the Kernel"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="configuring-the-kernel"></a>4.6. Configuring the Kernel</h2></div></div></div><p> | ||
| 2828 | Configuring the Yocto Project kernel consists of making sure the <code class="filename">.config</code> | ||
| 2829 | file has all the right information in it for the image you are building. | ||
| 2830 | You can use the <code class="filename">menuconfig</code> tool and configuration fragments to | ||
| 2831 | make sure your <code class="filename">.config</code> file is just how you need it. | ||
| 2832 | This section describes how to use <code class="filename">menuconfig</code>, create and use | ||
| 2833 | configuration fragments, and how to interactively tweak your <code class="filename">.config</code> | ||
| 2834 | file to create the leanest kernel configuration file possible. | ||
| 2835 | </p><p> | ||
| 2836 | For concepts on kernel configuration, see the | ||
| 2837 | "<a class="link" href="#kernel-configuration" target="_top">Kernel Configuration</a>" | ||
| 2838 | section in the Yocto Project Kernel Architecture and Use Manual. | ||
| 2839 | </p><div class="section" title="4.6.1. Using menuconfig"><div class="titlepage"><div><div><h3 class="title"><a id="using-menuconfig"></a>4.6.1. Using <code class="filename">menuconfig</code></h3></div></div></div><p> | ||
| 2840 | The easiest way to define kernel configurations is to set them through the | ||
| 2841 | <code class="filename">menuconfig</code> tool. | ||
| 2842 | For general information on <code class="filename">menuconfig</code>, see | ||
| 2843 | <a class="ulink" href="http://en.wikipedia.org/wiki/Menuconfig" target="_top">http://en.wikipedia.org/wiki/Menuconfig</a>. | ||
| 2844 | </p><p> | ||
| 2845 | To use the <code class="filename">menuconfig</code> tool in the Yocto Project development | ||
| 2846 | environment, you must build the tool using BitBake. | ||
| 2847 | The following commands build and invoke <code class="filename">menuconfig</code> assuming the | ||
| 2848 | source directory top-level folder is <code class="filename">~/poky</code>: | ||
| 2849 | </p><pre class="literallayout"> | ||
| 2850 | $ cd ~/poky | ||
| 2851 | $ source oe-init-build-env | ||
| 2852 | $ bitbake linux-yocto -c menuconfig | ||
| 2853 | </pre><p> | ||
| 2854 | Once <code class="filename">menuconfig</code> comes up, its standard interface allows you to | ||
| 2855 | examine and configure all the kernel configuration parameters. | ||
| 2856 | Once you have made your changes, simply exit the tool and save your changes to | ||
| 2857 | create an updated version of the <code class="filename">.config</code> configuration file. | ||
| 2858 | </p><p> | ||
| 2859 | For an example that shows how to change a specific kernel option | ||
| 2860 | using <code class="filename">menuconfig</code>, see the | ||
| 2861 | "<a class="link" href="#changing-the-config-smp-configuration-using-menuconfig" title="B.2.3. Changing the CONFIG_SMP Configuration Using menuconfig">Changing | ||
| 2862 | the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></a>" | ||
| 2863 | section. | ||
| 2864 | </p></div><div class="section" title="4.6.2. Creating Configuration Fragments"><div class="titlepage"><div><div><h3 class="title"><a id="creating-config-fragments"></a>4.6.2. Creating Configuration Fragments</h3></div></div></div><p> | ||
| 2865 | Configuration fragments are simply kernel options that appear in a file | ||
| 2866 | placed where the OpenEmbedded build system can find and apply them. | ||
| 2867 | Syntactically, the configuration statement is identical to what would appear | ||
| 2868 | in the <code class="filename">.config</code> file, which is in the | ||
| 2869 | <a class="link" href="#build-directory">build directory</a> in | ||
| 2870 | <code class="filename">tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></code>. | ||
| 2871 | </p><p> | ||
| 2872 | It is simple to create a configuration fragment. | ||
| 2873 | For example, issuing the following from the shell creates a configuration fragment | ||
| 2874 | file named <code class="filename">my_smp.cfg</code> that enables multi-processor support | ||
| 2875 | within the kernel: | ||
| 2876 | </p><pre class="literallayout"> | ||
| 2877 | $ echo "CONFIG_SMP=y" >> my_smp.cfg | ||
| 2878 | </pre><p> | ||
| 2879 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2880 | All configuration files must use the <code class="filename">.cfg</code> extension in order | ||
| 2881 | for the OpenEmbedded build system to recognize them as a configuration fragment. | ||
| 2882 | </div><p> | ||
| 2883 | </p><p> | ||
| 2884 | Where do you put your configuration files? | ||
| 2885 | You can place these configuration files in the same area pointed to by | ||
| 2886 | <code class="filename">SRC_URI</code>. | ||
| 2887 | The OpenEmbedded build system will pick up the configuration and add it to the | ||
| 2888 | kernel's configuration. | ||
| 2889 | For example, suppose you had a set of configuration options in a file called | ||
| 2890 | <code class="filename">myconfig.cfg</code>. | ||
| 2891 | If you put that file inside a directory named <code class="filename">/linux-yocto</code> | ||
| 2892 | that resides in the same directory as the kernel's append file and then add | ||
| 2893 | a <code class="filename">SRC_URI</code> statement such as the following to the kernel's append file, | ||
| 2894 | those configuration options will be picked up and applied when the kernel is built. | ||
| 2895 | </p><pre class="literallayout"> | ||
| 2896 | SRC_URI += "file://myconfig.cfg" | ||
| 2897 | </pre><p> | ||
| 2898 | </p><p> | ||
| 2899 | As mentioned earlier, you can group related configurations into multiple files and | ||
| 2900 | name them all in the <code class="filename">SRC_URI</code> statement as well. | ||
| 2901 | For example, you could group separate configurations specifically for Ethernet and graphics | ||
| 2902 | into their own files and add those by using a <code class="filename">SRC_URI</code> statement like the | ||
| 2903 | following in your append file: | ||
| 2904 | </p><pre class="literallayout"> | ||
| 2905 | SRC_URI += "file://myconfig.cfg \ | ||
| 2906 | file://eth.cfg \ | ||
| 2907 | file://gfx.cfg" | ||
| 2908 | </pre><p> | ||
| 2909 | </p></div><div class="section" title="4.6.3. Fine-tuning the Kernel Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="fine-tuning-the-kernel-configuration-file"></a>4.6.3. Fine-tuning the Kernel Configuration File</h3></div></div></div><p> | ||
| 2910 | You can make sure the <code class="filename">.config</code> is as lean or efficient as | ||
| 2911 | possible by reading the output of the kernel configuration fragment audit, | ||
| 2912 | noting any issues, making changes to correct the issues, and then repeating. | ||
| 2913 | </p><p> | ||
| 2914 | As part of the kernel build process, the | ||
| 2915 | <code class="filename">kernel_configcheck</code> task runs. | ||
| 2916 | This task validates the kernel configuration by checking the final | ||
| 2917 | <code class="filename">.config</code> file against the input files. | ||
| 2918 | During the check, the task produces warning messages for the following | ||
| 2919 | issues: | ||
| 2920 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Requested options that did not make the final | ||
| 2921 | <code class="filename">.config</code> file.</p></li><li class="listitem"><p>Configuration items that appear twice in the same | ||
| 2922 | configuration fragment.</p></li><li class="listitem"><p>Configuration items tagged as 'required' were overridden. | ||
| 2923 | </p></li><li class="listitem"><p>A board overrides a non-board specific option.</p></li><li class="listitem"><p>Listed options not valid for the kernel being processed. | ||
| 2924 | In other words, the option does not appear anywhere.</p></li></ul></div><p> | ||
| 2925 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 2926 | The <code class="filename">kernel_configcheck</code> task can also optionally report | ||
| 2927 | if an option is overridden during processing. | ||
| 2928 | </div><p> | ||
| 2929 | </p><p> | ||
| 2930 | For each output warning, a message points to the file | ||
| 2931 | that contains a list of the options and a pointer to the config | ||
| 2932 | fragment that defines them. | ||
| 2933 | Collectively, the files are the key to streamlining the configuration. | ||
| 2934 | </p><p> | ||
| 2935 | To streamline the configuration, do the following: | ||
| 2936 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start with a full configuration that you know | ||
| 2937 | works - it builds and boots successfully. | ||
| 2938 | This configuration file will be your baseline.</p></li><li class="listitem"><p>Separately run the <code class="filename">configme</code> and | ||
| 2939 | <code class="filename">kernel_configcheck</code> tasks.</p></li><li class="listitem"><p>Take the resulting list of files from the | ||
| 2940 | <code class="filename">kernel_configcheck</code> task warnings and do the following: | ||
| 2941 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Drop values that are redefined in the fragment but do not | ||
| 2942 | change the final <code class="filename">.config</code> file.</p></li><li class="listitem"><p>Analyze and potentially drop values from the | ||
| 2943 | <code class="filename">.config</code> file that override required | ||
| 2944 | configurations.</p></li><li class="listitem"><p>Analyze and potentially remove non-board specific options. | ||
| 2945 | </p></li><li class="listitem"><p>Remove repeated and invalid options.</p></li></ul></div></li><li class="listitem"><p>After you have worked through the output of the kernel configuration | ||
| 2946 | audit, you can re-run the <code class="filename">configme</code> | ||
| 2947 | and <code class="filename">kernel_configcheck</code> tasks to see the results of your | ||
| 2948 | changes. | ||
| 2949 | If you have more issues, you can deal with them as described in the | ||
| 2950 | previous step.</p></li></ol></div><p> | ||
| 2951 | </p><p> | ||
| 2952 | Iteratively working through steps two through four eventually yields | ||
| 2953 | a minimal, streamlined configuration file. | ||
| 2954 | Once you have the best <code class="filename">.config</code>, you can build the Linux | ||
| 2955 | Yocto kernel. | ||
| 2956 | </p></div></div><div class="section" title="4.7. Updating Existing Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-changes-updatingimages"></a>4.7. Updating Existing Images</h2></div></div></div><p> | ||
| 2957 | Often, rather than re-flashing a new image, you might wish to install updated | ||
| 2958 | packages into an existing running system. | ||
| 2959 | You can do this by first sharing the <code class="filename">tmp/deploy/ipk/</code> directory | ||
| 2960 | through a web server and then by changing <code class="filename">/etc/opkg/base-feeds.conf</code> | ||
| 2961 | to point at the shared server. | ||
| 2962 | Following is an example: | ||
| 2963 | </p><pre class="literallayout"> | ||
| 2964 | $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all | ||
| 2965 | $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a | ||
| 2966 | $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard | ||
| 2967 | </pre><p> | ||
| 2968 | </p></div><div class="section" title="4.8. Incrementing a Package Revision Number"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-changes-prbump"></a>4.8. Incrementing a Package Revision Number</h2></div></div></div><p> | ||
| 2969 | If a committed change results in changing the package output, | ||
| 2970 | then the value of the | ||
| 2971 | <code class="filename"><a class="link" href="#var-PR" target="_top">PR</a></code> | ||
| 2972 | variable needs to be increased | ||
| 2973 | (or "bumped") as part of that commit. | ||
| 2974 | This means that for new recipes you must be sure to add the <code class="filename">PR</code> | ||
| 2975 | variable and set its initial value equal to "r0". | ||
| 2976 | Failing to define <code class="filename">PR</code> makes it easy to miss when you bump a package. | ||
| 2977 | Note that you can only use integer values following the "r" in the | ||
| 2978 | <code class="filename">PR</code> variable. | ||
| 2979 | </p><p> | ||
| 2980 | If you are sharing a common <code class="filename">.inc</code> file with multiple recipes, | ||
| 2981 | you can also use the | ||
| 2982 | <code class="filename"><a class="link" href="#var-INC_PR" target="_top">INC_PR</a></code> | ||
| 2983 | variable to ensure that | ||
| 2984 | the recipes sharing the <code class="filename">.inc</code> file are rebuilt when the | ||
| 2985 | <code class="filename">.inc</code> file itself is changed. | ||
| 2986 | The <code class="filename">.inc</code> file must set <code class="filename">INC_PR</code> | ||
| 2987 | (initially to "r0"), and all recipes referring to it should set <code class="filename">PR</code> | ||
| 2988 | to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. | ||
| 2989 | If the <code class="filename">.inc</code> file is changed then its | ||
| 2990 | <code class="filename">INC_PR</code> should be incremented. | ||
| 2991 | </p><p> | ||
| 2992 | When upgrading the version of a package, assuming the | ||
| 2993 | <code class="filename"><a class="link" href="#var-PV" target="_top">PV</a></code> | ||
| 2994 | changes, the <code class="filename">PR</code> variable should be reset to "r0" | ||
| 2995 | (or "$(INC_PR).0" if you are using <code class="filename">INC_PR</code>). | ||
| 2996 | </p><p> | ||
| 2997 | Usually, version increases occur only to packages. | ||
| 2998 | However, if for some reason <code class="filename">PV</code> changes but does not | ||
| 2999 | increase, you can increase the | ||
| 3000 | <code class="filename"><a class="link" href="#var-PE" target="_top">PE</a></code> | ||
| 3001 | variable (Package Epoch). | ||
| 3002 | The <code class="filename">PE</code> variable defaults to "0". | ||
| 3003 | </p><p> | ||
| 3004 | Version numbering strives to follow the | ||
| 3005 | <a class="ulink" href="http://www.debian.org/doc/debian-policy/ch-controlfields.html" target="_top"> | ||
| 3006 | Debian Version Field Policy Guidelines</a>. | ||
| 3007 | These guidelines define how versions are compared and what "increasing" a version means. | ||
| 3008 | </p><p> | ||
| 3009 | There are two reasons for following the previously mentioned guidelines. | ||
| 3010 | First, to ensure that when a developer updates and rebuilds, they get all the changes to | ||
| 3011 | the repository and do not have to remember to rebuild any sections. | ||
| 3012 | Second, to ensure that target users are able to upgrade their | ||
| 3013 | devices using package manager commands such as <code class="filename">opkg upgrade</code> | ||
| 3014 | (or similar commands for dpkg/apt or rpm-based systems). | ||
| 3015 | </p><p> | ||
| 3016 | The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. | ||
| 3017 | </p></div><div class="section" title="4.9. Handling a Package Name Alias"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-configuring-DISTRO_PN_ALIAS"></a>4.9. Handling a Package Name Alias</h2></div></div></div><p> | ||
| 3018 | Sometimes a package name you are using might exist under an alias or as a similarly named | ||
| 3019 | package in a different distribution. | ||
| 3020 | The OpenEmbedded build system implements a <code class="filename">distro_check</code> | ||
| 3021 | task that automatically connects to major distributions | ||
| 3022 | and checks for these situations. | ||
| 3023 | If the package exists under a different name in a different distribution, you get a | ||
| 3024 | <code class="filename">distro_check</code> mismatch. | ||
| 3025 | You can resolve this problem by defining a per-distro recipe name alias using the | ||
| 3026 | <code class="filename"><a class="link" href="#var-DISTRO_PN_ALIAS" target="_top">DISTRO_PN_ALIAS</a></code> | ||
| 3027 | variable. | ||
| 3028 | </p><p> | ||
| 3029 | Following is an example that shows how you specify the <code class="filename">DISTRO_PN_ALIAS</code> | ||
| 3030 | variable: | ||
| 3031 | </p><pre class="literallayout"> | ||
| 3032 | DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ | ||
| 3033 | distro2=package_name_alias2 \ | ||
| 3034 | distro3=package_name_alias3 \ | ||
| 3035 | ..." | ||
| 3036 | </pre><p> | ||
| 3037 | </p><p> | ||
| 3038 | If you have more than one distribution alias, separate them with a space. | ||
| 3039 | Note that the build system currently automatically checks the | ||
| 3040 | Fedora, OpenSuSE, Debian, Ubuntu, | ||
| 3041 | and Mandriva distributions for source package recipes without having to specify them | ||
| 3042 | using the <code class="filename">DISTRO_PN_ALIAS</code> variable. | ||
| 3043 | For example, the following command generates a report that lists the Linux distributions | ||
| 3044 | that include the sources for each of the recipes. | ||
| 3045 | </p><pre class="literallayout"> | ||
| 3046 | $ bitbake world -f -c distro_check | ||
| 3047 | </pre><p> | ||
| 3048 | The results are stored in the <code class="filename">build/tmp/log/distro_check-${DATETIME}.results</code> | ||
| 3049 | file found in the source directory. | ||
| 3050 | </p></div><div class="section" title="4.10. Building Software from an External Source"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-software-from-an-external-source"></a>4.10. Building Software from an External Source</h2></div></div></div><p> | ||
| 3051 | By default, the OpenEmbedded build system does its work from within the | ||
| 3052 | <a class="link" href="#build-directory">build directory</a>. | ||
| 3053 | The build process involves fetching the source files, unpacking them, and then patching them | ||
| 3054 | if necessary before the build takes place. | ||
| 3055 | </p><p> | ||
| 3056 | Situations exist where you might want to build software from source files that are external to | ||
| 3057 | and thus outside of the <a class="link" href="#source-directory">source directory</a>. | ||
| 3058 | For example, suppose you have a project that includes a new BSP with a heavily customized | ||
| 3059 | kernel, a very minimal image, and some new user-space recipes. | ||
| 3060 | And, you want to minimize the exposure to the build system to the | ||
| 3061 | development team so that they can focus on their project and maintain everyone's workflow | ||
| 3062 | as much as possible. | ||
| 3063 | In this case, you want a kernel source directory on the development machine where the | ||
| 3064 | development occurs. | ||
| 3065 | You want the recipe's | ||
| 3066 | <a class="link" href="#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> | ||
| 3067 | variable to point to the external directory and use it as is, not copy it. | ||
| 3068 | </p><p> | ||
| 3069 | To build from software that comes from an external source, all you need to do is | ||
| 3070 | change your recipe so that it inherits the | ||
| 3071 | <a class="link" href="#ref-classes-externalsrc" target="_top"><code class="filename">externalsrc.bbclass</code></a> | ||
| 3072 | class and then sets the | ||
| 3073 | <a class="link" href="#var-S" target="_top"><code class="filename">S</code></a> | ||
| 3074 | variable to point to your external source code. | ||
| 3075 | Here are the statements to put in your recipe: | ||
| 3076 | </p><pre class="literallayout"> | ||
| 3077 | inherit externalsrc | ||
| 3078 | S = "/some/path/to/your/package/source" | ||
| 3079 | </pre><p> | ||
| 3080 | </p><p> | ||
| 3081 | It is important to know that the <code class="filename">externalsrc.bbclass</code> assumes that the | ||
| 3082 | source directory <code class="filename">S</code> and the build directory | ||
| 3083 | <a class="link" href="#var-B" target="_top"><code class="filename">B</code></a> | ||
| 3084 | are different even though by default these directories are the same. | ||
| 3085 | This assumption is important because it supports building different variants of the recipe | ||
| 3086 | by using the | ||
| 3087 | <a class="link" href="#var-BBCLASSEXTEND" target="_top"><code class="filename">BBCLASSEXTEND</code></a> | ||
| 3088 | variable. | ||
| 3089 | You could allow the build directory to be the same as the source directory but you would | ||
| 3090 | not be able to build more than one variant of the recipe. | ||
| 3091 | Consequently, if you are building multiple variants of the recipe, you need to establish a | ||
| 3092 | build directory that is different than the source directory. | ||
| 3093 | </p></div><div class="section" title="4.11. Excluding Recipes From the Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="excluding-recipes-from-the-build"></a>4.11. Excluding Recipes From the Build</h2></div></div></div><p> | ||
| 3094 | You might find that there are groups of recipes you want to filter | ||
| 3095 | out of the build process. | ||
| 3096 | For example, recipes you know you will never use or want should not | ||
| 3097 | be part of the build. | ||
| 3098 | Removing these recipes from parsing speeds up parts of the build. | ||
| 3099 | </p><p> | ||
| 3100 | It is possible to filter or mask out <code class="filename">.bb</code> and | ||
| 3101 | <code class="filename">.bbappend</code> files. | ||
| 3102 | You can do this by providing an expression with the | ||
| 3103 | <code class="filename"><a class="link" href="#var-BBMASK" target="_top">BBMASK</a></code> | ||
| 3104 | variable. | ||
| 3105 | Here is an example: | ||
| 3106 | </p><pre class="literallayout"> | ||
| 3107 | BBMASK = ".*/meta-mymachine/recipes-maybe/" | ||
| 3108 | </pre><p> | ||
| 3109 | Here, all <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files | ||
| 3110 | in the directory that match the expression are ignored during the build | ||
| 3111 | process. | ||
| 3112 | </p></div><div class="section" title="4.12. Using an External SCM"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-appdev-srcrev"></a>4.12. Using an External SCM</h2></div></div></div><p> | ||
| 3113 | If you're working on a recipe that pulls from an external Source Code Manager (SCM), it | ||
| 3114 | is possible to have the OpenEmbedded build system notice new changes added to the | ||
| 3115 | SCM and then build the package that depends on them using the latest version. | ||
| 3116 | This only works for SCMs from which it is possible to get a sensible revision number for changes. | ||
| 3117 | Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories. | ||
| 3118 | </p><p> | ||
| 3119 | To enable this behavior, simply add the following to the <code class="filename">local.conf</code> | ||
| 3120 | configuration file found in the | ||
| 3121 | <a class="link" href="#build-directory" target="_top">build directory</a>: | ||
| 3122 | </p><pre class="literallayout"> | ||
| 3123 | SRCREV_pn-<PN> = "${AUTOREV}" | ||
| 3124 | </pre><p> | ||
| 3125 | where <code class="filename">PN</code> | ||
| 3126 | is the name of the package for which you want to enable automatic source | ||
| 3127 | revision updating. | ||
| 3128 | </p></div><div class="section" title="4.13. Debugging With the GNU Project Debugger (GDB) Remotely"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-gdb-remotedebug"></a>4.13. Debugging With the GNU Project Debugger (GDB) Remotely</h2></div></div></div><p> | ||
| 3129 | GDB allows you to examine running programs, which in turn help you to understand and fix problems. | ||
| 3130 | It also allows you to perform post-mortem style analysis of program crashes. | ||
| 3131 | GDB is available as a package within the Yocto Project and by default is | ||
| 3132 | installed in sdk images. | ||
| 3133 | See the "<a class="link" href="#ref-images" target="_top">Images</a>" chapter | ||
| 3134 | in the Yocto Project Reference Manual for a description of these images. | ||
| 3135 | You can find information on GDB at <a class="ulink" href="http://sourceware.org/gdb/" target="_top">http://sourceware.org/gdb/</a>. | ||
| 3136 | </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> | ||
| 3137 | For best results, install <code class="filename">-dbg</code> packages for the applications | ||
| 3138 | you are going to debug. | ||
| 3139 | Doing so makes available extra debug symbols that give you more meaningful output. | ||
| 3140 | </div><p> | ||
| 3141 | Sometimes, due to memory or disk space constraints, it is not possible | ||
| 3142 | to use GDB directly on the remote target to debug applications. | ||
| 3143 | These constraints arise because GDB needs to load the debugging information and the | ||
| 3144 | binaries of the process being debugged. | ||
| 3145 | Additionally, GDB needs to perform many computations to locate information such as function | ||
| 3146 | names, variable names and values, stack traces and so forth - even before starting the | ||
| 3147 | debugging process. | ||
| 3148 | These extra computations place more load on the target system and can alter the | ||
| 3149 | characteristics of the program being debugged. | ||
| 3150 | </p><p> | ||
| 3151 | To help get past the previously mentioned constraints, you can use Gdbserver. | ||
| 3152 | Gdbserver runs on the remote target and does not load any debugging information | ||
| 3153 | from the debugged process. | ||
| 3154 | Instead, a GDB instance processes the debugging information that is run on a | ||
| 3155 | remote computer - the host GDB. | ||
| 3156 | The host GDB then sends control commands to Gdbserver to make it stop or start the debugged | ||
| 3157 | program, as well as read or write memory regions of that debugged program. | ||
| 3158 | All the debugging information loaded and processed as well | ||
| 3159 | as all the heavy debugging is done by the host GDB. | ||
| 3160 | Offloading these processes gives the Gdbserver running on the target a chance to remain | ||
| 3161 | small and fast. | ||
| 3162 | </p><p> | ||
| 3163 | Because the host GDB is responsible for loading the debugging information and | ||
| 3164 | for doing the necessary processing to make actual debugging happen, the | ||
| 3165 | user has to make sure the host can access the unstripped binaries complete | ||
| 3166 | with their debugging information and also be sure the target is compiled with no optimizations. | ||
| 3167 | The host GDB must also have local access to all the libraries used by the | ||
| 3168 | debugged program. | ||
| 3169 | Because Gdbserver does not need any local debugging information, the binaries on | ||
| 3170 | the remote target can remain stripped. | ||
| 3171 | However, the binaries must also be compiled without optimization | ||
| 3172 | so they match the host's binaries. | ||
| 3173 | </p><p> | ||
| 3174 | To remain consistent with GDB documentation and terminology, the binary being debugged | ||
| 3175 | on the remote target machine is referred to as the "inferior" binary. | ||
| 3176 | For documentation on GDB see the | ||
| 3177 | <a class="ulink" href="http://sourceware.org/gdb/documentation/" target="_top">GDB site</a>. | ||
| 3178 | </p><div class="section" title="4.13.1. Launching Gdbserver on the Target"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-gdb-remotedebug-launch-gdbserver"></a>4.13.1. Launching Gdbserver on the Target</h3></div></div></div><p> | ||
| 3179 | First, make sure Gdbserver is installed on the target. | ||
| 3180 | If it is not, install the package <code class="filename">gdbserver</code>, which needs the | ||
| 3181 | <code class="filename">libthread-db1</code> package. | ||
| 3182 | </p><p> | ||
| 3183 | As an example, to launch Gdbserver on the target and make it ready to "debug" a | ||
| 3184 | program located at <code class="filename">/path/to/inferior</code>, connect | ||
| 3185 | to the target and launch: | ||
| 3186 | </p><pre class="literallayout"> | ||
| 3187 | $ gdbserver localhost:2345 /path/to/inferior | ||
| 3188 | </pre><p> | ||
| 3189 | Gdbserver should now be listening on port 2345 for debugging | ||
| 3190 | commands coming from a remote GDB process that is running on the host computer. | ||
| 3191 | Communication between Gdbserver and the host GDB are done using TCP. | ||
| 3192 | To use other communication protocols, please refer to the | ||
| 3193 | <a class="ulink" href="http://www.gnu.org/software/gdb/" target="_top">Gdbserver documentation</a>. | ||
| 3194 | </p></div><div class="section" title="4.13.2. Launching GDB on the Host Computer"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-gdb-remotedebug-launch-gdb"></a>4.13.2. Launching GDB on the Host Computer</h3></div></div></div><p> | ||
| 3195 | Running GDB on the host computer takes a number of stages. | ||
| 3196 | This section describes those stages. | ||
| 3197 | </p><div class="section" title="4.13.2.1. Building the Cross-GDB Package"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-buildcross"></a>4.13.2.1. Building the Cross-GDB Package</h4></div></div></div><p> | ||
| 3198 | A suitable GDB cross-binary is required that runs on your host computer but | ||
| 3199 | also knows about the the ABI of the remote target. | ||
| 3200 | You can get this binary from the meta-toolchain. | ||
| 3201 | Here is an example: | ||
| 3202 | </p><pre class="literallayout"> | ||
| 3203 | /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb | ||
| 3204 | </pre><p> | ||
| 3205 | where <code class="filename">arm</code> is the target architecture and | ||
| 3206 | <code class="filename">linux-gnueabi</code> the target ABI. | ||
| 3207 | </p><p> | ||
| 3208 | Alternatively, you can use BitBake to build the <code class="filename">gdb-cross</code> binary. | ||
| 3209 | Here is an example: | ||
| 3210 | </p><pre class="literallayout"> | ||
| 3211 | $ bitbake gdb-cross | ||
| 3212 | </pre><p> | ||
| 3213 | Once the binary is built, you can find it here: | ||
| 3214 | </p><pre class="literallayout"> | ||
| 3215 | tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb | ||
| 3216 | </pre><p> | ||
| 3217 | </p></div><div class="section" title="4.13.2.2. Making the Inferior Binaries Available"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-inferiorbins"></a>4.13.2.2. Making the Inferior Binaries Available</h4></div></div></div><p> | ||
| 3218 | The inferior binary (complete with all debugging symbols) as well as any | ||
| 3219 | libraries (and their debugging symbols) on which the inferior binary depends | ||
| 3220 | need to be available. | ||
| 3221 | There are a number of ways you can make these available. | ||
| 3222 | </p><p> | ||
| 3223 | Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain | ||
| 3224 | image installed on the device. | ||
| 3225 | In the case of <code class="filename">core-image-sato</code>, | ||
| 3226 | <code class="filename">core-image-sato-sdk</code> would contain suitable symbols. | ||
| 3227 | Because the sdk images already have the debugging symbols installed, it is just a | ||
| 3228 | question of expanding the archive to some location and then informing GDB. | ||
| 3229 | </p><p> | ||
| 3230 | Alternatively, the OpenEmbedded build system can build a custom directory of files | ||
| 3231 | for a specific | ||
| 3232 | debugging purpose by reusing its <code class="filename">tmp/rootfs</code> directory. | ||
| 3233 | This directory contains the contents of the last built image. | ||
| 3234 | This process assumes two things: | ||
| 3235 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The image running on the target was the last image to | ||
| 3236 | be built.</p></li><li class="listitem"><p>The package (<code class="filename">foo</code> in the following | ||
| 3237 | example) that contains the inferior binary to be debugged has been built | ||
| 3238 | without optimization and has debugging information available.</p></li></ul></div><p> | ||
| 3239 | </p><p> | ||
| 3240 | The following steps show how to build the custom directory of files: | ||
| 3241 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install the package (<code class="filename">foo</code> in this case) to | ||
| 3242 | <code class="filename">tmp/rootfs</code>: | ||
| 3243 | </p><pre class="literallayout"> | ||
| 3244 | $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ | ||
| 3245 | tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf -o \ | ||
| 3246 | tmp/rootfs/ update | ||
| 3247 | </pre></li><li class="listitem"><p>Install the debugging information: | ||
| 3248 | </p><pre class="literallayout"> | ||
| 3249 | $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ | ||
| 3250 | tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \ | ||
| 3251 | -o tmp/rootfs install foo | ||
| 3252 | |||
| 3253 | $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ | ||
| 3254 | tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \ | ||
| 3255 | -o tmp/rootfs install foo-dbg | ||
| 3256 | </pre></li></ol></div><p> | ||
| 3257 | </p></div><div class="section" title="4.13.2.3. Launch the Host GDB"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-launchhost"></a>4.13.2.3. Launch the Host GDB</h4></div></div></div><p> | ||
| 3258 | To launch the host GDB, you run the <code class="filename">cross-gdb</code> binary and provide | ||
| 3259 | the inferior binary as part of the command line. | ||
| 3260 | For example, the following command form continues with the example used in | ||
| 3261 | the previous section. | ||
| 3262 | This command form loads the <code class="filename">foo</code> binary | ||
| 3263 | as well as the debugging information: | ||
| 3264 | </p><pre class="literallayout"> | ||
| 3265 | $ <target-abi>-gdb rootfs/usr/bin/foo | ||
| 3266 | </pre><p> | ||
| 3267 | Once the GDB prompt appears, you must instruct GDB to load all the libraries | ||
| 3268 | of the inferior binary from <code class="filename">tmp/rootfs</code> as follows: | ||
| 3269 | </p><pre class="literallayout"> | ||
| 3270 | $ set solib-absolute-prefix /path/to/tmp/rootfs | ||
| 3271 | </pre><p> | ||
| 3272 | The pathname <code class="filename">/path/to/tmp/rootfs</code> must either be | ||
| 3273 | the absolute path to <code class="filename">tmp/rootfs</code> or the location at which | ||
| 3274 | binaries with debugging information reside. | ||
| 3275 | </p><p> | ||
| 3276 | At this point you can have GDB connect to the Gdbserver that is running | ||
| 3277 | on the remote target by using the following command form: | ||
| 3278 | </p><pre class="literallayout"> | ||
| 3279 | $ target remote remote-target-ip-address:2345 | ||
| 3280 | </pre><p> | ||
| 3281 | The <code class="filename">remote-target-ip-address</code> is the IP address of the | ||
| 3282 | remote target where the Gdbserver is running. | ||
| 3283 | Port 2345 is the port on which the GDBSERVER is running. | ||
| 3284 | </p></div><div class="section" title="4.13.2.4. Using the Debugger"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-using"></a>4.13.2.4. Using the Debugger</h4></div></div></div><p> | ||
| 3285 | You can now proceed with debugging as normal - as if you were debugging | ||
| 3286 | on the local machine. | ||
| 3287 | For example, to instruct GDB to break in the "main" function and then | ||
| 3288 | continue with execution of the inferior binary use the following commands | ||
| 3289 | from within GDB: | ||
| 3290 | </p><pre class="literallayout"> | ||
| 3291 | (gdb) break main | ||
| 3292 | (gdb) continue | ||
| 3293 | </pre><p> | ||
| 3294 | </p><p> | ||
| 3295 | For more information about using GDB, see the project's online documentation at | ||
| 3296 | <a class="ulink" href="http://sourceware.org/gdb/download/onlinedocs/" target="_top">http://sourceware.org/gdb/download/onlinedocs/</a>. | ||
| 3297 | </p></div></div></div><div class="section" title="4.14. Profiling with OProfile"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-oprofile"></a>4.14. Profiling with OProfile</h2></div></div></div><p> | ||
| 3298 | <a class="ulink" href="http://oprofile.sourceforge.net/" target="_top">OProfile</a> is a | ||
| 3299 | statistical profiler well suited for finding performance | ||
| 3300 | bottlenecks in both userspace software and in the kernel. | ||
| 3301 | This profiler provides answers to questions like "Which functions does my application spend | ||
| 3302 | the most time in when doing X?" | ||
| 3303 | Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling | ||
| 3304 | applications on target hardware straightforward. | ||
| 3305 | </p><p> | ||
| 3306 | To use OProfile, you need an image that has OProfile installed. | ||
| 3307 | The easiest way to do this is with <code class="filename">tools-profile</code> in the | ||
| 3308 | <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" target="_top">IMAGE_FEATURES</a></code> variable. | ||
| 3309 | You also need debugging symbols to be available on the system where the analysis | ||
| 3310 | takes place. | ||
| 3311 | You can gain access to the symbols by using <code class="filename">dbg-pkgs</code> in the | ||
| 3312 | <code class="filename">IMAGE_FEATURES</code> variable or by | ||
| 3313 | installing the appropriate <code class="filename">-dbg</code> packages. | ||
| 3314 | </p><p> | ||
| 3315 | For successful call graph analysis, the binaries must preserve the frame | ||
| 3316 | pointer register and should also be compiled with the | ||
| 3317 | <code class="filename">-fno-omit-framepointer</code> flag. | ||
| 3318 | You can achieve this by setting the | ||
| 3319 | <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" target="_top">SELECTED_OPTIMIZATION</a></code> | ||
| 3320 | variable to | ||
| 3321 | <code class="filename">-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</code>. | ||
| 3322 | You can also achieve it by setting the | ||
| 3323 | <code class="filename"><a class="link" href="#var-DEBUG_BUILD" target="_top">DEBUG_BUILD</a></code> | ||
| 3324 | variable to "1" in the <code class="filename">local.conf</code> configuration file. | ||
| 3325 | If you use the <code class="filename">DEBUG_BUILD</code> variable you will also add extra debug information | ||
| 3326 | that can make the debug packages large. | ||
| 3327 | </p><div class="section" title="4.14.1. Profiling on the Target"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-oprofile-target"></a>4.14.1. Profiling on the Target</h3></div></div></div><p> | ||
| 3328 | Using OProfile you can perform all the profiling work on the target device. | ||
| 3329 | A simple OProfile session might look like the following: | ||
| 3330 | </p><p> | ||
| 3331 | </p><pre class="literallayout"> | ||
| 3332 | # opcontrol --reset | ||
| 3333 | # opcontrol --start --separate=lib --no-vmlinux -c 5 | ||
| 3334 | . | ||
| 3335 | . | ||
| 3336 | [do whatever is being profiled] | ||
| 3337 | . | ||
| 3338 | . | ||
| 3339 | # opcontrol --stop | ||
| 3340 | $ opreport -cl | ||
| 3341 | </pre><p> | ||
| 3342 | </p><p> | ||
| 3343 | In this example, the <code class="filename">reset</code> command clears any previously profiled data. | ||
| 3344 | The next command starts OProfile. | ||
| 3345 | The options used when starting the profiler separate dynamic library data | ||
| 3346 | within applications, disable kernel profiling, and enable callgraphing up to | ||
| 3347 | five levels deep. | ||
| 3348 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3349 | To profile the kernel, you would specify the | ||
| 3350 | <code class="filename">--vmlinux=/path/to/vmlinux</code> option. | ||
| 3351 | The <code class="filename">vmlinux</code> file is usually in the source directory in the | ||
| 3352 | <code class="filename">/boot/</code> directory and must match the running kernel. | ||
| 3353 | </div><p> | ||
| 3354 | </p><p> | ||
| 3355 | After you perform your profiling tasks, the next command stops the profiler. | ||
| 3356 | After that, you can view results with the <code class="filename">opreport</code> command with options | ||
| 3357 | to see the separate library symbols and callgraph information. | ||
| 3358 | </p><p> | ||
| 3359 | Callgraphing logs information about time spent in functions and about a function's | ||
| 3360 | calling function (parent) and called functions (children). | ||
| 3361 | The higher the callgraphing depth, the more accurate the results. | ||
| 3362 | However, higher depths also increase the logging overhead. | ||
| 3363 | Consequently, you should take care when setting the callgraphing depth. | ||
| 3364 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3365 | On ARM, binaries need to have the frame pointer enabled for callgraphing to work. | ||
| 3366 | To accomplish this use the <code class="filename">-fno-omit-framepointer</code> option | ||
| 3367 | with <code class="filename">gcc</code>. | ||
| 3368 | </div><p> | ||
| 3369 | </p><p> | ||
| 3370 | For more information on using OProfile, see the OProfile | ||
| 3371 | online documentation at | ||
| 3372 | <a class="ulink" href="http://oprofile.sourceforge.net/docs/" target="_top">http://oprofile.sourceforge.net/docs/</a>. | ||
| 3373 | </p></div><div class="section" title="4.14.2. Using OProfileUI"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-oprofile-oprofileui"></a>4.14.2. Using OProfileUI</h3></div></div></div><p> | ||
| 3374 | A graphical user interface for OProfile is also available. | ||
| 3375 | You can download and build this interface from the Yocto Project at | ||
| 3376 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/oprofileui/" target="_top">http://git.yoctoproject.org/cgit.cgi/oprofileui/</a>. | ||
| 3377 | If the "tools-profile" image feature is selected, all necessary binaries | ||
| 3378 | are installed onto the target device for OProfileUI interaction. | ||
| 3379 | </p><p> | ||
| 3380 | Even though the source directory usually includes all needed patches on the target device, you | ||
| 3381 | might find you need other OProfile patches for recent OProfileUI features. | ||
| 3382 | If so, see the <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/oprofileui/tree/README" target="_top"> | ||
| 3383 | OProfileUI README</a> for the most recent information. | ||
| 3384 | </p><div class="section" title="4.14.2.1. Online Mode"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-oprofile-oprofileui-online"></a>4.14.2.1. Online Mode</h4></div></div></div><p> | ||
| 3385 | Using OProfile in online mode assumes a working network connection with the target | ||
| 3386 | hardware. | ||
| 3387 | With this connection, you just need to run "oprofile-server" on the device. | ||
| 3388 | By default, OProfile listens on port 4224. | ||
| 3389 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3390 | You can change the port using the <code class="filename">--port</code> command-line | ||
| 3391 | option. | ||
| 3392 | </div><p> | ||
| 3393 | </p><p> | ||
| 3394 | The client program is called <code class="filename">oprofile-viewer</code> and its UI is relatively | ||
| 3395 | straightforward. | ||
| 3396 | You access key functionality through the buttons on the toolbar, which | ||
| 3397 | are duplicated in the menus. | ||
| 3398 | Here are the buttons: | ||
| 3399 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Connect:</em></span> Connects to the remote host. | ||
| 3400 | You can also supply the IP address or hostname.</p></li><li class="listitem"><p><span class="emphasis"><em>Disconnect:</em></span> Disconnects from the target. | ||
| 3401 | </p></li><li class="listitem"><p><span class="emphasis"><em>Start:</em></span> Starts profiling on the device. | ||
| 3402 | </p></li><li class="listitem"><p><span class="emphasis"><em>Stop:</em></span> Stops profiling on the device and | ||
| 3403 | downloads the data to the local host. | ||
| 3404 | Stopping the profiler generates the profile and displays it in the viewer. | ||
| 3405 | </p></li><li class="listitem"><p><span class="emphasis"><em>Download:</em></span> Downloads the data from the | ||
| 3406 | target and generates the profile, which appears in the viewer.</p></li><li class="listitem"><p><span class="emphasis"><em>Reset:</em></span> Resets the sample data on the device. | ||
| 3407 | Resetting the data removes sample information collected from previous | ||
| 3408 | sampling runs. | ||
| 3409 | Be sure you reset the data if you do not want to include old sample information. | ||
| 3410 | </p></li><li class="listitem"><p><span class="emphasis"><em>Save:</em></span> Saves the data downloaded from the | ||
| 3411 | target to another directory for later examination.</p></li><li class="listitem"><p><span class="emphasis"><em>Open:</em></span> Loads previously saved data. | ||
| 3412 | </p></li></ul></div><p> | ||
| 3413 | </p><p> | ||
| 3414 | The client downloads the complete 'profile archive' from | ||
| 3415 | the target to the host for processing. | ||
| 3416 | This archive is a directory that contains the sample data, the object files, | ||
| 3417 | and the debug information for the object files. | ||
| 3418 | The archive is then converted using the <code class="filename">oparchconv</code> script, which is | ||
| 3419 | included in this distribution. | ||
| 3420 | The script uses <code class="filename">opimport</code> to convert the archive from | ||
| 3421 | the target to something that can be processed on the host. | ||
| 3422 | </p><p> | ||
| 3423 | Downloaded archives reside in the build directory in | ||
| 3424 | <code class="filename">/tmp</code> and are cleared up when they are no longer in use. | ||
| 3425 | </p><p> | ||
| 3426 | If you wish to perform kernel profiling, you need to be sure | ||
| 3427 | a <code class="filename">vmlinux</code> file that matches the running kernel is available. | ||
| 3428 | In the source directory, that file is usually located in | ||
| 3429 | <code class="filename">/boot/vmlinux-KERNELVERSION</code>, where | ||
| 3430 | <code class="filename">KERNEL-version</code> is the version of the kernel. | ||
| 3431 | The OpenEmbedded build system generates separate <code class="filename">vmlinux</code> | ||
| 3432 | packages for each kernel it builds. | ||
| 3433 | Thus, it should just be a question of making sure a matching package is | ||
| 3434 | installed (e.g. <code class="filename">opkg install kernel-vmlinux</code>. | ||
| 3435 | The files are automatically installed into development and profiling images | ||
| 3436 | alongside OProfile. | ||
| 3437 | A configuration option exists within the OProfileUI settings page that you can use to | ||
| 3438 | enter the location of the <code class="filename">vmlinux</code> file. | ||
| 3439 | </p><p> | ||
| 3440 | Waiting for debug symbols to transfer from the device can be slow, and it | ||
| 3441 | is not always necessary to actually have them on the device for OProfile use. | ||
| 3442 | All that is needed is a copy of the filesystem with the debug symbols present | ||
| 3443 | on the viewer system. | ||
| 3444 | The "<a class="link" href="#platdev-gdb-remotedebug-launch-gdb" title="4.13.2. Launching GDB on the Host Computer">Launching GDB on the Host Computer</a>" | ||
| 3445 | section covers how to create such a directory with | ||
| 3446 | the source directory and how to use the OProfileUI Settings dialog to specify the location. | ||
| 3447 | If you specify the directory, it will be used when the file checksums | ||
| 3448 | match those on the system you are profiling. | ||
| 3449 | </p></div><div class="section" title="4.14.2.2. Offline Mode"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-oprofile-oprofileui-offline"></a>4.14.2.2. Offline Mode</h4></div></div></div><p> | ||
| 3450 | If network access to the target is unavailable, you can generate | ||
| 3451 | an archive for processing in <code class="filename">oprofile-viewer</code> as follows: | ||
| 3452 | </p><pre class="literallayout"> | ||
| 3453 | # opcontrol --reset | ||
| 3454 | # opcontrol --start --separate=lib --no-vmlinux -c 5 | ||
| 3455 | . | ||
| 3456 | . | ||
| 3457 | [do whatever is being profiled] | ||
| 3458 | . | ||
| 3459 | . | ||
| 3460 | # opcontrol --stop | ||
| 3461 | # oparchive -o my_archive | ||
| 3462 | </pre><p> | ||
| 3463 | </p><p> | ||
| 3464 | In the above example, <code class="filename">my_archive</code> is the name of the | ||
| 3465 | archive directory where you would like the profile archive to be kept. | ||
| 3466 | After the directory is created, you can copy it to another host and load it | ||
| 3467 | using <code class="filename">oprofile-viewer</code> open functionality. | ||
| 3468 | If necessary, the archive is converted. | ||
| 3469 | </p></div></div></div></div> | ||
| 3470 | |||
| 3471 | <div class="chapter" title="Chapter 5. Common Development Models"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-model"></a>Chapter 5. Common Development Models</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#system-development-model">5.1. System Development Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#developing-a-board-support-package-bsp">5.1.1. Developing a Board Support Package (BSP)</a></span></dt><dt><span class="section"><a href="#modifying-the-kernel">5.1.2. Modifying the Kernel</a></span></dt></dl></dd><dt><span class="section"><a href="#application-development-workflow">5.2. Application Development Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#workflow-using-the-adt-and-eclipse">5.2.1. Workflow Using the ADT and <span class="trademark">Eclipse</span>™</a></span></dt><dt><span class="section"><a href="#adt-eclipse">5.2.2. Working Within Eclipse</a></span></dt><dt><span class="section"><a href="#workflow-using-stand-alone-cross-development-toolchains">5.2.3. Workflow Using Stand-alone Cross-development Toolchains</a></span></dt></dl></dd><dt><span class="section"><a href="#modifying-temporary-source-code">5.3. Modifying Temporary Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#finding-the-temporary-source-code">5.3.1. Finding the Temporary Source Code</a></span></dt><dt><span class="section"><a href="#using-a-quilt-workflow">5.3.2. Using a Quilt Workflow</a></span></dt><dt><span class="section"><a href="#using-a-git-workflow">5.3.3. Using a Git Workflow</a></span></dt></dl></dd><dt><span class="section"><a href="#image-development-using-hob">5.4. Image Development Using Hob</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">5.5. Using a Development Shell</a></span></dt></dl></div><p> | ||
| 3472 | Many development models exist for which you can use the Yocto Project. | ||
| 3473 | This chapter overviews the following methods: | ||
| 3474 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>System Development:</em></span> | ||
| 3475 | System Development covers Board Support Package (BSP) development and kernel | ||
| 3476 | modification or configuration. | ||
| 3477 | If you want to examine specific examples of the system development models, | ||
| 3478 | see the "<a class="link" href="#dev-manual-bsp-appendix" title="Appendix A. BSP Development Example">BSP Development Example</a>" | ||
| 3479 | appendix and the | ||
| 3480 | "<a class="link" href="#dev-manual-kernel-appendix" title="Appendix B. Kernel Modification Example">Kernel Modification Example</a>" appendix. | ||
| 3481 | </p></li><li class="listitem"><p><span class="emphasis"><em>User Application Development:</em></span> | ||
| 3482 | User Application Development covers development of applications that you intend | ||
| 3483 | to run on some target hardware. | ||
| 3484 | For a user-space application development example that uses the | ||
| 3485 | <span class="trademark">Eclipse</span>™ IDE, | ||
| 3486 | see the | ||
| 3487 | Yocto Project Application Developer's Guide. | ||
| 3488 | </p></li><li class="listitem"><p><span class="emphasis"><em>Temporary Source Code Modification:</em></span> | ||
| 3489 | Direct modification of temporary source code is a convenient development model | ||
| 3490 | to quickly iterate and develop towards a solution. | ||
| 3491 | Once the solution has been implemented, you should of course take steps to | ||
| 3492 | get the changes upstream and applied in the affected recipes.</p></li><li class="listitem"><p><span class="emphasis"><em>Image Development using Hob:</em></span> | ||
| 3493 | You can use the <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> to build | ||
| 3494 | custom operating system images within the build environment. | ||
| 3495 | Hob provides an efficient interface to the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em>Using a Development Shell:</em></span> | ||
| 3496 | You can use a <code class="filename">devshell</code> to efficiently debug commands or simply | ||
| 3497 | edit packages. | ||
| 3498 | Working inside a development shell is a quick way to set up the OpenEmbedded build | ||
| 3499 | environment to work on parts of a project.</p></li></ul></div><p> | ||
| 3500 | </p><div class="section" title="5.1. System Development Workflow"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="system-development-model"></a>5.1. System Development Workflow</h2></div></div></div><p> | ||
| 3501 | System development involves modification or creation of an image that you want to run on | ||
| 3502 | a specific hardware target. | ||
| 3503 | Usually, when you want to create an image that runs on embedded hardware, the image does | ||
| 3504 | not require the same number of features that a full-fledged Linux distribution provides. | ||
| 3505 | Thus, you can create a much smaller image that is designed to use only the hardware | ||
| 3506 | features for your particular hardware. | ||
| 3507 | </p><p> | ||
| 3508 | To help you understand how system development works in the Yocto Project, this section | ||
| 3509 | covers two types of image development: BSP creation and kernel modification or | ||
| 3510 | configuration. | ||
| 3511 | </p><div class="section" title="5.1.1. Developing a Board Support Package (BSP)"><div class="titlepage"><div><div><h3 class="title"><a id="developing-a-board-support-package-bsp"></a>5.1.1. Developing a Board Support Package (BSP)</h3></div></div></div><p> | ||
| 3512 | A BSP is a packageof recipes that, when applied, during a build results in | ||
| 3513 | an image that you can run on a particular board. | ||
| 3514 | Thus, the package, when compiled into the new image, supports the operation of the board. | ||
| 3515 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3516 | For a brief list of terms used when describing the development process in the Yocto Project, | ||
| 3517 | see the "<a class="link" href="#yocto-project-terms" title="3.4. Yocto Project Terms">Yocto Project Terms</a>" section. | ||
| 3518 | </div><p> | ||
| 3519 | The remainder of this section presents the basic steps used to create a BSP | ||
| 3520 | based on an existing BSP that ships with the Yocto Project. | ||
| 3521 | You can reference the "<a class="link" href="#dev-manual-bsp-appendix" title="Appendix A. BSP Development Example">BSP Development Example</a>" | ||
| 3522 | appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start. | ||
| 3523 | </p><p> | ||
| 3524 | The following illustration and list summarize the BSP creation general workflow. | ||
| 3525 | </p><p> | ||
| 3526 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/bsp-dev-flow.png" align="middle" width="540" /></td></tr></table><p> | ||
| 3527 | </p><p> | ||
| 3528 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Set up your host development system to support | ||
| 3529 | development using the Yocto Project</em></span>: See the | ||
| 3530 | "<a class="link" href="#the-linux-distro" target="_top">The Linux Distributions</a>" | ||
| 3531 | and the | ||
| 3532 | "<a class="link" href="#packages" target="_top">The Packages</a>" sections both | ||
| 3533 | in the Yocto Project Quick Start for requirements.</p></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of the project files on your | ||
| 3534 | system</em></span>: You need this <a class="link" href="#source-directory">source | ||
| 3535 | directory</a> available on your host system. | ||
| 3536 | Having these files on your system gives you access to the build | ||
| 3537 | process and to the tools you need. | ||
| 3538 | For information on how to set up the source directory, see the | ||
| 3539 | "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Setup</a>" section.</p></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of the base BSP files</em></span>: Having | ||
| 3540 | the BSP files on your system gives you access to the build | ||
| 3541 | process and to the tools you need for creating a BSP. | ||
| 3542 | For information on how to get these files, see the | ||
| 3543 | "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Setup</a>" section.</p></li><li class="listitem"><p><span class="emphasis"><em>Choose a BSP that is supported by the Yocto Project | ||
| 3544 | as your base BSP</em></span>: | ||
| 3545 | The Yocto Project ships with several BSPs that support various hardware. | ||
| 3546 | It is best to base your new BSP on an existing BSP rather than create all the | ||
| 3547 | recipes and configuration files from scratch. | ||
| 3548 | While it is possible to create everything from scratch, basing your new BSP | ||
| 3549 | on something that is close is much easier. | ||
| 3550 | Or, at a minimum, leveraging off an existing BSP | ||
| 3551 | gives you some structure with which to start.</p><p>At this point you need to understand your target hardware well enough to determine which | ||
| 3552 | existing BSP it most closely matches. | ||
| 3553 | Things to consider are your hardware’s on-board features, such as CPU type and graphics support. | ||
| 3554 | You should look at the README files for supported BSPs to get an idea of which one | ||
| 3555 | you could use. | ||
| 3556 | A generic <span class="trademark">Intel</span>® | ||
| 3557 | <span class="trademark">Atom</span>™-based BSP to consider is the | ||
| 3558 | Crown Bay that does not support the <span class="trademark">Intel</span>® | ||
| 3559 | Embedded Media Graphics Driver (EMGD). | ||
| 3560 | The remainder of this example uses that base BSP.</p><p>To see the supported BSPs, go to the | ||
| 3561 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Download</a> page on the Yocto Project | ||
| 3562 | website and click on “BSP Downloads.”</p></li><li class="listitem"><p><span class="emphasis"><em>Create your own BSP layer</em></span>: Layers are ideal for | ||
| 3563 | isolating and storing work for a given piece of hardware. | ||
| 3564 | A layer is really just a location or area in which you place the recipes for your BSP. | ||
| 3565 | In fact, a BSP is, in itself, a special type of layer. | ||
| 3566 | </p><p> | ||
| 3567 | Another example that illustrates a layer is an application. | ||
| 3568 | Suppose you are creating an application that has library or other dependencies in | ||
| 3569 | order for it to compile and run. | ||
| 3570 | The layer, in this case, would be where all the recipes that define those dependencies | ||
| 3571 | are kept. | ||
| 3572 | The key point for a layer is that it is an isolated area that contains | ||
| 3573 | all the relevant information for the project that the OpenEmbedded build | ||
| 3574 | system knows about. | ||
| 3575 | For more information on layers, see the | ||
| 3576 | "<a class="link" href="#understanding-and-creating-layers" title="4.1. Understanding and Creating Layers">Understanding and Creating Layers</a>" | ||
| 3577 | section. | ||
| 3578 | For more information on BSP layers, see the | ||
| 3579 | "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" section in the | ||
| 3580 | Yocto Project Board Support Package (BSP) Developer's Guide.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Four BSPs exist that are part of the | ||
| 3581 | Yocto Project release: <code class="filename">atom-pc</code>, <code class="filename">beagleboard</code>, | ||
| 3582 | <code class="filename">mpc8315e</code>, and <code class="filename">routerstationpro</code>. | ||
| 3583 | The recipes and configurations for these four BSPs are located and dispersed | ||
| 3584 | within the <a class="link" href="#source-directory">source directory</a>. | ||
| 3585 | On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, | ||
| 3586 | N450, Cedar Trail, Fish River, Fish River Island II, Romley, sys940x, tlk, | ||
| 3587 | and Sugar Bay exist in their own separate layers within the larger | ||
| 3588 | <code class="filename">meta-intel</code> layer.</div><p>When you set up a layer for a new BSP, you should follow a standard layout. | ||
| 3589 | This layout is described in the section | ||
| 3590 | "<a class="link" href="#bsp-filelayout" target="_top">Example Filesystem Layout</a>" | ||
| 3591 | section of the Board Support Package (BSP) Development Guide. | ||
| 3592 | In the standard layout, you will notice a suggested structure for recipes and | ||
| 3593 | configuration information. | ||
| 3594 | You can see the standard layout for the Crown Bay BSP in this example by examining the | ||
| 3595 | directory structure of the <code class="filename">meta-crownbay</code> layer inside the | ||
| 3596 | source directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Make configuration changes to your new BSP | ||
| 3597 | layer</em></span>: The standard BSP layer structure organizes the files you need | ||
| 3598 | to edit in <code class="filename">conf</code> and several <code class="filename">recipes-*</code> | ||
| 3599 | directories within the BSP layer. | ||
| 3600 | Configuration changes identify where your new layer is on the local system | ||
| 3601 | and identify which kernel you are going to use. | ||
| 3602 | </p></li><li class="listitem"><p><span class="emphasis"><em>Make recipe changes to your new BSP layer</em></span>: Recipe | ||
| 3603 | changes include altering recipes (<code class="filename">.bb</code> files), removing | ||
| 3604 | recipes you don't use, and adding new recipes that you need to support your hardware. | ||
| 3605 | </p></li><li class="listitem"><p><span class="emphasis"><em>Prepare for the build</em></span>: Once you have made all the | ||
| 3606 | changes to your BSP layer, there remains a few things | ||
| 3607 | you need to do for the OpenEmbedded build system in order for it to create your image. | ||
| 3608 | You need to get the build environment ready by sourcing an environment setup script | ||
| 3609 | and you need to be sure two key configuration files are configured appropriately.</p><p>The entire process for building an image is overviewed in the section | ||
| 3610 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" section | ||
| 3611 | of the Yocto Project Quick Start. | ||
| 3612 | You might want to reference this information.</p></li><li class="listitem"><p><span class="emphasis"><em>Build the image</em></span>: The OpenEmbedded build system | ||
| 3613 | uses the BitBake tool to build images based on the type of image you want to create. | ||
| 3614 | You can find more information on BitBake | ||
| 3615 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">here</a>.</p><p>The build process supports several types of images to satisfy different needs. | ||
| 3616 | See the | ||
| 3617 | "<a class="link" href="#ref-images" target="_top">Images</a>" chapter | ||
| 3618 | in the Yocto Project Reference Manual for information on | ||
| 3619 | supported images.</p></li></ol></div><p> | ||
| 3620 | </p><p> | ||
| 3621 | You can view a video presentation on "Building Custom Embedded Images with Yocto" | ||
| 3622 | at <a class="ulink" href="http://free-electrons.com/blog/elc-2011-videos" target="_top">Free Electrons</a>. | ||
| 3623 | You can also find supplemental information in | ||
| 3624 | <a class="ulink" href="http://www.yoctoproject.org/docs/1.3/bsp-guide/bsp-guide.html" target="_top"> | ||
| 3625 | The Board Support Package (BSP) Development Guide</a>. | ||
| 3626 | Finally, there is wiki page write up of the example also located | ||
| 3627 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another" target="_top"> | ||
| 3628 | here</a> that you might find helpful. | ||
| 3629 | </p></div><div class="section" title="5.1.2. Modifying the Kernel"><div class="titlepage"><div><div><h3 class="title"><a id="modifying-the-kernel"></a>5.1.2. <a id="kernel-spot"></a>Modifying the Kernel</h3></div></div></div><p> | ||
| 3630 | Kernel modification involves changing the Yocto Project kernel, which could involve changing | ||
| 3631 | configuration options as well as adding new kernel recipes. | ||
| 3632 | Configuration changes can be added in the form of configuration fragments, while recipe | ||
| 3633 | modification comes through the kernel's <code class="filename">recipes-kernel</code> area | ||
| 3634 | in a kernel layer you create. | ||
| 3635 | </p><p> | ||
| 3636 | The remainder of this section presents a high-level overview of the Yocto Project | ||
| 3637 | kernel architecture and the steps to modify the kernel. | ||
| 3638 | For a complete discussion of the kernel, see the | ||
| 3639 | Yocto Project Kernel Architecture and Use Manual. | ||
| 3640 | You can reference the appendix | ||
| 3641 | "<a class="link" href="#dev-manual-kernel-appendix" title="Appendix B. Kernel Modification Example">Kernel Modification Example</a>" | ||
| 3642 | for a detailed example that changes the configuration of a kernel. | ||
| 3643 | </p><div class="section" title="5.1.2.1. Kernel Overview"><div class="titlepage"><div><div><h4 class="title"><a id="kernel-overview"></a>5.1.2.1. Kernel Overview</h4></div></div></div><p> | ||
| 3644 | Traditionally, when one thinks of a patched kernel, they think of a base kernel | ||
| 3645 | source tree and a fixed structure that contains kernel patches. | ||
| 3646 | The Yocto Project, however, employs mechanisms, that in a sense, result in a kernel source | ||
| 3647 | generator. | ||
| 3648 | By the end of this section, this analogy will become clearer. | ||
| 3649 | </p><p> | ||
| 3650 | You can find a web interface to the Yocto Project kernel source repositories at | ||
| 3651 | <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>. | ||
| 3652 | If you look at the interface, you will see to the left a grouping of | ||
| 3653 | Git repositories titled "Yocto Linux Kernel." | ||
| 3654 | Within this group, you will find several kernels supported by | ||
| 3655 | the Yocto Project: | ||
| 3656 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-2.6.34</code></em></span> - The | ||
| 3657 | stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-2.6.37</code></em></span> - The | ||
| 3658 | stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-3.0</code></em></span> - The stable | ||
| 3659 | Yocto Project kernel that is based on the Linux 3.0 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-3.0-1.1.x</code></em></span> - The | ||
| 3660 | stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel | ||
| 3661 | is based on the Linux 3.0 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-3.2</code></em></span> - The | ||
| 3662 | stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel | ||
| 3663 | is based on the Linux 3.2 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-dev</code></em></span> - A development | ||
| 3664 | kernel based on the latest upstream release candidate available.</p></li></ul></div><p> | ||
| 3665 | </p><p> | ||
| 3666 | The kernels are maintained using the Git revision control system | ||
| 3667 | that structures them using the familiar "tree", "branch", and "leaf" scheme. | ||
| 3668 | Branches represent diversions from general code to more specific code, while leaves | ||
| 3669 | represent the end-points for a complete and unique kernel whose source files | ||
| 3670 | when gathered from the root of the tree to the leaf accumulate to create the files | ||
| 3671 | necessary for a specific piece of hardware and its features. | ||
| 3672 | The following figure displays this concept: | ||
| 3673 | </p><p> | ||
| 3674 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 540px"><td align="center"><img src="figures/kernel-overview-1.png" align="middle" /></td></tr></table><p> | ||
| 3675 | </p><p> | ||
| 3676 | |||
| 3677 | </p><p> | ||
| 3678 | Within the figure, the "Kernel.org Branch Point" represents the point in the tree | ||
| 3679 | where a supported base kernel is modified from the Linux kernel. | ||
| 3680 | For example, this could be the branch point for the <code class="filename">linux-yocto-3.0</code> | ||
| 3681 | kernel. | ||
| 3682 | Thus, everything further to the right in the structure is based on the | ||
| 3683 | <code class="filename">linux-yocto-3.0</code> kernel. | ||
| 3684 | Branch points to right in the figure represent where the | ||
| 3685 | <code class="filename">linux-yocto-3.0</code> kernel is modified for specific hardware | ||
| 3686 | or types of kernels, such as real-time kernels. | ||
| 3687 | Each leaf thus represents the end-point for a kernel designed to run on a specific | ||
| 3688 | targeted device. | ||
| 3689 | </p><p> | ||
| 3690 | |||
| 3691 | </p><p> | ||
| 3692 | The overall result is a Git-maintained repository from which all the supported | ||
| 3693 | kernel types can be derived for all the supported devices. | ||
| 3694 | A big advantage to this scheme is the sharing of common features by keeping them in | ||
| 3695 | "larger" branches within the tree. | ||
| 3696 | This practice eliminates redundant storage of similar features shared among kernels. | ||
| 3697 | </p><p> | ||
| 3698 | |||
| 3699 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3700 | Keep in mind the figure does not take into account all the supported Yocto | ||
| 3701 | Project kernel types, but rather shows a single generic kernel just for conceptual purposes. | ||
| 3702 | Also keep in mind that this structure represents the Yocto Project source repositories | ||
| 3703 | that are either pulled from during the build or established on the host development system | ||
| 3704 | prior to the build by either cloning a particular kernel's Git repository or by | ||
| 3705 | downloading and unpacking a tarball. | ||
| 3706 | </div><p> | ||
| 3707 | |||
| 3708 | </p><p> | ||
| 3709 | Storage of all the available kernel source code is one thing, while representing the | ||
| 3710 | code on your host development system is another. | ||
| 3711 | Conceptually, you can think of the kernel source repositories as all the | ||
| 3712 | source files necessary for all the supported kernels. | ||
| 3713 | As a developer, you are just interested in the source files for the kernel on | ||
| 3714 | on which you are working. | ||
| 3715 | And, furthermore, you need them available on your host system. | ||
| 3716 | </p><p> | ||
| 3717 | |||
| 3718 | </p><p> | ||
| 3719 | You make kernel source code available on your host development system by using | ||
| 3720 | Git to create a bare clone of the Yocto Project kernel Git repository | ||
| 3721 | in which you are interested. | ||
| 3722 | Then, you use Git again to clone a copy of that bare clone. | ||
| 3723 | This copy represents the directory structure on your host system that is particular | ||
| 3724 | to the kernel you want. | ||
| 3725 | These are the files you actually modify to change the kernel. | ||
| 3726 | See the <a class="link" href="#local-kernel-files">Yocto Project Kernel</a> item earlier | ||
| 3727 | in this manual for an example of how to set up the kernel source directory | ||
| 3728 | structure on your host system. | ||
| 3729 | </p><p> | ||
| 3730 | |||
| 3731 | </p><p> | ||
| 3732 | This next figure illustrates how the kernel source files might be arranged on | ||
| 3733 | your host system. | ||
| 3734 | </p><p> | ||
| 3735 | |||
| 3736 | </p><p> | ||
| 3737 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/kernel-overview-3-denzil.png" align="middle" /></td></tr></table><p> | ||
| 3738 | </p><p> | ||
| 3739 | |||
| 3740 | </p><p> | ||
| 3741 | In the previous figure, the file structure on the left represents the bare clone | ||
| 3742 | set up to track the Yocto Project kernel Git repository. | ||
| 3743 | The structure on the right represents the copy of the bare clone. | ||
| 3744 | When you make modifcations to the kernel source code, this is the area in which | ||
| 3745 | you work. | ||
| 3746 | Once you make corrections, you must use Git to push the committed changes to the | ||
| 3747 | bare clone. | ||
| 3748 | The example in <a class="xref" href="#modifying-the-kernel-source-code" title="B.1. Modifying the Kernel Source Code">Section B.1, “Modifying the Kernel Source Code”</a> provides a detailed example. | ||
| 3749 | </p><p> | ||
| 3750 | |||
| 3751 | </p><p> | ||
| 3752 | What happens during the build? | ||
| 3753 | When you build the kernel on your development system all files needed for the build | ||
| 3754 | are taken from the source repositories pointed to by the | ||
| 3755 | <code class="filename">SRC_URI</code> variable and gathered in a temporary work area | ||
| 3756 | where they are subsequently used to create the unique kernel. | ||
| 3757 | Thus, in a sense, the process constructs a local source tree specific to your | ||
| 3758 | kernel to generate the new kernel image - a source generator if you will. | ||
| 3759 | </p><p> | ||
| 3760 | The following figure shows the temporary file structure | ||
| 3761 | created on your host system when the build occurs. | ||
| 3762 | This build directory contains all the source files used during the build. | ||
| 3763 | </p><p> | ||
| 3764 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 450px"><td align="center"><img src="figures/kernel-overview-2.png" align="middle" /></td></tr></table><p> | ||
| 3765 | </p><p> | ||
| 3766 | Again, for a complete discussion of the Yocto Project kernel's architecture and its | ||
| 3767 | branching strategy, see the | ||
| 3768 | Yocto Project Kernel Architecture and Use Manual. | ||
| 3769 | You can also reference the | ||
| 3770 | "<a class="link" href="#modifying-the-kernel-source-code" title="B.1. Modifying the Kernel Source Code">Modifying the Kernel Source Code</a>" | ||
| 3771 | section for a detailed example that modifies the kernel. | ||
| 3772 | </p></div><div class="section" title="5.1.2.2. Kernel Modification Workflow"><div class="titlepage"><div><div><h4 class="title"><a id="kernel-modification-workflow"></a>5.1.2.2. Kernel Modification Workflow</h4></div></div></div><p> | ||
| 3773 | This illustration and the following list summarizes the kernel modification general workflow. | ||
| 3774 | </p><p> | ||
| 3775 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 675px"><td align="center"><img src="figures/kernel-dev-flow.png" align="middle" width="540" /></td></tr></table><p> | ||
| 3776 | </p><p> | ||
| 3777 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Set up your host development system to support | ||
| 3778 | development using the Yocto Project</em></span>: See | ||
| 3779 | "<a class="link" href="#the-linux-distro" target="_top">The Linux Distributions</a>" and | ||
| 3780 | "<a class="link" href="#packages" target="_top">The Packages</a>" sections both | ||
| 3781 | in the Yocto Project Quick Start for requirements.</p></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of project files on your | ||
| 3782 | system</em></span>: Having the <a class="link" href="#source-directory">source | ||
| 3783 | directory</a> on your system gives you access to the build process and tools | ||
| 3784 | you need. | ||
| 3785 | For information on how to get these files, see the bulleted item | ||
| 3786 | "<a class="link" href="#local-yp-release">Yocto Project Release</a>" earlier in this manual. | ||
| 3787 | </p></li><li class="listitem"><p><span class="emphasis"><em>Set up a local copy of the <code class="filename">poky-extras</code> Git | ||
| 3788 | repository</em></span>: This local repository is the area for your configuration | ||
| 3789 | fragments, new kernel recipes, and the kernel <code class="filename">.bbappend</code> | ||
| 3790 | file used during the build. | ||
| 3791 | It is good practice to set this repository up inside your local | ||
| 3792 | source directory. | ||
| 3793 | For information on how to get these files, see the bulleted item | ||
| 3794 | "<a class="link" href="#poky-extras-repo">The <code class="filename">poky-extras</code> Git Repository</a>" | ||
| 3795 | earlier in this manual. | ||
| 3796 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>While it is certainly possible to modify the kernel without involving | ||
| 3797 | a local Git repository, the suggested workflow for kernel modification | ||
| 3798 | using the Yocto Project does use a Git repository.</div></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of the Yocto Project kernel files on your | ||
| 3799 | system</em></span>: In order to make modifications to the kernel you need two things: | ||
| 3800 | a bare clone of the Yocto Project kernel you are modifying and | ||
| 3801 | a copy of that bare clone. | ||
| 3802 | The bare clone is required by the build process and is the area to which you | ||
| 3803 | push your kernel source changes (pulling does not work with bare clones). | ||
| 3804 | The copy of the bare clone is a local Git repository that contains all the kernel's | ||
| 3805 | source files. | ||
| 3806 | You make your changes to the files in this copy of the bare clone. | ||
| 3807 | For information on how to set these two items up, see the bulleted item | ||
| 3808 | "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" | ||
| 3809 | earlier in this manual.</p></li><li class="listitem"><p><span class="emphasis"><em>Make changes to the kernel source code if | ||
| 3810 | applicable</em></span>: Modifying the kernel does not always mean directly | ||
| 3811 | changing source files. | ||
| 3812 | However, if you have to do this, you make the changes in the local | ||
| 3813 | Git repository you set up to hold the source files (i.e. the copy of the | ||
| 3814 | bare clone). | ||
| 3815 | Once the changes are made, you need to use Git commands to commit the changes | ||
| 3816 | and then push them to the bare clone.</p></li><li class="listitem"><p><span class="emphasis"><em>Make kernel configuration changes | ||
| 3817 | if applicable</em></span>: | ||
| 3818 | If your situation calls for changing the kernel's configuration, you can | ||
| 3819 | use <code class="filename">menuconfig</code> | ||
| 3820 | to enable and disable kernel configurations. | ||
| 3821 | Using <code class="filename">menuconfig</code> allows you to interactively develop and test the | ||
| 3822 | configuration changes you are making to the kernel. | ||
| 3823 | When saved, changes using <code class="filename">menuconfig</code> update the kernel's | ||
| 3824 | <code class="filename">.config</code>. | ||
| 3825 | Try to resist the temptation of directly editing the <code class="filename">.config</code> | ||
| 3826 | file found in the | ||
| 3827 | <a class="link" href="#build-directory">build directory</a> at | ||
| 3828 | <code class="filename">tmp/sysroots/<machine-name>/kernel</code>. | ||
| 3829 | Doing so, can produce unexpected results when the OpenEmbedded build system | ||
| 3830 | regenerates the configuration file.</p><p>Once you are satisfied with the configuration changes made using | ||
| 3831 | <code class="filename">menuconfig</code>, you can directly examine the | ||
| 3832 | <code class="filename">.config</code> file against a saved original and gather those | ||
| 3833 | changes into a config fragment to be referenced from within the kernel's | ||
| 3834 | <code class="filename">.bbappend</code> file.</p></li><li class="listitem"><p><span class="emphasis"><em>Add or extend kernel recipes if applicable</em></span>: | ||
| 3835 | The standard | ||
| 3836 | layer structure organizes recipe files inside the | ||
| 3837 | <code class="filename">meta-kernel-dev</code> layer that is within the local | ||
| 3838 | <code class="filename">poky-extras</code> Git repository. | ||
| 3839 | If you need to add new kernel recipes, you add them within this layer. | ||
| 3840 | Also within this area, you will find the <code class="filename">.bbappend</code> | ||
| 3841 | file that appends information to the kernel's recipe file used during the | ||
| 3842 | build. | ||
| 3843 | </p></li><li class="listitem"><p><span class="emphasis"><em>Prepare for the build</em></span>: Once you have made all the | ||
| 3844 | changes to your kernel (configurations, source code changes, recipe additions, | ||
| 3845 | or recipe changes), there remains a few things | ||
| 3846 | you need to do in order for the build system to create your image. | ||
| 3847 | If you have not done so, you need to get the build environment ready by sourcing | ||
| 3848 | the environment setup script described earlier. | ||
| 3849 | You also need to be sure two key configuration files | ||
| 3850 | (<code class="filename">local.conf</code> and <code class="filename">bblayers.conf</code>) | ||
| 3851 | are configured appropriately.</p><p>The entire process for building an image is overviewed in the | ||
| 3852 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" | ||
| 3853 | section of the Yocto Project Quick Start. | ||
| 3854 | You might want to reference this information. | ||
| 3855 | Also, you should look at the detailed examples found in the appendices at | ||
| 3856 | at the end of this manual.</p></li><li class="listitem"><p><span class="emphasis"><em>Build the image</em></span>: The OpenEmbedded | ||
| 3857 | build system uses the BitBake | ||
| 3858 | tool to build images based on the type of image you want to create. | ||
| 3859 | You can find more information on BitBake | ||
| 3860 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">here</a>.</p><p>The build process supports several types of images to satisfy different needs. | ||
| 3861 | See the "<a class="link" href="#ref-images" target="_top">Images</a>" chapter in | ||
| 3862 | the Yocto Project Reference Manual for information on supported images.</p></li><li class="listitem"><p><span class="emphasis"><em>Make your configuration changes available | ||
| 3863 | in the kernel layer</em></span>: Up to this point, all the configuration changes to the | ||
| 3864 | kernel have been done and tested iteratively. | ||
| 3865 | Once they are tested and ready to go, you can move them into the kernel layer, | ||
| 3866 | which allows you to distribute the layer.</p></li><li class="listitem"><p><span class="emphasis"><em>If applicable, share your in-tree changes</em></span>: | ||
| 3867 | If the changes you made | ||
| 3868 | are suited for all Yocto Project kernel users, you might want to send them on | ||
| 3869 | for inclusion into the upstream kernel's Git repository. | ||
| 3870 | If the changes are accepted, the Yocto Project Maintainer pulls them into | ||
| 3871 | the master branch of the kernel tree. | ||
| 3872 | Doing so makes them available to everyone using the kernel.</p></li></ol></div><p> | ||
| 3873 | </p></div></div></div><div class="section" title="5.2. Application Development Workflow"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="application-development-workflow"></a>5.2. Application Development Workflow</h2></div></div></div><p> | ||
| 3874 | Application development involves creating an application that you want | ||
| 3875 | to run on your target hardware, which is running a kernel image created using the | ||
| 3876 | OpenEmbedded build system. | ||
| 3877 | The Yocto Project provides an Application Development Toolkit (ADT) and | ||
| 3878 | stand-alone cross-development toolchains that | ||
| 3879 | facilitate quick development and integration of your application into its run-time environment. | ||
| 3880 | Using the ADT and toolchains, you can compile and link your application. | ||
| 3881 | You can then deploy your application to the actual hardware or to the QEMU emulator for testing. | ||
| 3882 | If you are familiar with the popular Eclipse IDE, you can use an Eclipse Yocto Plug-in to | ||
| 3883 | allow you to develop, deploy, and test your application all from within Eclipse. | ||
| 3884 | </p><p> | ||
| 3885 | While we strongly suggest using the ADT to develop your application, this option might not | ||
| 3886 | be best for you. | ||
| 3887 | If this is the case, you can still use pieces of the Yocto Project for your development process. | ||
| 3888 | However, because the process can vary greatly, this manual does not provide detail on the process. | ||
| 3889 | </p><div class="section" title="5.2.1. Workflow Using the ADT and Eclipse™"><div class="titlepage"><div><div><h3 class="title"><a id="workflow-using-the-adt-and-eclipse"></a>5.2.1. Workflow Using the ADT and <span class="trademark">Eclipse</span>™</h3></div></div></div><p> | ||
| 3890 | To help you understand how application development works using the ADT, this section | ||
| 3891 | provides an overview of the general development process and a detailed example of the process | ||
| 3892 | as it is used from within the Eclipse IDE. | ||
| 3893 | </p><p> | ||
| 3894 | The following illustration and list summarize the application development general workflow. | ||
| 3895 | </p><p> | ||
| 3896 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 720px"><td align="center"><img src="figures/app-dev-flow.png" align="middle" /></td></tr></table><p> | ||
| 3897 | </p><p> | ||
| 3898 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Prepare the Host System for the Yocto Project</em></span>: | ||
| 3899 | See | ||
| 3900 | "<a class="link" href="#the-linux-distro" target="_top">The Linux Distributions</a>" and | ||
| 3901 | "<a class="link" href="#packages" target="_top">The Packages</a>" sections both | ||
| 3902 | in the Yocto Project Quick Start for requirements.</p></li><li class="listitem"><p><span class="emphasis"><em>Secure the Yocto Project Kernel Target Image</em></span>: | ||
| 3903 | You must have a target kernel image that has been built using the OpenEmbeded | ||
| 3904 | build system.</p><p>Depending on whether the Yocto Project has a pre-built image that matches your target | ||
| 3905 | architecture and where you are going to run the image while you develop your application | ||
| 3906 | (QEMU or real hardware), the area from which you get the image differs. | ||
| 3907 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Download the image from | ||
| 3908 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top"> | ||
| 3909 | <code class="filename">machines</code></a> if your target architecture is supported | ||
| 3910 | and you are going to develop and test your application on actual hardware. | ||
| 3911 | </p></li><li class="listitem"><p>Download the image from the | ||
| 3912 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top"> | ||
| 3913 | <code class="filename">machines/qemu</code></a> if your target architecture is supported | ||
| 3914 | and you are going to develop and test your application using the QEMU | ||
| 3915 | emulator.</p></li><li class="listitem"><p>Build your image if you cannot find a pre-built image that matches | ||
| 3916 | your target architecture. | ||
| 3917 | If your target architecture is similar to a supported architecture, you can | ||
| 3918 | modify the kernel image before you build it. | ||
| 3919 | See the | ||
| 3920 | "<a class="link" href="#kernel-modification-workflow" title="5.1.2.2. Kernel Modification Workflow">Kernel Modification Workflow</a>" | ||
| 3921 | section earlier in this manual for information on how to create a modified | ||
| 3922 | Yocto Project kernel.</p></li></ul></div><p>For information on pre-built kernel image naming schemes for images | ||
| 3923 | that can run on the QEMU emulator, see the | ||
| 3924 | "<a class="link" href="#downloading-the-pre-built-linux-kernel" target="_top">Downloading the Pre-Built Linux Kernel</a>" | ||
| 3925 | section in the Yocto Project Quick Start.</p></li><li class="listitem"><p><span class="emphasis"><em>Install the ADT</em></span>: | ||
| 3926 | The ADT provides a target-specific cross-development toolchain, the root filesystem, | ||
| 3927 | the QEMU emulator, and other tools that can help you develop your application. | ||
| 3928 | While it is possible to get these pieces separately, the ADT Installer provides an | ||
| 3929 | easy method. | ||
| 3930 | You can get these pieces by running an ADT installer script, which is configurable. | ||
| 3931 | For information on how to install the ADT, see the | ||
| 3932 | "<a class="link" href="#using-the-adt-installer" target="_top">Using the ADT Installer</a>" | ||
| 3933 | section | ||
| 3934 | in the Yocto Project Application Developer's Guide.</p></li><li class="listitem"><p><span class="emphasis"><em>If Applicable, Secure the Target Root Filesystem</em></span>: | ||
| 3935 | If you choose not to install the ADT using the ADT Installer, | ||
| 3936 | you need to find and download the | ||
| 3937 | appropriate root filesystems. | ||
| 3938 | You can find these tarballs in the same areas used for the kernel images. | ||
| 3939 | Depending on the type of image you are running, the root filesystem you need differs. | ||
| 3940 | For example, if you are developing an application that runs on an image that | ||
| 3941 | supports Sato, you need to get root filesystem that supports Sato. | ||
| 3942 | </p></li><li class="listitem"><p><span class="emphasis"><em>Create and Build your Application</em></span>: | ||
| 3943 | At this point, you need to have source files for your application. | ||
| 3944 | Once you have the files, you can use the Eclipse IDE to import them and build the | ||
| 3945 | project. | ||
| 3946 | If you are not using Eclipse, you need to use the cross-development tools you have | ||
| 3947 | installed to create the image.</p></li><li class="listitem"><p><span class="emphasis"><em>Deploy the Image with the Application</em></span>: | ||
| 3948 | If you are using the Eclipse IDE, you can deploy your image to the hardware or to | ||
| 3949 | QEMU through the project's preferences. | ||
| 3950 | If you are not using the Eclipse IDE, then you need to deploy the application using | ||
| 3951 | other methods to the hardware. | ||
| 3952 | Or, if you are using QEMU, you need to use that tool and load your image in for testing. | ||
| 3953 | </p></li><li class="listitem"><p><span class="emphasis"><em>Test and Debug the Application</em></span>: | ||
| 3954 | Once your application is deployed, you need to test it. | ||
| 3955 | Within the Eclipse IDE, you can use the debubbing environment along with the | ||
| 3956 | set of user-space tools installed along with the ADT to debug your application. | ||
| 3957 | Of course, the same user-space tools are available separately if you choose | ||
| 3958 | not to use the Eclipse IDE.</p></li></ol></div><p> | ||
| 3959 | </p></div><div class="section" title="5.2.2. Working Within Eclipse"><div class="titlepage"><div><div><h3 class="title"><a id="adt-eclipse"></a>5.2.2. Working Within Eclipse</h3></div></div></div><p> | ||
| 3960 | The Eclipse IDE is a popular development environment and it fully supports | ||
| 3961 | development using the Yocto Project. | ||
| 3962 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project supports both the Juno and Indigo versions | ||
| 3963 | of the Eclipse IDE. | ||
| 3964 | Thus, the following information provides setup information for both versions. | ||
| 3965 | </div><p> | ||
| 3966 | </p><p> | ||
| 3967 | When you install and configure the Eclipse Yocto Project Plug-in into | ||
| 3968 | the Eclipse IDE, you maximize your Yocto Project experience. | ||
| 3969 | Installing and configuring the Plug-in results in an environment that | ||
| 3970 | has extensions specifically designed to let you more easily develop software. | ||
| 3971 | These extensions allow for cross-compilation, deployment, and execution of | ||
| 3972 | your output into a QEMU emulation session. | ||
| 3973 | You can also perform cross-debugging and profiling. | ||
| 3974 | The environment also supports a suite of tools that allows you to perform | ||
| 3975 | remote profiling, tracing, collection of power data, collection of | ||
| 3976 | latency data, and collection of performance data. | ||
| 3977 | </p><p> | ||
| 3978 | This section describes how to install and configure the Eclipse IDE | ||
| 3979 | Yocto Plug-in and how to use it to develop your application. | ||
| 3980 | </p><div class="section" title="5.2.2.1. Setting Up the Eclipse IDE"><div class="titlepage"><div><div><h4 class="title"><a id="setting-up-the-eclipse-ide"></a>5.2.2.1. Setting Up the Eclipse IDE</h4></div></div></div><p> | ||
| 3981 | To develop within the Eclipse IDE, you need to do the following: | ||
| 3982 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install the optimal version of the Eclipse IDE.</p></li><li class="listitem"><p>Configure the Eclipse IDE.</p></li><li class="listitem"><p>Install the Eclipse Yocto Plug-in.</p></li><li class="listitem"><p>Configure the Eclipse Yocto Plug-in.</p></li></ol></div><p> | ||
| 3983 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 3984 | Do not install Eclipse from your distribution's package repository. | ||
| 3985 | Be sure to install Eclipse from the official Eclipse download site as directed | ||
| 3986 | in the next section. | ||
| 3987 | </div><p> | ||
| 3988 | </p><div class="section" title="5.2.2.1.1. Installing the Eclipse IDE"><div class="titlepage"><div><div><h5 class="title"><a id="installing-eclipse-ide"></a>5.2.2.1.1. Installing the Eclipse IDE</h5></div></div></div><p> | ||
| 3989 | It is recommended that you have the Juno 4.2 version of the | ||
| 3990 | Eclipse IDE installed on your development system. | ||
| 3991 | However, if you currently have the Indigo 3.7.2 version installed and you do | ||
| 3992 | not want to upgrade the IDE, you can configure Indigo to work with the | ||
| 3993 | Yocto Project. | ||
| 3994 | See the | ||
| 3995 | "<a class="link" href="#configuring-the-eclipse-ide-indigo" title="5.2.2.1.3. Configuring the Eclipse IDE (Indigo)">Configuring the Eclipse IDE (Indigo)</a>" | ||
| 3996 | section. | ||
| 3997 | </p><p> | ||
| 3998 | If you don’t have the Juno 4.2 Eclipse IDE installed, you can find the tarball at | ||
| 3999 | <a class="ulink" href="http://www.eclipse.org/downloads" target="_top">http://www.eclipse.org/downloads</a>. | ||
| 4000 | From that site, choose the Eclipse Classic version particular to your development | ||
| 4001 | host. | ||
| 4002 | This version contains the Eclipse Platform, the Java Development | ||
| 4003 | Tools (JDT), and the Plug-in Development Environment. | ||
| 4004 | </p><p> | ||
| 4005 | Once you have downloaded the tarball, extract it into a clean | ||
| 4006 | directory. | ||
| 4007 | For example, the following commands unpack and install the Eclipse IDE | ||
| 4008 | tarball found in the <code class="filename">Downloads</code> area | ||
| 4009 | into a clean directory using the default name <code class="filename">eclipse</code>: | ||
| 4010 | </p><pre class="literallayout"> | ||
| 4011 | $ cd ~ | ||
| 4012 | $ tar -xzvf ~/Downloads/eclipse-SDK-4.2-linux-gtk-x86_64.tar.gz | ||
| 4013 | </pre><p> | ||
| 4014 | </p><p> | ||
| 4015 | If you have the Indigo 3.7.2 Eclipse IDE already installed and you want to use that | ||
| 4016 | version, one issue exists that you need to be aware of regarding the Java | ||
| 4017 | Virtual machine’s garbage collection (GC) process. | ||
| 4018 | The GC process does not clean up the permanent generation | ||
| 4019 | space (PermGen). | ||
| 4020 | This space stores metadata descriptions of classes. | ||
| 4021 | The default value is set too small and it could trigger an | ||
| 4022 | out-of-memory error such as the following: | ||
| 4023 | </p><pre class="literallayout"> | ||
| 4024 | Java.lang.OutOfMemoryError: PermGen space | ||
| 4025 | </pre><p> | ||
| 4026 | </p><p> | ||
| 4027 | This error causes the application to hang. | ||
| 4028 | </p><p> | ||
| 4029 | To fix this issue, you can use the <code class="filename">--vmargs</code> | ||
| 4030 | option when you start the Indigo 3.7.2 Eclipse IDE | ||
| 4031 | to increase the size of the permanent generation space: | ||
| 4032 | </p><pre class="literallayout"> | ||
| 4033 | eclipse --vmargs --XX:PermSize=256M | ||
| 4034 | </pre><p> | ||
| 4035 | </p></div><div class="section" title="5.2.2.1.2. Configuring the Eclipse IDE (Juno)"><div class="titlepage"><div><div><h5 class="title"><a id="configuring-the-eclipse-ide-juno"></a>5.2.2.1.2. Configuring the Eclipse IDE (Juno)</h5></div></div></div><p> | ||
| 4036 | This section presents the steps needed to configure the Juno 4.2 Eclipse IDE. | ||
| 4037 | If you are using Indigo 3.7.2, see the | ||
| 4038 | "<a class="link" href="#configuring-the-eclipse-ide-indigo" title="5.2.2.1.3. Configuring the Eclipse IDE (Indigo)">Configuring the Eclipse IDE (Indigo)</a>". | ||
| 4039 | </p><p> | ||
| 4040 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure | ||
| 4041 | the Juno 4.2 Eclipse IDE. | ||
| 4042 | Follow these general steps: | ||
| 4043 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start the Eclipse IDE.</p></li><li class="listitem"><p>Make sure you are in your Workbench and select | ||
| 4044 | "Install New Software" from the "Help" pull-down menu. | ||
| 4045 | </p></li><li class="listitem"><p>Select <code class="filename">Juno - http://download.eclipse.org/releases/juno</code> | ||
| 4046 | from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Expand the box next to "Linux Tools" and select the | ||
| 4047 | "LTTng - Linux Tracing Toolkit" boxes.</p></li><li class="listitem"><p>Expand the box next to "Mobile and Device Development" and select the | ||
| 4048 | following boxes: | ||
| 4049 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">C/C++ Remote Launch</code></p></li><li class="listitem"><p><code class="filename">Remote System Explorer End-user Runtime</code></p></li><li class="listitem"><p><code class="filename">Remote System Explorer User Actions</code></p></li><li class="listitem"><p><code class="filename">Target Management Terminal</code></p></li><li class="listitem"><p><code class="filename">TCF Remote System Explorer add-in</code></p></li><li class="listitem"><p><code class="filename">TCF Target Explorer</code></p></li></ul></div></li><li class="listitem"><p>Expand the box next to <code class="filename">Programming Languages</code> | ||
| 4050 | and select the <code class="filename">Autotools Support for CDT</code> | ||
| 4051 | and <code class="filename">C/C++ Development Tools</code> boxes.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li></ol></div><p> | ||
| 4052 | </p></div><div class="section" title="5.2.2.1.3. Configuring the Eclipse IDE (Indigo)"><div class="titlepage"><div><div><h5 class="title"><a id="configuring-the-eclipse-ide-indigo"></a>5.2.2.1.3. Configuring the Eclipse IDE (Indigo)</h5></div></div></div><p> | ||
| 4053 | This section presents the steps needed to configure the Indigo 3.7.2 Eclipse IDE. | ||
| 4054 | If you are using Juno 4.2, see the | ||
| 4055 | "<a class="link" href="#configuring-the-eclipse-ide-juno" title="5.2.2.1.2. Configuring the Eclipse IDE (Juno)">Configuring the Eclipse IDE (Juno)</a>". | ||
| 4056 | </p><p> | ||
| 4057 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure | ||
| 4058 | the Indigo 3.7.2 Eclipse IDE. | ||
| 4059 | Follow these general steps: | ||
| 4060 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start the Eclipse IDE.</p></li><li class="listitem"><p>Make sure you are in your Workbench and select | ||
| 4061 | "Install New Software" from the "Help" pull-down menu. | ||
| 4062 | </p></li><li class="listitem"><p>Select <code class="filename">indigo - http://download.eclipse.org/releases/indigo</code> | ||
| 4063 | from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Expand the box next to <code class="filename">Programming Languages</code> | ||
| 4064 | and select the <code class="filename">Autotools Support for CDT (incubation)</code> | ||
| 4065 | and <code class="filename">C/C++ Development Tools</code> boxes.</p></li><li class="listitem"><p>Expand the box next to "Linux Tools" and select the | ||
| 4066 | "LTTng - Linux Tracing Toolkit(incubation)" boxes.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li><li class="listitem"><p>After the Eclipse IDE restarts and from the Workbench, select | ||
| 4067 | "Install New Software" from the "Help" pull-down menu.</p></li><li class="listitem"><p>Click the | ||
| 4068 | "Available Software Sites" link.</p></li><li class="listitem"><p>Check the box next to | ||
| 4069 | <code class="filename">http://download.eclipse.org/tm/updates/3.3</code> | ||
| 4070 | and click "OK".</p></li><li class="listitem"><p>Select <code class="filename">http://download.eclipse.org/tm/updates/3.3</code> | ||
| 4071 | from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Check the box next to <code class="filename">TM and RSE Main Features</code>. | ||
| 4072 | </p></li><li class="listitem"><p>Expand the box next to <code class="filename">TM and RSE Optional Add-ons</code> | ||
| 4073 | and select every item except <code class="filename">RSE Unit Tests</code> and | ||
| 4074 | <code class="filename">RSE WinCE Services (incubation)</code>.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li><li class="listitem"><p>If necessary, select | ||
| 4075 | "Install New Software" from the "Help" pull-down menu so you can click the | ||
| 4076 | "Available Software Sites" link again.</p></li><li class="listitem"><p>After clicking "Available Software Sites", check the box next to | ||
| 4077 | <code class="filename">http://download.eclipse.org/tools/cdt/releases/indigo</code> | ||
| 4078 | and click "OK".</p></li><li class="listitem"><p>Select <code class="filename">http://download.eclipse.orgtools/cdt/releases/indigo</code> | ||
| 4079 | from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Check the box next to <code class="filename">CDT Main Features</code>. | ||
| 4080 | </p></li><li class="listitem"><p>Expand the box next to <code class="filename">CDT Optional Features</code> | ||
| 4081 | and select <code class="filename">C/C++ Remote Launch</code> and | ||
| 4082 | <code class="filename">Target Communication Framework (incubation)</code>.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li></ol></div><p> | ||
| 4083 | </p></div><div class="section" title="5.2.2.1.4. Installing or Accessing the Eclipse Yocto Plug-in"><div class="titlepage"><div><div><h5 class="title"><a id="installing-the-eclipse-yocto-plug-in"></a>5.2.2.1.4. Installing or Accessing the Eclipse Yocto Plug-in</h5></div></div></div><p> | ||
| 4084 | You can install the Eclipse Yocto Plug-in into the Eclipse IDE | ||
| 4085 | one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in, | ||
| 4086 | or build and install the plug-in from the latest source code. | ||
| 4087 | If you don't want to permanently install the plug-in but just want to try it out | ||
| 4088 | within the Eclipse environment, you can import the plug-in project from the | ||
| 4089 | Yocto Project source repositories. | ||
| 4090 | </p><div class="section" title="5.2.2.1.4.1. Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site"><div class="titlepage"><div><div><h6 class="title"><a id="new-software"></a>5.2.2.1.4.1. Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</h6></div></div></div><p> | ||
| 4091 | To install the Eclipse Yocto Plug-in from the update site, | ||
| 4092 | follow these steps: | ||
| 4093 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start up the Eclipse IDE.</p></li><li class="listitem"><p>In Eclipse, select "Install New Software" from the "Help" menu.</p></li><li class="listitem"><p>Click "Add..." in the "Work with:" area.</p></li><li class="listitem"><p>Enter | ||
| 4094 | <code class="filename">http://downloads.yoctoproject.org/releases/eclipse-plugin/1.3</code> | ||
| 4095 | in the URL field and provide a meaningful name in the "Name" field.</p></li><li class="listitem"><p>Click "OK" to have the entry added to the "Work with:" | ||
| 4096 | drop-down list.</p></li><li class="listitem"><p>Select the entry for the plug-in from the "Work with:" drop-down | ||
| 4097 | list.</p></li><li class="listitem"><p>Check the box next to <code class="filename">Development tools and SDKs for Yocto Linux</code>. | ||
| 4098 | </p></li><li class="listitem"><p>Complete the remaining software installation steps and | ||
| 4099 | then restart the Eclipse IDE to finish the installation of the plug-in. | ||
| 4100 | </p></li></ol></div><p> | ||
| 4101 | </p></div><div class="section" title="5.2.2.1.4.2. Installing the Plug-in Using the Latest Source Code"><div class="titlepage"><div><div><h6 class="title"><a id="zip-file-method"></a>5.2.2.1.4.2. Installing the Plug-in Using the Latest Source Code</h6></div></div></div><p> | ||
| 4102 | To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: | ||
| 4103 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Open a shell and create a Git repository with: | ||
| 4104 | </p><pre class="literallayout"> | ||
| 4105 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | ||
| 4106 | </pre><p> | ||
| 4107 | For this example, the repository is named | ||
| 4108 | <code class="filename">~/yocto-eclipse</code>.</p></li><li class="listitem"><p>Locate the <code class="filename">build.sh</code> script in the | ||
| 4109 | Git repository you created in the previous step. | ||
| 4110 | The script is located in the <code class="filename">scripts</code>.</p></li><li class="listitem"><p>Be sure to set and export the <code class="filename">ECLIPSE_HOME</code> environment | ||
| 4111 | variable to the top-level directory in which you installed the Indigo | ||
| 4112 | version of Eclipse. | ||
| 4113 | For example, if your Eclipse directory is <code class="filename">$HOME/eclipse</code>, | ||
| 4114 | use the following: | ||
| 4115 | </p><pre class="literallayout"> | ||
| 4116 | $ export ECLIPSE_HOME=$HOME/eclipse | ||
| 4117 | </pre></li><li class="listitem"><p>Run the <code class="filename">build.sh</code> script and provide the | ||
| 4118 | name of the Git branch along with the Yocto Project release you are | ||
| 4119 | using. | ||
| 4120 | Here is an example that uses the <code class="filename">master</code> Git repository | ||
| 4121 | and the <code class="filename">1.1M4</code> release: | ||
| 4122 | </p><pre class="literallayout"> | ||
| 4123 | $ scripts/build.sh master 1.1M4 | ||
| 4124 | </pre><p> | ||
| 4125 | After running the script, the file | ||
| 4126 | <code class="filename">org.yocto.sdk-<release>-<date>-archive.zip</code> | ||
| 4127 | is in the current directory.</p></li><li class="listitem"><p>If necessary, start the Eclipse IDE and be sure you are in the | ||
| 4128 | Workbench.</p></li><li class="listitem"><p>Select "Install New Software" from the "Help" pull-down menu. | ||
| 4129 | </p></li><li class="listitem"><p>Click "Add".</p></li><li class="listitem"><p>Provide anything you want in the "Name" field.</p></li><li class="listitem"><p>Click "Archive" and browse to the ZIP file you built | ||
| 4130 | in step four. | ||
| 4131 | This ZIP file should not be "unzipped", and must be the | ||
| 4132 | <code class="filename">*archive.zip</code> file created by running the | ||
| 4133 | <code class="filename">build.sh</code> script.</p></li><li class="listitem"><p>Check the box next to the new entry in the installation window and complete | ||
| 4134 | the installation.</p></li><li class="listitem"><p>Restart the Eclipse IDE if necessary.</p></li></ol></div><p> | ||
| 4135 | </p><p> | ||
| 4136 | At this point you should be able to configure the Eclipse Yocto Plug-in as described in the | ||
| 4137 | "<a class="link" href="#configuring-the-eclipse-yocto-plug-in" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in">Configuring the Eclipse Yocto Plug-in</a>" | ||
| 4138 | section.</p></div><div class="section" title="5.2.2.1.4.3. Importing the Plug-in Project into the Eclipse Environment"><div class="titlepage"><div><div><h6 class="title"><a id="yocto-project-source"></a>5.2.2.1.4.3. Importing the Plug-in Project into the Eclipse Environment</h6></div></div></div><p> | ||
| 4139 | Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories | ||
| 4140 | is useful when you want to try out the latest plug-in from the tip of plug-in's | ||
| 4141 | development tree. | ||
| 4142 | It is important to understand when you import the plug-in you are not installing | ||
| 4143 | it into the Eclipse application. | ||
| 4144 | Rather, you are importing the project and just using it. | ||
| 4145 | To import the plug-in project, follow these steps: | ||
| 4146 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Open a shell and create a Git repository with: | ||
| 4147 | </p><pre class="literallayout"> | ||
| 4148 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | ||
| 4149 | </pre><p> | ||
| 4150 | For this example, the repository is named | ||
| 4151 | <code class="filename">~/yocto-eclipse</code>.</p></li><li class="listitem"><p>In Eclipse, select "Import" from the "File" menu.</p></li><li class="listitem"><p>Expand the "General" box and select "existing projects into workspace" | ||
| 4152 | and then click "Next".</p></li><li class="listitem"><p>Select the root directory and browse to | ||
| 4153 | <code class="filename">~/yocto-eclipse/plugins</code>.</p></li><li class="listitem"><p>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and | ||
| 4154 | "org.yocto.sdk.remotetools". | ||
| 4155 | Select and import all of them.</p></li></ol></div><p> | ||
| 4156 | </p><p> | ||
| 4157 | The left navigation pane in the Eclipse application shows the default projects. | ||
| 4158 | Right-click on one of these projects and run it as an Eclipse application. | ||
| 4159 | This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. | ||
| 4160 | </p></div></div><div class="section" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in"><div class="titlepage"><div><div><h5 class="title"><a id="configuring-the-eclipse-yocto-plug-in"></a>5.2.2.1.5. Configuring the Eclipse Yocto Plug-in</h5></div></div></div><p> | ||
| 4161 | Configuring the Eclipse Yocto Plug-in involves setting the Cross | ||
| 4162 | Compiler options and the Target options. | ||
| 4163 | The configurations you choose become the default settings for all projects. | ||
| 4164 | You do have opportunities to change them later when | ||
| 4165 | you configure the project (see the following section). | ||
| 4166 | </p><p> | ||
| 4167 | To start, you need to do the following from within the Eclipse IDE: | ||
| 4168 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Choose <code class="filename">Windows -> Preferences</code> to display | ||
| 4169 | the <code class="filename">Preferences</code> Dialog</p></li><li class="listitem"><p>Click <code class="filename">Yocto Project ADT</code></p></li></ul></div><p> | ||
| 4170 | </p><div class="section" title="5.2.2.1.5.1. Configuring the Cross-Compiler Options"><div class="titlepage"><div><div><h6 class="title"><a id="configuring-the-cross-compiler-options"></a>5.2.2.1.5.1. Configuring the Cross-Compiler Options</h6></div></div></div><p> | ||
| 4171 | To configure the Cross Compiler Options, you must select the type of toolchain, | ||
| 4172 | point to the toolchain, specify the sysroot location, and select the target architecture. | ||
| 4173 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Selecting the Toolchain Type:</em></span> | ||
| 4174 | Choose between <code class="filename">Standalone pre-built toolchain</code> | ||
| 4175 | and <code class="filename">Build system derived toolchain</code> for Cross | ||
| 4176 | Compiler Options. | ||
| 4177 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em> | ||
| 4178 | <code class="filename">Standalone Pre-built Toolchain:</code></em></span> | ||
| 4179 | Select this mode when you are using a stand-alone cross-toolchain. | ||
| 4180 | For example, suppose you are an application developer and do not | ||
| 4181 | need to build a target image. | ||
| 4182 | Instead, you just want to use an architecture-specific toolchain on an | ||
| 4183 | existing kernel and target root filesystem. | ||
| 4184 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 4185 | <code class="filename">Build System Derived Toolchain:</code></em></span> | ||
| 4186 | Select this mode if the cross-toolchain has been installed and built | ||
| 4187 | as part of the build directory. | ||
| 4188 | When you select <code class="filename">Build system derived toolchain</code>, | ||
| 4189 | you are using the toolchain bundled | ||
| 4190 | inside the build directory. | ||
| 4191 | </p></li></ul></div><p> | ||
| 4192 | </p></li><li class="listitem"><p><span class="emphasis"><em>Point to the Toolchain:</em></span> | ||
| 4193 | If you are using a stand-alone pre-built toolchain, you should be pointing to the | ||
| 4194 | <code class="filename">/opt/poky/1.3</code> directory. | ||
| 4195 | This is the location for toolchains installed by the ADT Installer or by hand. | ||
| 4196 | Sections "<a class="link" href="#configuring-and-running-the-adt-installer-script" target="_top">Configuring | ||
| 4197 | and Running the ADT Installer Script</a>" and | ||
| 4198 | "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" | ||
| 4199 | in the Yocto Project Application Developer's Guide | ||
| 4200 | describe two ways to install a stand-alone cross-toolchain in the | ||
| 4201 | <code class="filename">/opt/poky</code> directory. | ||
| 4202 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>It is possible to install a stand-alone cross-toolchain in a directory | ||
| 4203 | other than <code class="filename">/opt/poky</code>. | ||
| 4204 | However, doing so is discouraged.</div><p>If you are using a system-derived toolchain, the path you provide | ||
| 4205 | for the <code class="filename">Toolchain Root Location</code> | ||
| 4206 | field is the build directory. | ||
| 4207 | See the "<a class="link" href="#using-the-toolchain-from-within-the-build-tree" target="_top">Using | ||
| 4208 | BitBake and the build directory</a>" section in the Yocto Project Application | ||
| 4209 | Developer's Guide for information on how to install the toolchain into the build | ||
| 4210 | directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Specify the Sysroot Location:</em></span> | ||
| 4211 | This location is where the root filesystem for the | ||
| 4212 | target hardware is created on the development system by the ADT Installer. | ||
| 4213 | The QEMU user-space tools, the | ||
| 4214 | NFS boot process, and the cross-toolchain all use the sysroot location. | ||
| 4215 | </p></li><li class="listitem"><p><span class="emphasis"><em>Select the Target Architecture:</em></span> | ||
| 4216 | The target architecture is the type of hardware you are | ||
| 4217 | going to use or emulate. | ||
| 4218 | Use the pull-down <code class="filename">Target Architecture</code> menu to make | ||
| 4219 | your selection. | ||
| 4220 | The pull-down menu should have the supported architectures. | ||
| 4221 | If the architecture you need is not listed in the menu, you | ||
| 4222 | will need to build the image. | ||
| 4223 | See the "<a class="link" href="#building-image" target="_top">Building an Image</a>" section | ||
| 4224 | of the Yocto Project Quick Start for more information.</p></li></ul></div><p> | ||
| 4225 | </p></div><div class="section" title="5.2.2.1.5.2. Configuring the Target Options"><div class="titlepage"><div><div><h6 class="title"><a id="configuring-the-target-options"></a>5.2.2.1.5.2. Configuring the Target Options</h6></div></div></div><p> | ||
| 4226 | You can choose to emulate hardware using the QEMU emulator, or you | ||
| 4227 | can choose to run your image on actual hardware. | ||
| 4228 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">QEMU:</code></em></span> Select this option if | ||
| 4229 | you will be using the QEMU emulator. | ||
| 4230 | If you are using the emulator, you also need to locate the kernel | ||
| 4231 | and specify any custom options.</p><p>If you selected <code class="filename">Build system derived toolchain</code>, | ||
| 4232 | the target kernel you built will be located in the | ||
| 4233 | build directory in <code class="filename">tmp/deploy/images</code> directory. | ||
| 4234 | If you selected <code class="filename">Standalone pre-built toolchain</code>, the | ||
| 4235 | pre-built image you downloaded is located | ||
| 4236 | in the directory you specified when you downloaded the image.</p><p>Most custom options are for advanced QEMU users to further | ||
| 4237 | customize their QEMU instance. | ||
| 4238 | These options are specified between paired angled brackets. | ||
| 4239 | Some options must be specified outside the brackets. | ||
| 4240 | In particular, the options <code class="filename">serial</code>, | ||
| 4241 | <code class="filename">nographic</code>, and <code class="filename">kvm</code> must all | ||
| 4242 | be outside the brackets. | ||
| 4243 | Use the <code class="filename">man qemu</code> command to get help on all the options | ||
| 4244 | and their use. | ||
| 4245 | The following is an example: | ||
| 4246 | </p><pre class="literallayout"> | ||
| 4247 | serial ‘<-m 256 -full-screen>’ | ||
| 4248 | </pre><p> | ||
| 4249 | Regardless of the mode, Sysroot is already defined as part of the | ||
| 4250 | Cross Compiler Options configuration in the | ||
| 4251 | <code class="filename">Sysroot Location:</code> field.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">External HW:</code></em></span> Select this option | ||
| 4252 | if you will be using actual hardware.</p></li></ul></div><p> | ||
| 4253 | </p><p> | ||
| 4254 | Click the <code class="filename">OK</code> button to save your plug-in configurations. | ||
| 4255 | </p></div></div></div><div class="section" title="5.2.2.2. Creating the Project"><div class="titlepage"><div><div><h4 class="title"><a id="creating-the-project"></a>5.2.2.2. Creating the Project</h4></div></div></div><p> | ||
| 4256 | You can create two types of projects: Autotools-based, or Makefile-based. | ||
| 4257 | This section describes how to create Autotools-based projects from within | ||
| 4258 | the Eclipse IDE. | ||
| 4259 | For information on creating Makefile-based projects in a terminal window, see the section | ||
| 4260 | "<a class="link" href="#using-the-command-line" target="_top">Using the Command Line</a>" | ||
| 4261 | in the Yocto Project Application Developer's Guide. | ||
| 4262 | </p><p> | ||
| 4263 | To create a project based on a Yocto template and then display the source code, | ||
| 4264 | follow these steps: | ||
| 4265 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">File -> New -> Project</code>.</p></li><li class="listitem"><p>Double click <code class="filename">CC++</code>.</p></li><li class="listitem"><p>Double click <code class="filename">C Project</code> to create the project.</p></li><li class="listitem"><p>Expand <code class="filename">Yocto Project ADT Project</code>.</p></li><li class="listitem"><p>Select <code class="filename">Hello World ANSI C Autotools Project</code>. | ||
| 4266 | This is an Autotools-based project based on a Yocto template.</p></li><li class="listitem"><p>Put a name in the <code class="filename">Project name:</code> field. | ||
| 4267 | Do not use hyphens as part of the name.</p></li><li class="listitem"><p>Click <code class="filename">Next</code>.</p></li><li class="listitem"><p>Add information in the <code class="filename">Author</code> and | ||
| 4268 | <code class="filename">Copyright notice</code> fields.</p></li><li class="listitem"><p>Be sure the <code class="filename">License</code> field is correct.</p></li><li class="listitem"><p>Click <code class="filename">Finish</code>.</p></li><li class="listitem"><p>If the "open perspective" prompt appears, click "Yes" so that you | ||
| 4269 | in the C/C++ perspective.</p></li><li class="listitem"><p>The left-hand navigation pane shows your project. | ||
| 4270 | You can display your source by double clicking the project's source file. | ||
| 4271 | </p></li></ol></div><p> | ||
| 4272 | </p></div><div class="section" title="5.2.2.3. Configuring the Cross-Toolchains"><div class="titlepage"><div><div><h4 class="title"><a id="configuring-the-cross-toolchains"></a>5.2.2.3. Configuring the Cross-Toolchains</h4></div></div></div><p> | ||
| 4273 | The earlier section, "<a class="link" href="#configuring-the-eclipse-yocto-plug-in" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in">Configuring | ||
| 4274 | the Eclipse Yocto Plug-in</a>", sets up the default project | ||
| 4275 | configurations. | ||
| 4276 | You can override these settings for a given project by following these steps: | ||
| 4277 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">Project -> Change Yocto Project Settings</code>: | ||
| 4278 | This selection brings up the <code class="filename">Yocot Project Settings</code> Dialog | ||
| 4279 | and allows you to make changes specific to an individual project. | ||
| 4280 | </p><p>By default, the Cross Compiler Options and Target Options for a project | ||
| 4281 | are inherited from settings you provide using the <code class="filename">Preferences</code> | ||
| 4282 | Dialog as described earlier | ||
| 4283 | in the "<a class="link" href="#configuring-the-eclipse-yocto-plug-in" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in">Configuring the Eclipse | ||
| 4284 | Yocto Plug-in</a>" section. | ||
| 4285 | The <code class="filename">Yocto Project Settings</code> | ||
| 4286 | Dialog allows you to override those default settings | ||
| 4287 | for a given project.</p></li><li class="listitem"><p>Make your configurations for the project and click "OK".</p></li><li class="listitem"><p>Select <code class="filename">Project -> Reconfigure Project</code>: | ||
| 4288 | This selection reconfigures the project by running | ||
| 4289 | <code class="filename">autogen.sh</code> in the workspace for your project. | ||
| 4290 | The script also runs <code class="filename">libtoolize</code>, <code class="filename">aclocal</code>, | ||
| 4291 | <code class="filename">autoconf</code>, <code class="filename">autoheader</code>, | ||
| 4292 | <code class="filename">automake --a</code>, and | ||
| 4293 | <code class="filename">./configure</code>. | ||
| 4294 | Click on the <code class="filename">Console</code> tab beneath your source code to | ||
| 4295 | see the results of reconfiguring your project.</p></li></ol></div><p> | ||
| 4296 | </p></div><div class="section" title="5.2.2.4. Building the Project"><div class="titlepage"><div><div><h4 class="title"><a id="building-the-project"></a>5.2.2.4. Building the Project</h4></div></div></div><p> | ||
| 4297 | To build the project, select <code class="filename">Project -> Build Project</code>. | ||
| 4298 | The console should update and you can note the cross-compiler you are using. | ||
| 4299 | </p></div><div class="section" title="5.2.2.5. Starting QEMU in User Space NFS Mode"><div class="titlepage"><div><div><h4 class="title"><a id="starting-qemu-in-user-space-nfs-mode"></a>5.2.2.5. Starting QEMU in User Space NFS Mode</h4></div></div></div><p> | ||
| 4300 | To start the QEMU emulator from within Eclipse, follow these steps: | ||
| 4301 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Expose the <code class="filename">Run -> External Tools</code> menu. | ||
| 4302 | Your image should appear as a selectable menu item. | ||
| 4303 | </p></li><li class="listitem"><p>Select your image from the menu to launch the | ||
| 4304 | emulator in a new window.</p></li><li class="listitem"><p>If needed, enter your host root password in the shell window at the prompt. | ||
| 4305 | This sets up a <code class="filename">Tap 0</code> connection needed for running in user-space | ||
| 4306 | NFS mode.</p></li><li class="listitem"><p>Wait for QEMU to launch.</p></li><li class="listitem"><p>Once QEMU launches, you can begin operating within that | ||
| 4307 | environment. | ||
| 4308 | For example, you could determine the IP Address | ||
| 4309 | for the user-space NFS by using the <code class="filename">ifconfig</code> command. | ||
| 4310 | </p></li></ol></div><p> | ||
| 4311 | </p></div><div class="section" title="5.2.2.6. Deploying and Debugging the Application"><div class="titlepage"><div><div><h4 class="title"><a id="deploying-and-debugging-the-application"></a>5.2.2.6. Deploying and Debugging the Application</h4></div></div></div><p> | ||
| 4312 | Once the QEMU emulator is running the image, using the Eclipse IDE | ||
| 4313 | you can deploy your application and use the emulator to perform debugging. | ||
| 4314 | Follow these steps to deploy the application. | ||
| 4315 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">Run -> Debug Configurations...</code></p></li><li class="listitem"><p>In the left area, expand <code class="filename">C/C++Remote Application</code>.</p></li><li class="listitem"><p>Locate your project and select it to bring up a new | ||
| 4316 | tabbed view in the <code class="filename">Debug Configurations</code> Dialog.</p></li><li class="listitem"><p>Enter the absolute path into which you want to deploy | ||
| 4317 | the application. | ||
| 4318 | Use the <code class="filename">Remote Absolute File Path for C/C++Application:</code> field. | ||
| 4319 | For example, enter <code class="filename">/usr/bin/<programname></code>.</p></li><li class="listitem"><p>Click on the <code class="filename">Debugger</code> tab to see the cross-tool debugger | ||
| 4320 | you are using.</p></li><li class="listitem"><p>Click on the <code class="filename">Main</code> tab.</p></li><li class="listitem"><p>Create a new connection to the QEMU instance | ||
| 4321 | by clicking on <code class="filename">new</code>.</p></li><li class="listitem"><p>Select <code class="filename">TCF</code>, which means Target Communication | ||
| 4322 | Framework.</p></li><li class="listitem"><p>Click <code class="filename">Next</code>.</p></li><li class="listitem"><p>Clear out the <code class="filename">host name</code> field and enter the IP Address | ||
| 4323 | determined earlier.</p></li><li class="listitem"><p>Click <code class="filename">Finish</code> to close the | ||
| 4324 | <code class="filename">New Connections</code> Dialog.</p></li><li class="listitem"><p>Use the drop-down menu now in the <code class="filename">Connection</code> field and pick | ||
| 4325 | the IP Address you entered.</p></li><li class="listitem"><p>Click <code class="filename">Debug</code> to bring up a login screen | ||
| 4326 | and login.</p></li><li class="listitem"><p>Accept the debug perspective.</p></li></ol></div><p> | ||
| 4327 | </p></div><div class="section" title="5.2.2.7. Running User-Space Tools"><div class="titlepage"><div><div><h4 class="title"><a id="running-user-space-tools"></a>5.2.2.7. Running User-Space Tools</h4></div></div></div><p> | ||
| 4328 | As mentioned earlier in the manual, several tools exist that enhance | ||
| 4329 | your development experience. | ||
| 4330 | These tools are aids in developing and debugging applications and images. | ||
| 4331 | You can run these user-space tools from within the Eclipse IDE through the | ||
| 4332 | <code class="filename">YoctoTools</code> menu. | ||
| 4333 | </p><p> | ||
| 4334 | Once you pick a tool, you need to configure it for the remote target. | ||
| 4335 | Every tool needs to have the connection configured. | ||
| 4336 | You must select an existing TCF-based RSE connection to the remote target. | ||
| 4337 | If one does not exist, click <code class="filename">New</code> to create one. | ||
| 4338 | </p><p> | ||
| 4339 | Here are some specifics about the remote tools: | ||
| 4340 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">OProfile</code>:</em></span> Selecting this tool causes | ||
| 4341 | the <code class="filename">oprofile-server</code> on the remote target to launch on | ||
| 4342 | the local host machine. | ||
| 4343 | The <code class="filename">oprofile-viewer</code> must be installed on the local host machine and the | ||
| 4344 | <code class="filename">oprofile-server</code> must be installed on the remote target, | ||
| 4345 | respectively, in order to use. | ||
| 4346 | You must compile and install the <code class="filename">oprofile-viewer</code> from the source code | ||
| 4347 | on your local host machine. | ||
| 4348 | Furthermore, in order to convert the target's sample format data into a form that the | ||
| 4349 | host can use, you must have <code class="filename">oprofile</code> version 0.9.4 or | ||
| 4350 | greater installed on the host.</p><p>You can locate both the viewer and server from | ||
| 4351 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/oprofileui/" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/oprofileui/</a>. | ||
| 4352 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The <code class="filename">oprofile-server</code> is installed by default on | ||
| 4353 | the <code class="filename">core-image-sato-sdk</code> image.</div></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">Lttng-ust</code>:</em></span> Selecting this tool runs | ||
| 4354 | <code class="filename">usttrace</code> on the remote target, transfers the output data back | ||
| 4355 | to the local host machine, and uses the <code class="filename">lttng</code> Eclipse plug-in to | ||
| 4356 | graphically display the output. | ||
| 4357 | For information on how to use <code class="filename">lttng</code> to trace an application, see | ||
| 4358 | <a class="ulink" href="http://lttng.org/files/ust/manual/ust.html" target="_top">http://lttng.org/files/ust/manual/ust.html</a>.</p><p>For <code class="filename">Application</code>, you must supply the absolute path name of the | ||
| 4359 | application to be traced by user mode <code class="filename">lttng</code>. | ||
| 4360 | For example, typing <code class="filename">/path/to/foo</code> triggers | ||
| 4361 | <code class="filename">usttrace /path/to/foo</code> on the remote target to trace the | ||
| 4362 | program <code class="filename">/path/to/foo</code>.</p><p><code class="filename">Argument</code> is passed to <code class="filename">usttrace</code> | ||
| 4363 | running on the remote target.</p><p>Before you use the <code class="filename">lttng-ust</code> tool, you need to setup | ||
| 4364 | the <code class="filename">lttng</code> Eclipse plug-in and create a <code class="filename">lttng</code> | ||
| 4365 | project. | ||
| 4366 | Do the following: | ||
| 4367 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Follow these | ||
| 4368 | <a class="ulink" href="http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library" target="_top">instructions</a> | ||
| 4369 | to download and install the <code class="filename">lttng</code> parser library. | ||
| 4370 | </p></li><li class="listitem"><p>Select <code class="filename">Window -> Open Perspective -> Other</code> | ||
| 4371 | and then select <code class="filename">LTTng</code>.</p></li><li class="listitem"><p>Click <code class="filename">OK</code> to change the Eclipse perspective | ||
| 4372 | into the <code class="filename">LTTng</code> perspective.</p></li><li class="listitem"><p>Create a new <code class="filename">LTTng</code> project by selecting | ||
| 4373 | <code class="filename">File -> New -> Project</code>.</p></li><li class="listitem"><p>Choose <code class="filename">LTTng -> LTTng Project</code>.</p></li><li class="listitem"><p>Click <code class="filename">YoctoTools -> lttng-ust</code> to start user mode | ||
| 4374 | <code class="filename">lttng</code> on the remote target.</p></li></ol></div><p>After the output data has been transferred from the remote target back to the local | ||
| 4375 | host machine, new traces will be imported into the selected <code class="filename">LTTng</code> project. | ||
| 4376 | Then you can go to the <code class="filename">LTTng</code> project, right click the imported | ||
| 4377 | trace, and set the trace type as the <code class="filename">LTTng</code> kernel trace. | ||
| 4378 | Finally, right click the imported trace and select <code class="filename">Open</code> | ||
| 4379 | to display the data graphically.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">PowerTOP</code>:</em></span> Selecting this tool runs | ||
| 4380 | <code class="filename">powertop</code> on the remote target machine and displays the results in a | ||
| 4381 | new view called <code class="filename">powertop</code>.</p><p><code class="filename">Time to gather data(sec):</code> is the time passed in seconds before data | ||
| 4382 | is gathered from the remote target for analysis.</p><p><code class="filename">show pids in wakeups list:</code> corresponds to the | ||
| 4383 | <code class="filename">-p</code> argument | ||
| 4384 | passed to <code class="filename">powertop</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">LatencyTOP and Perf</code>:</em></span> | ||
| 4385 | <code class="filename">latencytop</code> identifies system latency, while | ||
| 4386 | <code class="filename">perf</code> monitors the system's | ||
| 4387 | performance counter registers. | ||
| 4388 | Selecting either of these tools causes an RSE terminal view to appear | ||
| 4389 | from which you can run the tools. | ||
| 4390 | Both tools refresh the entire screen to display results while they run.</p></li></ul></div><p> | ||
| 4391 | </p></div><div class="section" title="5.2.2.8. Customizing an Image Using a BitBake Commander Project and Hob"><div class="titlepage"><div><div><h4 class="title"><a id="customizing-an-image-using-a-bitbake-commander-project-and-hob"></a>5.2.2.8. Customizing an Image Using a BitBake Commander Project and Hob</h4></div></div></div><p> | ||
| 4392 | Within Eclipse, you can create a Yocto BitBake Commander project, | ||
| 4393 | edit the metadata, and then use the | ||
| 4394 | <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> to build a customized | ||
| 4395 | image all within one IDE. | ||
| 4396 | </p><div class="section" title="5.2.2.8.1. Creating the Yocto BitBake Commander Project"><div class="titlepage"><div><div><h5 class="title"><a id="creating-the-yocto-bitbake-commander-project"></a>5.2.2.8.1. Creating the Yocto BitBake Commander Project</h5></div></div></div><p> | ||
| 4397 | To create a Yocto BitBake Commander project, follow these steps: | ||
| 4398 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">Window -> Open Perspective -> Other</code> | ||
| 4399 | and then choose <code class="filename">Bitbake Commander</code>.</p></li><li class="listitem"><p>Click <code class="filename">OK</code> to change the Eclipse perspective into the | ||
| 4400 | Bitbake Commander perspective.</p></li><li class="listitem"><p>Select <code class="filename">File -> New -> Project</code> to create a new Yocto | ||
| 4401 | Bitbake Commander project.</p></li><li class="listitem"><p>Choose <code class="filename">Yocto Project Bitbake Commander -> New Yocto Project</code> | ||
| 4402 | and click <code class="filename">Next</code>.</p></li><li class="listitem"><p>Enter the Project Name and choose the Project Location. | ||
| 4403 | The Yocto project's metadata files will be put under the directory | ||
| 4404 | <code class="filename"><project_location>/<project_name></code>. | ||
| 4405 | If that directory does not exist, you need to check | ||
| 4406 | the "Clone from Yocto Git Repository" box, which would execute a | ||
| 4407 | <code class="filename">git clone</code> command to get the project's metadata files. | ||
| 4408 | </p></li><li class="listitem"><p>Select <code class="filename">Finish</code> to create the project.</p></li></ol></div><p> | ||
| 4409 | </p></div><div class="section" title="5.2.2.8.2. Editing the Metadata Files"><div class="titlepage"><div><div><h5 class="title"><a id="editing-the-metadata-files"></a>5.2.2.8.2. Editing the Metadata Files</h5></div></div></div><p> | ||
| 4410 | After you create the Yocto Bitbake Commander project, you can modify the metadata files | ||
| 4411 | by opening them in the project. | ||
| 4412 | When editing recipe files (<code class="filename">.bb</code> files), you can view BitBake | ||
| 4413 | variable values and information by hovering the mouse pointer over the variable name and | ||
| 4414 | waiting a few seconds. | ||
| 4415 | </p><p> | ||
| 4416 | To edit the metadata, follow these steps: | ||
| 4417 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select your Yocto Bitbake Commander project.</p></li><li class="listitem"><p>Select <code class="filename">File -> New -> Yocto BitBake Commander -> BitBake Recipe</code> | ||
| 4418 | to open a new recipe wizard.</p></li><li class="listitem"><p>Point to your source by filling in the "SRC_URL" field. | ||
| 4419 | For example, you can add a recipe to your | ||
| 4420 | <a class="link" href="#source-directory" target="_top">source directory</a> | ||
| 4421 | by defining "SRC_URL" as follows: | ||
| 4422 | </p><pre class="literallayout"> | ||
| 4423 | ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz | ||
| 4424 | </pre></li><li class="listitem"><p>Click "Populate" to calculate the archive md5, sha256, | ||
| 4425 | license checksum values and to auto-generate the recipe filename.</p></li><li class="listitem"><p>Fill in the "Description" field.</p></li><li class="listitem"><p>Be sure values for all required fields exist.</p></li><li class="listitem"><p>Click <code class="filename">Finish</code>.</p></li></ol></div><p> | ||
| 4426 | </p></div><div class="section" title="5.2.2.8.3. Building and Customizing the Image"><div class="titlepage"><div><div><h5 class="title"><a id="buiding-and-customizing-the-image"></a>5.2.2.8.3. Building and Customizing the Image</h5></div></div></div><p> | ||
| 4427 | To build and customize the image in Eclipse, follow these steps: | ||
| 4428 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select your Yocto Bitbake Commander project.</p></li><li class="listitem"><p>Select <code class="filename">Project -> Launch HOB</code>.</p></li><li class="listitem"><p>Enter the build directory where you want to put your final images.</p></li><li class="listitem"><p>Click <code class="filename">OK</code> to launch Hob.</p></li><li class="listitem"><p>Use Hob to customize and build your own images. | ||
| 4429 | For information on Hob, see the | ||
| 4430 | <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob Project Page</a> on the | ||
| 4431 | Yocto Project website.</p></li></ol></div><p> | ||
| 4432 | </p></div></div></div><div class="section" title="5.2.3. Workflow Using Stand-alone Cross-development Toolchains"><div class="titlepage"><div><div><h3 class="title"><a id="workflow-using-stand-alone-cross-development-toolchains"></a>5.2.3. Workflow Using Stand-alone Cross-development Toolchains</h3></div></div></div><p> | ||
| 4433 | If you want to develop an application without prior installation of the ADT, you | ||
| 4434 | still can employ the cross-development toolchain, the QEMU emulator, and a number of supported | ||
| 4435 | target image files. | ||
| 4436 | You just need to follow these general steps: | ||
| 4437 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Install the cross-development toolchain for your target hardware:</em></span> | ||
| 4438 | For information on how to install the toolchain, see the | ||
| 4439 | "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" | ||
| 4440 | section | ||
| 4441 | in the Yocto Project Application Developer's Guide.</p></li><li class="listitem"><p><span class="emphasis"><em>Download the Target Image:</em></span> The Yocto Project supports | ||
| 4442 | several target architectures and has many pre-built kernel images and root filesystem | ||
| 4443 | images.</p><p>If you are going to develop your application on hardware, go to the | ||
| 4444 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top"><code class="filename">machines</code></a> | ||
| 4445 | download area and choose a target machine area | ||
| 4446 | from which to download the kernel image and root filesystem. | ||
| 4447 | This download area could have several files in it that support development using | ||
| 4448 | actual hardware. | ||
| 4449 | For example, the area might contain <code class="filename">.hddimg</code> files that combine the | ||
| 4450 | kernel image with the filesystem, boot loaders, etc. | ||
| 4451 | Be sure to get the files you need for your particular development process.</p><p>If you are going to develop your application and then run and test it using the QEMU | ||
| 4452 | emulator, go to the | ||
| 4453 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top"><code class="filename">machines/qemu</code></a> | ||
| 4454 | download area. | ||
| 4455 | From this area, go down into the directory for your target architecture | ||
| 4456 | (e.g. <code class="filename">qemux86_64</code> for an | ||
| 4457 | <span class="trademark">Intel</span>®-based 64-bit architecture). | ||
| 4458 | Download kernel, root filesystem, and any other files you need for your process. | ||
| 4459 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>In order to use the root filesystem in QEMU, you need to extract it. | ||
| 4460 | See the | ||
| 4461 | "<a class="link" href="#extracting-the-root-filesystem" target="_top">Extracting the Root Filesystem</a>" | ||
| 4462 | section for information on how to extract the root filesystem.</div></li><li class="listitem"><p><span class="emphasis"><em>Develop and Test your Application:</em></span> At this point, | ||
| 4463 | you have the tools to develop your application. | ||
| 4464 | If you need to separately install and use the QEMU emulator, you can go to | ||
| 4465 | <a class="ulink" href="http://www.qemu.org" target="_top">QEMU Home Page</a> to download and learn about the | ||
| 4466 | emulator.</p></li></ol></div><p> | ||
| 4467 | </p></div></div><div class="section" title="5.3. Modifying Temporary Source Code"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="modifying-temporary-source-code"></a>5.3. Modifying Temporary Source Code</h2></div></div></div><p> | ||
| 4468 | You might | ||
| 4469 | find it helpful during development to modify the temporary source code used by recipes | ||
| 4470 | to build packages. | ||
| 4471 | For example, suppose you are developing a patch and you need to experiment a bit | ||
| 4472 | to figure out your solution. | ||
| 4473 | After you have initially built the package, you can iteratively tweak the | ||
| 4474 | source code, which is located in the | ||
| 4475 | <a class="link" href="#build-directory">build directory</a>, and then | ||
| 4476 | you can force a re-compile and quickly test your altered code. | ||
| 4477 | Once you settle on a solution, you can then preserve your changes in the form of | ||
| 4478 | patches. | ||
| 4479 | You can accomplish these steps all within either a | ||
| 4480 | <a class="ulink" href="http://savannah.nongnu.org/projects/quilt" target="_top">Quilt</a> or | ||
| 4481 | <a class="link" href="#git" title="3.6. Git">Git</a> workflow. | ||
| 4482 | </p><div class="section" title="5.3.1. Finding the Temporary Source Code"><div class="titlepage"><div><div><h3 class="title"><a id="finding-the-temporary-source-code"></a>5.3.1. Finding the Temporary Source Code</h3></div></div></div><p> | ||
| 4483 | During a build, the unpacked temporary source code used by recipes | ||
| 4484 | to build packages is available in the build directory as | ||
| 4485 | defined by the | ||
| 4486 | <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> variable. | ||
| 4487 | Below is the default value for the <code class="filename">S</code> variable as defined in the | ||
| 4488 | <code class="filename">meta/conf/bitbake.conf</code> configuration file in the | ||
| 4489 | <a class="link" href="#source-directory">source directory</a>: | ||
| 4490 | </p><pre class="literallayout"> | ||
| 4491 | S = ${WORKDIR}/${BP} | ||
| 4492 | </pre><p> | ||
| 4493 | You should be aware that many recipes override the <code class="filename">S</code> variable. | ||
| 4494 | For example, recipes that fetch their source from Git usually set | ||
| 4495 | <code class="filename">S</code> to <code class="filename">${WORKDIR}/git</code>. | ||
| 4496 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><code class="filename">BP</code> represents the "Base Package", which is the base package | ||
| 4497 | name and the package version: | ||
| 4498 | <pre class="literallayout"> | ||
| 4499 | BP = ${BPN}-${PV} | ||
| 4500 | </pre></div><p> | ||
| 4501 | </p><p> | ||
| 4502 | The path to the work directory for the recipe | ||
| 4503 | (<a class="link" href="#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>) depends | ||
| 4504 | on the package name and the architecture of the target device. | ||
| 4505 | For example, here is the work directory for packages whose targets are not device-dependent: | ||
| 4506 | </p><pre class="literallayout"> | ||
| 4507 | ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | ||
| 4508 | </pre><p> | ||
| 4509 | Let's look at an example without variables. | ||
| 4510 | Assuming a top-level source directory named <code class="filename">poky</code> | ||
| 4511 | and a default build directory of <code class="filename">poky/build</code>, | ||
| 4512 | the following is the work directory for the <code class="filename">acl</code> package: | ||
| 4513 | </p><pre class="literallayout"> | ||
| 4514 | ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 | ||
| 4515 | </pre><p> | ||
| 4516 | </p><p> | ||
| 4517 | If your package is dependent on the target device, the work directory varies slightly: | ||
| 4518 | </p><pre class="literallayout"> | ||
| 4519 | ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | ||
| 4520 | </pre><p> | ||
| 4521 | Again, assuming top-level source directory named <code class="filename">poky</code> | ||
| 4522 | and a default build directory of <code class="filename">poky/build</code>, the | ||
| 4523 | following is the work directory for the <code class="filename">acl</code> package that is being | ||
| 4524 | built for a MIPS-based device: | ||
| 4525 | </p><pre class="literallayout"> | ||
| 4526 | ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 | ||
| 4527 | </pre><p> | ||
| 4528 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 4529 | To better understand how the OpenEmbedded build system resolves directories during the | ||
| 4530 | build process, see the glossary entries for the | ||
| 4531 | <a class="link" href="#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>, | ||
| 4532 | <a class="link" href="#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a>, | ||
| 4533 | <a class="link" href="#var-TOPDIR" target="_top"><code class="filename">TOPDIR</code></a>, | ||
| 4534 | <a class="link" href="#var-PACKAGE_ARCH" target="_top"><code class="filename">PACKAGE_ARCH</code></a>, | ||
| 4535 | <a class="link" href="#var-TARGET_OS" target="_top"><code class="filename">TARGET_OS</code></a>, | ||
| 4536 | <a class="link" href="#var-PN" target="_top"><code class="filename">PN</code></a>, | ||
| 4537 | <a class="link" href="#var-PV" target="_top"><code class="filename">PV</code></a>, | ||
| 4538 | and | ||
| 4539 | <a class="link" href="#var-PR" target="_top"><code class="filename">PR</code></a> | ||
| 4540 | variables in the Yocto Project Reference Manual. | ||
| 4541 | </div><p> | ||
| 4542 | Now that you know where to locate the directory that has the temporary source code, you can use a | ||
| 4543 | Quilt or Git workflow to make your edits, test the changes, and preserve the | ||
| 4544 | changes in the form of patches. | ||
| 4545 | </p></div><div class="section" title="5.3.2. Using a Quilt Workflow"><div class="titlepage"><div><div><h3 class="title"><a id="using-a-quilt-workflow"></a>5.3.2. Using a Quilt Workflow</h3></div></div></div><p> | ||
| 4546 | <a class="ulink" href="http://savannah.nongnu.org/projects/quilt" target="_top">Quilt</a> | ||
| 4547 | is a powerful tool that allows you to capture source code changes without having | ||
| 4548 | a clean source tree. | ||
| 4549 | This section outlines the typical workflow you can use to modify temporary source code, | ||
| 4550 | test changes, and then preserve the changes in the form of a patch all using Quilt. | ||
| 4551 | </p><p> | ||
| 4552 | Follow these general steps: | ||
| 4553 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Find the Source Code:</em></span> | ||
| 4554 | The temporary source code used by the OpenEmbedded build system is kept in the | ||
| 4555 | build directory. | ||
| 4556 | See the | ||
| 4557 | "<a class="link" href="#finding-the-temporary-source-code" title="5.3.1. Finding the Temporary Source Code">Finding the Temporary Source Code</a>" | ||
| 4558 | section to learn how to locate the directory that has the temporary source code for a | ||
| 4559 | particular package.</p></li><li class="listitem"><p><span class="emphasis"><em>Change Your Working Directory:</em></span> | ||
| 4560 | You need to be in the directory that has the temporary source code. | ||
| 4561 | That directory is defined by the | ||
| 4562 | <a class="link" href="#var-S" target="_top">S</a> | ||
| 4563 | variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Create a New Patch:</em></span> | ||
| 4564 | Before modifying source code, you need to create a new patch. | ||
| 4565 | To create a new patch file, use <code class="filename">quilt new</code> as below: | ||
| 4566 | </p><pre class="literallayout"> | ||
| 4567 | $ quilt new my_changes.patch | ||
| 4568 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Notify Quilt and Add Files:</em></span> | ||
| 4569 | After creating the patch, you need to notify Quilt about the files you will | ||
| 4570 | be changing. | ||
| 4571 | Add the files you will be modifying into the patch you just created: | ||
| 4572 | </p><pre class="literallayout"> | ||
| 4573 | $ quilt add file1.c file2.c file3.c | ||
| 4574 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Edit the Files:</em></span> | ||
| 4575 | Make the changes to the temporary source code.</p></li><li class="listitem"><p><span class="emphasis"><em>Test Your Changes:</em></span> | ||
| 4576 | Once you have modified the source code, the easiest way to test your changes | ||
| 4577 | is by calling the <code class="filename">compile</code> task as shown in the following example: | ||
| 4578 | </p><pre class="literallayout"> | ||
| 4579 | $ bitbake -c compile -f <name_of_package> | ||
| 4580 | </pre><p> | ||
| 4581 | The <code class="filename">-f</code> or <code class="filename">--force</code> | ||
| 4582 | option forces re-execution of the specified task. | ||
| 4583 | If you find problems with your code, you can just keep editing and | ||
| 4584 | re-testing iteratively until things work as expected. | ||
| 4585 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>All the modifications you make to the temporary source code | ||
| 4586 | disappear once you <code class="filename">-c clean</code> or | ||
| 4587 | <code class="filename">-c cleanall</code> with BitBake for the package. | ||
| 4588 | Modifications will also disappear if you use the <code class="filename">rm_work</code> | ||
| 4589 | feature as described in the | ||
| 4590 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" | ||
| 4591 | section of the Yocto Project Quick Start. | ||
| 4592 | </div></li><li class="listitem"><p><span class="emphasis"><em>Generate the Patch:</em></span> | ||
| 4593 | Once your changes work as expected, you need to use Quilt to generate the final patch that | ||
| 4594 | contains all your modifications. | ||
| 4595 | </p><pre class="literallayout"> | ||
| 4596 | $ quilt refresh | ||
| 4597 | </pre><p> | ||
| 4598 | At this point the <code class="filename">my_changes.patch</code> file has all your edits made | ||
| 4599 | to the <code class="filename">file1.c</code>, <code class="filename">file2.c</code>, and | ||
| 4600 | <code class="filename">file3.c</code> files.</p><p>You can find the resulting patch file in the <code class="filename">patches/</code> | ||
| 4601 | subdirectory of the source (<code class="filename">S</code>) directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Copy the Patch File:</em></span> | ||
| 4602 | For simplicity, copy the patch file into a directory named <code class="filename">files</code>, | ||
| 4603 | which you can create in the same directory as the recipe. | ||
| 4604 | Placing the patch here guarantees that the OpenEmbedded build system will find | ||
| 4605 | the patch. | ||
| 4606 | Next, add the patch into the | ||
| 4607 | <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> | ||
| 4608 | of the recipe. | ||
| 4609 | Here is an example: | ||
| 4610 | </p><pre class="literallayout"> | ||
| 4611 | SRC_URI += "file://my_changes.patch" | ||
| 4612 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Increment the Package Revision Number:</em></span> | ||
| 4613 | Finally, don't forget to 'bump' the | ||
| 4614 | <code class="filename"><a class="link" href="#var-PR" target="_top">PR</a></code> | ||
| 4615 | value in the same recipe since the resulting packages have changed.</p></li></ol></div><p> | ||
| 4616 | </p></div><div class="section" title="5.3.3. Using a Git Workflow"><div class="titlepage"><div><div><h3 class="title"><a id="using-a-git-workflow"></a>5.3.3. Using a Git Workflow</h3></div></div></div><p> | ||
| 4617 | Git is an even more powerful tool that allows you to capture source code changes without having | ||
| 4618 | a clean source tree. | ||
| 4619 | This section outlines the typical workflow you can use to modify temporary source code, | ||
| 4620 | test changes, and then preserve the changes in the form of a patch all using Git. | ||
| 4621 | For general information on Git as it is used in the Yocto Project, see the | ||
| 4622 | "<a class="link" href="#git" title="3.6. Git">Git</a>" section. | ||
| 4623 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 4624 | This workflow uses Git only for its ability to manage local changes to the source code | ||
| 4625 | and produce patches independent of any version control system used with the Yocto Project. | ||
| 4626 | </div><p> | ||
| 4627 | Follow these general steps: | ||
| 4628 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Find the Source Code:</em></span> | ||
| 4629 | The temporary source code used by the OpenEmbedded build system is kept in the | ||
| 4630 | build directory. | ||
| 4631 | See the | ||
| 4632 | "<a class="link" href="#finding-the-temporary-source-code" title="5.3.1. Finding the Temporary Source Code">Finding the Temporary Source Code</a>" | ||
| 4633 | section to learn how to locate the directory that has the temporary source code for a | ||
| 4634 | particular package.</p></li><li class="listitem"><p><span class="emphasis"><em>Change Your Working Directory:</em></span> | ||
| 4635 | You need to be in the directory that has the temporary source code. | ||
| 4636 | That directory is defined by the | ||
| 4637 | <a class="link" href="#var-S" target="_top">S</a> | ||
| 4638 | variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Initialize a Git Repository:</em></span> | ||
| 4639 | Use the <code class="filename">git init</code> command to initialize a new local repository | ||
| 4640 | that is based on the work directory: | ||
| 4641 | </p><pre class="literallayout"> | ||
| 4642 | $ git init | ||
| 4643 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Stage all the files:</em></span> | ||
| 4644 | Use the <code class="filename">git add *</code> command to stage all the files in the source | ||
| 4645 | code directory so that they can be committed: | ||
| 4646 | </p><pre class="literallayout"> | ||
| 4647 | $ git add * | ||
| 4648 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Commit the Source Files:</em></span> | ||
| 4649 | Use the <code class="filename">git commit</code> command to initially commit all the files in | ||
| 4650 | the work directory: | ||
| 4651 | </p><pre class="literallayout"> | ||
| 4652 | $ git commit | ||
| 4653 | </pre><p> | ||
| 4654 | At this point, your Git repository is aware of all the source code files. | ||
| 4655 | Any edits you now make to files will be tracked by Git.</p></li><li class="listitem"><p><span class="emphasis"><em>Edit the Files:</em></span> | ||
| 4656 | Make the changes to the temporary source code.</p></li><li class="listitem"><p><span class="emphasis"><em>Test Your Changes:</em></span> | ||
| 4657 | Once you have modified the source code, the easiest way to test your changes | ||
| 4658 | is by calling the <code class="filename">compile</code> task as shown in the following example: | ||
| 4659 | </p><pre class="literallayout"> | ||
| 4660 | $ bitbake -c compile -f <name_of_package> | ||
| 4661 | </pre><p> | ||
| 4662 | The <code class="filename">-f</code> or <code class="filename">--force</code> | ||
| 4663 | option forces re-execution of the specified task. | ||
| 4664 | If you find problems with your code, you can just keep editing and | ||
| 4665 | re-testing iteratively until things work as expected. | ||
| 4666 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>All the modifications you make to the temporary source code | ||
| 4667 | disappear once you <code class="filename">-c clean</code> or | ||
| 4668 | <code class="filename">-c cleanall</code> with BitBake for the package. | ||
| 4669 | Modifications will also disappear if you use the <code class="filename">rm_work</code> | ||
| 4670 | feature as described in the | ||
| 4671 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" | ||
| 4672 | section of the Yocto Project Quick Start. | ||
| 4673 | </div></li><li class="listitem"><p><span class="emphasis"><em>See the List of Files You Changed:</em></span> | ||
| 4674 | Use the <code class="filename">git status</code> command to see what files you have actually edited. | ||
| 4675 | The ability to have Git track the files you have changed is an advantage that this | ||
| 4676 | workflow has over the Quilt workflow. | ||
| 4677 | Here is the Git command to list your changed files: | ||
| 4678 | </p><pre class="literallayout"> | ||
| 4679 | $ git status | ||
| 4680 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Stage the Modified Files:</em></span> | ||
| 4681 | Use the <code class="filename">git add</code> command to stage the changed files so they | ||
| 4682 | can be committed as follows: | ||
| 4683 | </p><pre class="literallayout"> | ||
| 4684 | $ git add file1.c file2.c file3.c | ||
| 4685 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Commit the Staged Files and View Your Changes:</em></span> | ||
| 4686 | Use the <code class="filename">git commit</code> command to commit the changes to the | ||
| 4687 | local repository. | ||
| 4688 | Once you have committed the files, you can use the <code class="filename">git log</code> | ||
| 4689 | command to see your changes: | ||
| 4690 | </p><pre class="literallayout"> | ||
| 4691 | $ git commit | ||
| 4692 | $ git log | ||
| 4693 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Generate the Patch:</em></span> | ||
| 4694 | Once the changes are committed, use the <code class="filename">git format-patch</code> | ||
| 4695 | command to generate a patch file: | ||
| 4696 | </p><pre class="literallayout"> | ||
| 4697 | $ git format-patch HEAD~1 | ||
| 4698 | </pre><p> | ||
| 4699 | The <code class="filename">HEAD~1</code> part of the command causes Git to generate the | ||
| 4700 | patch file for the most recent commit.</p><p>At this point, the patch file has all your edits made | ||
| 4701 | to the <code class="filename">file1.c</code>, <code class="filename">file2.c</code>, and | ||
| 4702 | <code class="filename">file3.c</code> files. | ||
| 4703 | You can find the resulting patch file in the current directory. | ||
| 4704 | The patch file ends with <code class="filename">.patch</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Copy the Patch File:</em></span> | ||
| 4705 | For simplicity, copy the patch file into a directory named <code class="filename">files</code>, | ||
| 4706 | which you can create in the same directory as the recipe. | ||
| 4707 | Placing the patch here guarantees that the OpenEmbedded build system will find | ||
| 4708 | the patch. | ||
| 4709 | Next, add the patch into the | ||
| 4710 | <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> | ||
| 4711 | of the recipe. | ||
| 4712 | Here is an example: | ||
| 4713 | </p><pre class="literallayout"> | ||
| 4714 | SRC_URI += "file://my_changes.patch" | ||
| 4715 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Increment the Package Revision Number:</em></span> | ||
| 4716 | Finally, don't forget to 'bump' the | ||
| 4717 | <code class="filename"><a class="link" href="#var-PR" target="_top">PR</a></code> | ||
| 4718 | value in the same recipe since the resulting packages have changed.</p></li></ol></div><p> | ||
| 4719 | </p></div></div><div class="section" title="5.4. Image Development Using Hob"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="image-development-using-hob"></a>5.4. Image Development Using Hob</h2></div></div></div><p> | ||
| 4720 | The <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> is a graphical user interface for the | ||
| 4721 | OpenEmbedded build system, which is based on BitBake. | ||
| 4722 | You can use the Hob to build custom operating system images within the Yocto Project build environment. | ||
| 4723 | Hob simply provides a friendly interface over the build system used during system development. | ||
| 4724 | In other words, building images with the Hob lets you take care of common build tasks more easily. | ||
| 4725 | </p><p> | ||
| 4726 | For a better understanding of Hob, see the project page at | ||
| 4727 | <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">http://www.yoctoproject.org/projects/hob</a> on the Yocto Project website. | ||
| 4728 | The page has a short introductory training video on Hob. | ||
| 4729 | The following lists some features of Hob: | ||
| 4730 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can setup and run Hob using these commands: | ||
| 4731 | </p><pre class="literallayout"> | ||
| 4732 | $ source oe-init-build-env | ||
| 4733 | $ hob | ||
| 4734 | </pre></li><li class="listitem"><p>You can set the | ||
| 4735 | <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> | ||
| 4736 | for which you are building the image.</p></li><li class="listitem"><p>You can modify various policy settings such as the package format used to build with, | ||
| 4737 | the parrallelism BitBake uses, whether or not to build an external toolchain, and which host | ||
| 4738 | to build against.</p></li><li class="listitem"><p>You can manage | ||
| 4739 | <a class="link" href="#understanding-and-creating-layers" title="4.1. Understanding and Creating Layers">layers</a>.</p></li><li class="listitem"><p>You can select a base image and then add extra packages for your custom build. | ||
| 4740 | </p></li><li class="listitem"><p>You can launch and monitor the build from within Hob.</p></li></ul></div><p> | ||
| 4741 | </p></div><div class="section" title="5.5. Using a Development Shell"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-appdev-devshell"></a>5.5. Using a Development Shell</h2></div></div></div><p> | ||
| 4742 | When debugging certain commands or even when just editing packages, | ||
| 4743 | <code class="filename">devshell</code> can be a useful tool. | ||
| 4744 | When you invoke <code class="filename">devshell</code>, source files are | ||
| 4745 | extracted into your working directory and patches are applied. | ||
| 4746 | Then, a new terminal is opened and you are placed in the working directory. | ||
| 4747 | In the new terminal, all the OpenEmbedded build-related environment variables are | ||
| 4748 | still defined so you can use commands such as <code class="filename">configure</code> and | ||
| 4749 | <code class="filename">make</code>. | ||
| 4750 | The commands execute just as if the OpenEmbedded build system were executing them. | ||
| 4751 | Consequently, working this way can be helpful when debugging a build or preparing | ||
| 4752 | software to be used with the OpenEmbedded build system. | ||
| 4753 | </p><p> | ||
| 4754 | Following is an example that uses <code class="filename">devshell</code> on a target named | ||
| 4755 | <code class="filename">matchbox-desktop</code>: | ||
| 4756 | </p><pre class="literallayout"> | ||
| 4757 | $ bitbake matchbox-desktop -c devshell | ||
| 4758 | </pre><p> | ||
| 4759 | </p><p> | ||
| 4760 | This command opens a terminal with a shell prompt within the OpenEmbedded build environment. | ||
| 4761 | The default shell is xterm. | ||
| 4762 | The following occurs: | ||
| 4763 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">PATH</code> variable includes the | ||
| 4764 | cross-toolchain.</p></li><li class="listitem"><p>The <code class="filename">pkgconfig</code> variables find the correct | ||
| 4765 | <code class="filename">.pc</code> files.</p></li><li class="listitem"><p>The <code class="filename">configure</code> command finds the | ||
| 4766 | Yocto Project site files as well as any other necessary files.</p></li></ul></div><p> | ||
| 4767 | Within this environment, you can run <code class="filename">configure</code> | ||
| 4768 | or <code class="filename">compile</code> commands as if they were being run by | ||
| 4769 | the OpenEmbedded build system itself. | ||
| 4770 | As noted earlier, the working directory also automatically changes to the | ||
| 4771 | source directory (<a class="link" href="#var-S" target="_top"><code class="filename">S</code></a>). | ||
| 4772 | </p><p> | ||
| 4773 | When you are finished, you just exit the shell or close the terminal window. | ||
| 4774 | </p><p> | ||
| 4775 | Because an external shell is launched rather than opening directly into the | ||
| 4776 | original terminal window, it allows easier interaction with BitBake's multiple | ||
| 4777 | threads as well as accomodates a future client/server split. | ||
| 4778 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 4779 | It is worth remembering that when using <code class="filename">devshell</code> | ||
| 4780 | you need to use the full compiler name such as <code class="filename">arm-poky-linux-gnueabi-gcc</code> | ||
| 4781 | instead of just using <code class="filename">gcc</code>. | ||
| 4782 | The same applies to other applications such as <code class="filename">binutils</code>, | ||
| 4783 | <code class="filename">libtool</code> and so forth. | ||
| 4784 | BitBake sets up environment variables such as <code class="filename">CC</code> | ||
| 4785 | to assist applications, such as <code class="filename">make</code> to find the correct tools. | ||
| 4786 | </p><p> | ||
| 4787 | It is also worth noting that <code class="filename">devshell</code> still works over | ||
| 4788 | X11 forwarding and similar situations | ||
| 4789 | </p></div></div></div> | ||
| 4790 | |||
| 4791 | <div class="appendix" title="Appendix A. BSP Development Example"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-bsp-appendix"></a>Appendix A. BSP Development Example</h2></div></div></div><p> | ||
| 4792 | This appendix provides a complete BSP development example. | ||
| 4793 | The example assumes the following: | ||
| 4794 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>No previous preparation or use of the Yocto Project.</p></li><li class="listitem"><p>Use of the Crown Bay Board Support Package (BSP) as a "base" BSP from | ||
| 4795 | which to work. | ||
| 4796 | The example begins with the Crown Bay BSP as the starting point | ||
| 4797 | but ends by building a new 'atom-pc' BSP, which was based on the Crown Bay BSP. | ||
| 4798 | </p></li><li class="listitem"><p>Shell commands assume <code class="filename">bash</code></p></li><li class="listitem"><p>Example was developed on an Intel-based Core i7 platform running | ||
| 4799 | Ubuntu 10.04 LTS released in April of 2010.</p></li></ul></div><p> | ||
| 4800 | </p><div class="section" title="A.1. Getting Local Source Files and BSP Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="getting-local-yocto-project-files-and-bsp-files"></a>A.1. Getting Local Source Files and BSP Files</h2></div></div></div><p> | ||
| 4801 | You need to have the <a class="link" href="#source-directory">source directory</a> | ||
| 4802 | available on your host system. | ||
| 4803 | You can set up this directory through tarball extraction or by cloning the | ||
| 4804 | <code class="filename">poky</code> Git repository. | ||
| 4805 | The following paragraphs describe both methods. | ||
| 4806 | For additional information, see the bulleted item | ||
| 4807 | "<a class="link" href="#local-yp-release">Yocto Project Release</a>". | ||
| 4808 | </p><p> | ||
| 4809 | As mentioned, one way to set up the source directory is to use Git to clone the | ||
| 4810 | <code class="filename">poky</code> repository. | ||
| 4811 | These commands create a local copy of the Git repository. | ||
| 4812 | By default, the top-level directory of the repository is named <code class="filename">poky</code>: | ||
| 4813 | </p><pre class="literallayout"> | ||
| 4814 | $ git clone git://git.yoctoproject.org/poky | ||
| 4815 | $ cd poky | ||
| 4816 | </pre><p> | ||
| 4817 | Alternatively, you can start with the downloaded Poky "1.2+snapshot" tarball. | ||
| 4818 | These commands unpack the tarball into a source directory structure. | ||
| 4819 | By default, the top-level directory of the source directory is named | ||
| 4820 | <code class="filename">poky-1.2+snapshot-8.0</code>: | ||
| 4821 | </p><pre class="literallayout"> | ||
| 4822 | $ tar xfj poky-1.2+snapshot-8.0.tar.bz2 | ||
| 4823 | $ cd poky-1.2+snapshot-8.0 | ||
| 4824 | </pre><p> | ||
| 4825 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you're using the tarball method, you can ignore all the following steps that | ||
| 4826 | ask you to carry out Git operations. | ||
| 4827 | You already have the results of those operations | ||
| 4828 | in the form of the 1.2+snapshot release tarballs. | ||
| 4829 | Consequently, there is nothing left to do other than extract those tarballs into the | ||
| 4830 | proper locations.</p><p>Once you expand the released tarball, you have a snapshot of the Git repository | ||
| 4831 | that represents a specific release. | ||
| 4832 | Fundamentally, this is different than having a local copy of the Poky Git repository. | ||
| 4833 | Given the tarball method, changes you make are building on top of a release. | ||
| 4834 | With the Git repository method you have the ability to track development | ||
| 4835 | and keep changes in revision control. | ||
| 4836 | See the | ||
| 4837 | "<a class="link" href="#repositories-tags-and-branches" title="3.6.1. Repositories, Tags, and Branches">Repositories, Tags, and Branches</a>" section | ||
| 4838 | for more discussion around these differences.</p></div><p> | ||
| 4839 | </p><p> | ||
| 4840 | With the local <code class="filename">poky</code> Git repository set up, | ||
| 4841 | you have all the development branches available to you from which you can work. | ||
| 4842 | Next, you need to be sure that your local repository reflects the exact | ||
| 4843 | release in which you are interested. | ||
| 4844 | From inside the repository you can see the development branches that represent | ||
| 4845 | areas of development that have diverged from the main (master) branch | ||
| 4846 | at some point, such as a branch to track a maintenance release's development. | ||
| 4847 | You can also see the tag names used to mark snapshots of stable releases or | ||
| 4848 | points in the repository. | ||
| 4849 | Use the following commands to list out the branches and the tags in the repository, | ||
| 4850 | respectively. | ||
| 4851 | </p><pre class="literallayout"> | ||
| 4852 | $ git branch -a | ||
| 4853 | $ git tag -l | ||
| 4854 | </pre><p> | ||
| 4855 | For this example, we are going to use the Yocto Project 1.3 Release, which is code | ||
| 4856 | named "1.2+snapshot". | ||
| 4857 | To make sure we have a local area (branch in Git terms) on our machine that | ||
| 4858 | reflects the 1.3 release, we can use the following commands: | ||
| 4859 | </p><pre class="literallayout"> | ||
| 4860 | $ cd ~/poky | ||
| 4861 | $ git fetch --tags | ||
| 4862 | $ git checkout 1.2+snapshot-8.0 -b 1.2+snapshot | ||
| 4863 | Switched to a new branch '1.2+snapshot' | ||
| 4864 | </pre><p> | ||
| 4865 | The <code class="filename">git fetch --tags</code> is somewhat redundant since you just set | ||
| 4866 | up the repository and should have all the tags. | ||
| 4867 | The <code class="filename">fetch</code> command makes sure all the tags are available in your | ||
| 4868 | local repository. | ||
| 4869 | The Git <code class="filename">checkout</code> command with the <code class="filename">-b</code> option | ||
| 4870 | creates a local branch for you named <code class="filename">1.2+snapshot</code>. | ||
| 4871 | Your local branch begins in the same state as the Yocto Project 1.3 released tarball | ||
| 4872 | marked with the <code class="filename">1.2+snapshot-8.0</code> tag in the source repositories. | ||
| 4873 | </p></div><div class="section" title="A.2. Choosing a Base BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="choosing-a-base-bsp-app"></a>A.2. Choosing a Base BSP</h2></div></div></div><p> | ||
| 4874 | For this example, the base BSP is the <span class="trademark">Intel</span>® | ||
| 4875 | <span class="trademark">Atom</span>™ Processor E660 with Intel Platform | ||
| 4876 | Controller Hub EG20T Development Kit, which is otherwise referred to as "Crown Bay." | ||
| 4877 | The BSP layer is <code class="filename">meta-crownbay</code>. | ||
| 4878 | The base BSP is simply the BSP | ||
| 4879 | we will be using as a starting point, so don't worry if you don't actually have Crown Bay | ||
| 4880 | hardware. | ||
| 4881 | The remainder of the example transforms the base BSP into a BSP that should be | ||
| 4882 | able to boot on generic atom-pc (netbook) hardware. | ||
| 4883 | </p><p> | ||
| 4884 | For information on how to choose a base BSP, see | ||
| 4885 | "<a class="link" href="#developing-a-board-support-package-bsp" title="5.1.1. Developing a Board Support Package (BSP)">Developing a Board Support Package (BSP)</a>". | ||
| 4886 | </p></div><div class="section" title="A.3. Getting Your Base BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="getting-your-base-bsp-app"></a>A.3. Getting Your Base BSP</h2></div></div></div><p> | ||
| 4887 | You need to have the base BSP layer on your development system. | ||
| 4888 | Similar to the local <a class="link" href="#source-directory">source directory</a>, | ||
| 4889 | you can get the BSP | ||
| 4890 | layer in a couple of different ways: | ||
| 4891 | download the BSP tarball and extract it, or set up a local Git repository that | ||
| 4892 | has the BSP layers. | ||
| 4893 | You should use the same method that you used to set up the source directory earlier. | ||
| 4894 | See "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Setup</a>" for information on how to get | ||
| 4895 | the BSP files. | ||
| 4896 | </p><p> | ||
| 4897 | This example assumes the BSP layer will be located within a directory named | ||
| 4898 | <code class="filename">meta-intel</code> contained within the <code class="filename">poky</code> | ||
| 4899 | parent directory. | ||
| 4900 | The following steps will automatically create the | ||
| 4901 | <code class="filename">meta-intel</code> directory and the contained | ||
| 4902 | <code class="filename">meta-crownbay</code> starting point in both the Git and the tarball cases. | ||
| 4903 | </p><p> | ||
| 4904 | If you're using the Git method, you could do the following to create | ||
| 4905 | the starting layout after you have made sure you are in the <code class="filename">poky</code> | ||
| 4906 | directory created in the previous steps: | ||
| 4907 | </p><pre class="literallayout"> | ||
| 4908 | $ git clone git://git.yoctoproject.org/meta-intel.git | ||
| 4909 | $ cd meta-intel | ||
| 4910 | </pre><p> | ||
| 4911 | Alternatively, you can start with the downloaded Crown Bay tarball. | ||
| 4912 | You can download the 1.2+snapshot version of the BSP tarball from the | ||
| 4913 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Download</a> page of the | ||
| 4914 | Yocto Project website. | ||
| 4915 | Here is the specific link for the tarball needed for this example: | ||
| 4916 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/crownbay-noemgd/crownbay-noemgd-1.2+snapshot-8.0.tar.bz2" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/crownbay-noemgd/crownbay-noemgd-1.2+snapshot-8.0.tar.bz2</a>. | ||
| 4917 | Again, be sure that you are already in the <code class="filename">poky</code> directory | ||
| 4918 | as described previously before installing the tarball: | ||
| 4919 | </p><pre class="literallayout"> | ||
| 4920 | $ tar xfj crownbay-noemgd-1.2+snapshot-8.0.tar.bz2 | ||
| 4921 | $ cd meta-intel | ||
| 4922 | </pre><p> | ||
| 4923 | </p><p> | ||
| 4924 | The <code class="filename">meta-intel</code> directory contains all the metadata | ||
| 4925 | that supports BSP creation. | ||
| 4926 | If you're using the Git method, the following | ||
| 4927 | step will switch to the 1.2+snapshot metadata. | ||
| 4928 | If you're using the tarball method, you already have the correct metadata and can | ||
| 4929 | skip to the next step. | ||
| 4930 | Because <code class="filename">meta-intel</code> is its own Git repository, you will want | ||
| 4931 | to be sure you are in the appropriate branch for your work. | ||
| 4932 | For this example we are going to use the <code class="filename">1.2+snapshot</code> branch. | ||
| 4933 | </p><pre class="literallayout"> | ||
| 4934 | $ git checkout -b 1.2+snapshot origin/1.2+snapshot | ||
| 4935 | Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. | ||
| 4936 | Switched to a new branch '1.2+snapshot' | ||
| 4937 | </pre><p> | ||
| 4938 | </p></div><div class="section" title="A.4. Making a Copy of the Base BSP to Create Your New BSP Layer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app"></a>A.4. Making a Copy of the Base BSP to Create Your New BSP Layer</h2></div></div></div><p> | ||
| 4939 | Now that you have set up the source directory and included the base BSP files, you need to | ||
| 4940 | create a new layer for your BSP. | ||
| 4941 | To create your BSP layer, you simply copy the <code class="filename">meta-crownbay</code> | ||
| 4942 | layer to a new layer. | ||
| 4943 | </p><p> | ||
| 4944 | For this example, the new layer will be named <code class="filename">meta-mymachine</code>. | ||
| 4945 | The name should follow the BSP layer naming convention, which is | ||
| 4946 | <code class="filename">meta-<name></code>. | ||
| 4947 | The following assumes your working directory is <code class="filename">meta-intel</code> | ||
| 4948 | inside your source directory. | ||
| 4949 | To start your new layer, just copy the new layer alongside the existing | ||
| 4950 | BSP layers in the <code class="filename">meta-intel</code> directory: | ||
| 4951 | </p><pre class="literallayout"> | ||
| 4952 | $ cp -a meta-crownbay/ meta-mymachine | ||
| 4953 | </pre><p> | ||
| 4954 | </p></div><div class="section" title="A.5. Making Changes to Your BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="making-changes-to-your-bsp-app"></a>A.5. Making Changes to Your BSP</h2></div></div></div><p> | ||
| 4955 | Right now you have two identical BSP layers with different names: | ||
| 4956 | <code class="filename">meta-crownbay</code> and <code class="filename">meta-mymachine</code>. | ||
| 4957 | You need to change your configurations so that they work for your new BSP and | ||
| 4958 | your particular hardware. | ||
| 4959 | The following sections look at each of these areas of the BSP. | ||
| 4960 | </p><div class="section" title="A.5.1. Changing the BSP Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-bsp-configuration"></a>A.5.1. Changing the BSP Configuration</h3></div></div></div><p> | ||
| 4961 | We will look first at the configurations, which are all done in the layer’s | ||
| 4962 | <code class="filename">conf</code> directory. | ||
| 4963 | </p><p> | ||
| 4964 | First, since in this example the new BSP will not support EMGD, we will get rid of the | ||
| 4965 | <code class="filename">crownbay.conf</code> file and then rename the | ||
| 4966 | <code class="filename">crownbay-noemgd.conf</code> file to <code class="filename">mymachine.conf</code>. | ||
| 4967 | Much of what we do in the configuration directory is designed to help the OpenEmbedded | ||
| 4968 | build system work with the new layer and to be able to find and use the right software. | ||
| 4969 | The following two commands result in a single machine configuration file named | ||
| 4970 | <code class="filename">mymachine.conf</code>. | ||
| 4971 | </p><pre class="literallayout"> | ||
| 4972 | $ rm meta-mymachine/conf/machine/crownbay.conf | ||
| 4973 | $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ | ||
| 4974 | meta-mymachine/conf/machine/mymachine.conf | ||
| 4975 | </pre><p> | ||
| 4976 | </p><p> | ||
| 4977 | Next, we need to make changes to the <code class="filename">mymachine.conf</code> itself. | ||
| 4978 | The only changes we want to make for this example are to the comment lines. | ||
| 4979 | Changing comments, of course, is never strictly necessary, but it's alway good form to make | ||
| 4980 | them reflect reality as much as possible. | ||
| 4981 | |||
| 4982 | Here, simply substitute the Crown Bay name with an appropriate name for the BSP | ||
| 4983 | (<code class="filename">mymachine</code> in this case) and change the description to | ||
| 4984 | something that describes your hardware. | ||
| 4985 | </p><p> | ||
| 4986 | Note that inside the <code class="filename">mymachine.conf</code> is the | ||
| 4987 | <code class="filename">PREFERRED_VERSION_linux-yocto</code> statement. | ||
| 4988 | This statement identifies the kernel that the BSP is going to use. | ||
| 4989 | In this case, the BSP is using <code class="filename">linux-yocto</code>, which is the | ||
| 4990 | current Yocto Project kernel based on the Linux 3.2 release. | ||
| 4991 | </p><p> | ||
| 4992 | The next configuration file in the new BSP layer we need to edit is | ||
| 4993 | <code class="filename">meta-mymachine/conf/layer.conf</code>. | ||
| 4994 | This file identifies build information needed for the new layer. | ||
| 4995 | You can see the | ||
| 4996 | "<a class="link" href="#bsp-filelayout-layer" target="_top">Layer Configuration File</a>" section | ||
| 4997 | in The Board Support Packages (BSP) Development Guide for more information on this configuration file. | ||
| 4998 | Basically, we are changing the existing statements to work with our BSP. | ||
| 4999 | </p><p> | ||
| 5000 | The file contains these statements that reference the Crown Bay BSP: | ||
| 5001 | </p><pre class="literallayout"> | ||
| 5002 | BBFILE_COLLECTIONS += "crownbay" | ||
| 5003 | BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" | ||
| 5004 | BBFILE_PRIORITY_crownbay = "6" | ||
| 5005 | |||
| 5006 | LAYERDEPENDS_crownbay = "intel" | ||
| 5007 | </pre><p> | ||
| 5008 | </p><p> | ||
| 5009 | Simply substitute the machine string name <code class="filename">crownbay</code> | ||
| 5010 | with the new machine name <code class="filename">mymachine</code> to get the following: | ||
| 5011 | </p><pre class="literallayout"> | ||
| 5012 | BBFILE_COLLECTIONS += "mymachine" | ||
| 5013 | BBFILE_PATTERN_mymachine := "^${LAYERDIR}/" | ||
| 5014 | BBFILE_PRIORITY_mymachine = "6" | ||
| 5015 | |||
| 5016 | LAYERDEPENDS_mymachine = "intel" | ||
| 5017 | </pre><p> | ||
| 5018 | </p></div><div class="section" title="A.5.2. Changing the Recipes in Your BSP"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-recipes-in-your-bsp"></a>A.5.2. Changing the Recipes in Your BSP</h3></div></div></div><p> | ||
| 5019 | Now we will take a look at the recipes in your new layer. | ||
| 5020 | The standard BSP structure has areas for BSP, graphics, core, and kernel recipes. | ||
| 5021 | When you create a BSP, you use these areas for appropriate recipes and append files. | ||
| 5022 | Recipes take the form of <code class="filename">.bb</code> files, while append files take | ||
| 5023 | the form of <code class="filename">.bbappend</code> files. | ||
| 5024 | If you want to leverage the existing recipes the OpenEmbedded build system uses | ||
| 5025 | but change those recipes, you can use <code class="filename">.bbappend</code> files. | ||
| 5026 | All new recipes and append files for your layer must go in the layer’s | ||
| 5027 | <code class="filename">recipes-bsp</code>, <code class="filename">recipes-kernel</code>, | ||
| 5028 | <code class="filename">recipes-core</code>, and | ||
| 5029 | <code class="filename">recipes-graphics</code> directories. | ||
| 5030 | </p><div class="section" title="A.5.2.1. Changing recipes-bsp"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-bsp"></a>A.5.2.1. Changing <code class="filename">recipes-bsp</code></h4></div></div></div><p> | ||
| 5031 | First, let's look at <code class="filename">recipes-bsp</code>. | ||
| 5032 | For this example we are not adding any new BSP recipes. | ||
| 5033 | And, we only need to remove the formfactor we do not want and change the name of | ||
| 5034 | the remaining one that doesn't support EMGD. | ||
| 5035 | These commands take care of the <code class="filename">recipes-bsp</code> recipes: | ||
| 5036 | </p><pre class="literallayout"> | ||
| 5037 | $ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay | ||
| 5038 | $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ | ||
| 5039 | meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine | ||
| 5040 | </pre><p> | ||
| 5041 | </p></div><div class="section" title="A.5.2.2. Changing recipes-graphics"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-graphics"></a>A.5.2.2. Changing <code class="filename">recipes-graphics</code></h4></div></div></div><p> | ||
| 5042 | Now let's look at <code class="filename">recipes-graphics</code>. | ||
| 5043 | For this example we want to remove anything that supports EMGD and | ||
| 5044 | be sure to rename remaining directories appropriately. | ||
| 5045 | The following commands clean up the <code class="filename">recipes-graphics</code> directory: | ||
| 5046 | </p><pre class="literallayout"> | ||
| 5047 | $ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay | ||
| 5048 | $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \ | ||
| 5049 | meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine | ||
| 5050 | </pre><p> | ||
| 5051 | </p><p> | ||
| 5052 | At this point the <code class="filename">recipes-graphics</code> directory just has files that | ||
| 5053 | support Video Electronics Standards Association (VESA) graphics modes and not EMGD. | ||
| 5054 | </p></div><div class="section" title="A.5.2.3. Changing recipes-core"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-core"></a>A.5.2.3. Changing <code class="filename">recipes-core</code></h4></div></div></div><p> | ||
| 5055 | Now let's look at changes in <code class="filename">recipes-core</code>. | ||
| 5056 | The file <code class="filename">task-core-tools.bbappend</code> in | ||
| 5057 | <code class="filename">recipes-core/tasks</code> appends the similarly named recipe | ||
| 5058 | located in the <a class="link" href="#source-directory">source directory</a> at | ||
| 5059 | <code class="filename">meta/recipes-core/tasks</code>. | ||
| 5060 | The append file in our layer right now is Crown Bay-specific and supports | ||
| 5061 | EMGD and non-EMGD. | ||
| 5062 | Here are the contents of the file: | ||
| 5063 | </p><pre class="literallayout"> | ||
| 5064 | RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap" | ||
| 5065 | RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap" | ||
| 5066 | </pre><p> | ||
| 5067 | </p><p> | ||
| 5068 | The <code class="filename">RRECOMMENDS</code> statements list packages that | ||
| 5069 | extend usability. | ||
| 5070 | The first <code class="filename">RRECOMMENDS</code> statement can be removed, while the | ||
| 5071 | second one can be changed to reflect <code class="filename">meta-mymachine</code>: | ||
| 5072 | </p><pre class="literallayout"> | ||
| 5073 | RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap" | ||
| 5074 | </pre><p> | ||
| 5075 | </p></div><div class="section" title="A.5.2.4. Changing recipes-kernel"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-kernel"></a>A.5.2.4. Changing <code class="filename">recipes-kernel</code></h4></div></div></div><p> | ||
| 5076 | Finally, let's look at <code class="filename">recipes-kernel</code> changes. | ||
| 5077 | Recall that the BSP uses the <code class="filename">linux-yocto</code> kernel as determined | ||
| 5078 | earlier in the <code class="filename">mymachine.conf</code>. | ||
| 5079 | The recipe for that kernel is not located in the | ||
| 5080 | BSP layer but rather in the source directory at | ||
| 5081 | <code class="filename">meta/recipes-kernel/linux</code> and is | ||
| 5082 | named <code class="filename">linux-yocto_3.2.bb</code>. | ||
| 5083 | The <code class="filename">SRCREV_machine</code> and <code class="filename">SRCREV_meta</code> | ||
| 5084 | statements point to the exact commits used by the Yocto Project development team | ||
| 5085 | in their source repositories that identify the right kernel for our hardware. | ||
| 5086 | In other words, the <code class="filename">SRCREV</code> values are simply Git commit | ||
| 5087 | IDs that identify which commit on each | ||
| 5088 | of the kernel branches (machine and meta) will be checked out and used to build | ||
| 5089 | the kernel. | ||
| 5090 | </p><p> | ||
| 5091 | However, in the <code class="filename">meta-mymachine</code> layer in | ||
| 5092 | <code class="filename">recipes-kernel/linux</code> resides a <code class="filename">.bbappend</code> | ||
| 5093 | file named <code class="filename">linux-yocto_3.2.bbappend</code> that | ||
| 5094 | appends information to the recipe of the same name in <code class="filename">meta/recipes-kernel/linux</code>. | ||
| 5095 | Thus, the <code class="filename">SRCREV</code> statements in the append file override | ||
| 5096 | the more general statements found in <code class="filename">meta</code>. | ||
| 5097 | </p><p> | ||
| 5098 | The <code class="filename">SRCREV</code> statements in the append file currently identify | ||
| 5099 | the kernel that supports the Crown Bay BSP with and without EMGD support. | ||
| 5100 | Here are the statements: | ||
| 5101 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The commit ID strings used in this manual might not match the actual commit | ||
| 5102 | ID strings found in the <code class="filename">linux-yocto_3.2.bbappend</code> file. | ||
| 5103 | For the example, this difference does not matter.</div><p> | ||
| 5104 | </p><pre class="literallayout"> | ||
| 5105 | SRCREV_machine_pn-linux-yocto_crownbay ?= \ | ||
| 5106 | "211fc7f4d10ec2b82b424286aabbaff9254b7cbd" | ||
| 5107 | SRCREV_meta_pn-linux-yocto_crownbay ?= \ | ||
| 5108 | "514847185c78c07f52e02750fbe0a03ca3a31d8f" | ||
| 5109 | |||
| 5110 | SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \ | ||
| 5111 | "211fc7f4d10ec2b82b424286aabbaff9254b7cbd" | ||
| 5112 | SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \ | ||
| 5113 | "514847185c78c07f52e02750fbe0a03ca3a31d8f" | ||
| 5114 | </pre><p> | ||
| 5115 | </p><p> | ||
| 5116 | You will notice that there are two pairs of <code class="filename">SRCREV</code> statements. | ||
| 5117 | The top pair identifies the kernel that supports | ||
| 5118 | EMGD, which we don’t care about in this example. | ||
| 5119 | The bottom pair identifies the kernel that we will use: | ||
| 5120 | <code class="filename">linux-yocto</code>. | ||
| 5121 | At this point though, the unique commit strings all are still associated with | ||
| 5122 | Crown Bay and not <code class="filename">meta-mymachine</code>. | ||
| 5123 | </p><p> | ||
| 5124 | To fix this situation in <code class="filename">linux-yocto_3.2.bbappend</code>, | ||
| 5125 | we delete the two <code class="filename">SRCREV</code> statements that support | ||
| 5126 | EMGD (the top pair). | ||
| 5127 | We also change the remaining pair to specify <code class="filename">mymachine</code> | ||
| 5128 | and insert the commit identifiers to identify the kernel in which we | ||
| 5129 | are interested, which will be based on the <code class="filename">atom-pc-standard</code> | ||
| 5130 | kernel. | ||
| 5131 | In this case, because we're working with the 1.2+snapshot branch of everything, we | ||
| 5132 | need to use the <code class="filename">SRCREV</code> values for the atom-pc branch | ||
| 5133 | that are associated with the 1.2+snapshot release. | ||
| 5134 | To find those values, we need to find the <code class="filename">SRCREV</code> | ||
| 5135 | values that 1.2+snapshot uses for the atom-pc branch, which we find in the | ||
| 5136 | <code class="filename">poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.2.bbappend</code> | ||
| 5137 | file. | ||
| 5138 | </p><p> | ||
| 5139 | The machine <code class="filename">SRCREV</code> we want is in the | ||
| 5140 | <code class="filename">SRCREV_machine_atom-pc</code> variable. | ||
| 5141 | The meta <code class="filename">SRCREV</code> isn't specified in this file, so it must be | ||
| 5142 | specified in the base kernel recipe in the | ||
| 5143 | <code class="filename">poky/meta/recipes-kernel/linux/linux-yocto_3.2.bb</code> | ||
| 5144 | file, in the <code class="filename">SRCREV_meta</code> variable found there. | ||
| 5145 | Here are the final <code class="filename">SRCREV</code> statements: | ||
| 5146 | </p><pre class="literallayout"> | ||
| 5147 | SRCREV_machine_pn-linux-yocto_mymachine ?= \ | ||
| 5148 | "f29531a41df15d74be5ad47d958e4117ca9e489e" | ||
| 5149 | SRCREV_meta_pn-linux-yocto_mymachine ?= \ | ||
| 5150 | "b14a08f5c7b469a5077c10942f4e1aec171faa9d" | ||
| 5151 | </pre><p> | ||
| 5152 | </p><p> | ||
| 5153 | In this example, we're using the <code class="filename">SRCREV</code> values we | ||
| 5154 | found already captured in the 1.2+snapshot release because we're creating a BSP based on | ||
| 5155 | 1.2+snapshot. | ||
| 5156 | If, instead, we had based our BSP on the master branches, we would want to use | ||
| 5157 | the most recent <code class="filename">SRCREV</code> values taken directly from the kernel repo. | ||
| 5158 | We will not be doing that for this example. | ||
| 5159 | However, if you do base a future BSP on master and | ||
| 5160 | if you are familiar with Git repositories, you probably won’t have trouble locating the | ||
| 5161 | exact commit strings in the Yocto Project source repositories you need to change | ||
| 5162 | the <code class="filename">SRCREV</code> statements. | ||
| 5163 | You can find all the <code class="filename">machine</code> and <code class="filename">meta</code> | ||
| 5164 | branch points (commits) for the <code class="filename">linux-yocto-3.2</code> kernel at | ||
| 5165 | <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.2" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.2</a>. | ||
| 5166 | </p><p> | ||
| 5167 | If you need a little more assistance after going to the link then do the following: | ||
| 5168 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Expand the list of branches by clicking <code class="filename">[…]</code></p></li><li class="listitem"><p>Click on the <code class="filename">standard/default/common-pc/atom-pc</code> | ||
| 5169 | branch</p></li><li class="listitem"><p>Click on the commit column header to view the top commit</p></li><li class="listitem"><p>Copy the commit string for use in the | ||
| 5170 | <code class="filename">linux-yocto_3.2.bbappend</code> file</p></li></ol></div><p> | ||
| 5171 | </p><p> | ||
| 5172 | For the <code class="filename">SRCREV</code> statement that points to the <code class="filename">meta</code> | ||
| 5173 | branch use the same procedure except expand the <code class="filename">meta</code> | ||
| 5174 | branch in step 2 above. | ||
| 5175 | </p><p> | ||
| 5176 | Also in the <code class="filename">linux-yocto_3.2.bbappend</code> file are | ||
| 5177 | <a class="link" href="#var-COMPATIBLE_MACHINE" target="_top"><code class="filename">COMPATIBLE_MACHINE</code></a>, | ||
| 5178 | <a class="link" href="#var-KMACHINE" target="_top"><code class="filename">KMACHINE</code></a>, | ||
| 5179 | and | ||
| 5180 | <a class="link" href="#var-KBRANCH" target="_top"><code class="filename">KBRANCH</code></a> statements. | ||
| 5181 | Two sets of these exist: one set supports EMGD and one set does not. | ||
| 5182 | Because we are not interested in supporting EMGD those three can be deleted. | ||
| 5183 | The remaining three must be changed so that <code class="filename">mymachine</code> replaces | ||
| 5184 | <code class="filename">crownbay-noemgd</code> and <code class="filename">crownbay</code>. | ||
| 5185 | Because we are using the <code class="filename">atom-pc</code> branch for this new BSP, we can also find | ||
| 5186 | the exact branch we need for the <code class="filename">KMACHINE</code> | ||
| 5187 | and <code class="filename">KBRANCH</code> variables in our new BSP from the value | ||
| 5188 | we find in the | ||
| 5189 | <code class="filename">poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.2.bbappend</code> | ||
| 5190 | file we looked at in a previous step. | ||
| 5191 | In this case, the values we want are in the <code class="filename">KMACHINE_atom-pc</code> variable | ||
| 5192 | and the <code class="filename">KBRANCH_atom-pc</code> variables in that file. | ||
| 5193 | Here is the final <code class="filename">linux-yocto_3.2.bbappend</code> file after all | ||
| 5194 | the edits: | ||
| 5195 | </p><pre class="literallayout"> | ||
| 5196 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 5197 | |||
| 5198 | COMPATIBLE_MACHINE_mymachine = "mymachine" | ||
| 5199 | KMACHINE_mymachine = "atom-pc" | ||
| 5200 | KBRANCH_mymachine = "standard/default/common-pc/atom-pc" | ||
| 5201 | |||
| 5202 | SRCREV_machine_pn-linux-yocto_mymachine ?= \ | ||
| 5203 | "f29531a41df15d74be5ad47d958e4117ca9e489e" | ||
| 5204 | SRCREV_meta_pn-linux-yocto_mymachine ?= \ | ||
| 5205 | "b14a08f5c7b469a5077c10942f4e1aec171faa9d" | ||
| 5206 | </pre><p> | ||
| 5207 | </p></div></div><div class="section" title="A.5.3. BSP Recipe Change Summary"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-recipe-change-summary"></a>A.5.3. BSP Recipe Change Summary</h3></div></div></div><p> | ||
| 5208 | In summary, the edits to the layer’s recipe files result in removal of any files and | ||
| 5209 | statements that do not support your targeted hardware in addition to the inclusion | ||
| 5210 | of any new recipes you might need. | ||
| 5211 | In this example, it was simply a matter of ridding the new layer | ||
| 5212 | <code class="filename">meta-mymachine</code> of any code that supported the EMGD features | ||
| 5213 | and making sure we were identifying the kernel that supports our example, which | ||
| 5214 | is the <code class="filename">atom-pc-standard</code> kernel. | ||
| 5215 | We did not introduce any new recipes to the layer. | ||
| 5216 | </p><p> | ||
| 5217 | Finally, it is also important to update the layer’s <code class="filename">README</code> | ||
| 5218 | file so that the information in it reflects your BSP. | ||
| 5219 | </p></div></div><div class="section" title="A.6. Preparing for the Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="preparing-for-the-build-app"></a>A.6. Preparing for the Build</h2></div></div></div><p> | ||
| 5220 | To get ready to build your image that uses the new layer you need to do the following: | ||
| 5221 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Get the environment ready for the build by sourcing the environment | ||
| 5222 | script. | ||
| 5223 | The environment script is in the top-level of the source directory. | ||
| 5224 | The script has the string | ||
| 5225 | <code class="filename">init-build-env</code> in the file’s name. | ||
| 5226 | For this example, the following command gets the build environment ready: | ||
| 5227 | </p><pre class="literallayout"> | ||
| 5228 | $ source oe-init-build-env yocto-build | ||
| 5229 | </pre><p> | ||
| 5230 | When you source the script, a build directory is created in the current | ||
| 5231 | working directory. | ||
| 5232 | In our example we were in the <code class="filename">poky</code> directory. | ||
| 5233 | Thus, entering the previous command created the <code class="filename">yocto-build</code> directory. | ||
| 5234 | If you do not provide a name for the build directory it defaults to | ||
| 5235 | <code class="filename">build</code>. | ||
| 5236 | The <code class="filename">yocto-build</code> directory contains a | ||
| 5237 | <code class="filename">conf</code> directory that has | ||
| 5238 | two configuration files you will need to check: <code class="filename">bblayers.conf</code> | ||
| 5239 | and <code class="filename">local.conf</code>.</p></li><li class="listitem"><p>Check and edit the resulting <code class="filename">local.conf</code> file. | ||
| 5240 | This file minimally identifies the machine for which to build the image by | ||
| 5241 | configuring the <code class="filename">MACHINE</code> variable. | ||
| 5242 | For this example you must set the variable to mymachine as follows: | ||
| 5243 | </p><pre class="literallayout"> | ||
| 5244 | MACHINE ??= “mymachine” | ||
| 5245 | </pre><p> | ||
| 5246 | You should also be sure any other variables in which you are interested are set. | ||
| 5247 | Some variables to consider are <code class="filename">BB_NUMBER_THREADS</code> | ||
| 5248 | and <code class="filename">PARALLEL_MAKE</code>, both of which can greatly reduce your build time | ||
| 5249 | if your development system supports multiple cores. | ||
| 5250 | For development systems that support multiple cores, a good rule of thumb is to set | ||
| 5251 | both the <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code> | ||
| 5252 | variables to twice the number of cores your system supports.</p></li><li class="listitem"><p>Update the <code class="filename">bblayers.conf</code> file so that it includes | ||
| 5253 | both the path to your new BSP layer and the path to the | ||
| 5254 | <code class="filename">meta-intel</code> layer. | ||
| 5255 | In this example, you need to include both these paths as part of the | ||
| 5256 | <code class="filename">BBLAYERS</code> variable: | ||
| 5257 | </p><pre class="literallayout"> | ||
| 5258 | $HOME/poky/meta-intel | ||
| 5259 | $HOME/poky/meta-intel/meta-mymachine | ||
| 5260 | </pre></li></ol></div><p> | ||
| 5261 | </p><p> | ||
| 5262 | The | ||
| 5263 | <a class="link" href="#ref-variables-glos" target="_top">Variables Glossary</a> chapter in the | ||
| 5264 | Yocto Project Reference Manual has more information on configuration variables. | ||
| 5265 | </p></div><div class="section" title="A.7. Building and Booting the Image"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-the-image-app"></a>A.7. Building and Booting the Image</h2></div></div></div><p> | ||
| 5266 | To build the image for our <code class="filename">meta-mymachine</code> BSP enter the following command | ||
| 5267 | from the same shell from which you ran the setup script. | ||
| 5268 | You should run the <code class="filename">bitbake</code> command without any intervening shell commands. | ||
| 5269 | For example, moving your working directory around could cause problems. | ||
| 5270 | Here is the command for this example: | ||
| 5271 | </p><pre class="literallayout"> | ||
| 5272 | $ bitbake -k core-image-sato | ||
| 5273 | </pre><p> | ||
| 5274 | </p><p> | ||
| 5275 | This command specifies an image that has Sato support and that can be run from a USB device or | ||
| 5276 | from a CD without having to first install anything. | ||
| 5277 | The build process takes significant time and includes thousands of tasks, which are reported | ||
| 5278 | at the console. | ||
| 5279 | If the build results in any type of error you should check for misspellings in the | ||
| 5280 | files you changed or problems with your host development environment such as missing packages. | ||
| 5281 | </p><p> | ||
| 5282 | Finally, once you have an image, you can try booting it from a device | ||
| 5283 | (e.g. a USB device). | ||
| 5284 | To prepare a bootable USB device, insert a USB flash drive into your build system and | ||
| 5285 | copy the <code class="filename">.hddimg</code> file, located in the | ||
| 5286 | <code class="filename">poky/build/tmp/deploy/images</code> | ||
| 5287 | directory after a successful build to the flash drive. | ||
| 5288 | Assuming the USB flash drive takes device <code class="filename">/dev/sdf</code>, | ||
| 5289 | use <code class="filename">dd</code> to copy the live image to it. | ||
| 5290 | For example: | ||
| 5291 | </p><pre class="literallayout"> | ||
| 5292 | # dd if=core-image-sato-mymachine-20111101223904.hddimg of=/dev/sdf | ||
| 5293 | # sync | ||
| 5294 | # eject /dev/sdf | ||
| 5295 | </pre><p> | ||
| 5296 | You should now have a bootable USB flash device. | ||
| 5297 | </p><p> | ||
| 5298 | Insert the device | ||
| 5299 | into a bootable USB socket on the target, and power it on. | ||
| 5300 | The system should boot to the Sato graphical desktop. | ||
| 5301 | <sup>[<a id="id1497755" href="#ftn.id1497755" class="footnote">2</a>]</sup> | ||
| 5302 | </p><p> | ||
| 5303 | For reference, the sato image produced by the previous steps for 1.2+snapshot | ||
| 5304 | should look like the following in terms of size. | ||
| 5305 | If your sato image is much different from this, | ||
| 5306 | you probably made a mistake in one of the above steps: | ||
| 5307 | </p><pre class="literallayout"> | ||
| 5308 | 260538368 2012-04-27 01:44 core-image-sato-mymachine-20120427025051.hddimg | ||
| 5309 | </pre><p> | ||
| 5310 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The previous instructions are also present in the README that was copied | ||
| 5311 | from meta-crownbay, which should also be updated to reflect the specifics of your | ||
| 5312 | new BSP. | ||
| 5313 | That file and the <code class="filename">README.hardware</code> file in the top-level | ||
| 5314 | <code class="filename">poky</code> directory | ||
| 5315 | also provides some suggestions for things to try if booting fails and produces | ||
| 5316 | strange error messages.</div><p> | ||
| 5317 | </p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id1497755" href="#id1497755" class="para">2</a>] </sup>Because | ||
| 5318 | this new image is not in any way tailored to the system you're | ||
| 5319 | booting it on, which is assumed to be some sort of atom-pc (netbook) system for this | ||
| 5320 | example, it might not be completely functional though it should at least boot to a text | ||
| 5321 | prompt. | ||
| 5322 | Specifically, it might fail to boot into graphics without some tweaking. | ||
| 5323 | If this ends up being the case, a possible next step would be to replace the | ||
| 5324 | <code class="filename">mymachine.conf</code> | ||
| 5325 | contents with the contents of <code class="filename">atom-pc.conf</code> and replace | ||
| 5326 | <code class="filename">xorg.conf</code> with <code class="filename">atom-pc xorg.conf</code> | ||
| 5327 | in <code class="filename">meta-yocto</code> and see if it fares any better. | ||
| 5328 | In any case, following the previous steps will give you a buildable image that | ||
| 5329 | will probably boot on most systems. | ||
| 5330 | Getting things working like you want | ||
| 5331 | them to for your hardware will normally require some amount of experimentation with | ||
| 5332 | configuration settings.</p></div></div></div> | ||
| 5333 | |||
| 5334 | <div class="appendix" title="Appendix B. Kernel Modification Example"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-kernel-appendix"></a>Appendix B. Kernel Modification Example</h2></div></div></div><p> | ||
| 5335 | Kernel modification involves changing or adding configurations to an existing kernel, | ||
| 5336 | changing or adding recipes to the kernel that are needed to support specific hardware features, | ||
| 5337 | or even altering the source code itself. | ||
| 5338 | This appendix presents simple examples that modify the kernel source code, | ||
| 5339 | change the kernel configuration, and add a kernel source recipe. | ||
| 5340 | </p><div class="section" title="B.1. Modifying the Kernel Source Code"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="modifying-the-kernel-source-code"></a>B.1. Modifying the Kernel Source Code</h2></div></div></div><p> | ||
| 5341 | This example adds some simple QEMU emulator console output at boot time by | ||
| 5342 | adding <code class="filename">printk</code> statements to the kernel's | ||
| 5343 | <code class="filename">calibrate.c</code> source code file. | ||
| 5344 | Booting the modified image causes the added messages to appear on the emulator's | ||
| 5345 | console. | ||
| 5346 | </p><div class="section" title="B.1.1. Understanding the Files You Need"><div class="titlepage"><div><div><h3 class="title"><a id="understanding-the-files-you-need"></a>B.1.1. Understanding the Files You Need</h3></div></div></div><p> | ||
| 5347 | Before you modify the kernel, you need to know what Git repositories and file | ||
| 5348 | structures you need. | ||
| 5349 | Briefly, you need the following: | ||
| 5350 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A local | ||
| 5351 | <a class="link" href="#source-directory">source directory</a> for the | ||
| 5352 | poky Git repository</p></li><li class="listitem"><p>Local copies of the | ||
| 5353 | <a class="link" href="#poky-extras-repo"><code class="filename">poky-extras</code></a> | ||
| 5354 | Git repository placed within the source directory.</p></li><li class="listitem"><p>A bare clone of the | ||
| 5355 | <a class="link" href="#local-kernel-files">Yocto Project Kernel</a> upstream Git | ||
| 5356 | repository to which you want to push your modifications. | ||
| 5357 | </p></li><li class="listitem"><p>A copy of that bare clone in which you make your source | ||
| 5358 | modifications</p></li></ul></div><p> | ||
| 5359 | </p><p> | ||
| 5360 | The following figure summarizes these four areas. | ||
| 5361 | Within each rectangular that represents a data structure, a | ||
| 5362 | host development directory pathname appears at the | ||
| 5363 | lower left-hand corner of the box. | ||
| 5364 | These pathnames are the locations used in this example. | ||
| 5365 | The figure also provides key statements and commands used during the kernel | ||
| 5366 | modification process: | ||
| 5367 | </p><p> | ||
| 5368 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 450px"><td align="center"><img src="figures/kernel-example-repos-denzil.png" align="middle" /></td></tr></table><p> | ||
| 5369 | </p><p> | ||
| 5370 | Here is a brief description of the four areas: | ||
| 5371 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Local Source Directory:</em></span> | ||
| 5372 | This area contains all the metadata that supports building images | ||
| 5373 | using the OpenEmbedded build system. | ||
| 5374 | In this example, the source directory also | ||
| 5375 | contains the build directory, which contains the configuration directory | ||
| 5376 | that lets you control the build. | ||
| 5377 | Also in this example, the source directory contains local copies of the | ||
| 5378 | <code class="filename">poky-extras</code> Git repository.</p><p>See the bulleted item | ||
| 5379 | "<a class="link" href="#local-yp-release">Yocto Project Release</a>" | ||
| 5380 | for information on how to get these files on your local system.</p></li><li class="listitem"><p><span class="emphasis"><em>Local copies of the<code class="filename">poky-extras</code> | ||
| 5381 | Git Repository:</em></span> | ||
| 5382 | This area contains the <code class="filename">meta-kernel-dev</code> layer, | ||
| 5383 | which is where you make changes that append the kernel build recipes. | ||
| 5384 | You edit <code class="filename">.bbappend</code> files to locate your | ||
| 5385 | local kernel source files and to identify the kernel being built. | ||
| 5386 | This Git repository is a gathering place for extensions to the Yocto Project | ||
| 5387 | (or really any) kernel recipes that faciliate the creation and development | ||
| 5388 | of kernel features, BSPs or configurations.</p><p>See the bulleted item | ||
| 5389 | "<a class="link" href="#poky-extras-repo">The | ||
| 5390 | <code class="filename">poky-extras</code> Git Repository</a>" | ||
| 5391 | for information on how to get these files.</p></li><li class="listitem"><p><span class="emphasis"><em>Bare Clone of the Yocto Project kernel:</em></span> | ||
| 5392 | This bare Git repository tracks the upstream Git repository of the Linux | ||
| 5393 | Yocto kernel source code you are changing. | ||
| 5394 | When you modify the kernel you must work through a bare clone. | ||
| 5395 | All source code changes you make to the kernel must be committed and | ||
| 5396 | pushed to the bare clone using Git commands. | ||
| 5397 | As mentioned, the <code class="filename">.bbappend</code> file in the | ||
| 5398 | <code class="filename">poky-extras</code> repository points to the bare clone | ||
| 5399 | so that the build process can locate the locally changed source files.</p><p>See the bulleted item | ||
| 5400 | "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" | ||
| 5401 | for information on how to set up the bare clone. | ||
| 5402 | </p></li><li class="listitem"><p><span class="emphasis"><em>Copy of the Yocto Project Kernel Bare Clone:</em></span> | ||
| 5403 | This Git repository contains the actual source files that you modify. | ||
| 5404 | Any changes you make to files in this location need to ultimately be pushed | ||
| 5405 | to the bare clone using the <code class="filename">git push</code> command.</p><p>See the bulleted item | ||
| 5406 | "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" | ||
| 5407 | for information on how to set up the bare clone. | ||
| 5408 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Typically, Git workflows follow a scheme where changes made to a local area | ||
| 5409 | are pulled into a Git repository. | ||
| 5410 | However, because the <code class="filename">git pull</code> command does not work | ||
| 5411 | with bare clones, this workflow pushes changes to the | ||
| 5412 | repository even though you could use other more complicated methods to | ||
| 5413 | get changes into the bare clone.</div><p> | ||
| 5414 | </p></li></ul></div><p> | ||
| 5415 | </p></div><div class="section" title="B.1.2. Setting Up the Local Source Directory"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-the-local-yocto-project-files-git-repository"></a>B.1.2. Setting Up the Local Source Directory</h3></div></div></div><p> | ||
| 5416 | You can set up the source directory through tarball extraction or by | ||
| 5417 | cloning the <code class="filename">poky</code> Git repository. | ||
| 5418 | This example uses <code class="filename">poky</code> as the root directory of the | ||
| 5419 | local source directory. | ||
| 5420 | See the bulleted item | ||
| 5421 | "<a class="link" href="#local-yp-release">Yocto Project Release</a>" | ||
| 5422 | for information on how to get these files. | ||
| 5423 | </p><p> | ||
| 5424 | Once you have source directory set up, | ||
| 5425 | you have many development branches from which you can work. | ||
| 5426 | From inside the local repository you can see the branch names and the tag names used | ||
| 5427 | in the upstream Git repository by using either of the following commands: | ||
| 5428 | </p><pre class="literallayout"> | ||
| 5429 | $ cd poky | ||
| 5430 | $ git branch -a | ||
| 5431 | $ git tag -l | ||
| 5432 | </pre><p> | ||
| 5433 | This example uses the Yocto Project 1.3 Release code named "1.2+snapshot", | ||
| 5434 | which maps to the <code class="filename">1.2+snapshot</code> branch in the repository. | ||
| 5435 | The following commands create and checkout the local <code class="filename">1.2+snapshot</code> | ||
| 5436 | branch: | ||
| 5437 | </p><pre class="literallayout"> | ||
| 5438 | $ git checkout -b 1.2+snapshot origin/1.2+snapshot | ||
| 5439 | Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. | ||
| 5440 | Switched to a new branch '1.2+snapshot' | ||
| 5441 | </pre><p> | ||
| 5442 | </p></div><div class="section" title="B.1.3. Setting Up the Local poky-extras Git Repository"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-the-poky-extras-git-repository"></a>B.1.3. Setting Up the Local poky-extras Git Repository</h3></div></div></div><p> | ||
| 5443 | This example creates a local copy of the <code class="filename">poky-extras</code> Git | ||
| 5444 | repository inside the <code class="filename">poky</code> source directory. | ||
| 5445 | See the bulleted item "<a class="link" href="#poky-extras-repo">The | ||
| 5446 | <code class="filename">poky-extras</code> Git Repository</a>" | ||
| 5447 | for information on how to set up a local copy of the | ||
| 5448 | <code class="filename">poky-extras</code> repository. | ||
| 5449 | </p><p> | ||
| 5450 | Because this example uses the Yocto Project 1.3 Release code | ||
| 5451 | named "1.2+snapshot", which maps to the <code class="filename">1.2+snapshot</code> | ||
| 5452 | branch in the repository, you need to be sure you are using that | ||
| 5453 | branch for <code class="filename">poky-extra</code>. | ||
| 5454 | The following commands create and checkout the local | ||
| 5455 | branch you are using for the <code class="filename">1.2+snapshot</code> | ||
| 5456 | branch: | ||
| 5457 | </p><pre class="literallayout"> | ||
| 5458 | $ git checkout -b 1.2+snapshot origin/1.2+snapshot | ||
| 5459 | Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. | ||
| 5460 | Switched to a new branch '1.2+snapshot' | ||
| 5461 | </pre><p> | ||
| 5462 | </p></div><div class="section" title="B.1.4. Setting Up the Bare Clone and its Copy"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-the-bare-clone-and-its-copy"></a>B.1.4. Setting Up the Bare Clone and its Copy</h3></div></div></div><p> | ||
| 5463 | This example modifies the <code class="filename">linux-yocto-3.2</code> kernel. | ||
| 5464 | Thus, you need to create a bare clone of that kernel and then make a copy of the | ||
| 5465 | bare clone. | ||
| 5466 | See the bulleted item | ||
| 5467 | "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" | ||
| 5468 | for information on how to do that. | ||
| 5469 | </p><p> | ||
| 5470 | The bare clone exists for the kernel build tools and simply as the receiving end | ||
| 5471 | of <code class="filename">git push</code> | ||
| 5472 | commands after you make edits and commits inside the copy of the clone. | ||
| 5473 | The copy (<code class="filename">my-linux-yocto-3.2-work</code> in this example) has to have | ||
| 5474 | a local branch created and checked out for your work. | ||
| 5475 | This example uses <code class="filename">common-pc-base</code> as the local branch. | ||
| 5476 | The following commands create and checkout the branch: | ||
| 5477 | </p><pre class="literallayout"> | ||
| 5478 | $ cd ~/my-linux-yocto-3.2-work | ||
| 5479 | $ git checkout -b common-pc-base origin/standard/default/common-pc/base | ||
| 5480 | Checking out files: 100% (532/532), done. | ||
| 5481 | Branch common-pc-base set up to track remote branch | ||
| 5482 | standard/default/common-pc/base from origin. | ||
| 5483 | Switched to a new branch 'common-pc-base' | ||
| 5484 | </pre><p> | ||
| 5485 | </p></div><div class="section" title="B.1.5. Building and Booting the Default QEMU Kernel Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-and-booting-the-default-qemu-kernel-image"></a>B.1.5. Building and Booting the Default QEMU Kernel Image</h3></div></div></div><p> | ||
| 5486 | Before we make changes to the kernel source files, this example first builds the | ||
| 5487 | default image and then boots it inside the QEMU emulator. | ||
| 5488 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 5489 | Because a full build can take hours, you should check two variables in the | ||
| 5490 | <code class="filename">build</code> directory that is created after you source the | ||
| 5491 | <code class="filename">oe-init-build-env</code> script. | ||
| 5492 | You can find these variables | ||
| 5493 | <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code> | ||
| 5494 | in the <code class="filename">build/conf</code> directory in the | ||
| 5495 | <code class="filename">local.conf</code> configuration file. | ||
| 5496 | By default, these variables are commented out. | ||
| 5497 | If your host development system supports multi-core and multi-thread capabilities, | ||
| 5498 | you can uncomment these statements and set the variables to significantly shorten | ||
| 5499 | the full build time. | ||
| 5500 | As a guideline, set both <code class="filename">BB_NUMBER_THREADS</code> and | ||
| 5501 | <code class="filename">PARALLEL_MAKE</code> to twice the number | ||
| 5502 | of cores your machine supports. | ||
| 5503 | </div><p> | ||
| 5504 | The following two commands <code class="filename">source</code> the build environment setup script | ||
| 5505 | and build the default <code class="filename">qemux86</code> image. | ||
| 5506 | If necessary, the script creates the build directory: | ||
| 5507 | </p><pre class="literallayout"> | ||
| 5508 | $ cd ~/poky | ||
| 5509 | $ source oe-init-build-env | ||
| 5510 | |||
| 5511 | ### Shell environment set up for builds. ### | ||
| 5512 | |||
| 5513 | You can now run 'bitbake <target>' | ||
| 5514 | |||
| 5515 | Common targets are: | ||
| 5516 | core-image-minimal | ||
| 5517 | core-image-sato | ||
| 5518 | meta-toolchain | ||
| 5519 | meta-toolchain-sdk | ||
| 5520 | adt-installer | ||
| 5521 | meta-ide-support | ||
| 5522 | |||
| 5523 | You can also run generated qemu images with a command like 'runqemu qemux86' | ||
| 5524 | </pre><p> | ||
| 5525 | </p><p> | ||
| 5526 | The following <code class="filename">bitbake</code> command starts the build: | ||
| 5527 | </p><pre class="literallayout"> | ||
| 5528 | $ bitbake -k core-image-minimal | ||
| 5529 | </pre><p> | ||
| 5530 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Be sure to check the settings in the <code class="filename">local.conf</code> | ||
| 5531 | before starting the build.</div><p> | ||
| 5532 | </p><p> | ||
| 5533 | After the build completes, you can start the QEMU emulator using the resulting image | ||
| 5534 | <code class="filename">qemux86</code> as follows: | ||
| 5535 | </p><pre class="literallayout"> | ||
| 5536 | $ runqemu qemux86 | ||
| 5537 | </pre><p> | ||
| 5538 | </p><p> | ||
| 5539 | As the image boots in the emulator, console message and status output appears | ||
| 5540 | across the terminal window. | ||
| 5541 | Because the output scrolls by quickly, it is difficult to read. | ||
| 5542 | To examine the output, you log into the system using the | ||
| 5543 | login <code class="filename">root</code> with no password. | ||
| 5544 | Once you are logged in, issue the following command to scroll through the | ||
| 5545 | console output: | ||
| 5546 | </p><pre class="literallayout"> | ||
| 5547 | # dmesg | less | ||
| 5548 | </pre><p> | ||
| 5549 | </p><p> | ||
| 5550 | Take note of the output as you will want to look for your inserted print command output | ||
| 5551 | later in the example. | ||
| 5552 | </p></div><div class="section" title="B.1.6. Changing the Source Code and Pushing it to the Bare Clone"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-source-code-and-pushing-it-to-the-bare-clone"></a>B.1.6. Changing the Source Code and Pushing it to the Bare Clone</h3></div></div></div><p> | ||
| 5553 | The file you change in this example is named <code class="filename">calibrate.c</code> | ||
| 5554 | and is located in the <code class="filename">my-linux-yocto-3.2-work</code> Git repository | ||
| 5555 | (the copy of the bare clone) in <code class="filename">init</code>. | ||
| 5556 | This example simply inserts several <code class="filename">printk</code> statements | ||
| 5557 | at the beginning of the <code class="filename">calibrate_delay</code> function. | ||
| 5558 | </p><p> | ||
| 5559 | Here is the unaltered code at the start of this function: | ||
| 5560 | </p><pre class="literallayout"> | ||
| 5561 | void __cpuinit calibrate_delay(void) | ||
| 5562 | { | ||
| 5563 | unsigned long lpj; | ||
| 5564 | static bool printed; | ||
| 5565 | int this_cpu = smp_processor_id(); | ||
| 5566 | |||
| 5567 | if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { | ||
| 5568 | . | ||
| 5569 | . | ||
| 5570 | . | ||
| 5571 | </pre><p> | ||
| 5572 | </p><p> | ||
| 5573 | Here is the altered code showing five new <code class="filename">printk</code> statements | ||
| 5574 | near the top of the function: | ||
| 5575 | </p><pre class="literallayout"> | ||
| 5576 | void __cpuinit calibrate_delay(void) | ||
| 5577 | { | ||
| 5578 | unsigned long lpj; | ||
| 5579 | static bool printed; | ||
| 5580 | int this_cpu = smp_processor_id(); | ||
| 5581 | |||
| 5582 | printk("*************************************\n"); | ||
| 5583 | printk("* *\n"); | ||
| 5584 | printk("* HELLO YOCTO KERNEL *\n"); | ||
| 5585 | printk("* *\n"); | ||
| 5586 | printk("*************************************\n"); | ||
| 5587 | |||
| 5588 | if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { | ||
| 5589 | . | ||
| 5590 | . | ||
| 5591 | . | ||
| 5592 | </pre><p> | ||
| 5593 | </p><p> | ||
| 5594 | After making and saving your changes, you need to stage them for the push. | ||
| 5595 | The following Git commands are one method of staging and committing your changes: | ||
| 5596 | </p><pre class="literallayout"> | ||
| 5597 | $ git add calibrate.c | ||
| 5598 | $ git commit --signoff | ||
| 5599 | </pre><p> | ||
| 5600 | </p><p> | ||
| 5601 | Once the source code has been modified, you need to use Git to push the changes to | ||
| 5602 | the bare clone. | ||
| 5603 | If you do not push the changes, then the OpenEmbedded build system will not pick | ||
| 5604 | up the changed source files. | ||
| 5605 | </p><p> | ||
| 5606 | The following command pushes the changes to the bare clone: | ||
| 5607 | </p><pre class="literallayout"> | ||
| 5608 | $ git push origin common-pc-base:standard/default/common-pc/base | ||
| 5609 | </pre><p> | ||
| 5610 | </p></div><div class="section" title="B.1.7. Changing Build Parameters for Your Build"><div class="titlepage"><div><div><h3 class="title"><a id="changing-build-parameters-for-your-build"></a>B.1.7. Changing Build Parameters for Your Build</h3></div></div></div><p> | ||
| 5611 | At this point, the source has been changed and pushed. | ||
| 5612 | The example now defines some variables used by the OpenEmbedded build system | ||
| 5613 | to locate your kernel source. | ||
| 5614 | You essentially need to identify where to find the kernel recipe and the changed source code. | ||
| 5615 | You also need to be sure some basic configurations are in place that identify the | ||
| 5616 | type of machine you are building and to help speed up the build should your host support | ||
| 5617 | multiple-core and thread capabilities. | ||
| 5618 | </p><p> | ||
| 5619 | Do the following to make sure the build parameters are set up for the example. | ||
| 5620 | Once you set up these build parameters, they do not have to change unless you | ||
| 5621 | change the target architecture of the machine you are building or you move | ||
| 5622 | the bare clone, copy of the clone, or the <code class="filename">poky-extras</code> repository: | ||
| 5623 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Build for the Correct Target Architecture:</em></span> The | ||
| 5624 | <code class="filename">local.conf</code> file in the build directory defines the build's | ||
| 5625 | target architecture. | ||
| 5626 | By default, <code class="filename">MACHINE</code> is set to | ||
| 5627 | <code class="filename">qemux86</code>, which specifies a 32-bit | ||
| 5628 | <span class="trademark">Intel</span>® Architecture | ||
| 5629 | target machine suitable for the QEMU emulator. | ||
| 5630 | In this example, <code class="filename">MACHINE</code> is correctly configured. | ||
| 5631 | </p></li><li class="listitem"><p><span class="emphasis"><em>Optimize Build Time:</em></span> Also in the | ||
| 5632 | <code class="filename">local.conf</code> file are two variables that can speed your | ||
| 5633 | build time if your host supports multi-core and multi-thread capabilities: | ||
| 5634 | <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code>. | ||
| 5635 | If the host system has multiple cores then you can optimize build time | ||
| 5636 | by setting both these variables to twice the number of | ||
| 5637 | cores.</p></li><li class="listitem"><p><span class="emphasis"><em>Identify Your <code class="filename">meta-kernel-dev</code> | ||
| 5638 | Layer:</em></span> The <code class="filename">BBLAYERS</code> variable in the | ||
| 5639 | <code class="filename">bblayers.conf</code> file found in the | ||
| 5640 | <code class="filename">poky/build/conf</code> directory needs to have the path to your local | ||
| 5641 | <code class="filename">meta-kernel-dev</code> layer. | ||
| 5642 | By default, the <code class="filename">BBLAYERS</code> variable contains paths to | ||
| 5643 | <code class="filename">meta</code> and <code class="filename">meta-yocto</code> in the | ||
| 5644 | <code class="filename">poky</code> Git repository. | ||
| 5645 | Add the path to your <code class="filename">meta-kernel-dev</code> location. | ||
| 5646 | Be sure to substitute your user information in the statement. | ||
| 5647 | Here is an example: | ||
| 5648 | </p><pre class="literallayout"> | ||
| 5649 | BBLAYERS = " \ | ||
| 5650 | /home/scottrif/poky/meta \ | ||
| 5651 | /home/scottrif/poky/meta-yocto \ | ||
| 5652 | /home/scottrif/poky/poky-extras/meta-kernel-dev \ | ||
| 5653 | " | ||
| 5654 | </pre></li><li class="listitem"><p><span class="emphasis"><em>Identify Your Source Files:</em></span> In the | ||
| 5655 | <code class="filename">linux-yocto_3.2.bbappend</code> file located in the | ||
| 5656 | <code class="filename">poky-extras/meta-kernel-dev/recipes-kernel/linux</code> | ||
| 5657 | directory, you need to identify the location of the | ||
| 5658 | local source code, which in this example is the bare clone named | ||
| 5659 | <code class="filename">linux-yocto-3.2.git</code>. | ||
| 5660 | To do this, set the <code class="filename">KSRC_linux_yocto</code> variable to point to your | ||
| 5661 | local <code class="filename">linux-yocto-3.2.git</code> Git repository by adding the | ||
| 5662 | following statement. | ||
| 5663 | Be sure to substitute your user information in the statement: | ||
| 5664 | </p><pre class="literallayout"> | ||
| 5665 | KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git" | ||
| 5666 | </pre></li></ul></div><p> | ||
| 5667 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Before attempting to build the modified kernel, there is one more set of changes you | ||
| 5668 | need to make in the <code class="filename">meta-kernel-dev</code> layer. | ||
| 5669 | Because all the kernel <code class="filename">.bbappend</code> files are parsed during the | ||
| 5670 | build process regardless of whether you are using them or not, you should either | ||
| 5671 | comment out the <code class="filename">COMPATIBLE_MACHINE</code> statements in all | ||
| 5672 | unused <code class="filename">.bbappend</code> files, or simply remove (or rename) all the files | ||
| 5673 | except the one your are using for the build | ||
| 5674 | (i.e. <code class="filename">linux-yocto_3.2.bbappend</code> in this example).</p><p>If you do not make one of these two adjustments, your machine will be compatible | ||
| 5675 | with all the kernel recipes in the <code class="filename">meta-kernel-dev</code> layer. | ||
| 5676 | When your machine is comapatible with all the kernel recipes, the build attempts | ||
| 5677 | to build all kernels in the layer. | ||
| 5678 | You could end up with build errors blocking your work.</p></div></div><div class="section" title="B.1.8. Building and Booting the Modified QEMU Kernel Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-and-booting-the-modified-qemu-kernel-image"></a>B.1.8. Building and Booting the Modified QEMU Kernel Image</h3></div></div></div><p> | ||
| 5679 | Next, you need to build the modified image. | ||
| 5680 | Do the following: | ||
| 5681 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Your environment should be set up since you previously sourced | ||
| 5682 | the <code class="filename">oe-init-build-env</code> script. | ||
| 5683 | If it isn't, source the script again from <code class="filename">poky</code>. | ||
| 5684 | </p><pre class="literallayout"> | ||
| 5685 | $ cd ~/poky | ||
| 5686 | $ source oe-init-build-env | ||
| 5687 | </pre><p> | ||
| 5688 | </p></li><li class="listitem"><p>Be sure old images are cleaned out by running the | ||
| 5689 | <code class="filename">cleanall</code> BitBake task as follows from your build directory: | ||
| 5690 | </p><pre class="literallayout"> | ||
| 5691 | $ bitbake -c cleanall linux-yocto | ||
| 5692 | </pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Never remove any files by hand from the <code class="filename">tmp/deploy</code> | ||
| 5693 | directory insided the build directory. | ||
| 5694 | Always use the BitBake <code class="filename">cleanall</code> task to clear | ||
| 5695 | out previous builds.</div></li><li class="listitem"><p>Next, build the kernel image using this command: | ||
| 5696 | </p><pre class="literallayout"> | ||
| 5697 | $ bitbake -k core-image-minimal | ||
| 5698 | </pre></li><li class="listitem"><p>Finally, boot the modified image in the QEMU emulator | ||
| 5699 | using this command: | ||
| 5700 | </p><pre class="literallayout"> | ||
| 5701 | $ runqemu qemux86 | ||
| 5702 | </pre></li></ol></div><p> | ||
| 5703 | </p><p> | ||
| 5704 | Log into the machine using <code class="filename">root</code> with no password and then | ||
| 5705 | use the following shell command to scroll through the console's boot output. | ||
| 5706 | </p><pre class="literallayout"> | ||
| 5707 | # dmesg | less | ||
| 5708 | </pre><p> | ||
| 5709 | </p><p> | ||
| 5710 | You should see the results of your <code class="filename">printk</code> statements | ||
| 5711 | as part of the output. | ||
| 5712 | </p></div></div><div class="section" title="B.2. Changing the Kernel Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="changing-the-kernel-configuration"></a>B.2. Changing the Kernel Configuration</h2></div></div></div><p> | ||
| 5713 | This example changes the default behavior, which is "on", of the Symmetric | ||
| 5714 | Multi-processing Support (<code class="filename">CONFIG_SMP</code>) to "off". | ||
| 5715 | It is a simple example that demonstrates how to reconfigure the kernel. | ||
| 5716 | </p><div class="section" title="B.2.1. Getting Set Up to Run this Example"><div class="titlepage"><div><div><h3 class="title"><a id="getting-set-up-to-run-this-example"></a>B.2.1. Getting Set Up to Run this Example</h3></div></div></div><p> | ||
| 5717 | If you took the time to work through the example that modifies the kernel source code | ||
| 5718 | in "<a class="link" href="#modifying-the-kernel-source-code" title="B.1. Modifying the Kernel Source Code">Modifying the Kernel Source | ||
| 5719 | Code</a>" you should already have the source directory set up on your | ||
| 5720 | host machine. | ||
| 5721 | If this is the case, go to the next section, which is titled | ||
| 5722 | "<a class="link" href="#examining-the-default-config-smp-behavior" title="B.2.2. Examining the Default CONFIG_SMP Behavior">Examining the Default | ||
| 5723 | <code class="filename">CONFIG_SMP</code> Behavior</a>", and continue with the | ||
| 5724 | example. | ||
| 5725 | </p><p> | ||
| 5726 | If you don't have the source directory established on your system, | ||
| 5727 | you can get them through tarball extraction or by | ||
| 5728 | cloning the <code class="filename">poky</code> Git repository. | ||
| 5729 | This example uses <code class="filename">poky</code> as the root directory of the | ||
| 5730 | <a class="link" href="#source-directory">source directory</a>. | ||
| 5731 | See the bulleted item | ||
| 5732 | "<a class="link" href="#local-yp-release">Yocto Project Release</a>" | ||
| 5733 | for information on how to get these files. | ||
| 5734 | </p><p> | ||
| 5735 | Once you have the local copy of the repository set up, | ||
| 5736 | you have many development branches from which you can work. | ||
| 5737 | From inside the repository you can see the branch names and the tag names used | ||
| 5738 | in the upstream Git repository using either of the following commands: | ||
| 5739 | </p><pre class="literallayout"> | ||
| 5740 | $ cd poky | ||
| 5741 | $ git branch -a | ||
| 5742 | $ git tag -l | ||
| 5743 | </pre><p> | ||
| 5744 | This example uses the Yocto Project 1.3 Release code named "1.2+snapshot", | ||
| 5745 | which maps to the <code class="filename">1.2+snapshot</code> branch in the repository. | ||
| 5746 | The following commands create and checkout the local <code class="filename">1.2+snapshot</code> | ||
| 5747 | branch: | ||
| 5748 | </p><pre class="literallayout"> | ||
| 5749 | $ git checkout -b 1.2+snapshot origin/1.2+snapshot | ||
| 5750 | Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. | ||
| 5751 | Switched to a new branch '1.2+snapshot' | ||
| 5752 | </pre><p> | ||
| 5753 | </p><p> | ||
| 5754 | Next, you need to build the default <code class="filename">qemux86</code> image that you | ||
| 5755 | can boot using QEMU. | ||
| 5756 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 5757 | Because a full build can take hours, you should check two variables in the | ||
| 5758 | <code class="filename">build</code> directory that is created after you source the | ||
| 5759 | <code class="filename">oe-init-build-env</code> script. | ||
| 5760 | You can find these variables | ||
| 5761 | <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code> | ||
| 5762 | in the <code class="filename">build/conf</code> directory in the | ||
| 5763 | <code class="filename">local.conf</code> configuration file. | ||
| 5764 | By default, these variables are commented out. | ||
| 5765 | If your host development system supports multi-core and multi-thread capabilities, | ||
| 5766 | you can uncomment these statements and set the variables to significantly shorten | ||
| 5767 | the full build time. | ||
| 5768 | As a guideline, set both the <code class="filename">BB_NUMBER_THREADS</code> and the | ||
| 5769 | <code class="filename">PARALLEL_MAKE</code> variables to twice the number | ||
| 5770 | of cores your machine supports. | ||
| 5771 | </div><p> | ||
| 5772 | The following two commands <code class="filename">source</code> the build environment setup script | ||
| 5773 | and build the default <code class="filename">qemux86</code> image. | ||
| 5774 | If necessary, the script creates the build directory: | ||
| 5775 | </p><pre class="literallayout"> | ||
| 5776 | $ cd ~/poky | ||
| 5777 | $ source oe-init-build-env | ||
| 5778 | |||
| 5779 | ### Shell environment set up for builds. ### | ||
| 5780 | |||
| 5781 | You can now run 'bitbake <target>' | ||
| 5782 | |||
| 5783 | Common targets are: | ||
| 5784 | core-image-minimal | ||
| 5785 | core-image-sato | ||
| 5786 | meta-toolchain | ||
| 5787 | meta-toolchain-sdk | ||
| 5788 | adt-installer | ||
| 5789 | meta-ide-support | ||
| 5790 | |||
| 5791 | You can also run generated qemu images with a command like 'runqemu qemux86' | ||
| 5792 | </pre><p> | ||
| 5793 | </p><p> | ||
| 5794 | The following <code class="filename">bitbake</code> command starts the build: | ||
| 5795 | </p><pre class="literallayout"> | ||
| 5796 | $ bitbake -k core-image-minimal | ||
| 5797 | </pre><p> | ||
| 5798 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Be sure to check the settings in the <code class="filename">local.conf</code> | ||
| 5799 | before starting the build.</div><p> | ||
| 5800 | </p></div><div class="section" title="B.2.2. Examining the Default CONFIG_SMP Behavior"><div class="titlepage"><div><div><h3 class="title"><a id="examining-the-default-config-smp-behavior"></a>B.2.2. Examining the Default <code class="filename">CONFIG_SMP</code> Behavior</h3></div></div></div><p> | ||
| 5801 | By default, <code class="filename">CONFIG_SMP</code> supports multiple processor machines. | ||
| 5802 | To see this default setting from within the QEMU emulator, boot your image using | ||
| 5803 | the emulator as follows: | ||
| 5804 | </p><pre class="literallayout"> | ||
| 5805 | $ runqemu qemux86 qemuparams="-smp 4" | ||
| 5806 | </pre><p> | ||
| 5807 | </p><p> | ||
| 5808 | Login to the machine using <code class="filename">root</code> with no password. | ||
| 5809 | After logging in, enter the following command to see how many processors are | ||
| 5810 | being supported in the emulator. | ||
| 5811 | The emulator reports support for the number of processors you specified using | ||
| 5812 | the <code class="filename">-smp</code> option, four in this case: | ||
| 5813 | </p><pre class="literallayout"> | ||
| 5814 | # cat /proc/cpuinfo | grep processor | ||
| 5815 | processor : 0 | ||
| 5816 | processor : 1 | ||
| 5817 | processor : 2 | ||
| 5818 | processor : 3 | ||
| 5819 | # | ||
| 5820 | </pre><p> | ||
| 5821 | To check the setting for <code class="filename">CONFIG_SMP</code>, you can use the | ||
| 5822 | following command: | ||
| 5823 | </p><pre class="literallayout"> | ||
| 5824 | zcat /proc/config.gz | grep CONFIG_SMP | ||
| 5825 | </pre><p> | ||
| 5826 | The console returns the following showing that multi-processor machine support | ||
| 5827 | is set: | ||
| 5828 | </p><pre class="literallayout"> | ||
| 5829 | CONFIG_SMP=y | ||
| 5830 | </pre><p> | ||
| 5831 | Logout of the emulator using the <code class="filename">exit</code> command and | ||
| 5832 | then close it down. | ||
| 5833 | </p></div><div class="section" title="B.2.3. Changing the CONFIG_SMP Configuration Using menuconfig"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-config-smp-configuration-using-menuconfig"></a>B.2.3. Changing the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></h3></div></div></div><p> | ||
| 5834 | The <code class="filename">menuconfig</code> tool provides an interactive method with which | ||
| 5835 | to set kernel configurations. | ||
| 5836 | You need to run <code class="filename">menuconfig</code> inside the Yocto BitBake environment. | ||
| 5837 | Thus, the environment must be set up using the <code class="filename">oe-init-build-env</code> | ||
| 5838 | script found in the build directory. | ||
| 5839 | If you have not sourced this script do so with the following commands: | ||
| 5840 | </p><pre class="literallayout"> | ||
| 5841 | $ cd ~/poky | ||
| 5842 | $ source oe-init-build-env | ||
| 5843 | </pre><p> | ||
| 5844 | </p><p> | ||
| 5845 | After setting up the environment to run <code class="filename">menuconfig</code>, you are ready | ||
| 5846 | to use the tool to interactively change the kernel configuration. | ||
| 5847 | In this example, we are basing our changes on the <code class="filename">linux-yocto-3.2</code> | ||
| 5848 | kernel. | ||
| 5849 | The OpenEmbedded build system recognizes this kernel as | ||
| 5850 | <code class="filename">linux-yocto</code>. | ||
| 5851 | Thus, the following commands from the shell in which you previously sourced the | ||
| 5852 | environment initialization script cleans the shared state cache and the | ||
| 5853 | <a class="link" href="#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a> | ||
| 5854 | directory and then builds and launches <code class="filename">menuconfig</code>: | ||
| 5855 | </p><pre class="literallayout"> | ||
| 5856 | $ bitbake linux-yocto -c menuconfig | ||
| 5857 | </pre><p> | ||
| 5858 | </p><p> | ||
| 5859 | Once <code class="filename">menuconfig</code> launches, navigate through the user interface | ||
| 5860 | to find the <code class="filename">CONFIG_SMP</code> configuration setting. | ||
| 5861 | You can find it at <code class="filename">Processor Type and Features</code>. | ||
| 5862 | The configuration selection is | ||
| 5863 | <code class="filename">Symmetric Multi-processing Support</code>. | ||
| 5864 | After using the arrow keys to highlight this selection, press "n" to turn it off. | ||
| 5865 | Then, exit out and save your selections. | ||
| 5866 | </p><p> | ||
| 5867 | Once you save the selection, the <code class="filename">.config</code> configuration file | ||
| 5868 | is updated. | ||
| 5869 | This is the file that the build system uses to configure the Yocto Project kernel | ||
| 5870 | when it is built. | ||
| 5871 | You can find and examine this file in the build directory. | ||
| 5872 | This example uses the following: | ||
| 5873 | </p><pre class="literallayout"> | ||
| 5874 | ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.11+git1+84f... | ||
| 5875 | ...656ed30-r1/linux-qemux86-standard-build | ||
| 5876 | </pre><p> | ||
| 5877 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 5878 | The previous example directory is artificially split and many of the characters | ||
| 5879 | in the actual filename are omitted in order to make it more readable. | ||
| 5880 | Also, depending on the kernel you are using, the exact pathname might differ | ||
| 5881 | slightly. | ||
| 5882 | </div><p> | ||
| 5883 | </p><p> | ||
| 5884 | Within the <code class="filename">.config</code> file, you can see the following setting: | ||
| 5885 | </p><pre class="literallayout"> | ||
| 5886 | # CONFIG_SMP is not set | ||
| 5887 | </pre><p> | ||
| 5888 | </p><p> | ||
| 5889 | A good method to isolate changed configurations is to use a combination of the | ||
| 5890 | <code class="filename">menuconfig</code> tool and simple shell commands. | ||
| 5891 | Before changing configurations with <code class="filename">menuconfig</code>, copy the | ||
| 5892 | existing <code class="filename">.config</code> and rename it to something else, | ||
| 5893 | use <code class="filename">menuconfig</code> to make | ||
| 5894 | as many changes an you want and save them, then compare the renamed configuration | ||
| 5895 | file against the newly created file. | ||
| 5896 | You can use the resulting differences as your base to create configuration fragments | ||
| 5897 | to permanently save in your kernel layer. | ||
| 5898 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 5899 | Be sure to make a copy of the <code class="filename">.config</code> and don't just | ||
| 5900 | rename it. | ||
| 5901 | The build system needs an existing <code class="filename">.config</code> | ||
| 5902 | from which to work. | ||
| 5903 | </div><p> | ||
| 5904 | </p></div><div class="section" title="B.2.4. Recompiling the Kernel and Testing the New Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="recompiling-the-kernel-and-testing-the-new-configuration"></a>B.2.4. Recompiling the Kernel and Testing the New Configuration</h3></div></div></div><p> | ||
| 5905 | At this point, you are ready to recompile your kernel image with | ||
| 5906 | the new setting in effect using the BitBake command below: | ||
| 5907 | </p><pre class="literallayout"> | ||
| 5908 | $ bitbake linux-yocto | ||
| 5909 | </pre><p> | ||
| 5910 | </p><p> | ||
| 5911 | Now run the QEMU emulator and pass it the same multi-processor option as before: | ||
| 5912 | </p><pre class="literallayout"> | ||
| 5913 | $ runqemu qemux86 qemuparams="-smp 4" | ||
| 5914 | </pre><p> | ||
| 5915 | </p><p> | ||
| 5916 | Login to the machine using <code class="filename">root</code> with no password | ||
| 5917 | and test for the number of processors the kernel supports: | ||
| 5918 | </p><pre class="literallayout"> | ||
| 5919 | # cat /proc/cpuinfo | grep processor | ||
| 5920 | processor : 0 | ||
| 5921 | # | ||
| 5922 | </pre><p> | ||
| 5923 | </p><p> | ||
| 5924 | From the output, you can see that the kernel no longer supports multi-processor systems. | ||
| 5925 | The output indicates support for a single processor. You can verify the | ||
| 5926 | <code class="filename">CONFIG_SMP</code> setting by using this command: | ||
| 5927 | </p><pre class="literallayout"> | ||
| 5928 | zcat /proc/config.gz | grep CONFIG_SMP | ||
| 5929 | </pre><p> | ||
| 5930 | The console returns the following output: | ||
| 5931 | </p><pre class="literallayout"> | ||
| 5932 | # CONFIG_SMP is not set | ||
| 5933 | </pre><p> | ||
| 5934 | You have successfully reconfigured the kernel. | ||
| 5935 | </p></div></div><div class="section" title="B.3. Adding Kernel Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adding-kernel-recipes"></a>B.3. Adding Kernel Recipes</h2></div></div></div><p> | ||
| 5936 | A future release of this manual will present an example that adds kernel recipes, which provide | ||
| 5937 | new functionality to the kernel. | ||
| 5938 | </p><p> | ||
| 5939 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="180"><tr style="height: 270px"><td align="center"><img src="figures/wip.png" align="middle" width="180" /></td></tr></table><p> | ||
| 5940 | </p></div></div> | ||
| 5941 | |||
| 5942 | </div> | ||
| 5943 | |||
| 5944 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/adt-title.png" align="left" width="100%" /></td></tr></table> | ||
| 5945 | |||
| 5946 | <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="adt-manual"></a></h1></div><div><div class="authorgroup"> | ||
| 5947 | <div class="author"><h3 class="author"><span class="firstname">Jessica</span> <span class="surname">Zhang</span></h3><div class="affiliation"> | ||
| 5948 | <span class="orgname">Intel Corporation<br /></span> | ||
| 5949 | </div><code class="email"><<a class="email" href="mailto:jessica.zhang@intel.com">jessica.zhang@intel.com</a>></code></div> | ||
| 5950 | </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1499739"></a> | ||
| 5951 | <p> | ||
| 5952 | Permission is granted to copy, distribute and/or modify this document under | ||
| 5953 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. | ||
| 5954 | </p> | ||
| 5955 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 5956 | Due to production processes, there could be differences between the Yocto Project | ||
| 5957 | documentation bundled in the release tarball and the | ||
| 5958 | Yocto Project Application Developer's Guide on | ||
| 5959 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 5960 | For the latest version of this manual, see the manual on the website. | ||
| 5961 | </div> | ||
| 5962 | |||
| 5963 | </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> | ||
| 5964 | <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> | ||
| 5965 | <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> | ||
| 5966 | <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> | ||
| 5967 | <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> | ||
| 5968 | <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> | ||
| 5969 | </table></div></div></div><hr /></div> | ||
| 5970 | |||
| 5971 | |||
| 5972 | <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="adt-intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#adt-intro-section">1.1. The Application Development Toolkit (ADT)</a></span></dt><dd><dl><dt><span class="section"><a href="#the-cross-toolchain">1.1.1. The Cross-Toolchain</a></span></dt><dt><span class="section"><a href="#sysroot">1.1.2. Sysroot</a></span></dt><dt><span class="section"><a href="#eclipse-overview">1.1.3. Eclipse Yocto Plug-in</a></span></dt><dt><span class="section"><a href="#the-qemu-emulator">1.1.4. The QEMU Emulator</a></span></dt><dt><span class="section"><a href="#user-space-tools">1.1.5. User-Space Tools</a></span></dt></dl></dd></dl></div><p> | ||
| 5973 | Welcome to the Yocto Project Application Developer's Guide. | ||
| 5974 | This manual provides information that lets you begin developing applications | ||
| 5975 | using the Yocto Project. | ||
| 5976 | </p><p> | ||
| 5977 | The Yocto Project provides an application development environment based on | ||
| 5978 | an Application Development Toolkit (ADT) and the availability of stand-alone | ||
| 5979 | cross-development toolchains and other tools. | ||
| 5980 | This manual describes the ADT and how you can configure and install it, | ||
| 5981 | how to access and use the cross-development toolchains, how to | ||
| 5982 | customize the development packages installation, | ||
| 5983 | how to use command line development for both Autotools-based and Makefile-based projects, | ||
| 5984 | and an introduction to the Eclipse Yocto Plug-in. | ||
| 5985 | </p><div class="section" title="1.1. The Application Development Toolkit (ADT)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adt-intro-section"></a>1.1. The Application Development Toolkit (ADT)</h2></div></div></div><p> | ||
| 5986 | Part of the Yocto Project development solution is an Application Development | ||
| 5987 | Toolkit (ADT). | ||
| 5988 | The ADT provides you with a custom-built, cross-development | ||
| 5989 | platform suited for developing a user-targeted product application. | ||
| 5990 | </p><p> | ||
| 5991 | Fundamentally, the ADT consists of the following: | ||
| 5992 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>An architecture-specific cross-toolchain and matching | ||
| 5993 | sysroot both built by the OpenEmbedded build system, which uses Poky. | ||
| 5994 | The toolchain and sysroot are based on a metadata configuration and extensions, | ||
| 5995 | which allows you to cross-develop on the host machine for the target hardware. | ||
| 5996 | </p></li><li class="listitem"><p>The Eclipse IDE Yocto Plug-in.</p></li><li class="listitem"><p>The Quick EMUlator (QEMU), which lets you simulate target hardware. | ||
| 5997 | </p></li><li class="listitem"><p>Various user-space tools that greatly enhance your application | ||
| 5998 | development experience.</p></li></ul></div><p> | ||
| 5999 | </p><div class="section" title="1.1.1. The Cross-Toolchain"><div class="titlepage"><div><div><h3 class="title"><a id="the-cross-toolchain"></a>1.1.1. The Cross-Toolchain</h3></div></div></div><p> | ||
| 6000 | The cross-toolchain consists of a cross-compiler, cross-linker, and cross-debugger | ||
| 6001 | that are used to develop user-space applications for targeted hardware. | ||
| 6002 | This toolchain is created either by running the ADT Installer script or | ||
| 6003 | through a build directory that is based on your metadata | ||
| 6004 | configuration or extension for your targeted device. | ||
| 6005 | The cross-toolchain works with a matching target sysroot. | ||
| 6006 | </p></div><div class="section" title="1.1.2. Sysroot"><div class="titlepage"><div><div><h3 class="title"><a id="sysroot"></a>1.1.2. Sysroot</h3></div></div></div><p> | ||
| 6007 | The matching target sysroot contains needed headers and libraries for generating | ||
| 6008 | binaries that run on the target architecture. | ||
| 6009 | The sysroot is based on the target root filesystem image that is built by | ||
| 6010 | the OpenEmbedded build system Poky and uses the same metadata configuration | ||
| 6011 | used to build the cross-toolchain. | ||
| 6012 | </p></div><div class="section" title="1.1.3. Eclipse Yocto Plug-in"><div class="titlepage"><div><div><h3 class="title"><a id="eclipse-overview"></a>1.1.3. Eclipse Yocto Plug-in</h3></div></div></div><p> | ||
| 6013 | The Eclipse IDE is a popular development environment and it fully supports | ||
| 6014 | development using the Yocto Project. | ||
| 6015 | When you install and configure the Eclipse Yocto Project Plug-in into | ||
| 6016 | the Eclipse IDE, you maximize your Yocto Project experience. | ||
| 6017 | Installing and configuring the Plug-in results in an environment that | ||
| 6018 | has extensions specifically designed to let you more easily develop software. | ||
| 6019 | These extensions allow for cross-compilation, deployment, and execution of | ||
| 6020 | your output into a QEMU emulation session. | ||
| 6021 | You can also perform cross-debugging and profiling. | ||
| 6022 | The environment also supports a suite of tools that allows you to perform | ||
| 6023 | remote profiling, tracing, collection of power data, collection of | ||
| 6024 | latency data, and collection of performance data. | ||
| 6025 | </p><p> | ||
| 6026 | For information about the application development workflow that uses the Eclipse | ||
| 6027 | IDE and for a detailed example of how to install and configure the Eclipse | ||
| 6028 | Yocto Project Plug-in, see the | ||
| 6029 | "<a class="link" href="#adt-eclipse" target="_top">Working Within Eclipse</a>" section | ||
| 6030 | of the Yocto Project Development Manual. | ||
| 6031 | </p></div><div class="section" title="1.1.4. The QEMU Emulator"><div class="titlepage"><div><div><h3 class="title"><a id="the-qemu-emulator"></a>1.1.4. The QEMU Emulator</h3></div></div></div><p> | ||
| 6032 | The QEMU emulator allows you to simulate your hardware while running your | ||
| 6033 | application or image. | ||
| 6034 | QEMU is made available a number of ways: | ||
| 6035 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>If you use the ADT Installer script to install ADT, you can | ||
| 6036 | specify whether or not to install QEMU.</p></li><li class="listitem"><p>If you have downloaded a Yocto Project release and unpacked | ||
| 6037 | it to create a source directory and you have sourced | ||
| 6038 | the environment setup script, QEMU is installed and automatically | ||
| 6039 | available.</p></li><li class="listitem"><p>If you have installed the cross-toolchain | ||
| 6040 | tarball and you have sourcing the toolchain's setup environment script, QEMU | ||
| 6041 | is also installed and automatically available.</p></li></ul></div><p> | ||
| 6042 | </p></div><div class="section" title="1.1.5. User-Space Tools"><div class="titlepage"><div><div><h3 class="title"><a id="user-space-tools"></a>1.1.5. User-Space Tools</h3></div></div></div><p> | ||
| 6043 | User-space tools are included as part of the distribution. | ||
| 6044 | You will find these tools helpful during development. | ||
| 6045 | The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust. | ||
| 6046 | These tools are common development tools for the Linux platform. | ||
| 6047 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>LatencyTOP:</em></span> LatencyTOP focuses on latency | ||
| 6048 | that causes skips in audio, | ||
| 6049 | stutters in your desktop experience, or situations that overload your server | ||
| 6050 | even when you have plenty of CPU power left. | ||
| 6051 | You can find out more about LatencyTOP at | ||
| 6052 | <a class="ulink" href="http://www.latencytop.org/" target="_top">http://www.latencytop.org/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>PowerTOP:</em></span> Helps you determine what | ||
| 6053 | software is using the most power. | ||
| 6054 | You can find out more about PowerTOP at | ||
| 6055 | <a class="ulink" href="http://www.linuxpowertop.org/" target="_top">http://www.linuxpowertop.org/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>OProfile:</em></span> A system-wide profiler for Linux | ||
| 6056 | systems that is capable of profiling all running code at low overhead. | ||
| 6057 | You can find out more about OProfile at | ||
| 6058 | <a class="ulink" href="http://oprofile.sourceforge.net/about/" target="_top">http://oprofile.sourceforge.net/about/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Perf:</em></span> Performance counters for Linux used | ||
| 6059 | to keep track of certain types of hardware and software events. | ||
| 6060 | For more information on these types of counters see | ||
| 6061 | <a class="ulink" href="https://perf.wiki.kernel.org/" target="_top">https://perf.wiki.kernel.org/</a> and click | ||
| 6062 | on “Perf tools.”</p></li><li class="listitem"><p><span class="emphasis"><em>SystemTap:</em></span> A free software infrastructure | ||
| 6063 | that simplifies information gathering about a running Linux system. | ||
| 6064 | This information helps you diagnose performance or functional problems. | ||
| 6065 | SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in. | ||
| 6066 | See <a class="ulink" href="http://sourceware.org/systemtap" target="_top">http://sourceware.org/systemtap</a> for more information | ||
| 6067 | on SystemTap.</p></li><li class="listitem"><p><span class="emphasis"><em>Lttng-ust:</em></span> A User-space Tracer designed to | ||
| 6068 | provide detailed information on user-space activity. | ||
| 6069 | See <a class="ulink" href="http://lttng.org/ust" target="_top">http://lttng.org/ust</a> for more information on Lttng-ust. | ||
| 6070 | </p></li></ul></div><p> | ||
| 6071 | </p></div></div></div> | ||
| 6072 | |||
| 6073 | <div class="chapter" title="Chapter 2. Preparing for Application Development"><div class="titlepage"><div><div><h2 class="title"><a id="adt-prepare"></a>Chapter 2. Preparing for Application Development</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#installing-the-adt">2.1. Installing the ADT and Toolchains</a></span></dt><dd><dl><dt><span class="section"><a href="#using-the-adt-installer">2.1.1. Using the ADT Installer</a></span></dt><dt><span class="section"><a href="#using-an-existing-toolchain-tarball">2.1.2. Using a Cross-Toolchain Tarball</a></span></dt><dt><span class="section"><a href="#using-the-toolchain-from-within-the-build-tree">2.1.3. Using BitBake and the Build Directory</a></span></dt></dl></dd><dt><span class="section"><a href="#setting-up-the-cross-development-environment">2.2. Setting Up the Cross-Development Environment</a></span></dt><dt><span class="section"><a href="#securing-kernel-and-filesystem-images">2.3. Securing Kernel and Filesystem Images</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-the-images">2.3.1. Getting the Images</a></span></dt><dt><span class="section"><a href="#extracting-the-root-filesystem">2.3.2. Extracting the Root Filesystem</a></span></dt></dl></dd></dl></div><p> | ||
| 6074 | In order to develop applications, you need set up your host development system. | ||
| 6075 | Several ways exist that allow you to install cross-development tools, QEMU, the | ||
| 6076 | Eclipse Yocto Plug-in, and other tools. | ||
| 6077 | This chapter describes how to prepare for application development. | ||
| 6078 | </p><div class="section" title="2.1. Installing the ADT and Toolchains"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-the-adt"></a>2.1. Installing the ADT and Toolchains</h2></div></div></div><p> | ||
| 6079 | The following list describes installation methods that set up varying degrees of tool | ||
| 6080 | availabiltiy on your system. | ||
| 6081 | Regardless of the installation method you choose, | ||
| 6082 | you must <code class="filename">source</code> the cross-toolchain | ||
| 6083 | environment setup script before you use a toolchain. | ||
| 6084 | See the "<a class="link" href="#setting-up-the-cross-development-environment" title="2.2. Setting Up the Cross-Development Environment">Setting Up the | ||
| 6085 | Cross-Development Environment</a>" section for more information. | ||
| 6086 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Avoid mixing installation methods when installing toolchains for different architectures. | ||
| 6087 | For example, avoid using the ADT Installer to install some toolchains and then hand-installing | ||
| 6088 | cross-development toolchains from downloaded tarballs to install toolchains | ||
| 6089 | for different architectures. | ||
| 6090 | Mixing installation methods can result in situations where the ADT Installer becomes | ||
| 6091 | unreliable and might not install the toolchain.</p><p>If you must mix installation methods, you might avoid problems by deleting | ||
| 6092 | <code class="filename">/var/lib/opkg</code>, thus purging the <code class="filename">opkg</code> package | ||
| 6093 | metadata</p></div><p> | ||
| 6094 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Use the ADT Installer Script:</em></span> | ||
| 6095 | This method is the recommended way to install the ADT because it | ||
| 6096 | automates much of the process for you. | ||
| 6097 | For example, you can configure the installation to install the QEMU emulator | ||
| 6098 | and the user-space NFS, specify which root filesystem profiles to download, | ||
| 6099 | and define the target sysroot location.</p></li><li class="listitem"><p><span class="emphasis"><em>Use an Existing Toolchain Tarball:</em></span> | ||
| 6100 | Using this method, you select and download an architecture-specific | ||
| 6101 | toolchain tarball and then hand-install the toolchain. | ||
| 6102 | If you use this method, you just get the cross-toolchain and QEMU - you do not | ||
| 6103 | get any of the other mentioned benefits had you run the ADT Installer script.</p></li><li class="listitem"><p><span class="emphasis"><em>Use the Toolchain from within the Build Directory:</em></span> | ||
| 6104 | If you already have a | ||
| 6105 | <a class="link" href="#build-directory" target="_top">build directory</a>, | ||
| 6106 | you can build the cross-toolchain within the directory. | ||
| 6107 | However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you | ||
| 6108 | do not get any of the other benefits without taking separate steps.</p></li></ul></div><p> | ||
| 6109 | </p><div class="section" title="2.1.1. Using the ADT Installer"><div class="titlepage"><div><div><h3 class="title"><a id="using-the-adt-installer"></a>2.1.1. Using the ADT Installer</h3></div></div></div><p> | ||
| 6110 | To run the ADT Installer, you need to first get the ADT Installer tarball and then run the ADT | ||
| 6111 | Installer Script. | ||
| 6112 | </p><div class="section" title="2.1.1.1. Getting the ADT Installer Tarball"><div class="titlepage"><div><div><h4 class="title"><a id="getting-the-adt-installer-tarball"></a>2.1.1.1. Getting the ADT Installer Tarball</h4></div></div></div><p> | ||
| 6113 | The ADT Installer is contained in the ADT Installer tarball. | ||
| 6114 | You can download the tarball into any directory from the | ||
| 6115 | <a class="ulink" href="http://downloads.yoctoproject.org/releases" target="_top">Index of Releases</a>, specifically | ||
| 6116 | at | ||
| 6117 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/adt_installer" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/adt_installer</a>. | ||
| 6118 | Or, you can use BitBake to generate the tarball inside the existing | ||
| 6119 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 6120 | </p><p> | ||
| 6121 | If you use BitBake to generate the ADT Installer tarball, you must | ||
| 6122 | <code class="filename">source</code> the environment setup script | ||
| 6123 | (<code class="filename">oe-init-build-env</code>) located | ||
| 6124 | in the source directory before running the <code class="filename">bitbake</code> | ||
| 6125 | command that creates the tarball. | ||
| 6126 | </p><p> | ||
| 6127 | The following example commands download the Poky tarball, set up the | ||
| 6128 | <a class="link" href="#source-directory" target="_top">source directory</a>, | ||
| 6129 | set up the environment while also creating the default build directory, | ||
| 6130 | and run the <code class="filename">bitbake</code> command that results in the tarball | ||
| 6131 | <code class="filename">~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</code>: | ||
| 6132 | </p><pre class="literallayout"> | ||
| 6133 | $ cd ~ | ||
| 6134 | $ mkdir yocto-project | ||
| 6135 | $ cd yocto-project | ||
| 6136 | $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-1.2+snapshot-8.0.tar.bz2 | ||
| 6137 | $ tar xjf poky-1.2+snapshot-8.0.tar.bz2 | ||
| 6138 | $ source poky-1.2+snapshot-8.0/oe-init-build-env | ||
| 6139 | $ bitbake adt-installer | ||
| 6140 | </pre><p> | ||
| 6141 | </p></div><div class="section" title="2.1.1.2. Configuring and Running the ADT Installer Script"><div class="titlepage"><div><div><h4 class="title"><a id="configuring-and-running-the-adt-installer-script"></a>2.1.1.2. Configuring and Running the ADT Installer Script</h4></div></div></div><p> | ||
| 6142 | Before running the ADT Installer script, you need to unpack the tarball. | ||
| 6143 | You can unpack the tarball in any directory you wish. | ||
| 6144 | For example, this command copies the ADT Installer tarball from where | ||
| 6145 | it was built into the home directory and then unpacks the tarball into | ||
| 6146 | a top-level directory named <code class="filename">adt-installer</code>: | ||
| 6147 | </p><pre class="literallayout"> | ||
| 6148 | $ cd ~ | ||
| 6149 | $ cp ~/poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME | ||
| 6150 | $ tar -xjf adt_installer.tar.bz2 | ||
| 6151 | </pre><p> | ||
| 6152 | Unpacking it creates the directory <code class="filename">adt-installer</code>, | ||
| 6153 | which contains the ADT Installer script (<code class="filename">adt_installer</code>) | ||
| 6154 | and its configuration file (<code class="filename">adt_installer.conf</code>). | ||
| 6155 | </p><p> | ||
| 6156 | Before you run the script, however, you should examine the ADT Installer configuration | ||
| 6157 | file and be sure you are going to get what you want. | ||
| 6158 | Your configurations determine which kernel and filesystem image are downloaded. | ||
| 6159 | </p><p> | ||
| 6160 | The following list describes the configurations you can define for the ADT Installer. | ||
| 6161 | For configuration values and restrictions, see the comments in | ||
| 6162 | the <code class="filename">adt-installer.conf</code> file: | ||
| 6163 | |||
| 6164 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">YOCTOADT_REPO</code>: This area | ||
| 6165 | includes the IPKG-based packages and the root filesystem upon which | ||
| 6166 | the installation is based. | ||
| 6167 | If you want to set up your own IPKG repository pointed to by | ||
| 6168 | <code class="filename">YOCTOADT_REPO</code>, you need to be sure that the | ||
| 6169 | directory structure follows the same layout as the reference directory | ||
| 6170 | set up at <a class="ulink" href="http://adtrepo.yoctoproject.org" target="_top">http://adtrepo.yoctoproject.org</a>. | ||
| 6171 | Also, your repository needs to be accessible through HTTP.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_TARGETS</code>: The machine | ||
| 6172 | target architectures for which you want to set up cross-development | ||
| 6173 | environments.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_QEMU</code>: Indicates whether | ||
| 6174 | or not to install the emulator QEMU.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_NFS_UTIL</code>: Indicates whether | ||
| 6175 | or not to install user-mode NFS. | ||
| 6176 | If you plan to use the Eclipse IDE Yocto plug-in against QEMU, | ||
| 6177 | you should install NFS. | ||
| 6178 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>To boot QEMU images using our userspace NFS server, you need | ||
| 6179 | to be running <code class="filename">portmap</code> or <code class="filename">rpcbind</code>. | ||
| 6180 | If you are running <code class="filename">rpcbind</code>, you will also need to add the | ||
| 6181 | <code class="filename">-i</code> option when <code class="filename">rpcbind</code> starts up. | ||
| 6182 | Please make sure you understand the security implications of doing this. | ||
| 6183 | You might also have to modify your firewall settings to allow | ||
| 6184 | NFS booting to work.</div></li><li class="listitem"><p><code class="filename">YOCTOADT_ROOTFS_<arch></code>: The root | ||
| 6185 | filesystem images you want to download from the | ||
| 6186 | <code class="filename">YOCTOADT_IPKG_REPO</code> repository.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_TARGET_SYSROOT_IMAGE_<arch></code>: The | ||
| 6187 | particular root filesystem used to extract and create the target sysroot. | ||
| 6188 | The value of this variable must have been specified with | ||
| 6189 | <code class="filename">YOCTOADT_ROOTFS_<arch></code>. | ||
| 6190 | For example, if you downloaded both <code class="filename">minimal</code> and | ||
| 6191 | <code class="filename">sato-sdk</code> images by setting | ||
| 6192 | <code class="filename">YOCTOADT_ROOTFS_<arch></code> | ||
| 6193 | to "minimal sato-sdk", then <code class="filename">YOCTOADT_ROOTFS_<arch></code> | ||
| 6194 | must be set to either <code class="filename">minimal</code> or | ||
| 6195 | <code class="filename">sato-sdk</code>.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_TARGET_SYSROOT_LOC_<arch></code>: The | ||
| 6196 | location on the development host where the target sysroot is created. | ||
| 6197 | </p></li></ul></div><p> | ||
| 6198 | </p><p> | ||
| 6199 | After you have configured the <code class="filename">adt_installer.conf</code> file, | ||
| 6200 | run the installer using the following command. | ||
| 6201 | Be sure that you are not trying to use cross-compilation tools. | ||
| 6202 | When you run the installer, the environment must use a | ||
| 6203 | host <code class="filename">gcc</code>: | ||
| 6204 | </p><pre class="literallayout"> | ||
| 6205 | $ ./adt_installer | ||
| 6206 | </pre><p> | ||
| 6207 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 6208 | The ADT Installer requires the <code class="filename">libtool</code> package to complete. | ||
| 6209 | If you install the recommended packages as described in | ||
| 6210 | "<a class="link" href="#packages" target="_top">The Packages</a>" | ||
| 6211 | section of the Yocto Project Quick Start, then you will have libtool installed. | ||
| 6212 | </div><p> | ||
| 6213 | Once the installer begins to run, you are asked whether you want to run in | ||
| 6214 | interactive or silent mode. | ||
| 6215 | If you want to closely monitor the installation, choose “I” for interactive | ||
| 6216 | mode rather than “S” for silent mode. | ||
| 6217 | Follow the prompts from the script to complete the installation. | ||
| 6218 | </p><p> | ||
| 6219 | Once the installation completes, the ADT, which includes the cross-toolchain, is installed. | ||
| 6220 | You will notice environment setup files for the cross-toolchain in | ||
| 6221 | <code class="filename">/opt/poky/1.3</code>, | ||
| 6222 | and image tarballs in the <code class="filename">adt-installer</code> | ||
| 6223 | directory according to your installer configurations, and the target sysroot located | ||
| 6224 | according to the <code class="filename">YOCTOADT_TARGET_SYSROOT_LOC_<arch></code> variable | ||
| 6225 | also in your configuration file. | ||
| 6226 | </p></div></div><div class="section" title="2.1.2. Using a Cross-Toolchain Tarball"><div class="titlepage"><div><div><h3 class="title"><a id="using-an-existing-toolchain-tarball"></a>2.1.2. Using a Cross-Toolchain Tarball</h3></div></div></div><p> | ||
| 6227 | If you want to simply install the cross-toolchain by hand, you can do so by using an existing | ||
| 6228 | cross-toolchain tarball. | ||
| 6229 | If you use this method to install the cross-toolchain and you still need to install the target | ||
| 6230 | sysroot, you will have to install sysroot separately. | ||
| 6231 | </p><p> | ||
| 6232 | Follow these steps: | ||
| 6233 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Go to | ||
| 6234 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/</a> | ||
| 6235 | and find the folder that matches your host development system | ||
| 6236 | (i.e. <code class="filename">i686</code> for 32-bit machines or | ||
| 6237 | <code class="filename">x86-64</code> for 64-bit machines).</p></li><li class="listitem"><p>Go into that folder and download the toolchain tarball whose name | ||
| 6238 | includes the appropriate target architecture. | ||
| 6239 | For example, if your host development system is an Intel-based 64-bit system and | ||
| 6240 | you are going to use your cross-toolchain for an Intel-based 32-bit target, go into the | ||
| 6241 | <code class="filename">x86_64</code> folder and download the following tarball: | ||
| 6242 | </p><pre class="literallayout"> | ||
| 6243 | poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2 | ||
| 6244 | </pre><p> | ||
| 6245 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>As an alternative to steps one and two, you can build the toolchain tarball | ||
| 6246 | if you have a <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 6247 | If you need GMAE, you should use the <code class="filename">bitbake meta-toolchain-gmae</code> | ||
| 6248 | command. | ||
| 6249 | The resulting tarball will support such development. | ||
| 6250 | However, if you are not concerned with GMAE, | ||
| 6251 | you can generate the tarball using <code class="filename">bitbake meta-toolchain</code>.</p><p>Use the appropriate <code class="filename">bitbake</code> command only after you have | ||
| 6252 | sourced the <code class="filename">oe-build-init-env</code> script located in the source | ||
| 6253 | directory. | ||
| 6254 | When the <code class="filename">bitbake</code> command completes, the tarball will | ||
| 6255 | be in <code class="filename">tmp/deploy/sdk</code> in the build directory. | ||
| 6256 | </p></div></li><li class="listitem"><p>Make sure you are in the root directory with root privileges and then expand | ||
| 6257 | the tarball. | ||
| 6258 | The tarball expands into <code class="filename">/opt/poky/1.3</code>. | ||
| 6259 | Once the tarball is expanded, the cross-toolchain is installed. | ||
| 6260 | You will notice environment setup files for the cross-toolchain in the directory. | ||
| 6261 | </p></li></ol></div><p> | ||
| 6262 | </p></div><div class="section" title="2.1.3. Using BitBake and the Build Directory"><div class="titlepage"><div><div><h3 class="title"><a id="using-the-toolchain-from-within-the-build-tree"></a>2.1.3. Using BitBake and the Build Directory</h3></div></div></div><p> | ||
| 6263 | A final way of making the cross-toolchain available is to use BitBake | ||
| 6264 | to generate the toolchain within an existing | ||
| 6265 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 6266 | This method does not install the toolchain into the | ||
| 6267 | <code class="filename">/opt</code> directory. | ||
| 6268 | As with the previous method, if you need to install the target sysroot, you must | ||
| 6269 | do that separately as well. | ||
| 6270 | </p><p> | ||
| 6271 | Follow these steps to generate the toolchain into the build directory: | ||
| 6272 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Source the environment setup script | ||
| 6273 | <code class="filename">oe-init-build-env</code> located in the | ||
| 6274 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 6275 | </p></li><li class="listitem"><p>At this point, you should be sure that the | ||
| 6276 | <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> variable | ||
| 6277 | in the <code class="filename">local.conf</code> file found in the | ||
| 6278 | <code class="filename">conf</code> directory of the build directory | ||
| 6279 | is set for the target architecture. | ||
| 6280 | Comments within the <code class="filename">local.conf</code> file list the values you | ||
| 6281 | can use for the <code class="filename">MACHINE</code> variable. | ||
| 6282 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>You can populate the build directory with the cross-toolchains for more | ||
| 6283 | than a single architecture. | ||
| 6284 | You just need to edit the <code class="filename">MACHINE</code> variable in the | ||
| 6285 | <code class="filename">local.conf</code> file and re-run the BitBake | ||
| 6286 | command.</div></li><li class="listitem"><p>Run <code class="filename">bitbake meta-ide-support</code> to complete the | ||
| 6287 | cross-toolchain generation. | ||
| 6288 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If you change out of your working directory after you | ||
| 6289 | <code class="filename">source</code> the environment setup script and before you run | ||
| 6290 | the <code class="filename">bitbake</code> command, the command might not work. | ||
| 6291 | Be sure to run the <code class="filename">bitbake</code> command immediately | ||
| 6292 | after checking or editing the <code class="filename">local.conf</code> but without | ||
| 6293 | changing out of your working directory.</div><p> | ||
| 6294 | Once the <code class="filename">bitbake</code> command finishes, | ||
| 6295 | the cross-toolchain is generated and populated within the build directory. | ||
| 6296 | You will notice environment setup files for the cross-toolchain in the | ||
| 6297 | build directory in the <code class="filename">tmp</code> directory. | ||
| 6298 | Setup script filenames contain the strings <code class="filename">environment-setup</code>. | ||
| 6299 | </p></li></ol></div><p> | ||
| 6300 | </p></div></div><div class="section" title="2.2. Setting Up the Cross-Development Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="setting-up-the-cross-development-environment"></a>2.2. Setting Up the Cross-Development Environment</h2></div></div></div><p> | ||
| 6301 | Before you can develop using the cross-toolchain, you need to set up the | ||
| 6302 | cross-development environment by sourcing the toolchain's environment setup script. | ||
| 6303 | If you used the ADT Installer or hand-installed cross-toolchain, | ||
| 6304 | then you can find this script in the <code class="filename">/opt/poky/1.3</code> | ||
| 6305 | directory. | ||
| 6306 | If you installed the toolchain in the | ||
| 6307 | <a class="link" href="#build-directory" target="_top">build directory</a>, | ||
| 6308 | you can find the environment setup | ||
| 6309 | script for the toolchain in the build directory's <code class="filename">tmp</code> directory. | ||
| 6310 | </p><p> | ||
| 6311 | Be sure to run the environment setup script that matches the architecture for | ||
| 6312 | which you are developing. | ||
| 6313 | Environment setup scripts begin with the string “<code class="filename">environment-setup</code>” | ||
| 6314 | and include as part of their name the architecture. | ||
| 6315 | For example, the toolchain environment setup script for a 64-bit IA-based architecture would | ||
| 6316 | be the following: | ||
| 6317 | </p><pre class="literallayout"> | ||
| 6318 | /opt/poky/1.3/environment-setup-x86_64-poky-linux | ||
| 6319 | </pre><p> | ||
| 6320 | </p></div><div class="section" title="2.3. Securing Kernel and Filesystem Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="securing-kernel-and-filesystem-images"></a>2.3. Securing Kernel and Filesystem Images</h2></div></div></div><p> | ||
| 6321 | You will need to have a kernel and filesystem image to boot using your | ||
| 6322 | hardware or the QEMU emulator. | ||
| 6323 | Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem | ||
| 6324 | as the target sysroot, you need to extract the root filesystem. | ||
| 6325 | </p><div class="section" title="2.3.1. Getting the Images"><div class="titlepage"><div><div><h3 class="title"><a id="getting-the-images"></a>2.3.1. Getting the Images</h3></div></div></div><p> | ||
| 6326 | To get the kernel and filesystem images, you either have to build them or download | ||
| 6327 | pre-built versions. | ||
| 6328 | You can find examples for both these situations in the | ||
| 6329 | "<a class="link" href="#test-run" target="_top">A Quick Test Run</a>" section of | ||
| 6330 | the Yocto Project Quick Start. | ||
| 6331 | </p><p> | ||
| 6332 | The Yocto Project ships basic kernel and filesystem images for several | ||
| 6333 | architectures (<code class="filename">x86</code>, <code class="filename">x86-64</code>, | ||
| 6334 | <code class="filename">mips</code>, <code class="filename">powerpc</code>, and <code class="filename">arm</code>) | ||
| 6335 | that you can use unaltered in the QEMU emulator. | ||
| 6336 | These kernel images reside in the release | ||
| 6337 | area - <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines</a> | ||
| 6338 | and are ideal for experimentation using Yocto Project. | ||
| 6339 | For information on the image types you can build using the OpenEmbedded build system, | ||
| 6340 | see the | ||
| 6341 | "<a class="link" href="#ref-images" target="_top">Images</a>" chapter in | ||
| 6342 | the Yocto Project Reference Manual. | ||
| 6343 | </p><p> | ||
| 6344 | If you plan on remotely deploying and debugging your application from within the | ||
| 6345 | Eclipse IDE, you must have an image that contains the Yocto Target Communication | ||
| 6346 | Framework (TCF) agent (<code class="filename">tcf-agent</code>). | ||
| 6347 | By default, the Yocto Project provides only one type pre-built image that contains the | ||
| 6348 | <code class="filename">tcf-agent</code>. | ||
| 6349 | And, those images are SDK (e.g.<code class="filename">core-image-sato-sdk</code>). | ||
| 6350 | </p><p> | ||
| 6351 | If you want to use a different image type that contains the <code class="filename">tcf-agent</code>, | ||
| 6352 | you can do so one of two ways: | ||
| 6353 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Modify the <code class="filename">conf/local.conf</code> configuration in | ||
| 6354 | the <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 6355 | and then rebuild the image. | ||
| 6356 | With this method, you need to modify the | ||
| 6357 | <a class="link" href="#var-EXTRA_IMAGE_FEATURES" target="_top"><code class="filename">EXTRA_IMAGE_FEATURES</code></a> | ||
| 6358 | variable to have the value of "tools-debug" before rebuilding the image. | ||
| 6359 | Once the image is rebuilt, the <code class="filename">tcf-agent</code> will be included | ||
| 6360 | in the image and is launched automatically after the boot.</p></li><li class="listitem"><p>Manually build the <code class="filename">tcf-agent</code>. | ||
| 6361 | To build the agent, follow these steps: | ||
| 6362 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Be sure the ADT is installed as described in the | ||
| 6363 | "<a class="link" href="#installing-the-adt" title="2.1. Installing the ADT and Toolchains">Installing the ADT and Toolchains</a>" section. | ||
| 6364 | </p></li><li class="listitem"><p>Set up the cross-development environment as described in the | ||
| 6365 | "<a class="link" href="#setting-up-the-cross-development-environment" title="2.2. Setting Up the Cross-Development Environment">Setting | ||
| 6366 | Up the Cross-Development Environment</a>" section.</p></li><li class="listitem"><p>Get the <code class="filename">tcf-agent</code> source code using | ||
| 6367 | the following commands: | ||
| 6368 | </p><pre class="literallayout"> | ||
| 6369 | $ git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git | ||
| 6370 | $ cd agent | ||
| 6371 | </pre></li><li class="listitem"><p>Modify the <code class="filename">Makefile.inc</code> file | ||
| 6372 | for the cross-compilation environment by setting the | ||
| 6373 | <code class="filename">OPSYS</code> and | ||
| 6374 | <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> | ||
| 6375 | variables according to your target.</p></li><li class="listitem"><p>Use the cross-development tools to build the | ||
| 6376 | <code class="filename">tcf-agent</code>. | ||
| 6377 | Before you "Make" the file, be sure your cross-tools are set up first. | ||
| 6378 | See the "<a class="link" href="#makefile-based-projects" title="4.2. Makefile-Based Projects">Makefile-Based Projects</a>" | ||
| 6379 | section for information on how to make sure the cross-tools are set up | ||
| 6380 | correctly.</p><p>If the build is successful, the <code class="filename">tcf-agent</code> output will | ||
| 6381 | be <code class="filename">obj/$(OPSYS)/$(MACHINE)/Debug/agent</code>.</p></li><li class="listitem"><p>Deploy the agent into the image's root filesystem.</p></li></ol></div><p> | ||
| 6382 | </p></li></ul></div><p> | ||
| 6383 | </p></div><div class="section" title="2.3.2. Extracting the Root Filesystem"><div class="titlepage"><div><div><h3 class="title"><a id="extracting-the-root-filesystem"></a>2.3.2. Extracting the Root Filesystem</h3></div></div></div><p> | ||
| 6384 | You must extract the root filesystem if you want to boot the image using NFS | ||
| 6385 | or you want to use the root filesystem as the target sysroot. | ||
| 6386 | For example, the Eclipse IDE environment with the Eclipse Yocto Plug-in installed allows you | ||
| 6387 | to use QEMU to boot under NFS. | ||
| 6388 | Another example is if you want to develop your target application using the | ||
| 6389 | root filesystem as the target sysroot. | ||
| 6390 | </p><p> | ||
| 6391 | To extract the root filesystem, first <code class="filename">source</code> | ||
| 6392 | the cross-development environment setup script and then | ||
| 6393 | use the <code class="filename">runqemu-extract-sdk</code> command on the | ||
| 6394 | filesystem image. | ||
| 6395 | For example, the following commands set up the environment and then extract | ||
| 6396 | the root filesystem from a previously built filesystem image tarball named | ||
| 6397 | <code class="filename">core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2</code>. | ||
| 6398 | The example extracts the root filesystem into the <code class="filename">$HOME/qemux86-sato</code> | ||
| 6399 | directory: | ||
| 6400 | </p><pre class="literallayout"> | ||
| 6401 | $ source $HOME/poky/build/tmp/environment-setup-i586-poky-linux | ||
| 6402 | $ runqemu-extract-sdk \ | ||
| 6403 | tmp/deploy/images/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ | ||
| 6404 | $HOME/qemux86-sato | ||
| 6405 | </pre><p> | ||
| 6406 | In this case, you could now point to the target sysroot at | ||
| 6407 | <code class="filename">$HOME/qemux86-sato</code>. | ||
| 6408 | </p></div></div></div> | ||
| 6409 | |||
| 6410 | <div class="chapter" title="Chapter 3. Optionally Customizing the Development Packages Installation"><div class="titlepage"><div><div><h2 class="title"><a id="adt-package"></a>Chapter 3. Optionally Customizing the Development Packages Installation</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#package-management-systems">3.1. Package Management Systems</a></span></dt><dt><span class="section"><a href="#configuring-the-pms">3.2. Configuring the PMS</a></span></dt></dl></div><p> | ||
| 6411 | Because the Yocto Project is suited for embedded Linux development, it is | ||
| 6412 | likely that you will need to customize your development packages installation. | ||
| 6413 | For example, if you are developing a minimal image, then you might not need | ||
| 6414 | certain packages (e.g. graphics support packages). | ||
| 6415 | Thus, you would like to be able to remove those packages from your target sysroot. | ||
| 6416 | </p><div class="section" title="3.1. Package Management Systems"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="package-management-systems"></a>3.1. Package Management Systems</h2></div></div></div><p> | ||
| 6417 | The OpenEmbedded build system supports the generation of sysroot files using | ||
| 6418 | three different Package Management Systems (PMS): | ||
| 6419 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>OPKG:</em></span> A less well known PMS whose use | ||
| 6420 | originated in the OpenEmbedded and OpenWrt embedded Linux projects. | ||
| 6421 | This PMS works with files packaged in an <code class="filename">.ipk</code> format. | ||
| 6422 | See <a class="ulink" href="http://en.wikipedia.org/wiki/Opkg" target="_top">http://en.wikipedia.org/wiki/Opkg</a> for more | ||
| 6423 | information about OPKG.</p></li><li class="listitem"><p><span class="emphasis"><em>RPM:</em></span> A more widely known PMS intended for GNU/Linux | ||
| 6424 | distributions. | ||
| 6425 | This PMS works with files packaged in an <code class="filename">.rms</code> format. | ||
| 6426 | The build system currently installs through this PMS by default. | ||
| 6427 | See <a class="ulink" href="http://en.wikipedia.org/wiki/RPM_Package_Manager" target="_top">http://en.wikipedia.org/wiki/RPM_Package_Manager</a> | ||
| 6428 | for more information about RPM.</p></li><li class="listitem"><p><span class="emphasis"><em>Debian:</em></span> The PMS for Debian-based systems | ||
| 6429 | is built on many PMS tools. | ||
| 6430 | The lower-level PMS tool <code class="filename">dpkg</code> forms the base of the Debian PMS. | ||
| 6431 | For information on dpkg see | ||
| 6432 | <a class="ulink" href="http://en.wikipedia.org/wiki/Dpkg" target="_top">http://en.wikipedia.org/wiki/Dpkg</a>.</p></li></ul></div><p> | ||
| 6433 | </p></div><div class="section" title="3.2. Configuring the PMS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="configuring-the-pms"></a>3.2. Configuring the PMS</h2></div></div></div><p> | ||
| 6434 | Whichever PMS you are using, you need to be sure that the | ||
| 6435 | <a class="link" href="#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a> | ||
| 6436 | variable in the <code class="filename">conf/local.conf</code> | ||
| 6437 | file is set to reflect that system. | ||
| 6438 | The first value you choose for the variable specifies the package file format for the root | ||
| 6439 | filesystem at sysroot. | ||
| 6440 | Additional values specify additional formats for convenience or testing. | ||
| 6441 | See the configuration file for details. | ||
| 6442 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 6443 | For build performance information related to the PMS, see | ||
| 6444 | <a class="link" href="#ref-classes-package" target="_top">Packaging - <code class="filename">package*.bbclass</code></a> | ||
| 6445 | in the Yocto Project Reference Manual. | ||
| 6446 | </div><p> | ||
| 6447 | As an example, consider a scenario where you are using OPKG and you want to add | ||
| 6448 | the <code class="filename">libglade</code> package to the target sysroot. | ||
| 6449 | </p><p> | ||
| 6450 | First, you should generate the <code class="filename">ipk</code> file for the | ||
| 6451 | <code class="filename">libglade</code> package and add it | ||
| 6452 | into a working <code class="filename">opkg</code> repository. | ||
| 6453 | Use these commands: | ||
| 6454 | </p><pre class="literallayout"> | ||
| 6455 | $ bitbake libglade | ||
| 6456 | $ bitbake package-index | ||
| 6457 | </pre><p> | ||
| 6458 | </p><p> | ||
| 6459 | Next, source the environment setup script found in the | ||
| 6460 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 6461 | Follow that by setting up the installation destination to point to your | ||
| 6462 | sysroot as <code class="filename"><sysroot_dir></code>. | ||
| 6463 | Finally, have an OPKG configuration file <code class="filename"><conf_file></code> | ||
| 6464 | that corresponds to the <code class="filename">opkg</code> repository you have just created. | ||
| 6465 | The following command forms should now work: | ||
| 6466 | </p><pre class="literallayout"> | ||
| 6467 | $ opkg-cl –f <conf_file> -o <sysroot_dir> update | ||
| 6468 | $ opkg-cl –f <cconf_file> -o <sysroot_dir> \ | ||
| 6469 | --force-overwrite install libglade | ||
| 6470 | $ opkg-cl –f <cconf_file> -o <sysroot_dir> \ | ||
| 6471 | --force-overwrite install libglade-dbg | ||
| 6472 | $ opkg-cl –f <conf_file> -o <sysroot_dir> \ | ||
| 6473 | --force-overwrite install libglade-dev | ||
| 6474 | </pre><p> | ||
| 6475 | </p></div></div> | ||
| 6476 | |||
| 6477 | <div class="chapter" title="Chapter 4. Using the Command Line"><div class="titlepage"><div><div><h2 class="title"><a id="using-the-command-line"></a>Chapter 4. Using the Command Line</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#autotools-based-projects">4.1. Autotools-Based Projects</a></span></dt><dt><span class="section"><a href="#makefile-based-projects">4.2. Makefile-Based Projects</a></span></dt></dl></div><p> | ||
| 6478 | Recall that earlier the manual discussed how to use an existing toolchain | ||
| 6479 | tarball that had been installed into <code class="filename">/opt/poky</code>, | ||
| 6480 | which is outside of the build directory | ||
| 6481 | (see the section "<a class="link" href="#using-an-existing-toolchain-tarball" title="2.1.2. Using a Cross-Toolchain Tarball">Using an Existing | ||
| 6482 | Toolchain Tarball)</a>". | ||
| 6483 | And, that sourcing your architecture-specific environment setup script | ||
| 6484 | initializes a suitable cross-toolchain development environment. | ||
| 6485 | During the setup, locations for the compiler, QEMU scripts, QEMU binary, | ||
| 6486 | a special version of <code class="filename">pkgconfig</code> and other useful | ||
| 6487 | utilities are added to the <code class="filename">PATH</code> variable. | ||
| 6488 | Variables to assist <code class="filename">pkgconfig</code> and <code class="filename">autotools</code> | ||
| 6489 | are also defined so that, | ||
| 6490 | for example, <code class="filename">configure.sh</code> can find pre-generated | ||
| 6491 | test results for tests that need target hardware on which to run. | ||
| 6492 | These conditions allow you to easily use the toolchain outside of the | ||
| 6493 | OpenEmbedded build environment on both autotools-based projects and | ||
| 6494 | Makefile-based projects. | ||
| 6495 | </p><div class="section" title="4.1. Autotools-Based Projects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="autotools-based-projects"></a>4.1. Autotools-Based Projects</h2></div></div></div><p> | ||
| 6496 | For an Autotools-based project, you can use the cross-toolchain by just | ||
| 6497 | passing the appropriate host option to <code class="filename">configure.sh</code>. | ||
| 6498 | The host option you use is derived from the name of the environment setup | ||
| 6499 | script in <code class="filename">/opt/poky</code> resulting from unpacking the | ||
| 6500 | cross-toolchain tarball. | ||
| 6501 | For example, the host option for an ARM-based target that uses the GNU EABI | ||
| 6502 | is <code class="filename">armv5te-poky-linux-gnueabi</code>. | ||
| 6503 | Note that the name of the script is | ||
| 6504 | <code class="filename">environment-setup-armv5te-poky-linux-gnueabi</code>. | ||
| 6505 | Thus, the following command works: | ||
| 6506 | </p><pre class="literallayout"> | ||
| 6507 | $ configure --host=armv5te-poky-linux-gnueabi \ | ||
| 6508 | --with-libtool-sysroot=<sysroot-dir> | ||
| 6509 | </pre><p> | ||
| 6510 | </p><p> | ||
| 6511 | This single command updates your project and rebuilds it using the appropriate | ||
| 6512 | cross-toolchain tools. | ||
| 6513 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 6514 | If <code class="filename">configure</code> script results in problems recognizing the | ||
| 6515 | <code class="filename">--with-libtool-sysroot=<sysroot-dir></code> option, | ||
| 6516 | regenerate the script to enable the support by doing the following and then | ||
| 6517 | re-running the script: | ||
| 6518 | <pre class="literallayout"> | ||
| 6519 | $ libtoolize --automake | ||
| 6520 | $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ | ||
| 6521 | [-I <dir_containing_your_project-specific_m4_macros>] | ||
| 6522 | $ autoconf | ||
| 6523 | $ autoheader | ||
| 6524 | $ automake -a | ||
| 6525 | </pre></div></div><div class="section" title="4.2. Makefile-Based Projects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="makefile-based-projects"></a>4.2. Makefile-Based Projects</h2></div></div></div><p> | ||
| 6526 | For a Makefile-based project, you use the cross-toolchain by making sure | ||
| 6527 | the tools are used. | ||
| 6528 | You can do this as follows: | ||
| 6529 | </p><pre class="literallayout"> | ||
| 6530 | CC=arm-poky-linux-gnueabi-gcc | ||
| 6531 | LD=arm-poky-linux-gnueabi-ld | ||
| 6532 | CFLAGS=”${CFLAGS} --sysroot=<sysroot-dir>” | ||
| 6533 | CXXFLAGS=”${CXXFLAGS} --sysroot=<sysroot-dir>” | ||
| 6534 | </pre><p> | ||
| 6535 | </p></div></div> | ||
| 6536 | |||
| 6537 | |||
| 6538 | |||
| 6539 | </div> | ||
| 6540 | |||
| 6541 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/bsp-title.png" align="left" width="100%" /></td></tr></table> | ||
| 6542 | |||
| 6543 | <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="bsp-guide"></a></h1></div><div><div class="authorgroup"> | ||
| 6544 | <div class="author"><h3 class="author"><span class="firstname">Tom</span> <span class="surname">Zanussi</span></h3><div class="affiliation"> | ||
| 6545 | <span class="orgname">Intel Corporation<br /></span> | ||
| 6546 | </div><code class="email"><<a class="email" href="mailto:tom.zanussi@intel.com">tom.zanussi@intel.com</a>></code></div> | ||
| 6547 | <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"> | ||
| 6548 | <span class="orgname">Linux Foundation<br /></span> | ||
| 6549 | </div><code class="email"><<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>></code></div> | ||
| 6550 | </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1501714"></a> | ||
| 6551 | <p> | ||
| 6552 | Permission is granted to copy, distribute and/or modify this document under | ||
| 6553 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/" target="_top">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. | ||
| 6554 | </p> | ||
| 6555 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 6556 | Due to production processes, there could be differences between the Yocto Project | ||
| 6557 | documentation bundled in the release tarball and the | ||
| 6558 | Yocto Project Board Support Package (BSP) Developer's Guide on | ||
| 6559 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 6560 | For the latest version of this manual, see the manual on the website. | ||
| 6561 | </div> | ||
| 6562 | </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> | ||
| 6563 | <tr><td align="left">Revision 0.9</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">The initial document draft released with the Yocto Project 0.9 Release.</td></tr> | ||
| 6564 | <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> | ||
| 6565 | <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> | ||
| 6566 | <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> | ||
| 6567 | <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> | ||
| 6568 | <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> | ||
| 6569 | </table></div></div></div><hr /></div> | ||
| 6570 | |||
| 6571 | |||
| 6572 | <div class="chapter" title="Chapter 1. Board Support Packages (BSP) - Developer's Guide"><div class="titlepage"><div><div><h2 class="title"><a id="bsp"></a>Chapter 1. Board Support Packages (BSP) - Developer's Guide</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#bsp-layers">1.1. BSP Layers</a></span></dt><dt><span class="section"><a href="#bsp-filelayout">1.2. Example Filesystem Layout</a></span></dt><dd><dl><dt><span class="section"><a href="#bsp-filelayout-license">1.2.1. License Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-readme">1.2.2. README File</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-readme-sources">1.2.3. README.sources File</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-binary">1.2.4. Pre-built User Binaries</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-layer">1.2.5. Layer Configuration File</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-machine">1.2.6. Hardware Configuration Options</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-misc-recipes">1.2.7. Miscellaneous Recipe Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-core-recipes">1.2.8. Core Recipe Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-recipes-graphics">1.2.9. Display Support Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-kernel">1.2.10. Linux Kernel Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#requirements-and-recommendations-for-released-bsps">1.3. Requirements and Recommendations for Released BSPs</a></span></dt><dd><dl><dt><span class="section"><a href="#released-bsp-requirements">1.3.1. Released BSP Requirements</a></span></dt><dt><span class="section"><a href="#released-bsp-recommendations">1.3.2. Released BSP Recommendations</a></span></dt></dl></dd><dt><span class="section"><a href="#customizing-a-recipe-for-a-bsp">1.4. Customizing a Recipe for a BSP</a></span></dt><dt><span class="section"><a href="#bsp-licensing-considerations">1.5. BSP Licensing Considerations</a></span></dt><dt><span class="section"><a href="#using-the-yocto-projects-bsp-tools">1.6. Using the Yocto Project's BSP Tools</a></span></dt><dd><dl><dt><span class="section"><a href="#common-features">1.6.1. Common Features</a></span></dt><dt><span class="section"><a href="#creating-a-new-bsp-layer-using-the-yocto-bsp-script">1.6.2. Creating a new BSP Layer Using the yocto-bsp Script</a></span></dt><dt><span class="section"><a href="#managing-kernel-patches-and-config-items-with-yocto-kernel">1.6.3. Managing Kernel Patches and Config Items with yocto-kernel</a></span></dt></dl></dd></dl></div><p> | ||
| 6573 | A Board Support Package (BSP) is a collection of information that | ||
| 6574 | defines how to support a particular hardware device, set of devices, or | ||
| 6575 | hardware platform. | ||
| 6576 | The BSP includes information about the hardware features | ||
| 6577 | present on the device and kernel configuration information along with any | ||
| 6578 | additional hardware drivers required. | ||
| 6579 | The BSP also lists any additional software | ||
| 6580 | components required in addition to a generic Linux software stack for both | ||
| 6581 | essential and optional platform features. | ||
| 6582 | </p><p> | ||
| 6583 | This chapter (or document if you are reading the BSP Developer's Guide) | ||
| 6584 | talks about BSP Layers, defines a structure for components | ||
| 6585 | so that BSPs follow a commonly understood layout, discusses how to customize | ||
| 6586 | a recipe for a BSP, addresses BSP licensing, and provides information that | ||
| 6587 | shows you how to create and manage a | ||
| 6588 | <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layer</a> using two Yocto Project | ||
| 6589 | <a class="link" href="#using-the-yocto-projects-bsp-tools" title="1.6. Using the Yocto Project's BSP Tools">BSP Tools</a>. | ||
| 6590 | </p><div class="section" title="1.1. BSP Layers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bsp-layers"></a>1.1. BSP Layers</h2></div></div></div><p> | ||
| 6591 | The BSP consists of a file structure inside a base directory. | ||
| 6592 | Collectively, you can think of the base directory and the file structure | ||
| 6593 | as a BSP Layer. | ||
| 6594 | BSP Layers use the following naming convention: | ||
| 6595 | </p><pre class="literallayout"> | ||
| 6596 | meta-<bsp_name> | ||
| 6597 | </pre><p> | ||
| 6598 | "bsp_name" is a placeholder for the machine or platform name. | ||
| 6599 | </p><p> | ||
| 6600 | The layer's base directory (<code class="filename">meta-<bsp_name></code>) is the root | ||
| 6601 | of the BSP Layer. | ||
| 6602 | This root is what you add to the | ||
| 6603 | <a class="link" href="#var-BBLAYERS" target="_top"><code class="filename">BBLAYERS</code></a> | ||
| 6604 | variable in the <code class="filename">conf/bblayers.conf</code> file found in the | ||
| 6605 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 6606 | Adding the root allows the OpenEmbedded build system to recognize the BSP | ||
| 6607 | definition and from it build an image. | ||
| 6608 | Here is an example: | ||
| 6609 | </p><pre class="literallayout"> | ||
| 6610 | BBLAYERS = " \ | ||
| 6611 | /usr/local/src/yocto/meta \ | ||
| 6612 | /usr/local/src/yocto/meta-yocto \ | ||
| 6613 | /usr/local/src/yocto/meta-<bsp_name> \ | ||
| 6614 | " | ||
| 6615 | </pre><p> | ||
| 6616 | </p><p> | ||
| 6617 | Some BSPs require additional layers on | ||
| 6618 | top of the BSP's root layer in order to be functional. | ||
| 6619 | For these cases, you also need to add those layers to the | ||
| 6620 | <code class="filename">BBLAYERS</code> variable in order to build the BSP. | ||
| 6621 | You must also specify in the "Dependencies" section of the BSP's | ||
| 6622 | <code class="filename">README</code> file any requirements for additional | ||
| 6623 | layers and, preferably, any | ||
| 6624 | build instructions that might be contained elsewhere | ||
| 6625 | in the <code class="filename">README</code> file. | ||
| 6626 | </p><p> | ||
| 6627 | Some layers function as a layer to hold other BSP layers. | ||
| 6628 | An example of this type of layer is the <code class="filename">meta-intel</code> layer. | ||
| 6629 | The <code class="filename">meta-intel</code> layer contains over 10 individual BSP layers. | ||
| 6630 | </p><p> | ||
| 6631 | For more detailed information on layers, see the | ||
| 6632 | "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding and Creating Layers</a>" | ||
| 6633 | section of the Yocto Project Development Manual. | ||
| 6634 | You can also see the detailed examples in the appendices of the | ||
| 6635 | Yocto Project Development Manual. | ||
| 6636 | </p></div><div class="section" title="1.2. Example Filesystem Layout"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bsp-filelayout"></a>1.2. Example Filesystem Layout</h2></div></div></div><p> | ||
| 6637 | Providing a common form allows end-users to understand and become familiar | ||
| 6638 | with the layout. | ||
| 6639 | A common format also encourages standardization of software support of hardware. | ||
| 6640 | </p><p> | ||
| 6641 | The proposed form does have elements that are specific to the | ||
| 6642 | OpenEmbedded build system. | ||
| 6643 | It is intended that this information can be | ||
| 6644 | used by other build systems besides the OpenEmbedded build system | ||
| 6645 | and that it will be simple | ||
| 6646 | to extract information and convert it to other formats if required. | ||
| 6647 | The OpenEmbedded build system, through its standard layers mechanism, can directly | ||
| 6648 | accept the format described as a layer. | ||
| 6649 | The BSP captures all | ||
| 6650 | the hardware-specific details in one place in a standard format, which is | ||
| 6651 | useful for any person wishing to use the hardware platform regardless of | ||
| 6652 | the build system they are using. | ||
| 6653 | </p><p> | ||
| 6654 | The BSP specification does not include a build system or other tools - | ||
| 6655 | it is concerned with the hardware-specific components only. | ||
| 6656 | At the end-distribution point, you can ship the BSP combined with a build system | ||
| 6657 | and other tools. | ||
| 6658 | However, it is important to maintain the distinction that these | ||
| 6659 | are separate components that happen to be combined in certain end products. | ||
| 6660 | </p><p> | ||
| 6661 | Before looking at the common form for the file structure inside a BSP Layer, | ||
| 6662 | you should be aware that some requirements do exist in order for a BSP to | ||
| 6663 | be considered compliant with the Yocto Project. | ||
| 6664 | For that list of requirements, see the | ||
| 6665 | "<a class="link" href="#released-bsp-requirements" title="1.3.1. Released BSP Requirements">Released BSP Requirements</a>" | ||
| 6666 | section. | ||
| 6667 | </p><p> | ||
| 6668 | Below is the common form for the file structure inside a BSP Layer. | ||
| 6669 | While you can use this basic form for the standard, realize that the actual structures | ||
| 6670 | for specific BSPs could differ. | ||
| 6671 | |||
| 6672 | </p><pre class="literallayout"> | ||
| 6673 | meta-<bsp_name>/ | ||
| 6674 | meta-<bsp_name>/<bsp_license_file> | ||
| 6675 | meta-<bsp_name>/README | ||
| 6676 | meta-<bsp_name>/README.sources | ||
| 6677 | meta-<bsp_name>/binary/<bootable_images> | ||
| 6678 | meta-<bsp_name>/conf/layer.conf | ||
| 6679 | meta-<bsp_name>/conf/machine/*.conf | ||
| 6680 | meta-<bsp_name>/recipes-bsp/* | ||
| 6681 | meta-<bsp_name>/recipes-core/* | ||
| 6682 | meta-<bsp_name>/recipes-graphics/* | ||
| 6683 | meta-<bsp_name>/recipes-kernel/linux/linux-yocto_<kernel_rev>.bbappend | ||
| 6684 | </pre><p> | ||
| 6685 | </p><p> | ||
| 6686 | Below is an example of the Crown Bay BSP: | ||
| 6687 | |||
| 6688 | </p><pre class="literallayout"> | ||
| 6689 | meta-crownbay/COPYING.MIT | ||
| 6690 | meta-crownbay/README | ||
| 6691 | meta-crownbay/README.sources | ||
| 6692 | meta-crownbay/binary/ | ||
| 6693 | meta-crownbay/conf/ | ||
| 6694 | meta-crownbay/conf/layer.conf | ||
| 6695 | meta-crownbay/conf/machine/ | ||
| 6696 | meta-crownbay/conf/machine/crownbay.conf | ||
| 6697 | meta-crownbay/conf/machine/crownbay-noemgd.conf | ||
| 6698 | meta-crownbay/recipes-bsp/ | ||
| 6699 | meta-crownbay/recipes-bsp/formfactor/ | ||
| 6700 | meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend | ||
| 6701 | meta-crownbay/recipes-bsp/formfactor/formfactor/ | ||
| 6702 | meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/ | ||
| 6703 | meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig | ||
| 6704 | meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ | ||
| 6705 | meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig | ||
| 6706 | meta-crownbay/recipes-core/ | ||
| 6707 | meta-crownbay/recipes-core/tasks/ | ||
| 6708 | meta-crownbay/recipes-core/tasks/task-core-tools-profile.bbappend | ||
| 6709 | meta-crownbay/recipes-graphics/ | ||
| 6710 | meta-crownbay/recipes-graphics/xorg-xserver/ | ||
| 6711 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend | ||
| 6712 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/ | ||
| 6713 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/ | ||
| 6714 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf | ||
| 6715 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/ | ||
| 6716 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf | ||
| 6717 | meta-crownbay/recipes-kernel/ | ||
| 6718 | meta-crownbay/recipes-kernel/linux/ | ||
| 6719 | meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.0.bbappend | ||
| 6720 | meta-crownbay/recipes-kernel/linux/linux-yocto_2.6.37.bbappend | ||
| 6721 | meta-crownbay/recipes-kernel/linux/linux-yocto_3.0.bbappend | ||
| 6722 | </pre><p> | ||
| 6723 | </p><p> | ||
| 6724 | The following sections describe each part of the proposed BSP format. | ||
| 6725 | </p><div class="section" title="1.2.1. License Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-license"></a>1.2.1. License Files</h3></div></div></div><p> | ||
| 6726 | You can find these files in the BSP Layer at: | ||
| 6727 | </p><pre class="literallayout"> | ||
| 6728 | meta-<bsp_name>/<bsp_license_file> | ||
| 6729 | </pre><p> | ||
| 6730 | </p><p> | ||
| 6731 | These optional files satisfy licensing requirements for the BSP. | ||
| 6732 | The type or types of files here can vary depending on the licensing requirements. | ||
| 6733 | For example, in the Crown Bay BSP all licensing requirements are handled with the | ||
| 6734 | <code class="filename">COPYING.MIT</code> file. | ||
| 6735 | </p><p> | ||
| 6736 | Licensing files can be MIT, BSD, GPLv*, and so forth. | ||
| 6737 | These files are recommended for the BSP but are optional and totally up to the BSP developer. | ||
| 6738 | </p></div><div class="section" title="1.2.2. README File"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-readme"></a>1.2.2. README File</h3></div></div></div><p> | ||
| 6739 | You can find this file in the BSP Layer at: | ||
| 6740 | </p><pre class="literallayout"> | ||
| 6741 | meta-<bsp_name>/README | ||
| 6742 | </pre><p> | ||
| 6743 | </p><p> | ||
| 6744 | This file provides information on how to boot the live images that are optionally | ||
| 6745 | included in the <code class="filename">binary/</code> directory. | ||
| 6746 | The <code class="filename">README</code> file also provides special information needed for | ||
| 6747 | building the image. | ||
| 6748 | </p><p> | ||
| 6749 | At a minimum, the <code class="filename">README</code> file must | ||
| 6750 | contain a list of dependencies, such as the names of | ||
| 6751 | any other layers on which the BSP depends and the name of | ||
| 6752 | the BSP maintainer with his or her contact information. | ||
| 6753 | </p></div><div class="section" title="1.2.3. README.sources File"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-readme-sources"></a>1.2.3. README.sources File</h3></div></div></div><p> | ||
| 6754 | You can find this file in the BSP Layer at: | ||
| 6755 | </p><pre class="literallayout"> | ||
| 6756 | meta-<bsp_name>/README.sources | ||
| 6757 | </pre><p> | ||
| 6758 | </p><p> | ||
| 6759 | This file provides information on where to locate the BSP source files. | ||
| 6760 | For example, information provides where to find the sources that comprise | ||
| 6761 | the images shipped with the BSP. | ||
| 6762 | Information is also included to help you find the metadata used to generate the images | ||
| 6763 | that ship with the BSP. | ||
| 6764 | </p></div><div class="section" title="1.2.4. Pre-built User Binaries"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-binary"></a>1.2.4. Pre-built User Binaries</h3></div></div></div><p> | ||
| 6765 | You can find these files in the BSP Layer at: | ||
| 6766 | </p><pre class="literallayout"> | ||
| 6767 | meta-<bsp_name>/binary/<bootable_images> | ||
| 6768 | </pre><p> | ||
| 6769 | </p><p> | ||
| 6770 | This optional area contains useful pre-built kernels and user-space filesystem | ||
| 6771 | images appropriate to the target system. | ||
| 6772 | This directory typically contains graphical (e.g. sato) and minimal live images | ||
| 6773 | when the BSP tarball has been created and made available in the | ||
| 6774 | <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 6775 | You can use these kernels and images to get a system running and quickly get started | ||
| 6776 | on development tasks. | ||
| 6777 | </p><p> | ||
| 6778 | The exact types of binaries present are highly hardware-dependent. | ||
| 6779 | However, a README file should be present in the BSP Layer that explains how to use | ||
| 6780 | the kernels and images with the target hardware. | ||
| 6781 | If pre-built binaries are present, source code to meet licensing requirements must also | ||
| 6782 | exist in some form. | ||
| 6783 | </p></div><div class="section" title="1.2.5. Layer Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-layer"></a>1.2.5. Layer Configuration File</h3></div></div></div><p> | ||
| 6784 | You can find this file in the BSP Layer at: | ||
| 6785 | </p><pre class="literallayout"> | ||
| 6786 | meta-<bsp_name>/conf/layer.conf | ||
| 6787 | </pre><p> | ||
| 6788 | </p><p> | ||
| 6789 | The <code class="filename">conf/layer.conf</code> file identifies the file structure as a | ||
| 6790 | layer, identifies the | ||
| 6791 | contents of the layer, and contains information about how the build | ||
| 6792 | system should use it. | ||
| 6793 | Generally, a standard boilerplate file such as the following works. | ||
| 6794 | In the following example, you would replace "<code class="filename">bsp</code>" and | ||
| 6795 | "<code class="filename">_bsp</code>" with the actual name | ||
| 6796 | of the BSP (i.e. <code class="filename"><bsp_name></code> from the example template). | ||
| 6797 | </p><p> | ||
| 6798 | </p><pre class="literallayout"> | ||
| 6799 | # We have a conf and classes directory, add to BBPATH | ||
| 6800 | BBPATH := "${BBPATH}:${LAYERDIR}" | ||
| 6801 | |||
| 6802 | # We have a recipes directory, add to BBFILES | ||
| 6803 | BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*.bb \ | ||
| 6804 | ${LAYERDIR}/recipes-*/*.bbappend" | ||
| 6805 | |||
| 6806 | BBFILE_COLLECTIONS += "bsp" | ||
| 6807 | BBFILE_PATTERN_bsp := "^${LAYERDIR}/" | ||
| 6808 | BBFILE_PRIORITY_bsp = "6" | ||
| 6809 | </pre><p> | ||
| 6810 | </p><p> | ||
| 6811 | To illustrate the string substitutions, here are the last three statements from the Crown | ||
| 6812 | Bay <code class="filename">conf/layer.conf</code> file: | ||
| 6813 | </p><pre class="literallayout"> | ||
| 6814 | BBFILE_COLLECTIONS += "crownbay" | ||
| 6815 | BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" | ||
| 6816 | BBFILE_PRIORITY_crownbay = "6" | ||
| 6817 | </pre><p> | ||
| 6818 | </p><p> | ||
| 6819 | This file simply makes BitBake aware of the recipes and configuration directories. | ||
| 6820 | The file must exist so that the OpenEmbedded build system can recognize the BSP. | ||
| 6821 | </p></div><div class="section" title="1.2.6. Hardware Configuration Options"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-machine"></a>1.2.6. Hardware Configuration Options</h3></div></div></div><p> | ||
| 6822 | You can find these files in the BSP Layer at: | ||
| 6823 | </p><pre class="literallayout"> | ||
| 6824 | meta-<bsp_name>/conf/machine/*.conf | ||
| 6825 | </pre><p> | ||
| 6826 | </p><p> | ||
| 6827 | The machine files bind together all the information contained elsewhere | ||
| 6828 | in the BSP into a format that the build system can understand. | ||
| 6829 | If the BSP supports multiple machines, multiple machine configuration files | ||
| 6830 | can be present. | ||
| 6831 | These filenames correspond to the values to which users have set the | ||
| 6832 | <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> variable. | ||
| 6833 | </p><p> | ||
| 6834 | These files define things such as the kernel package to use | ||
| 6835 | (<a class="link" href="#var-PREFERRED_PROVIDER" target="_top"><code class="filename">PREFERRED_PROVIDER</code></a> | ||
| 6836 | of virtual/kernel), the hardware drivers to | ||
| 6837 | include in different types of images, any special software components | ||
| 6838 | that are needed, any bootloader information, and also any special image | ||
| 6839 | format requirements. | ||
| 6840 | </p><p> | ||
| 6841 | Each BSP Layer requires at least one machine file. | ||
| 6842 | However, you can supply more than one file. | ||
| 6843 | For example, in the Crown Bay BSP shown earlier in this section, the | ||
| 6844 | <code class="filename">conf/machine</code> directory contains two configuration files: | ||
| 6845 | <code class="filename">crownbay.conf</code> and <code class="filename">crownbay-noemgd.conf</code>. | ||
| 6846 | The <code class="filename">crownbay.conf</code> file is used for the Crown Bay BSP | ||
| 6847 | that supports the <span class="trademark">Intel</span>® Embedded | ||
| 6848 | Media and Graphics Driver (<span class="trademark">Intel</span>® | ||
| 6849 | EMGD), while the <code class="filename">crownbay-noemgd.conf</code> file is used for the | ||
| 6850 | Crown Bay BSP that does not support the <span class="trademark">Intel</span>® | ||
| 6851 | EMGD. | ||
| 6852 | </p><p> | ||
| 6853 | This <code class="filename">crownbay.conf</code> file could also include | ||
| 6854 | a hardware "tuning" file that is commonly used to | ||
| 6855 | define the package architecture and specify | ||
| 6856 | optimization flags, which are carefully chosen to give best | ||
| 6857 | performance on a given processor. | ||
| 6858 | </p><p> | ||
| 6859 | Tuning files are found in the <code class="filename">meta/conf/machine/include</code> | ||
| 6860 | directory within the | ||
| 6861 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 6862 | Tuning files can also reside in the BSP Layer itself. | ||
| 6863 | For example, the <code class="filename">ia32-base.inc</code> file resides in the | ||
| 6864 | <code class="filename">meta-intel</code> BSP Layer in <code class="filename">conf/machine/include</code>. | ||
| 6865 | </p><p> | ||
| 6866 | To use an include file, you simply include them in the machine configuration file. | ||
| 6867 | For example, the Crown Bay BSP <code class="filename">crownbay.conf</code> has the | ||
| 6868 | following statements: | ||
| 6869 | </p><pre class="literallayout"> | ||
| 6870 | include conf/machine/include/tune-atom.inc | ||
| 6871 | include conf/machine/include/ia32-base.inc | ||
| 6872 | </pre><p> | ||
| 6873 | </p></div><div class="section" title="1.2.7. Miscellaneous Recipe Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-misc-recipes"></a>1.2.7. Miscellaneous Recipe Files</h3></div></div></div><p> | ||
| 6874 | You can find these files in the BSP Layer at: | ||
| 6875 | </p><pre class="literallayout"> | ||
| 6876 | meta-<bsp_name>/recipes-bsp/* | ||
| 6877 | </pre><p> | ||
| 6878 | </p><p> | ||
| 6879 | This optional directory contains miscellaneous recipe files for the BSP. | ||
| 6880 | Most notably would be the formfactor files. | ||
| 6881 | For example, in the Crown Bay BSP there is the | ||
| 6882 | <code class="filename">formfactor_0.0.bbappend</code> file, which is an append file used | ||
| 6883 | to augment the recipe that starts the build. | ||
| 6884 | Furthermore, there are machine-specific settings used during the build that are | ||
| 6885 | defined by the <code class="filename">machconfig</code> files. | ||
| 6886 | In the Crown Bay example, two <code class="filename">machconfig</code> files exist: | ||
| 6887 | one that supports the | ||
| 6888 | <span class="trademark">Intel</span>® Embedded | ||
| 6889 | Media and Graphics Driver (<span class="trademark">Intel</span>® | ||
| 6890 | EMGD) and one that does not: | ||
| 6891 | </p><pre class="literallayout"> | ||
| 6892 | meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig | ||
| 6893 | meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig | ||
| 6894 | meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend | ||
| 6895 | </pre><p> | ||
| 6896 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 6897 | If a BSP does not have a formfactor entry, defaults are established according to | ||
| 6898 | the formfactor configuration file that is installed by the main | ||
| 6899 | formfactor recipe | ||
| 6900 | <code class="filename">meta/recipes-bsp/formfactor/formfactor_0.0.bb</code>, | ||
| 6901 | which is found in the | ||
| 6902 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 6903 | </p></div></div><div class="section" title="1.2.8. Core Recipe Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-core-recipes"></a>1.2.8. Core Recipe Files</h3></div></div></div><p> | ||
| 6904 | You can find these files in the BSP Layer at: | ||
| 6905 | </p><pre class="literallayout"> | ||
| 6906 | meta-<bsp_name>/recipes-core/* | ||
| 6907 | </pre><p> | ||
| 6908 | </p><p> | ||
| 6909 | This directory contains recipe files that are almost always necessary to build a | ||
| 6910 | useful, working Linux image. | ||
| 6911 | Thus, the term "core" is used to group these recipes. | ||
| 6912 | For example, in the Crown Bay BSP there is the | ||
| 6913 | <code class="filename">task-core-tools-profile.bbappend</code> file, which is an append file used | ||
| 6914 | to recommend that the | ||
| 6915 | <a class="ulink" href="http://sourceware.org/systemtap/wiki" target="_top">SystemTap</a> | ||
| 6916 | package be included as a package when the image is built. | ||
| 6917 | </p></div><div class="section" title="1.2.9. Display Support Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-recipes-graphics"></a>1.2.9. Display Support Files</h3></div></div></div><p> | ||
| 6918 | You can find these files in the BSP Layer at: | ||
| 6919 | </p><pre class="literallayout"> | ||
| 6920 | meta-<bsp_name>/recipes-graphics/* | ||
| 6921 | </pre><p> | ||
| 6922 | </p><p> | ||
| 6923 | This optional directory contains recipes for the BSP if it has | ||
| 6924 | special requirements for graphics support. | ||
| 6925 | All files that are needed for the BSP to support a display are kept here. | ||
| 6926 | For example, the Crown Bay BSP contains two versions of the | ||
| 6927 | <code class="filename">xorg.conf</code> file. | ||
| 6928 | The version in <code class="filename">crownbay</code> builds a BSP that supports the | ||
| 6929 | <span class="trademark">Intel</span>® Embedded Media Graphics Driver (EMGD), | ||
| 6930 | while the version in <code class="filename">crownbay-noemgd</code> builds | ||
| 6931 | a BSP that supports Video Electronics Standards Association (VESA) graphics only: | ||
| 6932 | </p><pre class="literallayout"> | ||
| 6933 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend | ||
| 6934 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf | ||
| 6935 | meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf | ||
| 6936 | </pre><p> | ||
| 6937 | </p></div><div class="section" title="1.2.10. Linux Kernel Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-kernel"></a>1.2.10. Linux Kernel Configuration</h3></div></div></div><p> | ||
| 6938 | You can find these files in the BSP Layer at: | ||
| 6939 | </p><pre class="literallayout"> | ||
| 6940 | meta-<bsp_name>/recipes-kernel/linux/linux-yocto_*.bbappend | ||
| 6941 | </pre><p> | ||
| 6942 | </p><p> | ||
| 6943 | These files append your specific changes to the main kernel recipe you are using. | ||
| 6944 | </p><p> | ||
| 6945 | For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the | ||
| 6946 | <a class="link" href="#source-directory" target="_top">source directory</a> | ||
| 6947 | at <code class="filename">meta/recipes-kernel/linux</code>. | ||
| 6948 | You can append your specific changes to the kernel recipe by using a | ||
| 6949 | similarly named append file, which is located in the BSP Layer (e.g. | ||
| 6950 | the <code class="filename">meta-<bsp_name>/recipes-kernel/linux</code> directory). | ||
| 6951 | </p><p> | ||
| 6952 | Suppose you are using the <code class="filename">linux-yocto_3.4.bb</code> recipe to build | ||
| 6953 | the kernel. | ||
| 6954 | In other words, you have selected the kernel in your | ||
| 6955 | <code class="filename"><bsp_name>.conf</code> file by adding the following statements: | ||
| 6956 | </p><pre class="literallayout"> | ||
| 6957 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | ||
| 6958 | PREFERRED_VERSION_linux-yocto = "3.4%" | ||
| 6959 | </pre><p> | ||
| 6960 | You would use the <code class="filename">linux-yocto_3.4.bbappend</code> file to append | ||
| 6961 | specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. | ||
| 6962 | </p><p> | ||
| 6963 | As an example, look at the existing Crown Bay BSP. | ||
| 6964 | The append file used is: | ||
| 6965 | </p><pre class="literallayout"> | ||
| 6966 | meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend | ||
| 6967 | </pre><p> | ||
| 6968 | The following listing shows the file. | ||
| 6969 | Be aware that the actual commit ID strings in this example listing might be different | ||
| 6970 | than the actual strings in the file from the <code class="filename">meta-intel</code> | ||
| 6971 | Git source repository. | ||
| 6972 | </p><pre class="literallayout"> | ||
| 6973 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 6974 | |||
| 6975 | COMPATIBLE_MACHINE_crownbay = "crownbay" | ||
| 6976 | KMACHINE_crownbay = "crownbay" | ||
| 6977 | KBRANCH_crownbay = "standard/default/crownbay" | ||
| 6978 | |||
| 6979 | COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" | ||
| 6980 | KMACHINE_crownbay-noemgd = "crownbay" | ||
| 6981 | KBRANCH_crownbay-noemgd = "standard/default/crownbay" | ||
| 6982 | |||
| 6983 | SRCREV_machine_pn-linux-yocto_crownbay ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" | ||
| 6984 | SRCREV_meta_pn-linux-yocto_crownbay ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" | ||
| 6985 | |||
| 6986 | SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" | ||
| 6987 | SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" | ||
| 6988 | </pre><p> | ||
| 6989 | This append file contains statements used to support the Crown Bay BSP for both | ||
| 6990 | <span class="trademark">Intel</span>® EMGD and the VESA graphics. | ||
| 6991 | The build process, in this case, recognizes and uses only the statements that | ||
| 6992 | apply to the defined machine name - <code class="filename">crownbay</code> in this case. | ||
| 6993 | So, the applicable statements in the <code class="filename">linux-yocto_3.4.bbappend</code> | ||
| 6994 | file are follows: | ||
| 6995 | </p><pre class="literallayout"> | ||
| 6996 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 6997 | |||
| 6998 | COMPATIBLE_MACHINE_crownbay = "crownbay" | ||
| 6999 | KMACHINE_crownbay = "crownbay" | ||
| 7000 | KBRANCH_crownbay = "standard/default/crownbay" | ||
| 7001 | |||
| 7002 | SRCREV_machine_pn-linux-yocto_crownbay ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" | ||
| 7003 | SRCREV_meta_pn-linux-yocto_crownbay ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" | ||
| 7004 | </pre><p> | ||
| 7005 | The append file defines <code class="filename">crownbay</code> as the | ||
| 7006 | <a class="link" href="#var-COMPATIBLE_MACHINE" target="_top"><code class="filename">COMPATIBLE_MACHINE</code></a> | ||
| 7007 | and uses the | ||
| 7008 | <a class="link" href="#var-KMACHINE" target="_top"><code class="filename">KMACHINE</code></a> variable to | ||
| 7009 | ensure the machine name used by the OpenEmbedded build system maps to the | ||
| 7010 | machine name used by the Linux Yocto kernel. | ||
| 7011 | The file also uses the optional | ||
| 7012 | <a class="link" href="#var-KBRANCH" target="_top"><code class="filename">KBRANCH</code></a> variable | ||
| 7013 | to ensure the build process uses the <code class="filename">standard/default/crownbay</code> | ||
| 7014 | kernel branch. | ||
| 7015 | Finally, the append file points to the specific top commits in the | ||
| 7016 | <a class="link" href="#source-directory" target="_top">source directory</a> Git | ||
| 7017 | repository and the <code class="filename">meta</code> Git repository branches to identify the | ||
| 7018 | exact kernel needed to build the Crown Bay BSP. | ||
| 7019 | </p><p> | ||
| 7020 | One thing missing in this particular BSP, which you will typically need when | ||
| 7021 | developing a BSP, is the kernel configuration file (<code class="filename">.config</code>) for your BSP. | ||
| 7022 | When developing a BSP, you probably have a kernel configuration file or a set of kernel | ||
| 7023 | configuration files that, when taken together, define the kernel configuration for your BSP. | ||
| 7024 | You can accomplish this definition by putting the configurations in a file or a set of files | ||
| 7025 | inside a directory located at the same level as your kernel's append file and having the same | ||
| 7026 | name as the kernel's main recipe file. | ||
| 7027 | With all these conditions met, simply reference those files in a | ||
| 7028 | <code class="filename">SRC_URI</code> statement in the append file. | ||
| 7029 | </p><p> | ||
| 7030 | For example, suppose you had a some configuration options in a file called | ||
| 7031 | <code class="filename">network_configs.cfg</code>. | ||
| 7032 | You can place that file inside a directory named <code class="filename">/linux-yocto</code> and then add | ||
| 7033 | a <code class="filename">SRC_URI</code> statement such as the following to the append file. | ||
| 7034 | When the OpenEmbedded build system builds the kernel, the configuration options are | ||
| 7035 | picked up and applied. | ||
| 7036 | </p><pre class="literallayout"> | ||
| 7037 | SRC_URI += "file://network_configs.cfg" | ||
| 7038 | </pre><p> | ||
| 7039 | </p><p> | ||
| 7040 | To group related configurations into multiple files, you perform a similar procedure. | ||
| 7041 | Here is an example that groups separate configurations specifically for Ethernet and graphics | ||
| 7042 | into their own files and adds the configurations | ||
| 7043 | by using a <code class="filename">SRC_URI</code> statement like the following in your append file: | ||
| 7044 | </p><pre class="literallayout"> | ||
| 7045 | SRC_URI += "file://myconfig.cfg \ | ||
| 7046 | file://eth.cfg \ | ||
| 7047 | file://gfx.cfg" | ||
| 7048 | </pre><p> | ||
| 7049 | </p><p> | ||
| 7050 | The <code class="filename">FILESEXTRAPATHS</code> variable is in boilerplate form in the | ||
| 7051 | previous example in order to make it easy to do that. | ||
| 7052 | This variable must be in your layer or BitBake will not find the patches or | ||
| 7053 | configurations even if you have them in your <code class="filename">SRC_URI</code>. | ||
| 7054 | The <code class="filename">FILESEXTRAPATHS</code> variable enables the build process to | ||
| 7055 | find those configuration files. | ||
| 7056 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> | ||
| 7057 | Other methods exist to accomplish grouping and defining configuration options. | ||
| 7058 | For example, if you are working with a local clone of the kernel repository, | ||
| 7059 | you could checkout the kernel's <code class="filename">meta</code> branch, make your changes, | ||
| 7060 | and then push the changes to the local bare clone of the kernel. | ||
| 7061 | The result is that you directly add configuration options to the | ||
| 7062 | <code class="filename">meta</code> branch for your BSP. | ||
| 7063 | The configuration options will likely end up in that location anyway if the BSP gets | ||
| 7064 | added to the Yocto Project. | ||
| 7065 | For an example showing how to change the BSP configuration, see the | ||
| 7066 | "<a class="link" href="#changing-the-bsp-configuration" target="_top">Changing the BSP Configuration</a>" | ||
| 7067 | section in the Yocto Project Development Manual. | ||
| 7068 | For a better understanding of working with a local clone of the kernel repository | ||
| 7069 | and a local bare clone of the kernel, see the | ||
| 7070 | "<a class="link" href="#modifying-the-kernel-source-code" target="_top">Modifying the Kernel | ||
| 7071 | Source Code</a>" section also in the Yocto Project Development Manual. | ||
| 7072 | </p><p> | ||
| 7073 | In general, however, the Yocto Project maintainers take care of moving the | ||
| 7074 | <code class="filename">SRC_URI</code>-specified | ||
| 7075 | configuration options to the kernel's <code class="filename">meta</code> branch. | ||
| 7076 | Not only is it easier for BSP developers to not have to worry about putting those | ||
| 7077 | configurations in the branch, but having the maintainers do it allows them to apply | ||
| 7078 | 'global' knowledge about the kinds of common configuration options multiple BSPs in | ||
| 7079 | the tree are typically using. | ||
| 7080 | This allows for promotion of common configurations into common features. | ||
| 7081 | </p></div></div></div><div class="section" title="1.3. Requirements and Recommendations for Released BSPs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirements-and-recommendations-for-released-bsps"></a>1.3. Requirements and Recommendations for Released BSPs</h2></div></div></div><p> | ||
| 7082 | Certain requirements exist for a released BSP to be considered | ||
| 7083 | compliant with the Yocto Project. | ||
| 7084 | Additionally, a single recommendation also exists. | ||
| 7085 | This section describes the requirements and recommendation for | ||
| 7086 | released BSPs. | ||
| 7087 | </p><div class="section" title="1.3.1. Released BSP Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="released-bsp-requirements"></a>1.3.1. Released BSP Requirements</h3></div></div></div><p> | ||
| 7088 | Before looking at BSP requirements, you should consider the following: | ||
| 7089 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The requirements here assume the BSP layer is a well-formed, "legal" | ||
| 7090 | layer that can be added to the Yocto Project. | ||
| 7091 | For guidelines on creating a layer that meets these base requirements, see the | ||
| 7092 | "<a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layers</a>" and the | ||
| 7093 | "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding | ||
| 7094 | and Creating Layers"</a> in the Yocto Project Development Manual.</p></li><li class="listitem"><p>The requirements in this section apply regardless of how you | ||
| 7095 | ultimately package a BSP. | ||
| 7096 | You should consult the packaging and distribution guidelines for your | ||
| 7097 | specific release process. | ||
| 7098 | For an example of packaging and distribution requirements, see the | ||
| 7099 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process" target="_top">Third | ||
| 7100 | Party BSP Release Process</a> wiki page.</p></li><li class="listitem"><p>The requirements for the BSP as it is made available to a developer | ||
| 7101 | are completely independent of the released form of the BSP. | ||
| 7102 | For example, the BSP metadata can be contained within a Git repository | ||
| 7103 | and could have a directory structure completely different from what appears | ||
| 7104 | in the officially released BSP layer.</p></li><li class="listitem"><p>It is not required that specific packages or package | ||
| 7105 | modifications exist in the BSP layer, beyond the requirements for general | ||
| 7106 | compliance with the Yocto Project. | ||
| 7107 | For example, no requirement exists dictating that a specific kernel or | ||
| 7108 | kernel version be used in a given BSP.</p></li></ul></div><p> | ||
| 7109 | </p><p> | ||
| 7110 | Following are the requirements for a released BSP that conforms to the | ||
| 7111 | Yocto Project: | ||
| 7112 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Layer Name:</em></span> | ||
| 7113 | The BSP must have a layer name that follows the Yocto | ||
| 7114 | Project standards. | ||
| 7115 | For information on BSP layer names, see the | ||
| 7116 | "<a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layers</a>" section. | ||
| 7117 | </p></li><li class="listitem"><p><span class="emphasis"><em>File System Layout:</em></span> | ||
| 7118 | When possible, use the same directory names in your | ||
| 7119 | BSP layer as listed in the <code class="filename">recipes.txt</code> file. | ||
| 7120 | In particular, you should place recipes | ||
| 7121 | (<code class="filename">.bb</code> files) and recipe | ||
| 7122 | modifications (<code class="filename">.bbappend</code> files) into | ||
| 7123 | <code class="filename">recipes-*</code> subdirectories by functional area | ||
| 7124 | as outlined in <code class="filename">recipes.txt</code>. | ||
| 7125 | If you cannot find a category in <code class="filename">recipes.txt</code> | ||
| 7126 | to fit a particular recipe, you can make up your own | ||
| 7127 | <code class="filename">recipe-*</code> subdirectory. | ||
| 7128 | You can find <code class="filename">recipes.txt</code> in the | ||
| 7129 | <code class="filename">meta</code> directory of the | ||
| 7130 | <a class="link" href="#source-directory" target="_top">source directory</a>, | ||
| 7131 | or in the OpenEmbedded Core Layer | ||
| 7132 | (<code class="filename">openembedded-core</code>) found at | ||
| 7133 | <a class="ulink" href="http://git.openembedded.org/openembedded-core/tree/meta" target="_top">http://git.openembedded.org/openembedded-core/tree/meta</a>. | ||
| 7134 | </p><p>Within any particular <code class="filename">recipes-*</code> category, the layout | ||
| 7135 | should match what is found in the OpenEmbedded Core | ||
| 7136 | Git repository (<code class="filename">openembedded-core</code>) | ||
| 7137 | or the source directory (<code class="filename">poky</code>). | ||
| 7138 | In other words, make sure you place related files in appropriately | ||
| 7139 | related <code class="filename">recipes-*</code> subdirectories specific to the | ||
| 7140 | recipe's function, or within a subdirectory containing a set of closely-related | ||
| 7141 | recipes. | ||
| 7142 | The recipes themselves should follow the general guidelines | ||
| 7143 | for recipes used in the Yocto Project found in the | ||
| 7144 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide" target="_top">Yocto | ||
| 7145 | Recipe and Patch Style Guide</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>License File:</em></span> | ||
| 7146 | You must include a license file in the | ||
| 7147 | <code class="filename">meta-<bsp_name></code> directory. | ||
| 7148 | This license covers the BSP metadata as a whole. | ||
| 7149 | You must specify which license to use since there is no | ||
| 7150 | default license if one is not specified. | ||
| 7151 | See the | ||
| 7152 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/meta-intel/tree/meta-fishriver/COPYING.MIT" target="_top"><code class="filename">COPYING.MIT</code></a> | ||
| 7153 | file for the Fish River BSP in the <code class="filename">meta-fishriver</code> BSP layer | ||
| 7154 | as an example.</p></li><li class="listitem"><p><span class="emphasis"><em>README File:</em></span> | ||
| 7155 | You must include a <code class="filename">README</code> file in the | ||
| 7156 | <code class="filename">meta-<bsp_name></code> directory. | ||
| 7157 | See the | ||
| 7158 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/meta-intel/tree/meta-fishriver/README" target="_top"><code class="filename">README</code></a> | ||
| 7159 | file for the Fish River BSP in the <code class="filename">meta-fishriver</code> BSP layer | ||
| 7160 | as an example.</p><p>At a minimum, the <code class="filename">README</code> file should | ||
| 7161 | contain the following: | ||
| 7162 | </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>A brief description about the hardware the BSP | ||
| 7163 | targets.</p></li><li class="listitem"><p>A list of all the dependencies a | ||
| 7164 | on which a BSP layer depends. | ||
| 7165 | These dependencies are typically a list of required layers needed | ||
| 7166 | to build the BSP. | ||
| 7167 | However, the dependencies should also contain information regarding | ||
| 7168 | any other dependencies the BSP might have.</p></li><li class="listitem"><p>Any required special licensing information. | ||
| 7169 | For example, this information includes information on | ||
| 7170 | special variables needed to satisfy a EULA, | ||
| 7171 | or instructions on information needed to build or distribute | ||
| 7172 | binaries built from the BSP metadata.</p></li><li class="listitem"><p>The name and contact information for the | ||
| 7173 | BSP layer maintainer. | ||
| 7174 | This is the person to whom patches and questions should | ||
| 7175 | be sent.</p></li><li class="listitem"><p>Instructions on how to build the BSP using the BSP | ||
| 7176 | layer.</p></li><li class="listitem"><p>Instructions on how to boot the BSP build from | ||
| 7177 | the BSP layer.</p></li><li class="listitem"><p>Instructions on how to boot the binary images | ||
| 7178 | contained in the <code class="filename">/binary</code> directory, | ||
| 7179 | if present.</p></li><li class="listitem"><p>Information on any known bugs or issues that users | ||
| 7180 | should know about when either building or booting the BSP | ||
| 7181 | binaries.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em>README.sources File:</em></span> | ||
| 7182 | You must include a <code class="filename">README.sources</code> in the | ||
| 7183 | <code class="filename">meta-<bsp_name></code> directory. | ||
| 7184 | This file specifies exactly where you can find the sources used to | ||
| 7185 | generate the binary images contained in the | ||
| 7186 | <code class="filename">/binary</code> directory, if present. | ||
| 7187 | See the | ||
| 7188 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/meta-intel/tree/meta-fishriver/README.sources" target="_top"><code class="filename">README.sources</code></a> | ||
| 7189 | file for the Fish River BSP in the <code class="filename">meta-fishriver</code> BSP layer | ||
| 7190 | as an example.</p></li><li class="listitem"><p><span class="emphasis"><em>Layer Configuration File:</em></span> | ||
| 7191 | You must include a <code class="filename">conf/layer.conf</code> in the | ||
| 7192 | <code class="filename">meta-<bsp_name></code> directory. | ||
| 7193 | This file identifies the <code class="filename">meta-<bsp_name></code> | ||
| 7194 | BSP layer as a layer to the build system.</p></li><li class="listitem"><p><span class="emphasis"><em>Machine Configuration File:</em></span> | ||
| 7195 | You must include a <code class="filename">conf/machine/<bsp_name>.conf</code> | ||
| 7196 | in the <code class="filename">meta-<bsp_name></code> directory. | ||
| 7197 | This configuration file defines a machine target that can be built | ||
| 7198 | using the BSP layer. | ||
| 7199 | Multiple machine configuration files define variations of machine | ||
| 7200 | configurations that are supported by the BSP. | ||
| 7201 | If a BSP supports more multiple machine variations, you need to | ||
| 7202 | adequately describe each variation in the BSP | ||
| 7203 | <code class="filename">README</code> file. | ||
| 7204 | Do not use multiple machine configuration files to describe disparate | ||
| 7205 | hardware. | ||
| 7206 | Multiple machine configuration files should describe very similar targets. | ||
| 7207 | If you do have very different targets, you should create a separate | ||
| 7208 | BSP. | ||
| 7209 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>It is completely possible for a developer to structure the | ||
| 7210 | working repository as a conglomeration of unrelated BSP | ||
| 7211 | files, and to possibly generate specifically targeted 'release' BSPs | ||
| 7212 | from that directory using scripts or some other mechanism. | ||
| 7213 | Such considerations are outside the scope of this document.</div><p> | ||
| 7214 | </p></li></ul></div><p> | ||
| 7215 | </p></div><div class="section" title="1.3.2. Released BSP Recommendations"><div class="titlepage"><div><div><h3 class="title"><a id="released-bsp-recommendations"></a>1.3.2. Released BSP Recommendations</h3></div></div></div><p> | ||
| 7216 | Following are recommendations for a released BSP that conforms to the | ||
| 7217 | Yocto Project: | ||
| 7218 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Bootable Images:</em></span> | ||
| 7219 | BSP releases | ||
| 7220 | can contain one or more bootable images. | ||
| 7221 | Including bootable images allows users to easily try out the BSP | ||
| 7222 | on their own hardware.</p><p>In some cases, it might not be convenient to include a | ||
| 7223 | bootable image. | ||
| 7224 | In this case, you might want to make two versions of the | ||
| 7225 | BSP available: one that contains binary images, and one | ||
| 7226 | that does not. | ||
| 7227 | The version that does not contain bootable images avoids | ||
| 7228 | unnecessary download times for users not interested in the images. | ||
| 7229 | </p><p>If you need to distribute a BSP and include bootable images or build kernel and | ||
| 7230 | filesystems meant to allow users to boot the BSP for evaluation | ||
| 7231 | purposes, you should put the images and artifacts within a | ||
| 7232 | <code class="filename">binary/</code> subdirectory located in the | ||
| 7233 | <code class="filename">meta-<bsp_name></code> directory. | ||
| 7234 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If you do include a bootable image as part of the BSP and the image | ||
| 7235 | was built by software covered by the GPL or other open source licenses, | ||
| 7236 | it is your responsibility to understand | ||
| 7237 | and meet all licensing requirements, which could include distribution | ||
| 7238 | of source files.</div></li><li class="listitem"><p><span class="emphasis"><em>Use a Yocto Linux Kernel:</em></span> | ||
| 7239 | Kernel recipes in the BSP should be based on a Yocto Linux kernel. | ||
| 7240 | Basing your recipes on these kernels reduces the costs for maintaining | ||
| 7241 | the BSP and increases its scalability. | ||
| 7242 | See the <code class="filename">Yocto Linux Kernel</code> category in the | ||
| 7243 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top"><code class="filename">Yocto Source Repositories</code></a> | ||
| 7244 | for these kernels.</p></li></ul></div><p> | ||
| 7245 | </p></div></div><div class="section" title="1.4. Customizing a Recipe for a BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customizing-a-recipe-for-a-bsp"></a>1.4. Customizing a Recipe for a BSP</h2></div></div></div><p> | ||
| 7246 | If you plan on customizing a recipe for a particular BSP, you need to do the | ||
| 7247 | following: | ||
| 7248 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Include within the BSP layer a <code class="filename">.bbappend</code> | ||
| 7249 | file for the modified recipe.</p></li><li class="listitem"><p>Place the BSP-specific file in the BSP's recipe | ||
| 7250 | <code class="filename">.bbappend</code> file path under a directory named | ||
| 7251 | after the machine.</p></li></ul></div><p> | ||
| 7252 | </p><p> | ||
| 7253 | To better understand this, consider an example that customizes a recipe by adding | ||
| 7254 | a BSP-specific configuration file named <code class="filename">interfaces</code> to the | ||
| 7255 | <code class="filename">netbase_4.47.bb</code> recipe for machine "xyz". | ||
| 7256 | Do the following: | ||
| 7257 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Edit the <code class="filename">netbase_4.47.bbappend</code> file so that it | ||
| 7258 | contains the following: | ||
| 7259 | </p><pre class="literallayout"> | ||
| 7260 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" | ||
| 7261 | PRINC := "${@int(PRINC) + 2}" | ||
| 7262 | </pre></li><li class="listitem"><p>Create and place the new <code class="filename">interfaces</code> | ||
| 7263 | configuration file in the BSP's layer here: | ||
| 7264 | </p><pre class="literallayout"> | ||
| 7265 | meta-xyz/recipes-core/netbase/files/xyz/interfaces | ||
| 7266 | </pre></li></ol></div><p> | ||
| 7267 | </p></div><div class="section" title="1.5. BSP Licensing Considerations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bsp-licensing-considerations"></a>1.5. BSP Licensing Considerations</h2></div></div></div><p> | ||
| 7268 | In some cases, a BSP contains separately licensed Intellectual Property (IP) | ||
| 7269 | for a component or components. | ||
| 7270 | For these cases, you are required to accept the terms of a commercial or other | ||
| 7271 | type of license that requires some kind of explicit End User License Agreement (EULA). | ||
| 7272 | Once the license is accepted, the OpenEmbedded build system can then build and | ||
| 7273 | include the corresponding component in the final BSP image. | ||
| 7274 | If the BSP is available as a pre-built image, you can download the image after | ||
| 7275 | agreeing to the license or EULA. | ||
| 7276 | </p><p> | ||
| 7277 | You could find that some separately licensed components that are essential | ||
| 7278 | for normal operation of the system might not have an unencumbered (or free) | ||
| 7279 | substitute. | ||
| 7280 | Without these essential components, the system would be non-functional. | ||
| 7281 | Then again, you might find that other licensed components that are simply | ||
| 7282 | 'good-to-have' or purely elective do have an unencumbered, free replacement | ||
| 7283 | component that you can use rather than agreeing to the separately licensed component. | ||
| 7284 | Even for components essential to the system, you might find an unencumbered component | ||
| 7285 | that is not identical but will work as a less-capable version of the | ||
| 7286 | licensed version in the BSP recipe. | ||
| 7287 | </p><p> | ||
| 7288 | For cases where you can substitute a free component and still | ||
| 7289 | maintain the system's functionality, the Yocto Project website's | ||
| 7290 | <a class="ulink" href="http://www.yoctoproject.org/download/all?keys=&download_type=1&download_version=" target="_top">BSP | ||
| 7291 | Download Page</a> makes available de-featured BSPs | ||
| 7292 | that are completely free of any IP encumbrances. | ||
| 7293 | For these cases, you can use the substitution directly and | ||
| 7294 | without any further licensing requirements. | ||
| 7295 | If present, these fully de-featured BSPs are named appropriately | ||
| 7296 | different as compared to the names of the respective | ||
| 7297 | encumbered BSPs. | ||
| 7298 | If available, these substitutions are your | ||
| 7299 | simplest and most preferred options. | ||
| 7300 | Use of these substitutions of course assumes the resulting functionality meets | ||
| 7301 | system requirements. | ||
| 7302 | </p><p> | ||
| 7303 | If however, a non-encumbered version is unavailable or | ||
| 7304 | it provides unsuitable functionality or quality, you can use an encumbered | ||
| 7305 | version. | ||
| 7306 | </p><p> | ||
| 7307 | A couple different methods exist within the OpenEmbedded build system to | ||
| 7308 | satisfy the licensing requirements for an encumbered BSP. | ||
| 7309 | The following list describes them in order of preference: | ||
| 7310 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Use the <code class="filename">LICENSE_FLAGS</code> variable | ||
| 7311 | to define the recipes that have commercial or other types of | ||
| 7312 | specially-licensed packages:</em></span> | ||
| 7313 | For each of those recipes, you can | ||
| 7314 | specify a matching license string in a | ||
| 7315 | <code class="filename">local.conf</code> variable named | ||
| 7316 | <code class="filename">LICENSE_FLAGS_WHITELIST</code>. | ||
| 7317 | Specifying the matching license string signifies that you agree to the license. | ||
| 7318 | Thus, the build system can build the corresponding recipe and include | ||
| 7319 | the component in the image. | ||
| 7320 | See the | ||
| 7321 | "<a class="link" href="#enabling-commercially-licensed-recipes" target="_top">Enabling | ||
| 7322 | Commercially Licensed Recipes</a>" section in the Yocto Project Reference | ||
| 7323 | Manual for details on how to use these variables.</p><p>If you build as you normally would, without | ||
| 7324 | specifying any recipes in the | ||
| 7325 | <code class="filename">LICENSE_FLAGS_WHITELIST</code>, the build stops and | ||
| 7326 | provides you with the list of recipes that you have | ||
| 7327 | tried to include in the image that need entries in | ||
| 7328 | the <code class="filename">LICENSE_FLAGS_WHITELIST</code>. | ||
| 7329 | Once you enter the appropriate license flags into the whitelist, | ||
| 7330 | restart the build to continue where it left off. | ||
| 7331 | During the build, the prompt will not appear again | ||
| 7332 | since you have satisfied the requirement.</p><p>Once the appropriate license flags are on the white list | ||
| 7333 | in the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, you | ||
| 7334 | can build the encumbered image with no change at all | ||
| 7335 | to the normal build process.</p></li><li class="listitem"><p><span class="emphasis"><em>Get a pre-built version of the BSP:</em></span> | ||
| 7336 | You can get this type of BSP by visiting the Yocto Project website's | ||
| 7337 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Download</a> | ||
| 7338 | page and clicking on "BSP Downloads". | ||
| 7339 | You can download BSP tarballs that contain proprietary components | ||
| 7340 | after agreeing to the licensing | ||
| 7341 | requirements of each of the individually encumbered | ||
| 7342 | packages as part of the download process. | ||
| 7343 | Obtaining the BSP this way allows you to access an encumbered | ||
| 7344 | image immediately after agreeing to the | ||
| 7345 | click-through license agreements presented by the | ||
| 7346 | website. | ||
| 7347 | Note that if you want to build the image | ||
| 7348 | yourself using the recipes contained within the BSP | ||
| 7349 | tarball, you will still need to create an | ||
| 7350 | appropriate <code class="filename">LICENSE_FLAGS_WHITELIST</code> to match the | ||
| 7351 | encumbered recipes in the BSP.</p></li></ol></div><p> | ||
| 7352 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 7353 | Pre-compiled images are bundled with | ||
| 7354 | a time-limited kernel that runs for a | ||
| 7355 | predetermined amount of time (10 days) before it forces | ||
| 7356 | the system to reboot. | ||
| 7357 | This limitation is meant to discourage direct redistribution | ||
| 7358 | of the image. | ||
| 7359 | You must eventually rebuild the image if you want to remove this restriction. | ||
| 7360 | </div></div><div class="section" title="1.6. Using the Yocto Project's BSP Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-the-yocto-projects-bsp-tools"></a>1.6. Using the Yocto Project's BSP Tools</h2></div></div></div><p> | ||
| 7361 | The Yocto Project includes a couple of tools that enable | ||
| 7362 | you to create a <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP layer</a> | ||
| 7363 | from scratch and do basic configuration and maintenance | ||
| 7364 | of the kernel without ever looking at a metadata file. | ||
| 7365 | These tools are <code class="filename">yocto-bsp</code> and <code class="filename">yocto-kernel</code>, | ||
| 7366 | respectively. | ||
| 7367 | </p><p> | ||
| 7368 | The following sections describe the common location and help features as well | ||
| 7369 | as details for the <code class="filename">yocto-bsp</code> and <code class="filename">yocto-kernel</code> | ||
| 7370 | tools. | ||
| 7371 | </p><div class="section" title="1.6.1. Common Features"><div class="titlepage"><div><div><h3 class="title"><a id="common-features"></a>1.6.1. Common Features</h3></div></div></div><p> | ||
| 7372 | Designed to have a command interface somewhat like | ||
| 7373 | <a class="link" href="#git" target="_top">Git</a>, each | ||
| 7374 | tool is structured as a set of sub-commands under a | ||
| 7375 | top-level command. | ||
| 7376 | The top-level command (<code class="filename">yocto-bsp</code> | ||
| 7377 | or <code class="filename">yocto-kernel</code>) itself does | ||
| 7378 | nothing but invoke or provide help on the sub-commands | ||
| 7379 | it supports. | ||
| 7380 | </p><p> | ||
| 7381 | Both tools reside in the <code class="filename">scripts/</code> subdirectory | ||
| 7382 | of the <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 7383 | Consequently, to use the scripts, you must <code class="filename">source</code> the | ||
| 7384 | environment just as you would when invoking a build: | ||
| 7385 | </p><pre class="literallayout"> | ||
| 7386 | $ source oe-init-build-env [build_dir] | ||
| 7387 | </pre><p> | ||
| 7388 | </p><p> | ||
| 7389 | The most immediately useful function is to get help on both tools. | ||
| 7390 | The built-in help system makes it easy to drill down at | ||
| 7391 | any time and view the syntax required for any specific command. | ||
| 7392 | Simply enter the name of the command, or the command along with | ||
| 7393 | <code class="filename">help</code> to display a list of the available sub-commands. | ||
| 7394 | Here is an example: | ||
| 7395 | </p><pre class="literallayout"> | ||
| 7396 | $ yocto-bsp | ||
| 7397 | $ yocto-bsp help | ||
| 7398 | |||
| 7399 | Usage: | ||
| 7400 | |||
| 7401 | Create a customized Yocto BSP layer. | ||
| 7402 | |||
| 7403 | usage: yocto-bsp [--version] [--help] COMMAND [ARGS] | ||
| 7404 | |||
| 7405 | The most commonly used 'yocto-bsp' commands are: | ||
| 7406 | create Create a new Yocto BSP | ||
| 7407 | list List available values for options and BSP properties | ||
| 7408 | |||
| 7409 | See 'yocto-bsp help COMMAND' for more information on a specific command. | ||
| 7410 | |||
| 7411 | |||
| 7412 | Options: | ||
| 7413 | --version show program's version number and exit | ||
| 7414 | -h, --help show this help message and exit | ||
| 7415 | -D, --debug output debug information | ||
| 7416 | </pre><p> | ||
| 7417 | </p><p> | ||
| 7418 | Similarly, entering just the name of a sub-command shows the detailed usage | ||
| 7419 | for that sub-command: | ||
| 7420 | </p><pre class="literallayout"> | ||
| 7421 | $ yocto-bsp create | ||
| 7422 | |||
| 7423 | Usage: | ||
| 7424 | |||
| 7425 | Create a new Yocto BSP | ||
| 7426 | usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
| 7427 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
| 7428 | |||
| 7429 | This command creates a Yocto BSP based on the specified parameters. | ||
| 7430 | The new BSP will be a new BSP layer contained by default within | ||
| 7431 | the top-level directory specified as 'meta-bsp-name'. The -o option | ||
| 7432 | can be used to place the BSP layer in a directory with a different | ||
| 7433 | name and location. | ||
| 7434 | |||
| 7435 | ... | ||
| 7436 | </pre><p> | ||
| 7437 | </p><p> | ||
| 7438 | For any sub-command, you can also use the word 'help' just before the | ||
| 7439 | sub-command to get more extensive documentation: | ||
| 7440 | </p><pre class="literallayout"> | ||
| 7441 | $ yocto-bsp help create | ||
| 7442 | |||
| 7443 | NAME | ||
| 7444 | yocto-bsp create - Create a new Yocto BSP | ||
| 7445 | |||
| 7446 | SYNOPSIS | ||
| 7447 | yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
| 7448 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
| 7449 | |||
| 7450 | DESCRIPTION | ||
| 7451 | This command creates a Yocto BSP based on the specified | ||
| 7452 | parameters. The new BSP will be a new Yocto BSP layer contained | ||
| 7453 | by default within the top-level directory specified as | ||
| 7454 | 'meta-bsp-name'. The -o option can be used to place the BSP layer | ||
| 7455 | in a directory with a different name and location. | ||
| 7456 | |||
| 7457 | The value of the 'karch' parameter determines the set of files | ||
| 7458 | that will be generated for the BSP, along with the specific set of | ||
| 7459 | 'properties' that will be used to fill out the BSP-specific | ||
| 7460 | portions of the BSP. | ||
| 7461 | |||
| 7462 | ... | ||
| 7463 | |||
| 7464 | NOTE: Once created, you should add your new layer to your | ||
| 7465 | bblayers.conf file in order for it to be subsequently seen and | ||
| 7466 | modified by the yocto-kernel tool. | ||
| 7467 | |||
| 7468 | NOTE for x86- and x86_64-based BSPs: The generated BSP assumes the | ||
| 7469 | presence of the of the meta-intel layer, so you should also have a | ||
| 7470 | meta-intel layer present and added to your bblayers.conf as well. | ||
| 7471 | </pre><p> | ||
| 7472 | </p><p> | ||
| 7473 | Now that you know where these two commands reside and how to access information | ||
| 7474 | on them, you should find it relatively straightforward to discover the commands | ||
| 7475 | necessary to create a BSP and perform basic kernel maintenance on that BSP using | ||
| 7476 | the tools. | ||
| 7477 | The next sections provide a concrete starting point to expand on a few points that | ||
| 7478 | might not be immediately obvious or that could use further explanation. | ||
| 7479 | </p></div><div class="section" title="1.6.2. Creating a new BSP Layer Using the yocto-bsp Script"><div class="titlepage"><div><div><h3 class="title"><a id="creating-a-new-bsp-layer-using-the-yocto-bsp-script"></a>1.6.2. Creating a new BSP Layer Using the yocto-bsp Script</h3></div></div></div><p> | ||
| 7480 | The <code class="filename">yocto-bsp</code> script creates a new | ||
| 7481 | <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP layer</a> for any architecture supported | ||
| 7482 | by the Yocto Project, as well as QEMU versions of the same. | ||
| 7483 | The default mode of the script's operation is to prompt you for information needed | ||
| 7484 | to generate the BSP layer. | ||
| 7485 | For the current set of BSPs, the script prompts you for various important | ||
| 7486 | parameters such as: | ||
| 7487 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>which kernel to use</p></li><li class="listitem"><p>which branch of that kernel to use (or re-use)</p></li><li class="listitem"><p>whether or not to use X, and if so, which drivers to use</p></li><li class="listitem"><p>whether to turn on SMP</p></li><li class="listitem"><p>whether the BSP has a keyboard</p></li><li class="listitem"><p>whether the BSP has a touchscreen</p></li><li class="listitem"><p>any remaining configurable items associated with the BSP</p></li></ul></div><p> | ||
| 7488 | </p><p> | ||
| 7489 | You use the <code class="filename">yocto-bsp create</code> sub-command to create | ||
| 7490 | a new BSP layer. | ||
| 7491 | This command requires you to specify a particular architecture on which to | ||
| 7492 | base the BSP. | ||
| 7493 | Assuming you have sourced the environment, you can use the | ||
| 7494 | <code class="filename">yocto-bsp list karch</code> sub-command to list the | ||
| 7495 | architectures available for BSP creation as follows: | ||
| 7496 | </p><pre class="literallayout"> | ||
| 7497 | $ yocto-bsp list karch | ||
| 7498 | Architectures available: | ||
| 7499 | arm | ||
| 7500 | powerpc | ||
| 7501 | i386 | ||
| 7502 | mips | ||
| 7503 | x86_64 | ||
| 7504 | qemu | ||
| 7505 | </pre><p> | ||
| 7506 | </p><p> | ||
| 7507 | The remainder of this section presents an example that uses | ||
| 7508 | <code class="filename">myarm</code> as the machine name and <code class="filename">qemu</code> | ||
| 7509 | as the machine architecture. | ||
| 7510 | Of the available architectures, <code class="filename">qemu</code> is the only architecture | ||
| 7511 | that causes the script to prompt you further for an actual architecture. | ||
| 7512 | In every other way, this architecture is representative of how creating a BSP for | ||
| 7513 | a 'real' machine would work. | ||
| 7514 | The reason the example uses this architecture is because it is an emulated architecture | ||
| 7515 | and can easily be followed without requiring actual hardware. | ||
| 7516 | </p><p> | ||
| 7517 | As the <code class="filename">yocto-bsp create</code> command runs, default values for | ||
| 7518 | the prompts appear in brackets. | ||
| 7519 | Pressing enter without supplying anything on the command line or pressing enter | ||
| 7520 | and providing an invalid response causes the script to accept the default value. | ||
| 7521 | </p><p> | ||
| 7522 | Following is the complete example: | ||
| 7523 | </p><pre class="literallayout"> | ||
| 7524 | $ yocto-bsp create myarm qemu | ||
| 7525 | Which qemu architecture would you like to use? [default: x86] | ||
| 7526 | 1) common 32-bit x86 | ||
| 7527 | 2) common 64-bit x86 | ||
| 7528 | 3) common 32-bit ARM | ||
| 7529 | 4) common 32-bit PowerPC | ||
| 7530 | 5) common 32-bit MIPS | ||
| 7531 | 3 | ||
| 7532 | Would you like to use the default (3.2) kernel? (Y/n) | ||
| 7533 | Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [Y/n] | ||
| 7534 | Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.2... | ||
| 7535 | Please choose a machine branch to base this BSP on => [default: standard/default/common-pc] | ||
| 7536 | 1) base | ||
| 7537 | 2) standard/base | ||
| 7538 | 3) standard/default/arm-versatile-926ejs | ||
| 7539 | 4) standard/default/base | ||
| 7540 | 5) standard/default/beagleboard | ||
| 7541 | 6) standard/default/cedartrailbsp (copy).xml | ||
| 7542 | 7) standard/default/common-pc-64/base | ||
| 7543 | 8) standard/default/common-pc-64/jasperforest | ||
| 7544 | 9) standard/default/common-pc-64/romley | ||
| 7545 | 10) standard/default/common-pc-64/sugarbay | ||
| 7546 | 11) standard/default/common-pc/atom-pc | ||
| 7547 | 12) standard/default/common-pc/base | ||
| 7548 | 13) standard/default/crownbay | ||
| 7549 | 14) standard/default/emenlow | ||
| 7550 | 15) standard/default/fishriver | ||
| 7551 | 16) standard/default/fri2 | ||
| 7552 | 17) standard/default/fsl-mpc8315e-rdb | ||
| 7553 | 18) standard/default/mti-malta32-be | ||
| 7554 | 19) standard/default/mti-malta32-le | ||
| 7555 | 20) standard/default/preempt-rt | ||
| 7556 | 21) standard/default/qemu-ppc32 | ||
| 7557 | 22) standard/default/routerstationpro | ||
| 7558 | 23) standard/preempt-rt/base | ||
| 7559 | 24) standard/preempt-rt/qemu-ppc32 | ||
| 7560 | 25) standard/preempt-rt/routerstationpro | ||
| 7561 | 26) standard/tiny | ||
| 7562 | 3 | ||
| 7563 | Do you need SMP support? (Y/n) | ||
| 7564 | Does your BSP have a touchscreen? (y/N) | ||
| 7565 | Does your BSP have a keyboard? (Y/n) | ||
| 7566 | New qemu BSP created in meta-myarm | ||
| 7567 | </pre><p> | ||
| 7568 | Let's take a closer look at the example now: | ||
| 7569 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>For the <code class="filename">qemu</code> architecture, | ||
| 7570 | the script first prompts you for which emulated architecture to use. | ||
| 7571 | In the example, we use the <code class="filename">arm</code> architecture. | ||
| 7572 | </p></li><li class="listitem"><p>The script then prompts you for the kernel. | ||
| 7573 | The default kernel is 3.2 and is acceptable. | ||
| 7574 | So, the example accepts the default. | ||
| 7575 | If you enter 'n', the script prompts you to further enter the kernel | ||
| 7576 | you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.).</p></li><li class="listitem"><p>Next, the script asks whether you would like to have a new | ||
| 7577 | branch created especially for your BSP in the local | ||
| 7578 | <a class="link" href="#local-kernel-files" target="_top">Linux Yocto Kernel</a> | ||
| 7579 | Git repository . | ||
| 7580 | If not, then the script re-uses an existing branch.</p><p>In this example, the default (or 'yes') is accepted. | ||
| 7581 | Thus, a new branch is created for the BSP rather than using a common, shared | ||
| 7582 | branch. | ||
| 7583 | The new branch is the branch committed to for any patches you might later add. | ||
| 7584 | The reason a new branch is the default is that typically | ||
| 7585 | new BSPs do require BSP-specific patches. | ||
| 7586 | The tool thus assumes that most of time a new branch is required. | ||
| 7587 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>In the current implementation, creation or re-use of a branch does | ||
| 7588 | not actually matter. | ||
| 7589 | The reason is because the generated BSPs assume that patches and | ||
| 7590 | configurations live in recipe-space, which is something that can be done | ||
| 7591 | with or without a dedicated branch. | ||
| 7592 | Generated BSPs, however, are different. | ||
| 7593 | This difference becomes significant once the tool's 'publish' functionality | ||
| 7594 | is implemented.</div></li><li class="listitem"><p>Regardless of which choice is made in the previous step, | ||
| 7595 | you are now given the opportunity to select a particular machine branch on | ||
| 7596 | which to base your new BSP-specific machine branch on | ||
| 7597 | (or to re-use if you had elected to not create a new branch). | ||
| 7598 | Because this example is generating an <code class="filename">arm</code> BSP, the example | ||
| 7599 | uses <code class="filename">#3</code> at the prompt, which selects the arm-versatile branch. | ||
| 7600 | </p></li><li class="listitem"><p>The remainder of the prompts are routine. | ||
| 7601 | Defaults are accepted for each.</p></li><li class="listitem"><p>By default, the script creates the new BSP Layer in the | ||
| 7602 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 7603 | </p></li></ol></div><p> | ||
| 7604 | </p><p> | ||
| 7605 | Once the BSP Layer is created, you must add it to your | ||
| 7606 | <code class="filename">bblayers.conf</code> file. | ||
| 7607 | Here is an example: | ||
| 7608 | </p><pre class="literallayout"> | ||
| 7609 | BBLAYERS = " \ | ||
| 7610 | /usr/local/src/yocto/meta \ | ||
| 7611 | /usr/local/src/yocto/meta-yocto \ | ||
| 7612 | /usr/local/src/yocto/meta-myarm \ | ||
| 7613 | " | ||
| 7614 | </pre><p> | ||
| 7615 | Adding the layer to this file allows the build system to build the BSP and | ||
| 7616 | the <code class="filename">yocto-kernel</code> tool to be able to find the layer and | ||
| 7617 | other metadata it needs on which to operate. | ||
| 7618 | </p></div><div class="section" title="1.6.3. Managing Kernel Patches and Config Items with yocto-kernel"><div class="titlepage"><div><div><h3 class="title"><a id="managing-kernel-patches-and-config-items-with-yocto-kernel"></a>1.6.3. Managing Kernel Patches and Config Items with yocto-kernel</h3></div></div></div><p> | ||
| 7619 | Assuming you have created a <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layer</a> using | ||
| 7620 | <a class="link" href="#creating-a-new-bsp-layer-using-the-yocto-bsp-script" title="1.6.2. Creating a new BSP Layer Using the yocto-bsp Script"> | ||
| 7621 | <code class="filename">yocto-bsp</code></a> and you added it to your | ||
| 7622 | <a class="link" href="#var-BBLAYERS" target="_top"><code class="filename">BBLAYERS</code></a> | ||
| 7623 | variable in the <code class="filename">bblayers.conf</code> file, you can now use | ||
| 7624 | the <code class="filename">yocto-kernel</code> script to add patches and configuration | ||
| 7625 | items to the BSP's kernel. | ||
| 7626 | </p><p> | ||
| 7627 | The <code class="filename">yocto-kernel</code> script allows you to add, remove, and list patches | ||
| 7628 | and kernel config settings to a BSP's kernel | ||
| 7629 | <code class="filename">.bbappend</code> file. | ||
| 7630 | All you need to do is use the appropriate sub-command. | ||
| 7631 | Recall that the easiest way to see exactly what sub-commands are available | ||
| 7632 | is to use the <code class="filename">yocto-kernel</code> built-in help as follows: | ||
| 7633 | </p><pre class="literallayout"> | ||
| 7634 | $ yocto-kernel | ||
| 7635 | Usage: | ||
| 7636 | |||
| 7637 | Modify and list Yocto BSP kernel config items and patches. | ||
| 7638 | |||
| 7639 | usage: yocto-kernel [--version] [--help] COMMAND [ARGS] | ||
| 7640 | |||
| 7641 | The most commonly used 'yocto-kernel' commands are: | ||
| 7642 | config list List the modifiable set of bare kernel config options for a BSP | ||
| 7643 | config add Add or modify bare kernel config options for a BSP | ||
| 7644 | config rm Remove bare kernel config options from a BSP | ||
| 7645 | patch list List the patches associated with a BSP | ||
| 7646 | patch add Patch the Yocto kernel for a BSP | ||
| 7647 | patch rm Remove patches from a BSP | ||
| 7648 | |||
| 7649 | See 'yocto-kernel help COMMAND' for more information on a specific command. | ||
| 7650 | </pre><p> | ||
| 7651 | </p><p> | ||
| 7652 | The <code class="filename">yocto-kernel patch add</code> sub-command allows you to add a | ||
| 7653 | patch to a BSP. | ||
| 7654 | The following example adds two patches to the <code class="filename">myarm</code> BSP: | ||
| 7655 | </p><pre class="literallayout"> | ||
| 7656 | $ yocto-kernel patch add myarm ~/test.patch | ||
| 7657 | Added patches: | ||
| 7658 | test.patch | ||
| 7659 | |||
| 7660 | $ yocto-kernel patch add myarm ~/yocto-testmod.patch | ||
| 7661 | Added patches: | ||
| 7662 | yocto-testmod.patch | ||
| 7663 | </pre><p> | ||
| 7664 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Although the previous example adds patches one at a time, it is possible | ||
| 7665 | to add multiple patches at the same time.</div><p> | ||
| 7666 | </p><p> | ||
| 7667 | You can verify patches have been added by using the | ||
| 7668 | <code class="filename">yocto-kernel patch list</code> sub-command. | ||
| 7669 | Here is an example: | ||
| 7670 | </p><pre class="literallayout"> | ||
| 7671 | $ yocto-kernel patch list myarm | ||
| 7672 | The current set of machine-specific patches for myarm is: | ||
| 7673 | 1) test.patch | ||
| 7674 | 2) yocto-testmod.patch | ||
| 7675 | </pre><p> | ||
| 7676 | </p><p> | ||
| 7677 | You can also use the <code class="filename">yocto-kernel</code> script to | ||
| 7678 | remove a patch using the <code class="filename">yocto-kernel patch rm</code> sub-command. | ||
| 7679 | Here is an example: | ||
| 7680 | </p><pre class="literallayout"> | ||
| 7681 | $ yocto-kernel patch rm myarm | ||
| 7682 | Specify the patches to remove: | ||
| 7683 | 1) test.patch | ||
| 7684 | 2) yocto-testmod.patch | ||
| 7685 | 1 | ||
| 7686 | Removed patches: | ||
| 7687 | test.patch | ||
| 7688 | </pre><p> | ||
| 7689 | </p><p> | ||
| 7690 | Again, using the <code class="filename">yocto-kernel patch list</code> sub-command, | ||
| 7691 | you can verify that the patch was in fact removed: | ||
| 7692 | </p><pre class="literallayout"> | ||
| 7693 | $ yocto-kernel patch list myarm | ||
| 7694 | The current set of machine-specific patches for myarm is: | ||
| 7695 | 1) yocto-testmod.patch | ||
| 7696 | </pre><p> | ||
| 7697 | </p><p> | ||
| 7698 | In a completely similar way, you can use the <code class="filename">yocto-kernel config add</code> | ||
| 7699 | sub-command to add one or more kernel config item settings to a BSP. | ||
| 7700 | The following commands add a couple of config items to the | ||
| 7701 | <code class="filename">myarm</code> BSP: | ||
| 7702 | </p><pre class="literallayout"> | ||
| 7703 | $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y | ||
| 7704 | Added items: | ||
| 7705 | CONFIG_MISC_DEVICES=y | ||
| 7706 | |||
| 7707 | $ yocto-kernel config add myarm KCONFIG_YOCTO_TESTMOD=y | ||
| 7708 | Added items: | ||
| 7709 | CONFIG_YOCTO_TESTMOD=y | ||
| 7710 | </pre><p> | ||
| 7711 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Although the previous example adds config items one at a time, it is possible | ||
| 7712 | to add multiple config items at the same time.</div><p> | ||
| 7713 | </p><p> | ||
| 7714 | You can list the config items now associated with the BSP. | ||
| 7715 | Doing so shows you the config items you added as well as others associated | ||
| 7716 | with the BSP: | ||
| 7717 | </p><pre class="literallayout"> | ||
| 7718 | $ yocto-kernel config list myarm | ||
| 7719 | The current set of machine-specific kernel config items for myarm is: | ||
| 7720 | 1) CONFIG_MISC_DEVICES=y | ||
| 7721 | 2) CONFIG_YOCTO_TESTMOD=y | ||
| 7722 | </pre><p> | ||
| 7723 | </p><p> | ||
| 7724 | Finally, you can remove one or more config items using the | ||
| 7725 | <code class="filename">yocto-kernel config rm</code> sub-command in a manner | ||
| 7726 | completely analogous to <code class="filename">yocto-kernel patch rm</code>. | ||
| 7727 | </p></div></div></div> | ||
| 7728 | |||
| 7729 | |||
| 7730 | |||
| 7731 | </div> | ||
| 7732 | |||
| 7733 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/kernel-title.png" align="left" width="100%" /></td></tr></table> | ||
| 7734 | |||
| 7735 | <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="kernel-manual"></a></h1></div><div><div class="authorgroup"> | ||
| 7736 | <div class="author"><h3 class="author"><span class="firstname">Bruce</span> <span class="surname">Ashfield</span></h3><div class="affiliation"> | ||
| 7737 | <span class="orgname">Wind River Corporation<br /></span> | ||
| 7738 | </div><code class="email"><<a class="email" href="mailto:bruce.ashfield@windriver.com">bruce.ashfield@windriver.com</a>></code></div> | ||
| 7739 | </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1504523"></a> | ||
| 7740 | <p> | ||
| 7741 | Permission is granted to copy, distribute and/or modify this document under | ||
| 7742 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. | ||
| 7743 | </p> | ||
| 7744 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 7745 | Due to production processes, there could be differences between the Yocto Project | ||
| 7746 | documentation bundled in the release tarball and the | ||
| 7747 | Yocto Project Kernel Architecture and Use Manual on | ||
| 7748 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 7749 | For the latest version of this manual, see the manual on the website. | ||
| 7750 | </div> | ||
| 7751 | </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> | ||
| 7752 | <tr><td align="left">Revision 0.9</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">The initial document draft released with the Yocto Project 0.9 Release.</td></tr> | ||
| 7753 | <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> | ||
| 7754 | <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> | ||
| 7755 | <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> | ||
| 7756 | <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> | ||
| 7757 | <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> | ||
| 7758 | </table></div></div></div><hr /></div> | ||
| 7759 | |||
| 7760 | |||
| 7761 | <div class="chapter" title="Chapter 1. Yocto Project Kernel Architecture and Use Manual"><div class="titlepage"><div><div><h2 class="title"><a id="kernel-doc-intro"></a>Chapter 1. Yocto Project Kernel Architecture and Use Manual</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#kernel-intro-section">1.1. Introduction</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-intro-section"></a>1.1. Introduction</h2></div></div></div><p> | ||
| 7762 | The Yocto Project presents kernels as a fully patched, history-clean Git | ||
| 7763 | repositories. | ||
| 7764 | Each repository represents selected features, board support, | ||
| 7765 | and configurations extensively tested by the Yocto Project. | ||
| 7766 | Yocto Project kernels allow the end user to leverage community | ||
| 7767 | best practices to seamlessly manage the development, build and debug cycles. | ||
| 7768 | </p><p> | ||
| 7769 | This manual describes Yocto Project kernels by providing information | ||
| 7770 | on history, organization, benefits, and use. | ||
| 7771 | The manual consists of two sections: | ||
| 7772 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Concepts:</em></span> Describes concepts behind a kernel. | ||
| 7773 | You will understand how a kernel is organized and why it is organized in | ||
| 7774 | the way it is. You will understand the benefits of a kernel's organization | ||
| 7775 | and the mechanisms used to work with the kernel and how to apply it in your | ||
| 7776 | design process.</p></li><li class="listitem"><p><span class="emphasis"><em>Using a Kernel:</em></span> Describes best practices | ||
| 7777 | and "how-to" information | ||
| 7778 | that lets you put a kernel to practical use. | ||
| 7779 | Some examples are how to examine changes in a branch and how to | ||
| 7780 | save kernel modifications.</p></li></ul></div><p> | ||
| 7781 | </p><p> | ||
| 7782 | For more information on the Linux kernel, see the following links: | ||
| 7783 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Linux Foundation's guide for kernel development | ||
| 7784 | process - <a class="ulink" href="http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process" target="_top">http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process</a></p></li><li class="listitem"><p>A fairly encompassing guide on Linux kernel development - | ||
| 7785 | <a class="ulink" href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD" target="_top">http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD</a></p></li></ul></div><p> | ||
| 7786 | </p><p> | ||
| 7787 | For more discussion on the Yocto Project kernel, you can see these sections | ||
| 7788 | in the Yocto Project Development Manual: | ||
| 7789 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 7790 | "<a class="link" href="#kernel-overview" target="_top">Kernel Overview</a>"</p></li><li class="listitem"><p> | ||
| 7791 | "<a class="link" href="#kernel-modification-workflow" target="_top">Kernel Modification Workflow</a>" | ||
| 7792 | </p></li><li class="listitem"><p> | ||
| 7793 | "<a class="link" href="#dev-manual-kernel-appendix" target="_top">Kernel Modification Example</a>"</p></li></ul></div><p> | ||
| 7794 | </p><p> | ||
| 7795 | For general information on the Yocto Project, visit the website at | ||
| 7796 | <a class="ulink" href="http://www.yoctoproject.org" target="_top">http://www.yoctoproject.org</a>. | ||
| 7797 | </p></div></div> | ||
| 7798 | |||
| 7799 | <div class="chapter" title="Chapter 2. Yocto Project Kernel Concepts"><div class="titlepage"><div><div><h2 class="title"><a id="kernel-concepts"></a>Chapter 2. Yocto Project Kernel Concepts</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#concepts-org">2.1. Introduction</a></span></dt><dt><span class="section"><a href="#kernel-goals">2.2. Kernel Goals</a></span></dt><dt><span class="section"><a href="#kernel-big-picture">2.3. Yocto Project Kernel Development and Maintenance Overview</a></span></dt><dt><span class="section"><a href="#kernel-architecture">2.4. Kernel Architecture</a></span></dt><dd><dl><dt><span class="section"><a href="#architecture-overview">2.4.1. Overview</a></span></dt><dt><span class="section"><a href="#branching-and-workflow">2.4.2. Branching Strategy and Workflow</a></span></dt><dt><span class="section"><a href="#source-code-manager-git">2.4.3. Source Code Manager - Git</a></span></dt></dl></dd><dt><span class="section"><a href="#kernel-configuration">2.5. Kernel Configuration</a></span></dt><dt><span class="section"><a href="#kernel-tools">2.6. Kernel Tools</a></span></dt></dl></div><div class="section" title="2.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="concepts-org"></a>2.1. Introduction</h2></div></div></div><p> | ||
| 7800 | This chapter provides conceptual information about the kernel: | ||
| 7801 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Kernel Goals</p></li><li class="listitem"><p>Kernel Development and Maintenance Overview</p></li><li class="listitem"><p>Kernel Architecture</p></li><li class="listitem"><p>Kernel Tools</p></li></ul></div><p> | ||
| 7802 | </p></div><div class="section" title="2.2. Kernel Goals"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-goals"></a>2.2. Kernel Goals</h2></div></div></div><p> | ||
| 7803 | The complexity of embedded kernel design has increased dramatically. | ||
| 7804 | Whether it is managing multiple implementations of a particular feature or tuning and | ||
| 7805 | optimizing board specific features, both flexibility and maintainability are key concerns. | ||
| 7806 | The Linux kernels available through the Yocto Project are presented with the embedded | ||
| 7807 | developer's needs in mind and have evolved to assist in these key concerns. | ||
| 7808 | For example, prior methods such as applying hundreds of patches to an extracted | ||
| 7809 | tarball have been replaced with proven techniques that allow easy inspection, | ||
| 7810 | bisection and analysis of changes. | ||
| 7811 | Application of these techniques also creates a platform for performing integration and | ||
| 7812 | collaboration with the thousands of upstream development projects. | ||
| 7813 | </p><p> | ||
| 7814 | With all these considerations in mind, the Yocto Project's kernel and development team | ||
| 7815 | strives to attain these goals: | ||
| 7816 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Allow the end user to leverage community best practices to seamlessly | ||
| 7817 | manage the development, build and debug cycles.</p></li><li class="listitem"><p>Create a platform for performing integration and collaboration with the | ||
| 7818 | thousands of upstream development projects that exist.</p></li><li class="listitem"><p>Provide mechanisms that support many different work flows, front-ends and | ||
| 7819 | management techniques.</p></li><li class="listitem"><p>Deliver the most up-to-date kernel possible while still ensuring that | ||
| 7820 | the baseline kernel is the most stable official release.</p></li><li class="listitem"><p>Include major technological features as part of the Yocto Project's | ||
| 7821 | upward revision strategy.</p></li><li class="listitem"><p>Present a kernel Git repository that, similar to the upstream | ||
| 7822 | <code class="filename">kernel.org</code> tree, | ||
| 7823 | has a clear and continuous history.</p></li><li class="listitem"><p>Deliver a key set of supported kernel types, where each type is tailored | ||
| 7824 | to meet a specific use (e.g. networking, consumer, devices, and so forth).</p></li><li class="listitem"><p>Employ a Git branching strategy that, from a developer's point of view, | ||
| 7825 | results in a linear path from the baseline <code class="filename">kernel.org</code>, | ||
| 7826 | through a select group of features and | ||
| 7827 | ends with their BSP-specific commits.</p></li></ul></div><p> | ||
| 7828 | </p></div><div class="section" title="2.3. Yocto Project Kernel Development and Maintenance Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-big-picture"></a>2.3. Yocto Project Kernel Development and Maintenance Overview</h2></div></div></div><p> | ||
| 7829 | Kernels available through the Yocto Project, like other kernels, are based off the Linux | ||
| 7830 | kernel releases from <a class="ulink" href="http://www.kernel.org" target="_top">http://www.kernel.org</a>. | ||
| 7831 | At the beginning of a major development cycle, the Yocto Project team | ||
| 7832 | chooses its kernel based on factors such as release timing, the anticipated release | ||
| 7833 | timing of final upstream <code class="filename">kernel.org</code> versions, and Yocto Project | ||
| 7834 | feature requirements. | ||
| 7835 | Typically, the kernel chosen is in the | ||
| 7836 | final stages of development by the community. | ||
| 7837 | In other words, the kernel is in the release | ||
| 7838 | candidate or "rc" phase and not yet a final release. | ||
| 7839 | But, by being in the final stages of external development, the team knows that the | ||
| 7840 | <code class="filename">kernel.org</code> final release will clearly be within the early stages of | ||
| 7841 | the Yocto Project development window. | ||
| 7842 | </p><p> | ||
| 7843 | This balance allows the team to deliver the most up-to-date kernel | ||
| 7844 | as possible, while still ensuring that the team has a stable official release for | ||
| 7845 | the baseline Linux kernel version. | ||
| 7846 | </p><p> | ||
| 7847 | The ultimate source for kernels available through the Yocto Project are released kernels | ||
| 7848 | from <code class="filename">kernel.org</code>. | ||
| 7849 | In addition to a foundational kernel from <code class="filename">kernel.org</code>, the | ||
| 7850 | kernels available contain a mix of important new mainline | ||
| 7851 | developments, non-mainline developments (when there is no alternative), | ||
| 7852 | Board Support Package (BSP) developments, | ||
| 7853 | and custom features. | ||
| 7854 | These additions result in a commercially released Yocto Project Linux kernel that caters | ||
| 7855 | to specific embedded designer needs for targeted hardware. | ||
| 7856 | </p><p> | ||
| 7857 | Once a kernel is officially released, the Yocto Project team goes into | ||
| 7858 | their next development cycle, or upward revision (uprev) cycle, while still | ||
| 7859 | continuing maintenance on the released kernel. | ||
| 7860 | It is important to note that the most sustainable and stable way | ||
| 7861 | to include feature development upstream is through a kernel uprev process. | ||
| 7862 | Back-porting hundreds of individual fixes and minor features from various | ||
| 7863 | kernel versions is not sustainable and can easily compromise quality. | ||
| 7864 | </p><p> | ||
| 7865 | During the uprev cycle, the Yocto Project team uses an ongoing analysis of | ||
| 7866 | kernel development, BSP support, and release timing to select the best | ||
| 7867 | possible <code class="filename">kernel.org</code> version. | ||
| 7868 | The team continually monitors community kernel | ||
| 7869 | development to look for significant features of interest. | ||
| 7870 | The team does consider back-porting large features if they have a significant advantage. | ||
| 7871 | User or community demand can also trigger a back-port or creation of new | ||
| 7872 | functionality in the Yocto Project baseline kernel during the uprev cycle. | ||
| 7873 | </p><p> | ||
| 7874 | Generally speaking, every new kernel both adds features and introduces new bugs. | ||
| 7875 | These consequences are the basic properties of upstream kernel development and are | ||
| 7876 | managed by the Yocto Project team's kernel strategy. | ||
| 7877 | It is the Yocto Project team's policy to not back-port minor features to the released kernel. | ||
| 7878 | They only consider back-porting significant technological jumps - and, that is done | ||
| 7879 | after a complete gap analysis. | ||
| 7880 | The reason for this policy is that back-porting any small to medium sized change | ||
| 7881 | from an evolving kernel can easily create mismatches, incompatibilities and very | ||
| 7882 | subtle errors. | ||
| 7883 | </p><p> | ||
| 7884 | These policies result in both a stable and a cutting | ||
| 7885 | edge kernel that mixes forward ports of existing features and significant and critical | ||
| 7886 | new functionality. | ||
| 7887 | Forward porting functionality in the kernels available through the Yocto Project kernel | ||
| 7888 | can be thought of as a "micro uprev." | ||
| 7889 | The many “micro uprevs” produce a kernel version with a mix of | ||
| 7890 | important new mainline, non-mainline, BSP developments and feature integrations. | ||
| 7891 | This kernel gives insight into new features and allows focused | ||
| 7892 | amounts of testing to be done on the kernel, which prevents | ||
| 7893 | surprises when selecting the next major uprev. | ||
| 7894 | The quality of these cutting edge kernels is evolving and the kernels are used in leading edge | ||
| 7895 | feature and BSP development. | ||
| 7896 | </p></div><div class="section" title="2.4. Kernel Architecture"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-architecture"></a>2.4. Kernel Architecture</h2></div></div></div><p> | ||
| 7897 | This section describes the architecture of the kernels available through the | ||
| 7898 | Yocto Project and provides information | ||
| 7899 | on the mechanisms used to achieve that architecture. | ||
| 7900 | </p><div class="section" title="2.4.1. Overview"><div class="titlepage"><div><div><h3 class="title"><a id="architecture-overview"></a>2.4.1. Overview</h3></div></div></div><p> | ||
| 7901 | As mentioned earlier, a key goal of the Yocto Project is to present the | ||
| 7902 | developer with | ||
| 7903 | a kernel that has a clear and continuous history that is visible to the user. | ||
| 7904 | The architecture and mechanisms used achieve that goal in a manner similar to the | ||
| 7905 | upstream <code class="filename">kernel.org</code>. | ||
| 7906 | </p><p> | ||
| 7907 | You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with | ||
| 7908 | added features logically structured on top of the baseline. | ||
| 7909 | The features are tagged and organized by way of a branching strategy implemented by the | ||
| 7910 | source code manager (SCM) Git. | ||
| 7911 | For information on Git as applied to the Yocto Project, see the | ||
| 7912 | "<a class="link" href="#git" target="_top">Git</a>" section in the | ||
| 7913 | Yocto Project Development Manual. | ||
| 7914 | </p><p> | ||
| 7915 | The result is that the user has the ability to see the added features and | ||
| 7916 | the commits that make up those features. | ||
| 7917 | In addition to being able to see added features, the user can also view the history of what | ||
| 7918 | made up the baseline kernel. | ||
| 7919 | </p><p> | ||
| 7920 | The following illustration shows the conceptual Yocto Project kernel. | ||
| 7921 | </p><p> | ||
| 7922 | </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/kernel-architecture-overview.png" align="middle" /></td></tr></table><p> | ||
| 7923 | </p><p> | ||
| 7924 | In the illustration, the "Kernel.org Branch Point" | ||
| 7925 | marks the specific spot (or release) from | ||
| 7926 | which the Yocto Project kernel is created. | ||
| 7927 | From this point "up" in the tree, features and differences are organized and tagged. | ||
| 7928 | </p><p> | ||
| 7929 | The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel | ||
| 7930 | type and BSP that is organized further up the tree. | ||
| 7931 | Placing these common features in the | ||
| 7932 | tree this way means features don't have to be duplicated along individual branches of the | ||
| 7933 | structure. | ||
| 7934 | </p><p> | ||
| 7935 | From the Yocto Project Baseline Kernel, branch points represent specific functionality | ||
| 7936 | for individual BSPs as well as real-time kernels. | ||
| 7937 | The illustration represents this through three BSP-specific branches and a real-time | ||
| 7938 | kernel branch. | ||
| 7939 | Each branch represents some unique functionality for the BSP or a real-time kernel. | ||
| 7940 | </p><p> | ||
| 7941 | In this example structure, the real-time kernel branch has common features for all | ||
| 7942 | real-time kernels and contains | ||
| 7943 | more branches for individual BSP-specific real-time kernels. | ||
| 7944 | The illustration shows three branches as an example. | ||
| 7945 | Each branch points the way to specific, unique features for a respective real-time | ||
| 7946 | kernel as they apply to a given BSP. | ||
| 7947 | </p><p> | ||
| 7948 | The resulting tree structure presents a clear path of markers (or branches) to the | ||
| 7949 | developer that, for all practical purposes, is the kernel needed for any given set | ||
| 7950 | of requirements. | ||
| 7951 | </p></div><div class="section" title="2.4.2. Branching Strategy and Workflow"><div class="titlepage"><div><div><h3 class="title"><a id="branching-and-workflow"></a>2.4.2. Branching Strategy and Workflow</h3></div></div></div><p> | ||
| 7952 | The Yocto Project team creates kernel branches at points where functionality is | ||
| 7953 | no longer shared and thus, needs to be isolated. | ||
| 7954 | For example, board-specific incompatibilities would require different functionality | ||
| 7955 | and would require a branch to separate the features. | ||
| 7956 | Likewise, for specific kernel features, the same branching strategy is used. | ||
| 7957 | </p><p> | ||
| 7958 | This branching strategy results in a tree that has features organized to be specific | ||
| 7959 | for particular functionality, single kernel types, or a subset of kernel types. | ||
| 7960 | This strategy also results in not having to store the same feature twice | ||
| 7961 | internally in the tree. | ||
| 7962 | Rather, the kernel team stores the unique differences required to apply the | ||
| 7963 | feature onto the kernel type in question. | ||
| 7964 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 7965 | The Yocto Project team strives to place features in the tree such that they can be | ||
| 7966 | shared by all boards and kernel types where possible. | ||
| 7967 | However, during development cycles or when large features are merged, | ||
| 7968 | the team cannot always follow this practice. | ||
| 7969 | In those cases, the team uses isolated branches to merge features. | ||
| 7970 | </div><p> | ||
| 7971 | </p><p> | ||
| 7972 | BSP-specific code additions are handled in a similar manner to kernel-specific additions. | ||
| 7973 | Some BSPs only make sense given certain kernel types. | ||
| 7974 | So, for these types, the team creates branches off the end of that kernel type for all | ||
| 7975 | of the BSPs that are supported on that kernel type. | ||
| 7976 | From the perspective of the tools that create the BSP branch, the BSP is really no | ||
| 7977 | different than a feature. | ||
| 7978 | Consequently, the same branching strategy applies to BSPs as it does to features. | ||
| 7979 | So again, rather than store the BSP twice, the team only stores the unique | ||
| 7980 | differences for the BSP across the supported multiple kernels. | ||
| 7981 | </p><p> | ||
| 7982 | While this strategy can result in a tree with a significant number of branches, it is | ||
| 7983 | important to realize that from the developer's point of view, there is a linear | ||
| 7984 | path that travels from the baseline <code class="filename">kernel.org</code>, through a select | ||
| 7985 | group of features and ends with their BSP-specific commits. | ||
| 7986 | In other words, the divisions of the kernel are transparent and are not relevant | ||
| 7987 | to the developer on a day-to-day basis. | ||
| 7988 | From the developer's perspective, this path is the "master" branch. | ||
| 7989 | The developer does not need to be aware of the existence of any other branches at all. | ||
| 7990 | Of course, there is value in the existence of these branches | ||
| 7991 | in the tree, should a person decide to explore them. | ||
| 7992 | For example, a comparison between two BSPs at either the commit level or at the line-by-line | ||
| 7993 | code <code class="filename">diff</code> level is now a trivial operation. | ||
| 7994 | </p><p> | ||
| 7995 | Working with the kernel as a structured tree follows recognized community best practices. | ||
| 7996 | In particular, the kernel as shipped with the product, should be | ||
| 7997 | considered an "upstream source" and viewed as a series of | ||
| 7998 | historical and documented modifications (commits). | ||
| 7999 | These modifications represent the development and stabilization done | ||
| 8000 | by the Yocto Project kernel development team. | ||
| 8001 | </p><p> | ||
| 8002 | Because commits only change at significant release points in the product life cycle, | ||
| 8003 | developers can work on a branch created | ||
| 8004 | from the last relevant commit in the shipped Yocto Project kernel. | ||
| 8005 | As mentioned previously, the structure is transparent to the developer | ||
| 8006 | because the kernel tree is left in this state after cloning and building the kernel. | ||
| 8007 | </p></div><div class="section" title="2.4.3. Source Code Manager - Git"><div class="titlepage"><div><div><h3 class="title"><a id="source-code-manager-git"></a>2.4.3. Source Code Manager - Git</h3></div></div></div><p> | ||
| 8008 | The Source Code Manager (SCM) is Git. | ||
| 8009 | This SCM is the obvious mechanism for meeting the previously mentioned goals. | ||
| 8010 | Not only is it the SCM for <code class="filename">kernel.org</code> but, | ||
| 8011 | Git continues to grow in popularity and supports many different work flows, | ||
| 8012 | front-ends and management techniques. | ||
| 8013 | </p><p> | ||
| 8014 | You can find documentation on Git at <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. | ||
| 8015 | You can also get an introduction to Git as it applies to the Yocto Project in the | ||
| 8016 | "<a class="link" href="#git" target="_top">Git</a>" | ||
| 8017 | section in the Yocto Project Development Manual. | ||
| 8018 | These referenced sections overview Git and describe a minimal set of | ||
| 8019 | commands that allows you to be functional using Git. | ||
| 8020 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8021 | You can use as much, or as little, of what Git has to offer to accomplish what | ||
| 8022 | you need for your project. | ||
| 8023 | You do not have to be a "Git Master" in order to use it with the Yocto Project. | ||
| 8024 | </div><p> | ||
| 8025 | </p></div></div><div class="section" title="2.5. Kernel Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-configuration"></a>2.5. Kernel Configuration</h2></div></div></div><p> | ||
| 8026 | Kernel configuration, along with kernel features, defines how a kernel | ||
| 8027 | image is built for the Yocto Project. | ||
| 8028 | Through configuration settings, you can customize a Yocto Project kernel to be | ||
| 8029 | specific to particular hardware. | ||
| 8030 | For example, you can specify sound support or networking support. | ||
| 8031 | This section describes basic concepts behind Kernel configuration within the | ||
| 8032 | Yocto Project and references you to other areas for specific configuration | ||
| 8033 | applications. | ||
| 8034 | </p><p> | ||
| 8035 | Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any | ||
| 8036 | Linux kernel. | ||
| 8037 | The build process for a Yocto Project kernel uses a <code class="filename">.config</code> file, which | ||
| 8038 | is created through the Linux Kernel Coinfiguration (LKC) tool. | ||
| 8039 | You can directly set various configurations in the | ||
| 8040 | <code class="filename">.config</code> file by using the <code class="filename">menuconfig</code> | ||
| 8041 | tool as built by BitBake. | ||
| 8042 | You can also define configurations in the file by using configuration fragments. | ||
| 8043 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8044 | It is not recommended that you edit the <code class="filename">.config</code> file directly. | ||
| 8045 | </div><p> | ||
| 8046 | Here are some brief descriptions of the ways you can affect the | ||
| 8047 | <code class="filename">.config</code> file: | ||
| 8048 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The <code class="filename">menuconfig</code> Tool:</em></span> | ||
| 8049 | One of many front-ends that allows you to define kernel configurations. | ||
| 8050 | Some others are <code class="filename">make config</code>, | ||
| 8051 | <code class="filename">make nconfig</code>, and <code class="filename">make gconfig</code>. | ||
| 8052 | In the Yocto Project environment, you must use BitBake to build the | ||
| 8053 | <code class="filename">menuconfig</code> tool before you can use it to define | ||
| 8054 | configurations: | ||
| 8055 | </p><pre class="literallayout"> | ||
| 8056 | $ bitbake linux-yocto -c menuconfig | ||
| 8057 | </pre><p> | ||
| 8058 | After the tool is built, you can interact with it normally. | ||
| 8059 | You can see how <code class="filename">menuconfig</code> is used to change a simple | ||
| 8060 | kernel configuration in the | ||
| 8061 | "<a class="link" href="#changing-the-config-smp-configuration-using-menuconfig" target="_top">Changing the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></a>" | ||
| 8062 | section of the Yocto Project Development Manual. | ||
| 8063 | For general information on <code class="filename">menuconfig</code>, see | ||
| 8064 | <a class="ulink" href="http://en.wikipedia.org/wiki/Menuconfig" target="_top">http://en.wikipedia.org/wiki/Menuconfig</a>. | ||
| 8065 | </p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Fragments:</em></span> A file with a | ||
| 8066 | list of kernel options just as they would appear syntactically in the | ||
| 8067 | <code class="filename">.config</code> file. | ||
| 8068 | Configuration fragments are typically logical groupings and are assembled | ||
| 8069 | by the OpenEmbedded build system to produce input used by the LKC | ||
| 8070 | that ultimately generates the <code class="filename">.config</code> file.</p><p>The | ||
| 8071 | <code class="filename"><a class="link" href="#var-KERNEL_FEATURES" target="_top">KERNEL_FEATURES</a></code> | ||
| 8072 | variable can be used to list configuration fragments. | ||
| 8073 | For further discussion on applying configuration fragments, see the | ||
| 8074 | "<a class="link" href="#bsp-filelayout-kernel" target="_top">Linux Kernel Configuration</a>" | ||
| 8075 | section in the Yocto Project Board Support Package (BSP) Guide. | ||
| 8076 | </p></li></ul></div><p> | ||
| 8077 | </p></div><div class="section" title="2.6. Kernel Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-tools"></a>2.6. Kernel Tools</h2></div></div></div><p> | ||
| 8078 | Since most standard workflows involve moving forward with an existing tree by | ||
| 8079 | continuing to add and alter the underlying baseline, the tools that manage | ||
| 8080 | the Yocto Project's kernel construction are largely hidden from the developer to | ||
| 8081 | present a simplified view of the kernel for ease of use. | ||
| 8082 | </p><p> | ||
| 8083 | Fundamentally, the kernel tools that manage and construct the | ||
| 8084 | Yocto Project kernel accomplish the following: | ||
| 8085 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Group patches into named, reusable features.</p></li><li class="listitem"><p>Allow top-down control of included features.</p></li><li class="listitem"><p>Bind kernel configurations to kernel patches and features.</p></li><li class="listitem"><p>Present a seamless Git repository that blends Yocto Project value | ||
| 8086 | with the <code class="filename">kernel.org</code> history and development.</p></li></ul></div><p> | ||
| 8087 | </p></div></div> | ||
| 8088 | |||
| 8089 | <div class="chapter" title="Chapter 3. Working with the Yocto Project Kernel"><div class="titlepage"><div><div><h2 class="title"><a id="kernel-how-to"></a>Chapter 3. Working with the Yocto Project Kernel</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#actions-org">3.1. Introduction</a></span></dt><dt><span class="section"><a href="#tree-construction">3.2. Tree Construction</a></span></dt><dt><span class="section"><a href="#build-strategy">3.3. Build Strategy</a></span></dt><dt><span class="section"><a href="#workflow-examples">3.4. Workflow Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#change-inspection-kernel-changes-commits">3.4.1. Change Inspection: Changes/Commits</a></span></dt><dt><span class="section"><a href="#development-saving-kernel-modifications">3.4.2. Development: Saving Kernel Modifications</a></span></dt><dt><span class="section"><a href="#scm-working-with-the-yocto-project-kernel-in-another-scm">3.4.3. Working with the Yocto Project Kernel in Another SCM</a></span></dt><dt><span class="section"><a href="#bsp-creating">3.4.4. Creating a BSP Based on an Existing Similar BSP</a></span></dt><dt><span class="section"><a href="#tip-dirty-string">3.4.5. "-dirty" String</a></span></dt></dl></dd></dl></div><div class="section" title="3.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="actions-org"></a>3.1. Introduction</h2></div></div></div><p> | ||
| 8090 | This chapter describes how to accomplish tasks involving a kernel's tree structure. | ||
| 8091 | The information is designed to help the developer that wants to modify the Yocto | ||
| 8092 | Project kernel and contribute changes upstream to the Yocto Project. | ||
| 8093 | The information covers the following: | ||
| 8094 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Tree construction</p></li><li class="listitem"><p>Build strategies</p></li><li class="listitem"><p>Workflow examples</p></li></ul></div><p> | ||
| 8095 | </p></div><div class="section" title="3.2. Tree Construction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="tree-construction"></a>3.2. Tree Construction</h2></div></div></div><p> | ||
| 8096 | This section describes construction of the Yocto Project kernel source repositories | ||
| 8097 | as accomplished by the Yocto Project team to create kernel repositories. | ||
| 8098 | These kernel repositories are found under the heading "Yocto Linux Kernel" at | ||
| 8099 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a> | ||
| 8100 | and can be shipped as part of a Yocto Project release. | ||
| 8101 | The team creates these repositories by | ||
| 8102 | compiling and executing the set of feature descriptions for every BSP/feature | ||
| 8103 | in the product. | ||
| 8104 | Those feature descriptions list all necessary patches, | ||
| 8105 | configuration, branching, tagging and feature divisions found in a kernel. | ||
| 8106 | Thus, the Yocto Project kernel repository (or tree) is built. | ||
| 8107 | </p><p> | ||
| 8108 | The existence of this tree allows you to access and clone a particular | ||
| 8109 | Yocto Project kernel repository and use it to build images based on their configurations | ||
| 8110 | and features. | ||
| 8111 | </p><p> | ||
| 8112 | You can find the files used to describe all the valid features and BSPs | ||
| 8113 | in the Yocto Project kernel in any clone of the Yocto Project kernel source repository | ||
| 8114 | Git tree. | ||
| 8115 | For example, the following command clones the Yocto Project baseline kernel that | ||
| 8116 | branched off of <code class="filename">linux.org</code> version 3.4: | ||
| 8117 | </p><pre class="literallayout"> | ||
| 8118 | $ git clone git://git.yoctoproject.org/linux-yocto-3.4 | ||
| 8119 | </pre><p> | ||
| 8120 | For another example of how to set up a local Git repository of the Yocto Project | ||
| 8121 | kernel files, see the | ||
| 8122 | "<a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a>" bulleted | ||
| 8123 | item in the Yocto Project Development Manual. | ||
| 8124 | </p><p> | ||
| 8125 | Once you have cloned the kernel Git repository on your local machine, you can | ||
| 8126 | switch to the <code class="filename">meta</code> branch within the repository. | ||
| 8127 | Here is an example that assumes the local Git repository for the kernel is in | ||
| 8128 | a top-level directory named <code class="filename">linux-yocto-3.4</code>: | ||
| 8129 | </p><pre class="literallayout"> | ||
| 8130 | $ cd ~/linux-yocto-3.4 | ||
| 8131 | $ git checkout -b meta origin/meta | ||
| 8132 | </pre><p> | ||
| 8133 | Once you have checked out and switched to the <code class="filename">meta</code> branch, | ||
| 8134 | you can see a snapshot of all the kernel configuration and feature descriptions that are | ||
| 8135 | used to build that particular kernel repository. | ||
| 8136 | These descriptions are in the form of <code class="filename">.scc</code> files. | ||
| 8137 | </p><p> | ||
| 8138 | You should realize, however, that browsing your local kernel repository | ||
| 8139 | for feature descriptions and patches is not an effective way to determine what is in a | ||
| 8140 | particular kernel branch. | ||
| 8141 | Instead, you should use Git directly to discover the changes in a branch. | ||
| 8142 | Using Git is an efficient and flexible way to inspect changes to the kernel. | ||
| 8143 | For examples showing how to use Git to inspect kernel commits, see the following sections | ||
| 8144 | in this chapter. | ||
| 8145 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8146 | Ground up reconstruction of the complete kernel tree is an action only taken by the | ||
| 8147 | Yocto Project team during an active development cycle. | ||
| 8148 | When you create a clone of the kernel Git repository, you are simply making it | ||
| 8149 | efficiently available for building and development. | ||
| 8150 | </div><p> | ||
| 8151 | </p><p> | ||
| 8152 | The following steps describe what happens when the Yocto Project Team constructs | ||
| 8153 | the Yocto Project kernel source Git repository (or tree) found at | ||
| 8154 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a> given the | ||
| 8155 | introduction of a new top-level kernel feature or BSP. | ||
| 8156 | These are the actions that effectively create the tree | ||
| 8157 | that includes the new feature, patch or BSP: | ||
| 8158 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A top-level kernel feature is passed to the kernel build subsystem. | ||
| 8159 | Normally, this feature is a BSP for a particular kernel type.</p></li><li class="listitem"><p>The file that describes the top-level feature is located by searching | ||
| 8160 | these system directories: | ||
| 8161 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The in-tree kernel-cache directories, which are located | ||
| 8162 | in <code class="filename">meta/cfg/kernel-cache</code></p></li><li class="listitem"><p>Areas pointed to by <code class="filename">SRC_URI</code> statements | ||
| 8163 | found in recipes</p></li></ul></div><p> | ||
| 8164 | For a typical build, the target of the search is a | ||
| 8165 | feature description in an <code class="filename">.scc</code> file | ||
| 8166 | whose name follows this format: | ||
| 8167 | </p><pre class="literallayout"> | ||
| 8168 | <bsp_name>-<kernel_type>.scc | ||
| 8169 | </pre><p> | ||
| 8170 | </p></li><li class="listitem"><p>Once located, the feature description is either compiled into a simple script | ||
| 8171 | of actions, or into an existing equivalent script that is already part of the | ||
| 8172 | shipped kernel.</p></li><li class="listitem"><p>Extra features are appended to the top-level feature description. | ||
| 8173 | These features can come from the | ||
| 8174 | <a class="link" href="#var-KERNEL_FEATURES" target="_top"><code class="filename">KERNEL_FEATURES</code></a> | ||
| 8175 | variable in recipes.</p></li><li class="listitem"><p>Each extra feature is located, compiled and appended to the script | ||
| 8176 | as described in step three.</p></li><li class="listitem"><p>The script is executed to produce a series of <code class="filename">meta-*</code> | ||
| 8177 | directories. | ||
| 8178 | These directories are descriptions of all the branches, tags, patches and configurations that | ||
| 8179 | need to be applied to the base Git repository to completely create the | ||
| 8180 | source (build) branch for the new BSP or feature.</p></li><li class="listitem"><p>The base repository is cloned, and the actions | ||
| 8181 | listed in the <code class="filename">meta-*</code> directories are applied to the | ||
| 8182 | tree.</p></li><li class="listitem"><p>The Git repository is left with the desired branch checked out and any | ||
| 8183 | required branching, patching and tagging has been performed.</p></li></ol></div><p> | ||
| 8184 | </p><p> | ||
| 8185 | The kernel tree is now ready for developer consumption to be locally cloned, | ||
| 8186 | configured, and built into a Yocto Project kernel specific to some target hardware. | ||
| 8187 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The generated <code class="filename">meta-*</code> directories add to the kernel | ||
| 8188 | as shipped with the Yocto Project release. | ||
| 8189 | Any add-ons and configuration data are applied to the end of an existing branch. | ||
| 8190 | The full repository generation that is found in the | ||
| 8191 | official Yocto Project kernel repositories at | ||
| 8192 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a> | ||
| 8193 | is the combination of all supported boards and configurations.</p><p>The technique the Yocto Project team uses is flexible and allows for seamless | ||
| 8194 | blending of an immutable history with additional patches specific to a | ||
| 8195 | deployment. | ||
| 8196 | Any additions to the kernel become an integrated part of the branches.</p></div><p> | ||
| 8197 | </p></div><div class="section" title="3.3. Build Strategy"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="build-strategy"></a>3.3. Build Strategy</h2></div></div></div><p> | ||
| 8198 | Once a local Git repository of the Yocto Project kernel exists on a development system, | ||
| 8199 | you can consider the compilation phase of kernel development - building a kernel image. | ||
| 8200 | Some prerequisites exist that are validated by the build process before compilation | ||
| 8201 | starts: | ||
| 8202 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">SRC_URI</code> points to the kernel Git | ||
| 8203 | repository.</p></li><li class="listitem"><p>A BSP build branch exists. | ||
| 8204 | This branch has the following form: | ||
| 8205 | </p><pre class="literallayout"> | ||
| 8206 | <kernel_type>/<bsp_name> | ||
| 8207 | </pre></li></ul></div><p> | ||
| 8208 | The OpenEmbedded build system makes sure these conditions exist before attempting compilation. | ||
| 8209 | Other means, however, do exist, such as as bootstrapping a BSP, see | ||
| 8210 | the "<a class="link" href="#workflow-examples" title="3.4. Workflow Examples">Workflow Examples</a>". | ||
| 8211 | </p><p> | ||
| 8212 | Before building a kernel, the build process verifies the tree | ||
| 8213 | and configures the kernel by processing all of the | ||
| 8214 | configuration "fragments" specified by feature descriptions in the <code class="filename">.scc</code> | ||
| 8215 | files. | ||
| 8216 | As the features are compiled, associated kernel configuration fragments are noted | ||
| 8217 | and recorded in the <code class="filename">meta-*</code> series of directories in their compilation order. | ||
| 8218 | The fragments are migrated, pre-processed and passed to the Linux Kernel | ||
| 8219 | Configuration subsystem (<code class="filename">lkc</code>) as raw input in the form | ||
| 8220 | of a <code class="filename">.config</code> file. | ||
| 8221 | The <code class="filename">lkc</code> uses its own internal dependency constraints to do the final | ||
| 8222 | processing of that information and generates the final <code class="filename">.config</code> file | ||
| 8223 | that is used during compilation. | ||
| 8224 | </p><p> | ||
| 8225 | Using the board's architecture and other relevant values from the board's template, | ||
| 8226 | kernel compilation is started and a kernel image is produced. | ||
| 8227 | </p><p> | ||
| 8228 | The other thing that you notice once you configure a kernel is that | ||
| 8229 | the build process generates a build tree that is separate from your kernel's local Git | ||
| 8230 | source repository tree. | ||
| 8231 | This build tree has a name that uses the following form, where | ||
| 8232 | <code class="filename">${MACHINE}</code> is the metadata name of the machine (BSP) and "kernel_type" is one | ||
| 8233 | of the Yocto Project supported kernel types (e.g. "standard"): | ||
| 8234 | </p><pre class="literallayout"> | ||
| 8235 | linux-${MACHINE}-<kernel_type>-build | ||
| 8236 | </pre><p> | ||
| 8237 | </p><p> | ||
| 8238 | The existing support in the <code class="filename">kernel.org</code> tree achieves this | ||
| 8239 | default functionality. | ||
| 8240 | </p><p> | ||
| 8241 | This behavior means that all the generated files for a particular machine or BSP are now in | ||
| 8242 | the build tree directory. | ||
| 8243 | The files include the final <code class="filename">.config</code> file, all the <code class="filename">.o</code> | ||
| 8244 | files, the <code class="filename">.a</code> files, and so forth. | ||
| 8245 | Since each machine or BSP has its own separate build directory in its own separate branch | ||
| 8246 | of the Git repository, you can easily switch between different builds. | ||
| 8247 | </p></div><div class="section" title="3.4. Workflow Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="workflow-examples"></a>3.4. Workflow Examples</h2></div></div></div><p> | ||
| 8248 | As previously noted, the Yocto Project kernel has built-in Git integration. | ||
| 8249 | However, these utilities are not the only way to work with the kernel repository. | ||
| 8250 | The Yocto Project has not made changes to Git or to other tools that | ||
| 8251 | would invalidate alternate workflows. | ||
| 8252 | Additionally, the way the kernel repository is constructed results in using | ||
| 8253 | only core Git functionality, thus allowing any number of tools or front ends to use the | ||
| 8254 | resulting tree. | ||
| 8255 | </p><p> | ||
| 8256 | This section contains several workflow examples. | ||
| 8257 | Many of the examples use Git commands. | ||
| 8258 | You can find Git documentation at | ||
| 8259 | <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. | ||
| 8260 | You can find a simple overview of using Git with the Yocto Project in the | ||
| 8261 | "<a class="link" href="#git" target="_top">Git</a>" | ||
| 8262 | section of the Yocto Project Development Manual. | ||
| 8263 | </p><div class="section" title="3.4.1. Change Inspection: Changes/Commits"><div class="titlepage"><div><div><h3 class="title"><a id="change-inspection-kernel-changes-commits"></a>3.4.1. Change Inspection: Changes/Commits</h3></div></div></div><p> | ||
| 8264 | A common question when working with a kernel is: | ||
| 8265 | "What changes have been applied to this tree?" | ||
| 8266 | </p><p> | ||
| 8267 | In projects that have a collection of directories that | ||
| 8268 | contain patches to the kernel, it is possible to inspect or "grep" the contents | ||
| 8269 | of the directories to get a general feel for the changes. | ||
| 8270 | This sort of patch inspection is not an efficient way to determine what has been | ||
| 8271 | done to the kernel. | ||
| 8272 | The reason it is inefficient is because there are many optional patches that are | ||
| 8273 | selected based on the kernel type and the feature description. | ||
| 8274 | Additionally, patches could exist in directories that are not included in the search. | ||
| 8275 | </p><p> | ||
| 8276 | A more efficient way to determine what has changed in the branch is to use | ||
| 8277 | Git and inspect or search the kernel tree. | ||
| 8278 | This method gives you a full view of not only the source code modifications, | ||
| 8279 | but also provides the reasons for the changes. | ||
| 8280 | </p><div class="section" title="3.4.1.1. What Changed in a Kernel?"><div class="titlepage"><div><div><h4 class="title"><a id="what-changed-in-a-kernel"></a>3.4.1.1. What Changed in a Kernel?</h4></div></div></div><p> | ||
| 8281 | Following are a few examples that show how to use Git commands to examine changes. | ||
| 8282 | Because Git repositories in the Yocto Project do not break existing Git | ||
| 8283 | functionality, and because there exists many permutations of these types of | ||
| 8284 | Git commands, many methods exist by which you can discover changes. | ||
| 8285 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8286 | In the following examples, unless you provide a commit range, | ||
| 8287 | <code class="filename">kernel.org</code> history is blended with Yocto Project | ||
| 8288 | kernel changes. | ||
| 8289 | You can form ranges by using branch names from the kernel tree as the | ||
| 8290 | upper and lower commit markers with the Git commands. | ||
| 8291 | You can see the branch names through the web interface to the | ||
| 8292 | Yocto Project source repositories at | ||
| 8293 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. | ||
| 8294 | For example, the branch names for the <code class="filename">linux-yocto-3.4</code> | ||
| 8295 | kernel repository can be seen at | ||
| 8296 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads</a>. | ||
| 8297 | </div><p> | ||
| 8298 | To see a full range of the changes, use the | ||
| 8299 | <code class="filename">git whatchanged</code> command and specify a commit range | ||
| 8300 | for the branch (<code class="filename"><commit>..<commit></code>). | ||
| 8301 | </p><p> | ||
| 8302 | Here is an example that looks at what has changed in the | ||
| 8303 | <code class="filename">emenlow</code> branch of the | ||
| 8304 | <code class="filename">linux-yocto-3.4</code> kernel. | ||
| 8305 | The lower commit range is the commit associated with the | ||
| 8306 | <code class="filename">standard/base</code> branch, while | ||
| 8307 | the upper commit range is the commit associated with the | ||
| 8308 | <code class="filename">standard/emenlow</code> branch. | ||
| 8309 | </p><pre class="literallayout"> | ||
| 8310 | $ git whatchanged origin/standard/base..origin/standard/emenlow | ||
| 8311 | </pre><p> | ||
| 8312 | </p><p> | ||
| 8313 | To see a summary of changes use the <code class="filename">git log</code> command. | ||
| 8314 | Here is an example using the same branches: | ||
| 8315 | </p><pre class="literallayout"> | ||
| 8316 | $ git log --oneline origin/standard/base..origin/standard/emenlow | ||
| 8317 | </pre><p> | ||
| 8318 | The <code class="filename">git log</code> output might be more useful than | ||
| 8319 | the <code class="filename">git whatchanged</code> as you get | ||
| 8320 | a short, one-line summary of each change and not the entire commit. | ||
| 8321 | </p><p> | ||
| 8322 | If you want to see code differences associated with all the changes, use | ||
| 8323 | the <code class="filename">git diff</code> command. | ||
| 8324 | Here is an example: | ||
| 8325 | </p><pre class="literallayout"> | ||
| 8326 | $ git diff origin/standard/base..origin/standard/emenlow | ||
| 8327 | </pre><p> | ||
| 8328 | </p><p> | ||
| 8329 | You can see the commit log messages and the text differences using the | ||
| 8330 | <code class="filename">git show</code> command: | ||
| 8331 | Here is an example: | ||
| 8332 | </p><pre class="literallayout"> | ||
| 8333 | $ git show origin/standard/base..origin/standard/emenlow | ||
| 8334 | </pre><p> | ||
| 8335 | </p><p> | ||
| 8336 | You can create individual patches for each change by using the | ||
| 8337 | <code class="filename">git format-patch</code> command. | ||
| 8338 | Here is an example that that creates patch files for each commit and | ||
| 8339 | places them in your <code class="filename">Documents</code> directory: | ||
| 8340 | </p><pre class="literallayout"> | ||
| 8341 | $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow | ||
| 8342 | </pre><p> | ||
| 8343 | </p></div><div class="section" title="3.4.1.2. Show a Particular Feature or Branch Change"><div class="titlepage"><div><div><h4 class="title"><a id="show-a-particular-feature-or-branch-change"></a>3.4.1.2. Show a Particular Feature or Branch Change</h4></div></div></div><p> | ||
| 8344 | Developers use tags in the Yocto Project kernel tree to divide changes for significant | ||
| 8345 | features or branches. | ||
| 8346 | Once you know a particular tag, you can use Git commands | ||
| 8347 | to show changes associated with the tag and find the branches that contain | ||
| 8348 | the feature. | ||
| 8349 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8350 | Because BSP branch, <code class="filename">kernel.org</code>, and feature tags are all | ||
| 8351 | present, there could be many tags. | ||
| 8352 | </div><p> | ||
| 8353 | The <code class="filename">git show <tag></code> command shows changes that are tagged by | ||
| 8354 | a feature. | ||
| 8355 | Here is an example that shows changes tagged by the <code class="filename">systemtap</code> | ||
| 8356 | feature: | ||
| 8357 | </p><pre class="literallayout"> | ||
| 8358 | $ git show systemtap | ||
| 8359 | </pre><p> | ||
| 8360 | You can use the <code class="filename">git branch --contains <tag></code> command | ||
| 8361 | to show the branches that contain a particular feature. | ||
| 8362 | This command shows the branches that contain the <code class="filename">systemtap</code> | ||
| 8363 | feature: | ||
| 8364 | </p><pre class="literallayout"> | ||
| 8365 | $ git branch --contains systemtap | ||
| 8366 | </pre><p> | ||
| 8367 | </p><p> | ||
| 8368 | You can use many other comparisons to isolate BSP and kernel changes. | ||
| 8369 | For example, you can compare against <code class="filename">kernel.org</code> tags | ||
| 8370 | such as the <code class="filename">v3.4</code> tag. | ||
| 8371 | </p></div></div><div class="section" title="3.4.2. Development: Saving Kernel Modifications"><div class="titlepage"><div><div><h3 class="title"><a id="development-saving-kernel-modifications"></a>3.4.2. Development: Saving Kernel Modifications</h3></div></div></div><p> | ||
| 8372 | Another common operation is to build a BSP supplied by the Yocto Project, make some | ||
| 8373 | changes, rebuild, and then test. | ||
| 8374 | Those local changes often need to be exported, shared or otherwise maintained. | ||
| 8375 | </p><p> | ||
| 8376 | Since the Yocto Project kernel source tree is backed by Git, this activity is | ||
| 8377 | much easier as compared to with previous releases. | ||
| 8378 | Because Git tracks file modifications, additions and deletions, it is easy | ||
| 8379 | to modify the code and later realize that you need to save the changes. | ||
| 8380 | It is also easy to determine what has changed. | ||
| 8381 | This method also provides many tools to commit, undo and export those modifications. | ||
| 8382 | </p><p> | ||
| 8383 | This section and its sub-sections, describe general application of Git's | ||
| 8384 | <code class="filename">push</code> and <code class="filename">pull</code> commands, which are used to | ||
| 8385 | get your changes upstream or source your code from an upstream repository. | ||
| 8386 | The Yocto Project provides scripts that help you work in a collaborative development | ||
| 8387 | environment. | ||
| 8388 | For information on these scripts, see the | ||
| 8389 | "<a class="link" href="#pushing-a-change-upstream" target="_top">Using Scripts to Push a Change | ||
| 8390 | Upstream and Request a Pull</a>" and | ||
| 8391 | "<a class="link" href="#submitting-a-patch" target="_top">Using Email to Submit a Patch</a>" | ||
| 8392 | sections in the Yocto Project Development Manual. | ||
| 8393 | </p><p> | ||
| 8394 | There are many ways to save kernel modifications. | ||
| 8395 | The technique employed | ||
| 8396 | depends on the destination for the patches: | ||
| 8397 | |||
| 8398 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bulk storage</p></li><li class="listitem"><p>Internal sharing either through patches or by using Git</p></li><li class="listitem"><p>External submissions</p></li><li class="listitem"><p>Exporting for integration into another Source Code | ||
| 8399 | Manager (SCM)</p></li></ul></div><p> | ||
| 8400 | </p><p> | ||
| 8401 | Because of the following list of issues, the destination of the patches also influences | ||
| 8402 | the method for gathering them: | ||
| 8403 | |||
| 8404 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bisectability</p></li><li class="listitem"><p>Commit headers</p></li><li class="listitem"><p>Division of subsystems for separate submission or review</p></li></ul></div><p> | ||
| 8405 | </p><div class="section" title="3.4.2.1. Bulk Export"><div class="titlepage"><div><div><h4 class="title"><a id="bulk-export"></a>3.4.2.1. Bulk Export</h4></div></div></div><p> | ||
| 8406 | This section describes how you can "bulk" export changes that have not | ||
| 8407 | been separated or divided. | ||
| 8408 | This situation works well when you are simply storing patches outside of the kernel | ||
| 8409 | source repository, either permanently or temporarily, and you are not committing | ||
| 8410 | incremental changes during development. | ||
| 8411 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8412 | This technique is not appropriate for full integration of upstream submission | ||
| 8413 | because changes are not properly divided and do not provide an avenue for per-change | ||
| 8414 | commit messages. | ||
| 8415 | Therefore, this example assumes that changes have not been committed incrementally | ||
| 8416 | during development and that you simply must gather and export them. | ||
| 8417 | </div><p> | ||
| 8418 | </p><pre class="literallayout"> | ||
| 8419 | # bulk export of ALL modifications without separation or division | ||
| 8420 | # of the changes | ||
| 8421 | |||
| 8422 | $ git add . | ||
| 8423 | $ git commit -s -a -m <msg> | ||
| 8424 | or | ||
| 8425 | $ git commit -s -a # and interact with $EDITOR | ||
| 8426 | </pre><p> | ||
| 8427 | </p><p> | ||
| 8428 | The previous operations capture all the local changes in the project source | ||
| 8429 | tree in a single Git commit. | ||
| 8430 | And, that commit is also stored in the project's source tree. | ||
| 8431 | </p><p> | ||
| 8432 | Once the changes are exported, you can restore them manually using a template | ||
| 8433 | or through integration with the <code class="filename">default_kernel</code>. | ||
| 8434 | </p></div><div class="section" title="3.4.2.2. Incremental/Planned Sharing"><div class="titlepage"><div><div><h4 class="title"><a id="incremental-planned-sharing"></a>3.4.2.2. Incremental/Planned Sharing</h4></div></div></div><p> | ||
| 8435 | This section describes how to save modifications when you are making incremental | ||
| 8436 | commits or practicing planned sharing. | ||
| 8437 | The examples in this section assume that you have incrementally committed | ||
| 8438 | changes to the tree during development and now need to export them. | ||
| 8439 | The sections that follow | ||
| 8440 | describe how you can export your changes internally through either patches or by | ||
| 8441 | using Git commands. | ||
| 8442 | </p><p> | ||
| 8443 | During development, the following commands are of interest. | ||
| 8444 | For full Git documentation, refer to the Git documentation at | ||
| 8445 | <a class="ulink" href="http://github.com" target="_top">http://github.com</a>. | ||
| 8446 | |||
| 8447 | </p><pre class="literallayout"> | ||
| 8448 | # edit a file | ||
| 8449 | $ vi <path>/file | ||
| 8450 | # stage the change | ||
| 8451 | $ git add <path>/file | ||
| 8452 | # commit the change | ||
| 8453 | $ git commit -s | ||
| 8454 | # remove a file | ||
| 8455 | $ git rm <path>/file | ||
| 8456 | # commit the change | ||
| 8457 | $ git commit -s | ||
| 8458 | |||
| 8459 | ... etc. | ||
| 8460 | </pre><p> | ||
| 8461 | </p><p> | ||
| 8462 | Distributed development with Git is possible when you use a universally | ||
| 8463 | agreed-upon unique commit identifier (set by the creator of the commit) that maps to a | ||
| 8464 | specific change set with a specific parent. | ||
| 8465 | This identifier is created for you when | ||
| 8466 | you create a commit, and is re-created when you amend, alter or re-apply | ||
| 8467 | a commit. | ||
| 8468 | As an individual in isolation, this is of no interest. | ||
| 8469 | However, if you | ||
| 8470 | intend to share your tree with normal Git <code class="filename">push</code> and | ||
| 8471 | <code class="filename">pull</code> operations for | ||
| 8472 | distributed development, you should consider the ramifications of changing a | ||
| 8473 | commit that you have already shared with others. | ||
| 8474 | </p><p> | ||
| 8475 | Assuming that the changes have not been pushed upstream, or pulled into | ||
| 8476 | another repository, you can update both the commit content and commit messages | ||
| 8477 | associated with development by using the following commands: | ||
| 8478 | |||
| 8479 | </p><pre class="literallayout"> | ||
| 8480 | $ Git add <path>/file | ||
| 8481 | $ Git commit --amend | ||
| 8482 | $ Git rebase or Git rebase -i | ||
| 8483 | </pre><p> | ||
| 8484 | </p><p> | ||
| 8485 | Again, assuming that the changes have not been pushed upstream, and that | ||
| 8486 | no pending works-in-progress exist (use <code class="filename">git status</code> to check), then | ||
| 8487 | you can revert (undo) commits by using the following commands: | ||
| 8488 | |||
| 8489 | </p><pre class="literallayout"> | ||
| 8490 | # remove the commit, update working tree and remove all | ||
| 8491 | # traces of the change | ||
| 8492 | $ git reset --hard HEAD^ | ||
| 8493 | # remove the commit, but leave the files changed and staged for re-commit | ||
| 8494 | $ git reset --soft HEAD^ | ||
| 8495 | # remove the commit, leave file change, but not staged for commit | ||
| 8496 | $ git reset --mixed HEAD^ | ||
| 8497 | </pre><p> | ||
| 8498 | </p><p> | ||
| 8499 | You can create branches, "cherry-pick" changes, or perform any number of Git | ||
| 8500 | operations until the commits are in good order for pushing upstream | ||
| 8501 | or for pull requests. | ||
| 8502 | After a <code class="filename">push</code> or <code class="filename">pull</code> command, | ||
| 8503 | commits are normally considered | ||
| 8504 | "permanent" and you should not modify them. | ||
| 8505 | If the commits need to be changed, you can incrementally do so with new commits. | ||
| 8506 | These practices follow standard Git workflow and the <code class="filename">kernel.org</code> best | ||
| 8507 | practices, which is recommended. | ||
| 8508 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8509 | It is recommended to tag or branch before adding changes to a Yocto Project | ||
| 8510 | BSP or before creating a new one. | ||
| 8511 | The reason for this recommendation is because the branch or tag provides a | ||
| 8512 | reference point to facilitate locating and exporting local changes. | ||
| 8513 | </div><p> | ||
| 8514 | </p><div class="section" title="3.4.2.2.1. Exporting Changes Internally by Using Patches"><div class="titlepage"><div><div><h5 class="title"><a id="export-internally-via-patches"></a>3.4.2.2.1. Exporting Changes Internally by Using Patches</h5></div></div></div><p> | ||
| 8515 | This section describes how you can extract committed changes from a working directory | ||
| 8516 | by exporting them as patches. | ||
| 8517 | Once the changes have been extracted, you can use the patches for upstream submission, | ||
| 8518 | place them in a Yocto Project template for automatic kernel patching, | ||
| 8519 | or apply them in many other common uses. | ||
| 8520 | </p><p> | ||
| 8521 | This example shows how to create a directory with sequentially numbered patches. | ||
| 8522 | Once the directory is created, you can apply it to a repository using the | ||
| 8523 | <code class="filename">git am</code> command to reproduce the original commit and all | ||
| 8524 | the related information such as author, date, commit log, and so forth. | ||
| 8525 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8526 | The new commit identifiers (ID) will be generated upon re-application. | ||
| 8527 | This action reflects that the commit is now applied to an underlying commit | ||
| 8528 | with a different ID. | ||
| 8529 | </div><p> | ||
| 8530 | </p><pre class="literallayout"> | ||
| 8531 | # <first-commit> can be a tag if one was created before development | ||
| 8532 | # began. It can also be the parent branch if a branch was created | ||
| 8533 | # before development began. | ||
| 8534 | |||
| 8535 | $ git format-patch -o <dir> <first commit>..<last commit> | ||
| 8536 | </pre><p> | ||
| 8537 | </p><p> | ||
| 8538 | In other words: | ||
| 8539 | </p><pre class="literallayout"> | ||
| 8540 | # Identify commits of interest. | ||
| 8541 | |||
| 8542 | # If the tree was tagged before development | ||
| 8543 | $ git format-patch -o <save dir> <tag> | ||
| 8544 | |||
| 8545 | # If no tags are available | ||
| 8546 | $ git format-patch -o <save dir> HEAD^ # last commit | ||
| 8547 | $ git format-patch -o <save dir> HEAD^^ # last 2 commits | ||
| 8548 | $ git whatchanged # identify last commit | ||
| 8549 | $ git format-patch -o <save dir> <commit id> | ||
| 8550 | $ git format-patch -o <save dir> <rev-list> | ||
| 8551 | </pre><p> | ||
| 8552 | </p></div><div class="section" title="3.4.2.2.2. Exporting Changes Internally by Using Git"><div class="titlepage"><div><div><h5 class="title"><a id="export-internally-via-git"></a>3.4.2.2.2. Exporting Changes Internally by Using Git</h5></div></div></div><p> | ||
| 8553 | This section describes how you can export changes from a working directory | ||
| 8554 | by pushing the changes into a master repository or by making a pull request. | ||
| 8555 | Once you have pushed the changes to the master repository, you can then | ||
| 8556 | pull those same changes into a new kernel build at a later time. | ||
| 8557 | </p><p> | ||
| 8558 | Use this command form to push the changes: | ||
| 8559 | </p><pre class="literallayout"> | ||
| 8560 | $ git push ssh://<master_server>/<path_to_repo> | ||
| 8561 | <local_branch>:<remote_branch> | ||
| 8562 | </pre><p> | ||
| 8563 | </p><p> | ||
| 8564 | For example, the following command pushes the changes from your local branch | ||
| 8565 | <code class="filename">yocto/standard/common-pc/base</code> to the remote branch with the same name | ||
| 8566 | in the master repository <code class="filename">//git.mycompany.com/pub/git/kernel-3.4</code>. | ||
| 8567 | </p><pre class="literallayout"> | ||
| 8568 | $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ | ||
| 8569 | yocto/standard/common-pc/base:yocto/standard/common-pc/base | ||
| 8570 | </pre><p> | ||
| 8571 | </p><p> | ||
| 8572 | A pull request entails using the <code class="filename">git request-pull</code> command to compose | ||
| 8573 | an email to the | ||
| 8574 | maintainer requesting that a branch be pulled into the master repository, see | ||
| 8575 | <a class="ulink" href="http://github.com/guides/pull-requests" target="_top">http://github.com/guides/pull-requests</a> for an example. | ||
| 8576 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8577 | Other commands such as <code class="filename">git stash</code> or branching can also be used to save | ||
| 8578 | changes, but are not covered in this document. | ||
| 8579 | </div><p> | ||
| 8580 | </p></div></div><div class="section" title="3.4.2.3. Exporting Changes for External (Upstream) Submission"><div class="titlepage"><div><div><h4 class="title"><a id="export-for-external-upstream-submission"></a>3.4.2.3. Exporting Changes for External (Upstream) Submission</h4></div></div></div><p> | ||
| 8581 | This section describes how to export changes for external upstream submission. | ||
| 8582 | If the patch series is large or the maintainer prefers to pull | ||
| 8583 | changes, you can submit these changes by using a pull request. | ||
| 8584 | However, it is common to send patches as an email series. | ||
| 8585 | This method allows easy review and integration of the changes. | ||
| 8586 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8587 | Before sending patches for review be sure you understand the | ||
| 8588 | community standards for submitting and documenting changes and follow their best practices. | ||
| 8589 | For example, kernel patches should follow standards such as: | ||
| 8590 | <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | ||
| 8591 | <a class="ulink" href="http://linux.yyz.us/patch-format.html" target="_top">http://linux.yyz.us/patch-format.html</a></p></li><li class="listitem"><p>Documentation/SubmittingPatches (in any linux | ||
| 8592 | kernel source tree)</p></li></ul></div></div><p> | ||
| 8593 | </p><p> | ||
| 8594 | The messages used to commit changes are a large part of these standards. | ||
| 8595 | Consequently, be sure that the headers for each commit have the required information. | ||
| 8596 | For information on how to follow the Yocto Project commit message standards, see the | ||
| 8597 | "<a class="link" href="#how-to-submit-a-change" target="_top">How to Submit a | ||
| 8598 | Change</a>" section in the Yocto Project Development Manual. | ||
| 8599 | </p><p> | ||
| 8600 | If the initial commits were not properly documented or do not meet those standards, | ||
| 8601 | you can re-base by using the <code class="filename">git rebase -i</code> command to | ||
| 8602 | manipulate the commits and | ||
| 8603 | get them into the required format. | ||
| 8604 | Other techniques such as branching and cherry-picking commits are also viable options. | ||
| 8605 | </p><p> | ||
| 8606 | Once you complete the commits, you can generate the email that sends the patches | ||
| 8607 | to the maintainer(s) or lists that review and integrate changes. | ||
| 8608 | The command <code class="filename">git send-email</code> is commonly used to ensure | ||
| 8609 | that patches are properly | ||
| 8610 | formatted for easy application and avoid mailer-induced patch damage. | ||
| 8611 | </p><p> | ||
| 8612 | The following is an example of dumping patches for external submission: | ||
| 8613 | </p><pre class="literallayout"> | ||
| 8614 | # dump the last 4 commits | ||
| 8615 | $ git format-patch --thread -n -o ~/rr/ HEAD^^^^ | ||
| 8616 | $ git send-email --compose --subject '[RFC 0/N] <patch series summary>' \ | ||
| 8617 | --to foo@yoctoproject.org --to bar@yoctoproject.org \ | ||
| 8618 | --cc list@yoctoproject.org ~/rr | ||
| 8619 | # the editor is invoked for the 0/N patch, and when complete the entire | ||
| 8620 | # series is sent via email for review | ||
| 8621 | </pre><p> | ||
| 8622 | </p></div><div class="section" title="3.4.2.4. Exporting Changes for Import into Another SCM"><div class="titlepage"><div><div><h4 class="title"><a id="export-for-import-into-other-scm"></a>3.4.2.4. Exporting Changes for Import into Another SCM</h4></div></div></div><p> | ||
| 8623 | When you want to export changes for import into another | ||
| 8624 | Source Code Manager (SCM), you can use any of the previously discussed | ||
| 8625 | techniques. | ||
| 8626 | However, if the patches are manually applied to a secondary tree and then | ||
| 8627 | that tree is checked into the SCM, you can lose change information such as | ||
| 8628 | commit logs. | ||
| 8629 | This process is not recommended. | ||
| 8630 | </p><p> | ||
| 8631 | Many SCMs can directly import Git commits, or can translate Git patches so that | ||
| 8632 | information is not lost. | ||
| 8633 | Those facilities are SCM-dependent and you should use them whenever possible. | ||
| 8634 | </p></div></div><div class="section" title="3.4.3. Working with the Yocto Project Kernel in Another SCM"><div class="titlepage"><div><div><h3 class="title"><a id="scm-working-with-the-yocto-project-kernel-in-another-scm"></a>3.4.3. Working with the Yocto Project Kernel in Another SCM</h3></div></div></div><p> | ||
| 8635 | This section describes kernel development in an SCM other than Git, | ||
| 8636 | which is not the same as exporting changes to another SCM described earlier. | ||
| 8637 | For this scenario, you use the OpenEmbedded build system to | ||
| 8638 | develop the kernel in a different SCM. | ||
| 8639 | The following must be true for you to accomplish this: | ||
| 8640 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The delivered Yocto Project kernel must be exported into the second | ||
| 8641 | SCM.</p></li><li class="listitem"><p>Development must be exported from that secondary SCM into a | ||
| 8642 | format that can be used by the OpenEmbedded build system.</p></li></ul></div><p> | ||
| 8643 | </p><div class="section" title="3.4.3.1. Exporting the Delivered Kernel to the SCM"><div class="titlepage"><div><div><h4 class="title"><a id="exporting-delivered-kernel-to-scm"></a>3.4.3.1. Exporting the Delivered Kernel to the SCM</h4></div></div></div><p> | ||
| 8644 | Depending on the SCM, it might be possible to export the entire Yocto Project | ||
| 8645 | kernel Git repository, branches and all, into a new environment. | ||
| 8646 | This method is preferred because it has the most flexibility and potential to maintain | ||
| 8647 | the meta data associated with each commit. | ||
| 8648 | </p><p> | ||
| 8649 | When a direct import mechanism is not available, it is still possible to | ||
| 8650 | export a branch (or series of branches) and check them into a new repository. | ||
| 8651 | </p><p> | ||
| 8652 | The following commands illustrate some of the steps you could use to | ||
| 8653 | import the <code class="filename">yocto/standard/common-pc/base</code> | ||
| 8654 | kernel into a secondary SCM: | ||
| 8655 | </p><pre class="literallayout"> | ||
| 8656 | $ git checkout yocto/standard/common-pc/base | ||
| 8657 | $ cd .. ; echo linux/.git > .cvsignore | ||
| 8658 | $ cvs import -m "initial import" linux MY_COMPANY start | ||
| 8659 | </pre><p> | ||
| 8660 | </p><p> | ||
| 8661 | You could now relocate the CVS repository and use it in a centralized manner. | ||
| 8662 | </p><p> | ||
| 8663 | The following commands illustrate how you can condense and merge two BSPs into a | ||
| 8664 | second SCM: | ||
| 8665 | </p><pre class="literallayout"> | ||
| 8666 | $ git checkout yocto/standard/common-pc/base | ||
| 8667 | $ git merge yocto/standard/common-pc-64/base | ||
| 8668 | # resolve any conflicts and commit them | ||
| 8669 | $ cd .. ; echo linux/.git > .cvsignore | ||
| 8670 | $ cvs import -m "initial import" linux MY_COMPANY start | ||
| 8671 | </pre><p> | ||
| 8672 | </p></div><div class="section" title="3.4.3.2. Importing Changes for the Build"><div class="titlepage"><div><div><h4 class="title"><a id="importing-changes-for-build"></a>3.4.3.2. Importing Changes for the Build</h4></div></div></div><p> | ||
| 8673 | Once development has reached a suitable point in the second development | ||
| 8674 | environment, you need to export the changes as patches. | ||
| 8675 | To export them, place the changes in a recipe and | ||
| 8676 | automatically apply them to the kernel during patching. | ||
| 8677 | </p></div></div><div class="section" title="3.4.4. Creating a BSP Based on an Existing Similar BSP"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-creating"></a>3.4.4. Creating a BSP Based on an Existing Similar BSP</h3></div></div></div><p> | ||
| 8678 | This section overviews the process of creating a BSP based on an | ||
| 8679 | existing similar BSP. | ||
| 8680 | The information is introductory in nature and does not provide step-by-step examples. | ||
| 8681 | For detailed information on how to create a BSP given an existing similar BSP, see | ||
| 8682 | the "<a class="link" href="#dev-manual-bsp-appendix" target="_top">BSP Development | ||
| 8683 | Example</a>" appendix in the Yocto Project Development Manual, or see the | ||
| 8684 | <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another" target="_top">Transcript:_creating_one_generic_Atom_BSP_from_another</a> | ||
| 8685 | wiki page. | ||
| 8686 | </p><p> | ||
| 8687 | The basic steps you need to follow are: | ||
| 8688 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Make sure you have set up a local source directory:</em></span> | ||
| 8689 | You must create a local <a class="link" href="#source-directory" target="_top">source | ||
| 8690 | directory</a> by either creating a Git repository (recommended) or | ||
| 8691 | extracting a Yocto Project release tarball.</p></li><li class="listitem"><p><span class="emphasis"><em>Choose an existing BSP available with the Yocto Project:</em></span> | ||
| 8692 | Try to map your board features as closely to the features of a BSP that is | ||
| 8693 | already supported and exists in the Yocto Project. | ||
| 8694 | Starting with something as close as possible to your board makes developing | ||
| 8695 | your BSP easier. | ||
| 8696 | You can find all the BSPs that are supported and ship with the Yocto Project | ||
| 8697 | on the Yocto Project's Download page at | ||
| 8698 | <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">http://www.yoctoproject.org/download</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Be sure you have the Base BSP:</em></span> | ||
| 8699 | You need to either have a local Git repository of the base BSP set up or | ||
| 8700 | have downloaded and extracted the files from a release BSP tarball. | ||
| 8701 | Either method gives you access to the BSP source files.</p></li><li class="listitem"><p><span class="emphasis"><em>Make a copy of the existing BSP, thus isolating your new | ||
| 8702 | BSP work:</em></span> | ||
| 8703 | Copying the existing BSP file structure gives you a new area in which to work.</p></li><li class="listitem"><p><span class="emphasis"><em>Make configuration and recipe changes to your new BSP:</em></span> | ||
| 8704 | Configuration changes involve the files in the BSP's <code class="filename">conf</code> | ||
| 8705 | directory. | ||
| 8706 | Changes include creating a machine-specific configuration file and editing the | ||
| 8707 | <code class="filename">layer.conf</code> file. | ||
| 8708 | The configuration changes identify the kernel you will be using. | ||
| 8709 | Recipe changes include removing, modifying, or adding new recipe files that | ||
| 8710 | instruct the build process on what features to include in the image.</p></li><li class="listitem"><p><span class="emphasis"><em>Prepare for the build:</em></span> | ||
| 8711 | Before you actually initiate the build, you need to set up the build environment | ||
| 8712 | by sourcing the environment initialization script. | ||
| 8713 | After setting up the environment, you need to make some build configuration | ||
| 8714 | changes to the <code class="filename">local.conf</code> and <code class="filename">bblayers.conf</code> | ||
| 8715 | files.</p></li><li class="listitem"><p><span class="emphasis"><em>Build the image:</em></span> | ||
| 8716 | The OpenEmbedded build system uses BitBake to create the image. | ||
| 8717 | You need to decide on the type of image you are going to build (e.g. minimal, base, | ||
| 8718 | core, sato, and so forth) and then start the build using the <code class="filename">bitbake</code> | ||
| 8719 | command.</p></li></ol></div><p> | ||
| 8720 | </p></div><div class="section" title="3.4.5. "-dirty" String"><div class="titlepage"><div><div><h3 class="title"><a id="tip-dirty-string"></a>3.4.5. "-dirty" String</h3></div></div></div><p> | ||
| 8721 | If kernel images are being built with "-dirty" on the end of the version | ||
| 8722 | string, this simply means that modifications in the source | ||
| 8723 | directory have not been committed. | ||
| 8724 | </p><pre class="literallayout"> | ||
| 8725 | $ git status | ||
| 8726 | </pre><p> | ||
| 8727 | </p><p> | ||
| 8728 | You can use the above Git command to report modified, removed, or added files. | ||
| 8729 | You should commit those changes to the tree regardless of whether they will be saved, | ||
| 8730 | exported, or used. | ||
| 8731 | Once you commit the changes you need to rebuild the kernel. | ||
| 8732 | </p><p> | ||
| 8733 | To brute force pickup and commit all such pending changes, enter the following: | ||
| 8734 | </p><pre class="literallayout"> | ||
| 8735 | $ git add . | ||
| 8736 | $ git commit -s -a -m "getting rid of -dirty" | ||
| 8737 | </pre><p> | ||
| 8738 | </p><p> | ||
| 8739 | Next, rebuild the kernel. | ||
| 8740 | </p></div></div></div> | ||
| 8741 | |||
| 8742 | |||
| 8743 | |||
| 8744 | </div> | ||
| 8745 | |||
| 8746 | <table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/poky-title.png" align="left" width="100%" /></td></tr></table> | ||
| 8747 | |||
| 8748 | <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="poky-ref-manual"></a></h1></div><div><div class="authorgroup"> | ||
| 8749 | <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"> | ||
| 8750 | <span class="orgname">Linux Foundation<br /></span> | ||
| 8751 | </div><code class="email"><<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>></code></div> | ||
| 8752 | |||
| 8753 | </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1506919"></a> | ||
| 8754 | <p> | ||
| 8755 | Permission is granted to copy, distribute and/or modify this document under | ||
| 8756 | the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. | ||
| 8757 | </p> | ||
| 8758 | <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8759 | Due to production processes, there could be differences between the Yocto Project | ||
| 8760 | documentation bundled in the release tarball and the | ||
| 8761 | Yocto Project Reference Manual on | ||
| 8762 | the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. | ||
| 8763 | For the latest version of this manual, see the manual on the website. | ||
| 8764 | </div> | ||
| 8765 | </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> | ||
| 8766 | <tr><td align="left">Revision 4.0+git</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr> | ||
| 8767 | <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> | ||
| 8768 | <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> | ||
| 8769 | <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> | ||
| 8770 | <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> | ||
| 8771 | <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> | ||
| 8772 | </table></div></div></div><hr /></div> | ||
| 8773 | |||
| 8774 | |||
| 8775 | <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-welcome"></a>1.1. Introduction</h2></div></div></div><p> | ||
| 8776 | This manual provides reference information for the current release of the Yocto Project. | ||
| 8777 | The Yocto Project is an open-source collaboration project focused on embedded Linux | ||
| 8778 | developers. | ||
| 8779 | Amongst other things, the Yocto Project uses the OpenEmbedded build system, which | ||
| 8780 | is based on the Poky project, to construct complete Linux images. | ||
| 8781 | You can find complete introductory and getting started information on the Yocto Project | ||
| 8782 | by reading the | ||
| 8783 | Yocto Project Quick Start. | ||
| 8784 | For task-based information using the Yocto Project, see the | ||
| 8785 | Yocto Project Development Manual. | ||
| 8786 | You can also find lots of information on the Yocto Project on the | ||
| 8787 | <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>. | ||
| 8788 | </p></div><div class="section" title="1.2. Documentation Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div><p> | ||
| 8789 | This reference manual consists of the following: | ||
| 8790 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em> | ||
| 8791 | <a class="link" href="#usingpoky" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter | ||
| 8792 | provides an overview of the components that make up the Yocto Project | ||
| 8793 | followed by information about debugging images created in the Yocto Project. | ||
| 8794 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8795 | <a class="link" href="#technical-details" title="Chapter 3. Technical Details">Technical Details</a>:</em></span> | ||
| 8796 | This chapter describes fundamental Yocto Project components as well as an explanation | ||
| 8797 | behind how the Yocto Project uses shared state (sstate) cache to speed build time. | ||
| 8798 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8799 | <a class="link" href="#ref-structure" title="Chapter 4. Source Directory Structure">Directory Structure</a>:</em></span> | ||
| 8800 | This chapter describes the | ||
| 8801 | <a class="link" href="#source-directory" target="_top">source directory</a> created | ||
| 8802 | either by unpacking a released Yocto Project tarball on your host development system, | ||
| 8803 | or by cloning the upstream | ||
| 8804 | <a class="link" href="#poky" target="_top">Poky</a> Git repository. | ||
| 8805 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8806 | <a class="link" href="#ref-bitbake" title="Chapter 5. BitBake">BitBake</a>:</em></span> | ||
| 8807 | This chapter provides an overview of the BitBake tool and its role within | ||
| 8808 | the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8809 | <a class="link" href="#ref-classes" title="Chapter 6. Classes">Classes</a>:</em></span> | ||
| 8810 | This chapter describes the classes used in the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8811 | <a class="link" href="#ref-images" title="Chapter 7. Images">Images</a>:</em></span> | ||
| 8812 | This chapter describes the standard images that the Yocto Project supports. | ||
| 8813 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8814 | <a class="link" href="#ref-features" title="Chapter 8. Reference: Features">Features</a>:</em></span> | ||
| 8815 | This chapter describes mechanisms for creating distribution, machine, and image | ||
| 8816 | features during the build process using the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8817 | <a class="link" href="#ref-variables-glos" title="Chapter 9. Variables Glossary">Variables Glossary</a>:</em></span> | ||
| 8818 | This chapter presents most variables used by the OpenEmbedded build system, which | ||
| 8819 | using BitBake. | ||
| 8820 | Entries describe the function of the variable and how to apply them. | ||
| 8821 | </p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8822 | <a class="link" href="#ref-varlocality" title="Chapter 10. Variable Context">Variable Context</a>:</em></span> | ||
| 8823 | This chapter provides variable locality or context.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8824 | <a class="link" href="#faq" title="Chapter 11. FAQ">FAQ</a>:</em></span> | ||
| 8825 | This chapter provides answers for commonly asked questions in the Yocto Project | ||
| 8826 | development environment.</p></li><li class="listitem"><p><span class="emphasis"><em> | ||
| 8827 | <a class="link" href="#resources" title="Chapter 12. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span> | ||
| 8828 | This chapter provides guidance on how you can contribute back to the Yocto | ||
| 8829 | Project.</p></li></ul></div><p> | ||
| 8830 | </p></div><div class="section" title="1.3. System Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-requirements"></a>1.3. System Requirements</h2></div></div></div><p> | ||
| 8831 | For Yocto Project system requirements, see the | ||
| 8832 | <a class="link" href="#yp-resources" target="_top"> | ||
| 8833 | What You Need and How You Get It</a> section in the Yocto Project Quick Start. | ||
| 8834 | </p></div><div class="section" title="1.4. Obtaining the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div><p> | ||
| 8835 | The Yocto Project development team makes the Yocto Project available through a number | ||
| 8836 | of methods: | ||
| 8837 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through | ||
| 8838 | <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_top">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at | ||
| 8839 | <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_top">http://autobuilder.yoctoproject.org/nightly</a>. | ||
| 8840 | These builds include Yocto Project releases, meta-toolchain tarballs, and | ||
| 8841 | experimental builds.</p></li><li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases | ||
| 8842 | of the Yocto Project and supported BSPs at the | ||
| 8843 | <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>. | ||
| 8844 | Along with these downloads, you can find lots of other information at this site. | ||
| 8845 | </p></li></ul></div><p> | ||
| 8846 | </p></div><div class="section" title="1.5. Development Checkouts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div><p> | ||
| 8847 | Development using the Yocto Project requires a local | ||
| 8848 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 8849 | You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, | ||
| 8850 | or by cloning a copy of the upstream | ||
| 8851 | <a class="link" href="#poky" target="_top">Poky</a> Git repository. | ||
| 8852 | For information on both these methods, see the | ||
| 8853 | "<a class="link" href="#getting-setup" target="_top">Getting Setup</a>" | ||
| 8854 | section in the Yocto Project Development Manual. | ||
| 8855 | </p></div></div> | ||
| 8856 | |||
| 8857 | <div class="chapter" title="Chapter 2. Using the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd></dl></div><p> | ||
| 8858 | This chapter describes common usage for the Yocto Project. | ||
| 8859 | The information is introductory in nature as other manuals in the Yocto Project | ||
| 8860 | documentation set provide more details on how to use the Yocto Project. | ||
| 8861 | </p><div class="section" title="2.1. Running a Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div><p> | ||
| 8862 | You can find general information on how to build an image using the OpenEmbedded build | ||
| 8863 | system in the | ||
| 8864 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" | ||
| 8865 | section of the Yocto Project Quick Start. | ||
| 8866 | This section provides a summary of the build process and provides information | ||
| 8867 | for less obvious aspects of the build process. | ||
| 8868 | </p><div class="section" title="2.1.1. Build Overview"><div class="titlepage"><div><div><h3 class="title"><a id="build-overview"></a>2.1.1. Build Overview</h3></div></div></div><p> | ||
| 8869 | The first thing you need to do is set up the OpenEmbedded build environment by sourcing | ||
| 8870 | the environment setup script as follows: | ||
| 8871 | </p><pre class="literallayout"> | ||
| 8872 | $ source oe-init-build-env [build_dir] | ||
| 8873 | </pre><p> | ||
| 8874 | </p><p> | ||
| 8875 | The <code class="filename">build_dir</code> is optional and specifies the directory the | ||
| 8876 | OpenEmbedded build system uses for the build - | ||
| 8877 | the <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 8878 | If you do not specify a build directory it defaults to <code class="filename">build</code> | ||
| 8879 | in your current working directory. | ||
| 8880 | A common practice is to use a different build directory for different targets. | ||
| 8881 | For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code> | ||
| 8882 | target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target. | ||
| 8883 | See <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a> | ||
| 8884 | for more information on this script. | ||
| 8885 | </p><p> | ||
| 8886 | Once the build environment is set up, you can build a target using: | ||
| 8887 | </p><pre class="literallayout"> | ||
| 8888 | $ bitbake <target> | ||
| 8889 | </pre><p> | ||
| 8890 | </p><p> | ||
| 8891 | The <code class="filename">target</code> is the name of the recipe you want to build. | ||
| 8892 | Common targets are the images in <code class="filename">meta/recipes-core/images</code>, | ||
| 8893 | <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the | ||
| 8894 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 8895 | Or, the target can be the name of a recipe for a specific piece of software such as | ||
| 8896 | <span class="application">busybox</span>. | ||
| 8897 | For more details about the images the OpenEmbedded build system supports, see the | ||
| 8898 | "<a class="link" href="#ref-images" title="Chapter 7. Images">Images</a>" chapter. | ||
| 8899 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 8900 | Building an image without GNU Public License Version 3 (GPLv3) components is | ||
| 8901 | only supported for minimal and base images. | ||
| 8902 | See the "<a class="link" href="#ref-images" title="Chapter 7. Images">Images</a>" chapter for more information. | ||
| 8903 | </div></div><div class="section" title="2.1.2. Building an Image Using GPL Components"><div class="titlepage"><div><div><h3 class="title"><a id="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div><p> | ||
| 8904 | When building an image using GPL components, you need to maintain your original | ||
| 8905 | settings and not switch back and forth applying different versions of the GNU | ||
| 8906 | Public License. | ||
| 8907 | If you rebuild using different versions of GPL, dependency errors might occur | ||
| 8908 | due to some components not being rebuilt. | ||
| 8909 | </p></div></div><div class="section" title="2.2. Installing and Using the Result"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div><p> | ||
| 8910 | Once an image has been built, it often needs to be installed. | ||
| 8911 | The images and kernels built by the OpenEmbedded build system are placed in the | ||
| 8912 | <a class="link" href="#build-directory" target="_top">build directory</a> in | ||
| 8913 | <code class="filename">tmp/deploy/images</code>. | ||
| 8914 | For information on how to run pre-built images such as <code class="filename">qemux86</code> | ||
| 8915 | and <code class="filename">qemuarm</code>, see the | ||
| 8916 | "<a class="link" href="#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>" | ||
| 8917 | section in the Yocto Project Quick Start. | ||
| 8918 | For information about how to install these images, see the documentation for your | ||
| 8919 | particular board/machine. | ||
| 8920 | </p></div><div class="section" title="2.3. Debugging Build Failures"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div><p> | ||
| 8921 | The exact method for debugging build failures depends on the nature of the | ||
| 8922 | problem and on the system's area from which the bug originates. | ||
| 8923 | Standard debugging practices such as comparison against the last | ||
| 8924 | known working version with examination of the changes and the re-application of steps | ||
| 8925 | to identify the one causing the problem are | ||
| 8926 | valid for the Yocto Project just as they are for any other system. | ||
| 8927 | Even though it is impossible to detail every possible potential failure, | ||
| 8928 | this section provides some general tips to aid in debugging. | ||
| 8929 | </p><div class="section" title="2.3.1. Task Failures"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in | ||
| 8930 | <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. | ||
| 8931 | For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86 | ||
| 8932 | machine (<code class="filename">qemux86</code>) might be | ||
| 8933 | <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</code>. | ||
| 8934 | To see what BitBake runs to generate that log, look at the corresponding | ||
| 8935 | <code class="filename">run.do_taskname.pid</code> file located in the same directory. | ||
| 8936 | </p><p> | ||
| 8937 | Presently, the output from Python tasks is sent directly to the console. | ||
| 8938 | </p></div><div class="section" title="2.3.2. Running Specific Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div><p> | ||
| 8939 | Any given package consists of a set of tasks. | ||
| 8940 | The standard BitBake behavior in most cases is: <code class="filename">fetch</code>, | ||
| 8941 | <code class="filename">unpack</code>, | ||
| 8942 | <code class="filename">patch</code>, <code class="filename">configure</code>, | ||
| 8943 | <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>, | ||
| 8944 | <code class="filename">package_write</code>, and <code class="filename">build</code>. | ||
| 8945 | The default task is <code class="filename">build</code> and any tasks on which it depends | ||
| 8946 | build first. | ||
| 8947 | Some tasks exist, such as <code class="filename">devshell</code>, that are not part of the | ||
| 8948 | default build chain. | ||
| 8949 | If you wish to run a task that is not part of the default build chain, you can use the | ||
| 8950 | <code class="filename">-c</code> option in BitBake as follows: | ||
| 8951 | </p><pre class="literallayout"> | ||
| 8952 | $ bitbake matchbox-desktop -c devshell | ||
| 8953 | </pre><p> | ||
| 8954 | </p><p> | ||
| 8955 | If you wish to rerun a task, use the <code class="filename">-f</code> force option. | ||
| 8956 | For example, the following sequence forces recompilation after changing files in the | ||
| 8957 | working directory. | ||
| 8958 | </p><pre class="literallayout"> | ||
| 8959 | $ bitbake matchbox-desktop | ||
| 8960 | . | ||
| 8961 | . | ||
| 8962 | [make some changes to the source code in the working directory] | ||
| 8963 | . | ||
| 8964 | . | ||
| 8965 | $ bitbake matchbox-desktop -c compile -f | ||
| 8966 | $ bitbake matchbox-desktop | ||
| 8967 | </pre><p> | ||
| 8968 | </p><p> | ||
| 8969 | This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it. | ||
| 8970 | The last command reruns all tasks (basically the packaging tasks) after the compile. | ||
| 8971 | BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore | ||
| 8972 | understands that the other tasks also need to be run again. | ||
| 8973 | </p><p> | ||
| 8974 | You can view a list of tasks in a given package by running the | ||
| 8975 | <code class="filename">listtasks</code> task as follows: | ||
| 8976 | </p><pre class="literallayout"> | ||
| 8977 | $ bitbake matchbox-desktop -c listtasks | ||
| 8978 | </pre><p> | ||
| 8979 | The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>. | ||
| 8980 | </p></div><div class="section" title="2.3.3. Dependency Graphs"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div><p> | ||
| 8981 | Sometimes it can be hard to see why BitBake wants to build some other packages before a given | ||
| 8982 | package you have specified. | ||
| 8983 | The <code class="filename">bitbake -g targetname</code> command creates the | ||
| 8984 | <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>, | ||
| 8985 | and <code class="filename">task-depends.dot</code> files in the current directory. | ||
| 8986 | These files show the package and task dependencies and are useful for debugging problems. | ||
| 8987 | You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to | ||
| 8988 | display the results in a more human-readable form. | ||
| 8989 | </p></div><div class="section" title="2.3.4. General BitBake Problems"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div><p> | ||
| 8990 | You can see debug output from BitBake by using the <code class="filename">-D</code> option. | ||
| 8991 | The debug output gives more information about what BitBake | ||
| 8992 | is doing and the reason behind it. | ||
| 8993 | Each <code class="filename">-D</code> option you use increases the logging level. | ||
| 8994 | The most common usage is <code class="filename">-DDD</code>. | ||
| 8995 | </p><p> | ||
| 8996 | The output from <code class="filename">bitbake -DDD -v targetname</code> can reveal why | ||
| 8997 | BitBake chose a certain version of a package or why BitBake | ||
| 8998 | picked a certain provider. | ||
| 8999 | This command could also help you in a situation where you think BitBake did something | ||
| 9000 | unexpected. | ||
| 9001 | </p></div><div class="section" title="2.3.5. Building with No Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div><p> | ||
| 9002 | If you really want to build a specific <code class="filename">.bb</code> file, you can use | ||
| 9003 | the command form <code class="filename">bitbake -b <somepath/somefile.bb></code>. | ||
| 9004 | This command form does not check for dependencies so you should use it | ||
| 9005 | only when you know its dependencies already exist. | ||
| 9006 | You can also specify fragments of the filename. | ||
| 9007 | In this case, BitBake checks for a unique match. | ||
| 9008 | </p></div><div class="section" title="2.3.6. Variables"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div><p> | ||
| 9009 | The <code class="filename">-e</code> option dumps the resulting environment for | ||
| 9010 | either the configuration (no package specified) or for a | ||
| 9011 | specific package when specified; or <code class="filename">-b recipename</code> | ||
| 9012 | to show the environment from parsing a single recipe file only. | ||
| 9013 | </p></div><div class="section" title="2.3.7. Recipe Logging Mechanisms"><div class="titlepage"><div><div><h3 class="title"><a id="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div><p> | ||
| 9014 | Best practices exist while writing recipes that both log build progress and | ||
| 9015 | act on build conditions such as warnings and errors. | ||
| 9016 | Both Python and Bash language bindings exist for the logging mechanism: | ||
| 9017 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake | ||
| 9018 | supports several loglevels: <code class="filename">bb.fatal</code>, | ||
| 9019 | <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>, | ||
| 9020 | <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>, | ||
| 9021 | and <code class="filename">bb.debug</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set | ||
| 9022 | of loglevels exist and are accessed with a similar syntax: | ||
| 9023 | <code class="filename">bbfatal</code>, <code class="filename">bberror</code>, | ||
| 9024 | <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>, | ||
| 9025 | <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li></ul></div><p> | ||
| 9026 | </p><p> | ||
| 9027 | For guidance on how logging is handled in both Python and Bash recipes, see the | ||
| 9028 | <code class="filename">logging.bbclass</code> file in the | ||
| 9029 | <code class="filename">meta/classes</code> folder of the | ||
| 9030 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 9031 | </p><div class="section" title="2.3.7.1. Logging With Python"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div><p> | ||
| 9032 | When creating recipes using Python and inserting code that handles build logs | ||
| 9033 | keep in mind the goal is to have informative logs while keeping the console as | ||
| 9034 | "silent" as possible. | ||
| 9035 | Also, if you want status messages in the log use the "debug" loglevel. | ||
| 9036 | </p><p> | ||
| 9037 | Following is an example written in Python. | ||
| 9038 | The code handles logging for a function that determines the number of tasks | ||
| 9039 | needed to be run: | ||
| 9040 | </p><pre class="literallayout"> | ||
| 9041 | python do_listtasks() { | ||
| 9042 | bb.debug(2, "Starting to figure out the task list") | ||
| 9043 | if noteworthy_condition: | ||
| 9044 | bb.note("There are 47 tasks to run") | ||
| 9045 | bb.debug(2, "Got to point xyz") | ||
| 9046 | if warning_trigger: | ||
| 9047 | bb.warn("Detected warning_trigger, this might be a problem later.") | ||
| 9048 | if recoverable_error: | ||
| 9049 | bb.error("Hit recoverable_error, you really need to fix this!") | ||
| 9050 | if fatal_error: | ||
| 9051 | bb.fatal("fatal_error detected, unable to print the task list") | ||
| 9052 | bb.plain("The tasks present are abc") | ||
| 9053 | bb.debug(2, "Finished figuring out the tasklist") | ||
| 9054 | } | ||
| 9055 | </pre><p> | ||
| 9056 | </p></div><div class="section" title="2.3.7.2. Logging With Bash"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div><p> | ||
| 9057 | When creating recipes using Bash and inserting code that handles build | ||
| 9058 | logs you have the same goals - informative with minimal console output. | ||
| 9059 | The syntax you use for recipes written in Bash is similar to that of | ||
| 9060 | recipes written in Python described in the previous section. | ||
| 9061 | </p><p> | ||
| 9062 | Following is an example written in Bash. | ||
| 9063 | The code logs the progress of the <code class="filename">do_my_function</code> function. | ||
| 9064 | </p><pre class="literallayout"> | ||
| 9065 | do_my_function() { | ||
| 9066 | bbdebug 2 "Running do_my_function" | ||
| 9067 | if [ exceptional_condition ]; then | ||
| 9068 | bbnote "Hit exceptional_condition" | ||
| 9069 | fi | ||
| 9070 | bbdebug 2 "Got to point xyz" | ||
| 9071 | if [ warning_trigger ]; then | ||
| 9072 | bbwarn "Detected warning_trigger, this might cause a problem later." | ||
| 9073 | fi | ||
| 9074 | if [ recoverable_error ]; then | ||
| 9075 | bberror "Hit recoverable_error, correcting" | ||
| 9076 | fi | ||
| 9077 | if [ fatal_error ]; then | ||
| 9078 | bbfatal "fatal_error detected" | ||
| 9079 | fi | ||
| 9080 | bbdebug 2 "Completed do_my_function" | ||
| 9081 | } | ||
| 9082 | </pre><p> | ||
| 9083 | </p></div></div><div class="section" title="2.3.8. Other Tips"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div><p> | ||
| 9084 | Here are some other tips that you might find useful: | ||
| 9085 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>When adding new packages, it is worth watching for | ||
| 9086 | undesirable items making their way into compiler command lines. | ||
| 9087 | For example, you do not want references to local system files like | ||
| 9088 | <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>. | ||
| 9089 | </p></li><li class="listitem"><p>If you want to remove the psplash boot splashscreen, | ||
| 9090 | add <code class="filename">psplash=false</code> to the kernel command line. | ||
| 9091 | Doing so prevents psplash from loading and thus allows you to see the console. | ||
| 9092 | It is also possible to switch out of the splashscreen by | ||
| 9093 | switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). | ||
| 9094 | </p></li></ul></div><p> | ||
| 9095 | </p></div></div></div> | ||
| 9096 | |||
| 9097 | <div class="chapter" title="Chapter 3. Technical Details"><div class="titlepage"><div><div><h2 class="title"><a id="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></div><p> | ||
| 9098 | This chapter provides technical details for various parts of the Yocto Project. | ||
| 9099 | Currently, topics include Yocto Project components and shared state (sstate) cache. | ||
| 9100 | </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div><p> | ||
| 9101 | The BitBake task executor together with various types of configuration files form the | ||
| 9102 | OpenEmbedded Core. | ||
| 9103 | This section overviews the BitBake task executor and the | ||
| 9104 | configuration files by describing what they are used for and how they interact. | ||
| 9105 | </p><p> | ||
| 9106 | BitBake handles the parsing and execution of the data files. | ||
| 9107 | The data itself is of various types: | ||
| 9108 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular | ||
| 9109 | pieces of software</p></li><li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build | ||
| 9110 | information (e.g. how to build a Linux kernel).</p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings, | ||
| 9111 | policy decisions, etc. | ||
| 9112 | Configuration data acts as the glue to bind everything together.</p></li></ul></div><p> | ||
| 9113 | For more information on data, see the | ||
| 9114 | "<a class="link" href="#yocto-project-terms" target="_top">Yocto Project Terms</a>" | ||
| 9115 | section in the Yocto Project Development Manual. | ||
| 9116 | </p><p> | ||
| 9117 | BitBake knows how to combine multiple data sources together and refers to each data source | ||
| 9118 | as a layer. | ||
| 9119 | For information on layers, see the | ||
| 9120 | "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding and | ||
| 9121 | Creating Layers</a>" section of the Yocto Project Development Manual. | ||
| 9122 | </p><p> | ||
| 9123 | Following are some brief details on these core components. | ||
| 9124 | For more detailed information on these components see the | ||
| 9125 | "<a class="link" href="#ref-structure" title="Chapter 4. Source Directory Structure">Directory Structure</a>" chapter. | ||
| 9126 | </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div><p> | ||
| 9127 | BitBake is the tool at the heart of the OpenEmbedded build system and is responsible | ||
| 9128 | for parsing the metadata, generating a list of tasks from it, | ||
| 9129 | and then executing those tasks. | ||
| 9130 | To see a list of the options BitBake supports, use the following help command: | ||
| 9131 | </p><pre class="literallayout"> | ||
| 9132 | $ bitbake --help | ||
| 9133 | </pre><p> | ||
| 9134 | </p><p> | ||
| 9135 | The most common usage for BitBake is <code class="filename">bitbake <packagename></code>, where | ||
| 9136 | <code class="filename">packagename</code> is the name of the package you want to build | ||
| 9137 | (referred to as the "target" in this manual). | ||
| 9138 | The target often equates to the first part of a <code class="filename">.bb</code> filename. | ||
| 9139 | So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you | ||
| 9140 | might type the following: | ||
| 9141 | </p><pre class="literallayout"> | ||
| 9142 | $ bitbake matchbox-desktop | ||
| 9143 | </pre><p> | ||
| 9144 | Several different versions of <code class="filename">matchbox-desktop</code> might exist. | ||
| 9145 | BitBake chooses the one selected by the distribution configuration. | ||
| 9146 | You can get more details about how BitBake chooses between different | ||
| 9147 | target versions and providers in the | ||
| 9148 | "<a class="link" href="#ref-bitbake-providers" title="5.2. Preferences and Providers">Preferences and Providers</a>" section. | ||
| 9149 | </p><p> | ||
| 9150 | BitBake also tries to execute any dependent tasks first. | ||
| 9151 | So for example, before building <code class="filename">matchbox-desktop</code>, BitBake | ||
| 9152 | would build a cross compiler and <code class="filename">eglibc</code> if they had not already | ||
| 9153 | been built. | ||
| 9154 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code> | ||
| 9155 | GNU version of the Unix standard C library. By default, the OpenEmbedded build system | ||
| 9156 | builds with <code class="filename">eglibc</code>.</div><p> | ||
| 9157 | </p><p> | ||
| 9158 | A useful BitBake option to consider is the <code class="filename">-k</code> or | ||
| 9159 | <code class="filename">--continue</code> option. | ||
| 9160 | This option instructs BitBake to try and continue processing the job as much | ||
| 9161 | as possible even after encountering an error. | ||
| 9162 | When an error occurs, the target that | ||
| 9163 | failed and those that depend on it cannot be remade. | ||
| 9164 | However, when you use this option other dependencies can still be processed. | ||
| 9165 | </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div><p> | ||
| 9166 | The <code class="filename">.bb</code> files are usually referred to as "recipes." | ||
| 9167 | In general, a recipe contains information about a single piece of software. | ||
| 9168 | The information includes the location from which to download the source patches | ||
| 9169 | (if any are needed), which special configuration options to apply, | ||
| 9170 | how to compile the source files, and how to package the compiled output. | ||
| 9171 | </p><p> | ||
| 9172 | The term "package" can also be used to describe recipes. | ||
| 9173 | However, since the same word is used for the packaged output from the OpenEmbedded | ||
| 9174 | build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files), | ||
| 9175 | this document avoids using the term "package" when referring to recipes. | ||
| 9176 | </p></div><div class="section" title="3.1.3. Classes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div><p> | ||
| 9177 | Class files (<code class="filename">.bbclass</code>) contain information that is useful to share | ||
| 9178 | between metadata files. | ||
| 9179 | An example is the Autotools class, which contains | ||
| 9180 | common settings for any application that Autotools uses. | ||
| 9181 | The "<a class="link" href="#ref-classes" title="Chapter 6. Classes">Reference: Classes</a>" chapter provides details | ||
| 9182 | about common classes and how to use them. | ||
| 9183 | </p></div><div class="section" title="3.1.4. Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div><p> | ||
| 9184 | The configuration files (<code class="filename">.conf</code>) define various configuration variables | ||
| 9185 | that govern the OpenEmbedded build process. | ||
| 9186 | These files fall into several areas that define machine configuration options, | ||
| 9187 | distribution configuration options, compiler tuning options, general common configuration | ||
| 9188 | options and user configuration options (<code class="filename">local.conf</code>, which is found | ||
| 9189 | in the <a class="ulink" href="build-directory" target="_top">build directory</a>). | ||
| 9190 | </p></div></div><div class="section" title="3.2. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div><p> | ||
| 9191 | By design, the OpenEmbedded build system builds everything from scratch unless | ||
| 9192 | BitBake can determine that parts don't need to be rebuilt. | ||
| 9193 | Fundamentally, building from scratch is attractive as it means all parts are | ||
| 9194 | built fresh and there is no possibility of stale data causing problems. | ||
| 9195 | When developers hit problems, they typically default back to building from scratch | ||
| 9196 | so they know the state of things from the start. | ||
| 9197 | </p><p> | ||
| 9198 | Building an image from scratch is both an advantage and a disadvantage to the process. | ||
| 9199 | As mentioned in the previous paragraph, building from scratch ensures that | ||
| 9200 | everything is current and starts from a known state. | ||
| 9201 | However, building from scratch also takes much longer as it generally means | ||
| 9202 | rebuilding things that don't necessarily need rebuilt. | ||
| 9203 | </p><p> | ||
| 9204 | The Yocto Project implements shared state code that supports incremental builds. | ||
| 9205 | The implementation of the shared state code answers the following questions that | ||
| 9206 | were fundamental roadblocks within the OpenEmbedded incremental build support system: | ||
| 9207 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">What pieces of the system have changed and what pieces have not changed?</li><li class="listitem">How are changed pieces of software removed and replaced?</li><li class="listitem">How are pre-built components that don't need to be rebuilt from scratch | ||
| 9208 | used when they are available?</li></ul></div><p> | ||
| 9209 | </p><p> | ||
| 9210 | For the first question, the build system detects changes in the "inputs" to a given task by | ||
| 9211 | creating a checksum (or signature) of the task's inputs. | ||
| 9212 | If the checksum changes, the system assumes the inputs have changed and the task needs to be | ||
| 9213 | rerun. | ||
| 9214 | For the second question, the shared state (sstate) code tracks which tasks add which output | ||
| 9215 | to the build process. | ||
| 9216 | This means the output from a given task can be removed, upgraded or otherwise manipulated. | ||
| 9217 | The third question is partly addressed by the solution for the second question | ||
| 9218 | assuming the build system can fetch the sstate objects from remote locations and | ||
| 9219 | install them if they are deemed to be valid. | ||
| 9220 | </p><p> | ||
| 9221 | The rest of this section goes into detail about the overall incremental build | ||
| 9222 | architecture, the checksums (signatures), shared state, and some tips and tricks. | ||
| 9223 | </p><div class="section" title="3.2.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title"><a id="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div><p> | ||
| 9224 | When determining what parts of the system need to be built, BitBake | ||
| 9225 | uses a per-task basis and does not use a per-recipe basis. | ||
| 9226 | You might wonder why using a per-task basis is preferred over a per-recipe basis. | ||
| 9227 | To help explain, consider having the IPK packaging backend enabled and then switching to DEB. | ||
| 9228 | In this case, <code class="filename">do_install</code> and <code class="filename">do_package</code> | ||
| 9229 | output are still valid. | ||
| 9230 | However, with a per-recipe approach, the build would not include the | ||
| 9231 | <code class="filename">.deb</code> files. | ||
| 9232 | Consequently, you would have to invalidate the whole build and rerun it. | ||
| 9233 | Rerunning everything is not the best situation. | ||
| 9234 | Also in this case, the core must be "taught" much about specific tasks. | ||
| 9235 | This methodology does not scale well and does not allow users to easily add new tasks | ||
| 9236 | in layers or as external recipes without touching the packaged-staging core. | ||
| 9237 | </p></div><div class="section" title="3.2.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title"><a id="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div><p> | ||
| 9238 | The shared state code uses a checksum, which is a unique signature of a task's | ||
| 9239 | inputs, to determine if a task needs to be run again. | ||
| 9240 | Because it is a change in a task's inputs that triggers a rerun, the process | ||
| 9241 | needs to detect all the inputs to a given task. | ||
| 9242 | For shell tasks, this turns out to be fairly easy because | ||
| 9243 | the build process generates a "run" shell script for each task and | ||
| 9244 | it is possible to create a checksum that gives you a good idea of when | ||
| 9245 | the task's data changes. | ||
| 9246 | </p><p> | ||
| 9247 | To complicate the problem, there are things that should not be included in | ||
| 9248 | the checksum. | ||
| 9249 | First, there is the actual specific build path of a given task - | ||
| 9250 | the <code class="filename">WORKDIR</code>. | ||
| 9251 | It does not matter if the working directory changes because it should not | ||
| 9252 | affect the output for target packages. | ||
| 9253 | Also, the build process has the objective of making native/cross packages relocatable. | ||
| 9254 | The checksum therefore needs to exclude <code class="filename">WORKDIR</code>. | ||
| 9255 | The simplistic approach for excluding the working directory is to set | ||
| 9256 | <code class="filename">WORKDIR</code> to some fixed value and create the checksum | ||
| 9257 | for the "run" script. | ||
| 9258 | </p><p> | ||
| 9259 | Another problem results from the "run" scripts containing functions that | ||
| 9260 | might or might not get called. | ||
| 9261 | The incremental build solution contains code that figures out dependencies | ||
| 9262 | between shell functions. | ||
| 9263 | This code is used to prune the "run" scripts down to the minimum set, | ||
| 9264 | thereby alleviating this problem and making the "run" scripts much more | ||
| 9265 | readable as a bonus. | ||
| 9266 | </p><p> | ||
| 9267 | So far we have solutions for shell scripts. | ||
| 9268 | What about python tasks? | ||
| 9269 | The same approach applies even though these tasks are more difficult. | ||
| 9270 | The process needs to figure out what variables a python function accesses | ||
| 9271 | and what functions it calls. | ||
| 9272 | Again, the incremental build solution contains code that first figures out | ||
| 9273 | the variable and function dependencies, and then creates a checksum for the data | ||
| 9274 | used as the input to the task. | ||
| 9275 | </p><p> | ||
| 9276 | Like the <code class="filename">WORKDIR</code> case, situations exist where dependencies | ||
| 9277 | should be ignored. | ||
| 9278 | For these cases, you can instruct the build process to ignore a dependency | ||
| 9279 | by using a line like the following: | ||
| 9280 | </p><pre class="literallayout"> | ||
| 9281 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | ||
| 9282 | </pre><p> | ||
| 9283 | This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not | ||
| 9284 | depend on the value of <code class="filename">MACHINE</code>, even if it does reference it. | ||
| 9285 | </p><p> | ||
| 9286 | Equally, there are cases where we need to add dependencies BitBake is not able to find. | ||
| 9287 | You can accomplish this by using a line like the following: | ||
| 9288 | </p><pre class="literallayout"> | ||
| 9289 | PACKAGE_ARCHS[vardeps] = "MACHINE" | ||
| 9290 | </pre><p> | ||
| 9291 | This example explicitly adds the <code class="filename">MACHINE</code> variable as a | ||
| 9292 | dependency for <code class="filename">PACKAGE_ARCHS</code>. | ||
| 9293 | </p><p> | ||
| 9294 | Consider a case with inline python, for example, where BitBake is not | ||
| 9295 | able to figure out dependencies. | ||
| 9296 | When running in debug mode (i.e. using <code class="filename">-DDD</code>), BitBake | ||
| 9297 | produces output when it discovers something for which it cannot figure out | ||
| 9298 | dependencies. | ||
| 9299 | The Yocto Project team has currently not managed to cover those dependencies | ||
| 9300 | in detail and is aware of the need to fix this situation. | ||
| 9301 | </p><p> | ||
| 9302 | Thus far, this section has limited discussion to the direct inputs into a task. | ||
| 9303 | Information based on direct inputs is referred to as the "basehash" in the | ||
| 9304 | code. | ||
| 9305 | However, there is still the question of a task's indirect inputs - the | ||
| 9306 | things that were already built and present in the build directory. | ||
| 9307 | The checksum (or signature) for a particular task needs to add the hashes | ||
| 9308 | of all the tasks on which the particular task depends. | ||
| 9309 | Choosing which dependencies to add is a policy decision. | ||
| 9310 | However, the effect is to generate a master checksum that combines the basehash | ||
| 9311 | and the hashes of the task's dependencies. | ||
| 9312 | </p><p> | ||
| 9313 | At the code level, there are a variety of ways both the basehash and the | ||
| 9314 | dependent task hashes can be influenced. | ||
| 9315 | Within the BitBake configuration file, we can give BitBake some extra information | ||
| 9316 | to help it construct the basehash. | ||
| 9317 | The following statements effectively result in a list of global variable | ||
| 9318 | dependency excludes - variables never included in any checksum: | ||
| 9319 | </p><pre class="literallayout"> | ||
| 9320 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" | ||
| 9321 | BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" | ||
| 9322 | BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" | ||
| 9323 | BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" | ||
| 9324 | </pre><p> | ||
| 9325 | The previous example actually excludes | ||
| 9326 | <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a> | ||
| 9327 | since it is actually constructed as a path within | ||
| 9328 | <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on | ||
| 9329 | the whitelist. | ||
| 9330 | </p><p> | ||
| 9331 | The rules for deciding which hashes of dependent tasks to include through | ||
| 9332 | dependency chains are more complex and are generally accomplished with a | ||
| 9333 | python function. | ||
| 9334 | The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows two examples | ||
| 9335 | of this and also illustrates how you can insert your own policy into the system | ||
| 9336 | if so desired. | ||
| 9337 | This file defines the two basic signature generators <code class="filename">OE-Core</code> | ||
| 9338 | uses: "OEBasic" and "OEBasicHash". | ||
| 9339 | By default, there is a dummy "noop" signature handler enabled in BitBake. | ||
| 9340 | This means that behavior is unchanged from previous versions. | ||
| 9341 | <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default | ||
| 9342 | through this setting in the <code class="filename">bitbake.conf</code> file: | ||
| 9343 | </p><pre class="literallayout"> | ||
| 9344 | BB_SIGNATURE_HANDLER ?= "OEBasic" | ||
| 9345 | </pre><p> | ||
| 9346 | The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the | ||
| 9347 | "OEBasic" version but adds the task hash to the stamp files. | ||
| 9348 | This results in any metadata change that changes the task hash, automatically | ||
| 9349 | causing the task to be run again. | ||
| 9350 | This removes the need to bump <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> | ||
| 9351 | values and changes to metadata automatically ripple across the build. | ||
| 9352 | Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code> | ||
| 9353 | but is the default in <code class="filename">poky</code>. | ||
| 9354 | </p><p> | ||
| 9355 | It is also worth noting that the end result of these signature generators is to | ||
| 9356 | make some dependency and hash information available to the build. | ||
| 9357 | This information includes: | ||
| 9358 | </p><pre class="literallayout"> | ||
| 9359 | BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe | ||
| 9360 | BB_BASEHASH_<filename:taskname> - the base hashes for each dependent task | ||
| 9361 | BBHASHDEPS_<filename:taskname> - The task dependencies for each task | ||
| 9362 | BB_TASKHASH - the hash of the currently running task | ||
| 9363 | </pre><p> | ||
| 9364 | </p></div><div class="section" title="3.2.3. Shared State"><div class="titlepage"><div><div><h3 class="title"><a id="shared-state"></a>3.2.3. Shared State</h3></div></div></div><p> | ||
| 9365 | Checksums and dependencies, as discussed in the previous section, solve half the | ||
| 9366 | problem. | ||
| 9367 | The other part of the problem is being able to use checksum information during the build | ||
| 9368 | and being able to reuse or rebuild specific components. | ||
| 9369 | </p><p> | ||
| 9370 | The shared state class (<code class="filename">sstate.bbclass</code>) | ||
| 9371 | is a relatively generic implementation of how to "capture" a snapshot of a given task. | ||
| 9372 | The idea is that the build process does not care about the source of a task's output. | ||
| 9373 | Output could be freshly built or it could be downloaded and unpacked from | ||
| 9374 | somewhere - the build process doesn't need to worry about its source. | ||
| 9375 | </p><p> | ||
| 9376 | There are two types of output, one is just about creating a directory | ||
| 9377 | in <code class="filename">WORKDIR</code>. | ||
| 9378 | A good example is the output of either <code class="filename">do_install</code> or | ||
| 9379 | <code class="filename">do_package</code>. | ||
| 9380 | The other type of output occurs when a set of data is merged into a shared directory | ||
| 9381 | tree such as the sysroot. | ||
| 9382 | </p><p> | ||
| 9383 | The Yocto Project team has tried to keep the details of the implementation hidden in | ||
| 9384 | <code class="filename">sstate.bbclass</code>. | ||
| 9385 | From a user's perspective, adding shared state wrapping to a task | ||
| 9386 | is as simple as this <code class="filename">do_deploy</code> example taken from | ||
| 9387 | <code class="filename">do_deploy.bbclass</code>: | ||
| 9388 | </p><pre class="literallayout"> | ||
| 9389 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | ||
| 9390 | SSTATETASKS += "do_deploy" | ||
| 9391 | do_deploy[sstate-name] = "deploy" | ||
| 9392 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" | ||
| 9393 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" | ||
| 9394 | |||
| 9395 | python do_deploy_setscene () { | ||
| 9396 | sstate_setscene(d) | ||
| 9397 | } | ||
| 9398 | addtask do_deploy_setscene | ||
| 9399 | </pre><p> | ||
| 9400 | In the example, we add some extra flags to the task, a name field ("deploy"), an | ||
| 9401 | input directory where the task sends data, and the output | ||
| 9402 | directory where the data from the task should eventually be copied. | ||
| 9403 | We also add a <code class="filename">_setscene</code> variant of the task and add the task | ||
| 9404 | name to the <code class="filename">SSTATETASKS</code> list. | ||
| 9405 | </p><p> | ||
| 9406 | If you have a directory whose contents you need to preserve, you can do this with | ||
| 9407 | a line like the following: | ||
| 9408 | </p><pre class="literallayout"> | ||
| 9409 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | ||
| 9410 | </pre><p> | ||
| 9411 | This method, as well as the following example, also works for multiple directories. | ||
| 9412 | </p><pre class="literallayout"> | ||
| 9413 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | ||
| 9414 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | ||
| 9415 | do_package[sstate-lockfile] = "${PACKAGELOCK}" | ||
| 9416 | </pre><p> | ||
| 9417 | These methods also include the ability to take a lockfile when manipulating | ||
| 9418 | shared state directory structures since some cases are sensitive to file | ||
| 9419 | additions or removals. | ||
| 9420 | </p><p> | ||
| 9421 | Behind the scenes, the shared state code works by looking in | ||
| 9422 | <code class="filename">SSTATE_DIR</code> and | ||
| 9423 | <code class="filename">SSTATE_MIRRORS</code> for shared state files. | ||
| 9424 | Here is an example: | ||
| 9425 | </p><pre class="literallayout"> | ||
| 9426 | SSTATE_MIRRORS ?= "\ | ||
| 9427 | file://.* http://someserver.tld/share/sstate/ \n \ | ||
| 9428 | file://.* file:///some/local/dir/sstate/" | ||
| 9429 | </pre><p> | ||
| 9430 | </p><p> | ||
| 9431 | The shared state package validity can be detected just by looking at the | ||
| 9432 | filename since the filename contains the task checksum (or signature) as | ||
| 9433 | described earlier in this section. | ||
| 9434 | If a valid shared state package is found, the build process downloads it | ||
| 9435 | and uses it to accelerate the task. | ||
| 9436 | </p><p> | ||
| 9437 | The build processes uses the <code class="filename">*_setscene</code> tasks | ||
| 9438 | for the task acceleration phase. | ||
| 9439 | BitBake goes through this phase before the main execution code and tries | ||
| 9440 | to accelerate any tasks for which it can find shared state packages. | ||
| 9441 | If a shared state package for a task is available, the shared state | ||
| 9442 | package is used. | ||
| 9443 | This means the task and any tasks on which it is dependent are not | ||
| 9444 | executed. | ||
| 9445 | </p><p> | ||
| 9446 | As a real world example, the aim is when building an IPK-based image, | ||
| 9447 | only the <code class="filename">do_package_write_ipk</code> tasks would have their | ||
| 9448 | shared state packages fetched and extracted. | ||
| 9449 | Since the sysroot is not used, it would never get extracted. | ||
| 9450 | This is another reason why a task-based approach is preferred over a | ||
| 9451 | recipe-based approach, which would have to install the output from every task. | ||
| 9452 | </p></div><div class="section" title="3.2.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title"><a id="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div><p> | ||
| 9453 | The code in the build system that supports incremental builds is not | ||
| 9454 | simple code. | ||
| 9455 | This section presents some tips and tricks that help you work around | ||
| 9456 | issues related to shared state code. | ||
| 9457 | </p><div class="section" title="3.2.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title"><a id="debugging"></a>3.2.4.1. Debugging</h4></div></div></div><p> | ||
| 9458 | When things go wrong, debugging needs to be straightforward. | ||
| 9459 | Because of this, the Yocto Project team included strong debugging | ||
| 9460 | tools: | ||
| 9461 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Whenever a shared state package is written out, so is a | ||
| 9462 | corresponding <code class="filename">.siginfo</code> file. | ||
| 9463 | This practice results in a pickled python database of all | ||
| 9464 | the metadata that went into creating the hash for a given shared state | ||
| 9465 | package.</p></li><li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code> | ||
| 9466 | (or <code class="filename">-S</code>) option, BitBake dumps out | ||
| 9467 | <code class="filename">.siginfo</code> files in | ||
| 9468 | the stamp directory for every task it would have executed instead of | ||
| 9469 | building the specified target package.</p></li><li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that | ||
| 9470 | can process these <code class="filename">.siginfo</code> files. | ||
| 9471 | If one file is specified, it will dump out the dependency | ||
| 9472 | information in the file. | ||
| 9473 | If two files are specified, it will compare the two files and dump out | ||
| 9474 | the differences between the two. | ||
| 9475 | This allows the question of "What changed between X and Y?" to be | ||
| 9476 | answered easily.</p></li></ul></div><p> | ||
| 9477 | </p></div><div class="section" title="3.2.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title"><a id="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div><p> | ||
| 9478 | The shared state code uses checksums and shared state | ||
| 9479 | cache to avoid unnecessarily rebuilding tasks. | ||
| 9480 | As with all schemes, this one has some drawbacks. | ||
| 9481 | It is possible that you could make implicit changes that are not factored | ||
| 9482 | into the checksum calculation, but do affect a task's output. | ||
| 9483 | A good example is perhaps when a tool changes its output. | ||
| 9484 | Let's say that the output of <code class="filename">rpmdeps</code> needed to change. | ||
| 9485 | The result of the change should be that all the "package", "package_write_rpm", | ||
| 9486 | and "package_deploy-rpm" shared state cache items would become invalid. | ||
| 9487 | But, because this is a change that is external to the code and therefore implicit, | ||
| 9488 | the associated shared state cache items do not become invalidated. | ||
| 9489 | In this case, the build process would use the cached items rather than running the | ||
| 9490 | task again. | ||
| 9491 | Obviously, these types of implicit changes can cause problems. | ||
| 9492 | </p><p> | ||
| 9493 | To avoid these problems during the build, you need to understand the effects of any | ||
| 9494 | change you make. | ||
| 9495 | Note that any changes you make directly to a function automatically are factored into | ||
| 9496 | the checksum calculation and thus, will invalidate the associated area of sstate cache. | ||
| 9497 | You need to be aware of any implicit changes that are not obvious changes to the | ||
| 9498 | code and could affect the output of a given task. | ||
| 9499 | Once you are aware of such a change, you can take steps to invalidate the cache | ||
| 9500 | and force the task to run. | ||
| 9501 | The step to take is as simple as changing a function's comments in the source code. | ||
| 9502 | For example, to invalidate package shared state files, change the comment statements | ||
| 9503 | of <code class="filename">do_package</code> or the comments of one of the functions it calls. | ||
| 9504 | The change is purely cosmetic, but it causes the checksum to be recalculated and | ||
| 9505 | forces the task to be run again. | ||
| 9506 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 9507 | For an example of a commit that makes a cosmetic change to invalidate | ||
| 9508 | a shared state, see this | ||
| 9509 | <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>. | ||
| 9510 | </div></div></div></div><div class="section" title="3.3. x32"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="x32"></a>3.3. x32</h2></div></div></div><p> | ||
| 9511 | x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. | ||
| 9512 | An ABI defines the calling conventions between functions in a processing environment. | ||
| 9513 | The interface determines what registers are used and what the sizes are for various C data types. | ||
| 9514 | </p><p> | ||
| 9515 | Some processing environments prefer using 32-bit applications even when running | ||
| 9516 | on Intel 64-bit platforms. | ||
| 9517 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms. | ||
| 9518 | The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources, | ||
| 9519 | leaving the system underutilized. | ||
| 9520 | Now consider the x86_64 psABI. | ||
| 9521 | This ABI is newer and uses 64-bits for data sizes and program pointers. | ||
| 9522 | The extra bits increase the footprint size of the programs, libraries, | ||
| 9523 | and also increases the memory and file system size requirements. | ||
| 9524 | Executing under the x32 psABI enables user programs to utilize CPU and system resources | ||
| 9525 | more efficiently while keeping the memory footprint of the applications low. | ||
| 9526 | Extra bits are used for registers but not for addressing mechanisms. | ||
| 9527 | </p><div class="section" title="3.3.1. Support"><div class="titlepage"><div><div><h3 class="title"><a id="support"></a>3.3.1. Support</h3></div></div></div><p> | ||
| 9528 | While the x32 psABI specifications are not fully finalized, this Yocto Project | ||
| 9529 | release supports current development specifications of x32 psABI. | ||
| 9530 | As of this release of the Yocto Project, x32 psABI support exists as follows: | ||
| 9531 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets. | ||
| 9532 | </p></li><li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code> | ||
| 9533 | layer on top of the OE-core/Yocto layer.</p></li><li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer | ||
| 9534 | is used for building x32 psABI program binaries.</p></li><li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li><li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and | ||
| 9535 | <code class="filename">core-image-sato</code> images.</p></li></ul></div><p> | ||
| 9536 | </p></div><div class="section" title="3.3.2. Future Development and Limitations"><div class="titlepage"><div><div><h3 class="title"><a id="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div><p> | ||
| 9537 | As of this Yocto Project release, the x32 psABI kernel and library interfaces | ||
| 9538 | specifications are not finalized. | ||
| 9539 | </p><p> | ||
| 9540 | Future Plans for the x32 psABI in the Yocto Project include the following: | ||
| 9541 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enhance and fix the few remaining recipes so they | ||
| 9542 | work with and support x32 toolchains.</p></li><li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li><li class="listitem"><p>Support larger images.</p></li><li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from | ||
| 9543 | <code class="filename">experimental/meta-x32</code> into OE-core.</p></li></ul></div><p> | ||
| 9544 | </p></div><div class="section" title="3.3.3. Using x32 Right Now"><div class="titlepage"><div><div><h3 class="title"><a id="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div><p> | ||
| 9545 | Despite the fact the x32 psABI support is in development state for this release of the | ||
| 9546 | Yocto Project, you can follow these steps to use the x32 spABI: | ||
| 9547 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local | ||
| 9548 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 9549 | You can find the <code class="filename">experimental/meta-x32</code> source repository at | ||
| 9550 | <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>.</p></li><li class="listitem"><p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes | ||
| 9551 | the <code class="filename">meta-x32</code>. | ||
| 9552 | Here is an example: | ||
| 9553 | </p><pre class="literallayout"> | ||
| 9554 | BBLAYERS ?= " \ | ||
| 9555 | /home/nitin/prj/poky.git/meta \ | ||
| 9556 | /home/nitin/prj/poky.git/meta-yocto \ | ||
| 9557 | /home/nitin/prj/meta-x32.git \ | ||
| 9558 | " | ||
| 9559 | </pre></li><li class="listitem"><p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code> | ||
| 9560 | machines by editing the <code class="filename">conf/local.conf</code> like this: | ||
| 9561 | </p><pre class="literallayout"> | ||
| 9562 | MACHINE = "qemux86-64" | ||
| 9563 | DEFAULTTUNE = "x86-64-x32" | ||
| 9564 | baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ | ||
| 9565 | or 'INVALID'), True) or 'lib'}" | ||
| 9566 | #MACHINE = "atom-pc" | ||
| 9567 | #DEFAULTTUNE = "core2-64-x32" | ||
| 9568 | </pre></li><li class="listitem"><p>As usual, use BitBake to build an image that supports the x32 psABI. | ||
| 9569 | Here is an example: | ||
| 9570 | </p><pre class="literallayout"> | ||
| 9571 | $ bitake core-image-sato | ||
| 9572 | </pre></li><li class="listitem"><p>As usual, run your image using QEMU: | ||
| 9573 | </p><pre class="literallayout"> | ||
| 9574 | $ runqemu qemux86-64 core-image-sato | ||
| 9575 | </pre></li></ul></div><p> | ||
| 9576 | </p></div></div><div class="section" title="3.4. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licenses"></a>3.4. Licenses</h2></div></div></div><p> | ||
| 9577 | This section describes the mechanism by which the OpenEmbedded build system | ||
| 9578 | tracks changes to licensing text. | ||
| 9579 | The section also describes how to enable commercially licensed recipes, | ||
| 9580 | which by default are disabled. | ||
| 9581 | </p><div class="section" title="3.4.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div><p> | ||
| 9582 | The license of an upstream project might change in the future. | ||
| 9583 | In order to prevent these changes going unnoticed, the | ||
| 9584 | <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code> | ||
| 9585 | variable tracks changes to the license text. The checksums are validated at the end of the | ||
| 9586 | configure step, and if the checksums do not match, the build will fail. | ||
| 9587 | </p><div class="section" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.4.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div><p> | ||
| 9588 | The <code class="filename">LIC_FILES_CHKSUM</code> | ||
| 9589 | variable contains checksums of the license text in the source code for the recipe. | ||
| 9590 | Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>: | ||
| 9591 | </p><pre class="literallayout"> | ||
| 9592 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ | ||
| 9593 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | ||
| 9594 | file://licfile2.txt;endline=50;md5=zzzz \ | ||
| 9595 | ..." | ||
| 9596 | </pre><p> | ||
| 9597 | </p><p> | ||
| 9598 | The build system uses the | ||
| 9599 | <code class="filename"><a class="link" href="#var-S" title="S">S</a></code> variable as the | ||
| 9600 | default directory used when searching files listed in | ||
| 9601 | <code class="filename">LIC_FILES_CHKSUM</code>. | ||
| 9602 | The previous example employs the default directory. | ||
| 9603 | </p><p> | ||
| 9604 | You can also use relative paths as shown in the following example: | ||
| 9605 | </p><pre class="literallayout"> | ||
| 9606 | LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ | ||
| 9607 | md5=bb14ed3c4cda583abc85401304b5cd4e" | ||
| 9608 | LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | ||
| 9609 | </pre><p> | ||
| 9610 | </p><p> | ||
| 9611 | In this example, the first line locates a file in | ||
| 9612 | <code class="filename">${S}/src/ls.c</code>. | ||
| 9613 | The second line refers to a file in | ||
| 9614 | <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent | ||
| 9615 | of <code class="filename"><a class="link" href="#var-S" title="S">S</a></code>. | ||
| 9616 | </p><p> | ||
| 9617 | Note that this variable is mandatory for all recipes, unless the | ||
| 9618 | <code class="filename">LICENSE</code> variable is set to "CLOSED". | ||
| 9619 | </p></div><div class="section" title="3.4.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div><p> | ||
| 9620 | As mentioned in the previous section, the | ||
| 9621 | <code class="filename">LIC_FILES_CHKSUM</code> variable lists all the | ||
| 9622 | important files that contain the license text for the source code. | ||
| 9623 | It is possible to specify a checksum for an entire file, or a specific section of a | ||
| 9624 | file (specified by beginning and ending line numbers with the "beginline" and "endline" | ||
| 9625 | parameters, respectively). | ||
| 9626 | The latter is useful for source files with a license notice header, | ||
| 9627 | README documents, and so forth. | ||
| 9628 | If you do not use the "beginline" parameter, then it is assumed that the text begins on the | ||
| 9629 | first line of the file. | ||
| 9630 | Similarly, if you do not use the "endline" parameter, it is assumed that the license text | ||
| 9631 | ends with the last line of the file. | ||
| 9632 | </p><p> | ||
| 9633 | The "md5" parameter stores the md5 checksum of the license text. | ||
| 9634 | If the license text changes in any way as compared to this parameter | ||
| 9635 | then a mismatch occurs. | ||
| 9636 | This mismatch triggers a build failure and notifies the developer. | ||
| 9637 | Notification allows the developer to review and address the license text changes. | ||
| 9638 | Also note that if a mismatch occurs during the build, the correct md5 | ||
| 9639 | checksum is placed in the build log and can be easily copied to the recipe. | ||
| 9640 | </p><p> | ||
| 9641 | There is no limit to how many files you can specify using the | ||
| 9642 | <code class="filename">LIC_FILES_CHKSUM</code> variable. | ||
| 9643 | Generally, however, every project requires a few specifications for license tracking. | ||
| 9644 | Many projects have a "COPYING" file that stores the license information for all the source | ||
| 9645 | code files. | ||
| 9646 | This practice allows you to just track the "COPYING" file as long as it is kept up to date. | ||
| 9647 | </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> | ||
| 9648 | If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match | ||
| 9649 | error and displays the correct "md5" parameter value during the build. | ||
| 9650 | The correct parameter is also captured in the build log. | ||
| 9651 | </div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> | ||
| 9652 | If the whole file contains only license text, you do not need to use the "beginline" and | ||
| 9653 | "endline" parameters. | ||
| 9654 | </div></div></div><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div><p> | ||
| 9655 | By default, the OpenEmbedded build system disables | ||
| 9656 | components that have commercial or other special licensing | ||
| 9657 | requirements. | ||
| 9658 | Such requirements are defined on a | ||
| 9659 | recipe-by-recipe basis through the <code class="filename">LICENSE_FLAGS</code> variable | ||
| 9660 | definition in the affected recipe. | ||
| 9661 | For instance, the | ||
| 9662 | <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> | ||
| 9663 | recipe contains the following statement: | ||
| 9664 | </p><pre class="literallayout"> | ||
| 9665 | LICENSE_FLAGS = "commercial" | ||
| 9666 | </pre><p> | ||
| 9667 | Here is a slightly more complicated example that contains both an | ||
| 9668 | explicit package name and version (after variable expansion): | ||
| 9669 | </p><pre class="literallayout"> | ||
| 9670 | LICENSE_FLAGS = "license_${PN}_${PV}" | ||
| 9671 | </pre><p> | ||
| 9672 | In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code> | ||
| 9673 | definition to be enabled and included in an image, it | ||
| 9674 | needs to have a matching entry in the global | ||
| 9675 | <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable | ||
| 9676 | typically defined in your <code class="filename">local.conf</code> file. | ||
| 9677 | For example, to enable | ||
| 9678 | the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> | ||
| 9679 | package, you could add either the string | ||
| 9680 | "commercial_gst-plugins-ugly" or the more general string | ||
| 9681 | "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>. | ||
| 9682 | See the | ||
| 9683 | "<a class="link" href="#license-flag-matching" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section | ||
| 9684 | for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works. | ||
| 9685 | Here is the example: | ||
| 9686 | </p><pre class="literallayout"> | ||
| 9687 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | ||
| 9688 | </pre><p> | ||
| 9689 | Likewise, to additionally enable the package containing | ||
| 9690 | <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming | ||
| 9691 | that the actual recipe name was <code class="filename">emgd_1.10.bb</code>, | ||
| 9692 | the following string would enable that package as well as | ||
| 9693 | the original <code class="filename">gst-plugins-ugly</code> package: | ||
| 9694 | </p><pre class="literallayout"> | ||
| 9695 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" | ||
| 9696 | </pre><p> | ||
| 9697 | As a convenience, you do not need to specify the complete license string | ||
| 9698 | in the whitelist for every package. | ||
| 9699 | you can use an abbreviated form, which consists | ||
| 9700 | of just the first portion or portions of the license string before | ||
| 9701 | the initial underscore character or characters. | ||
| 9702 | A partial string will match | ||
| 9703 | any license that contains the given string as the first | ||
| 9704 | portion of its license. | ||
| 9705 | For example, the following | ||
| 9706 | whitelist string will also match both of the packages | ||
| 9707 | previously mentioned as well as any other packages that have | ||
| 9708 | licenses starting with "commercial" or "license". | ||
| 9709 | </p><pre class="literallayout"> | ||
| 9710 | LICENSE_FLAGS_WHITELIST = "commercial license" | ||
| 9711 | </pre><p> | ||
| 9712 | </p><div class="section" title="3.4.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title"><a id="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div><p> | ||
| 9713 | The definition of 'matching' in reference to a | ||
| 9714 | recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple. | ||
| 9715 | However, some things exist that you should know about in order to | ||
| 9716 | correctly and effectively use it. | ||
| 9717 | </p><p> | ||
| 9718 | Before a flag | ||
| 9719 | defined by a particular recipe is tested against the | ||
| 9720 | contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the | ||
| 9721 | string <code class="filename">_${PN}</code> (with | ||
| 9722 | <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is | ||
| 9723 | appended to the flag, thus automatically making each | ||
| 9724 | <code class="filename">LICENSE_FLAGS</code> value recipe-specific. | ||
| 9725 | That string is | ||
| 9726 | then matched against the whitelist. | ||
| 9727 | So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe | ||
| 9728 | "foo" for example, the string <code class="filename">"commercial_foo"</code> | ||
| 9729 | would normally be what is specified in the whitelist in order for it to | ||
| 9730 | match. | ||
| 9731 | </p><p> | ||
| 9732 | You can broaden the match by | ||
| 9733 | putting any "_"-separated beginning subset of a | ||
| 9734 | <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also | ||
| 9735 | match. | ||
| 9736 | For example, simply specifying "commercial" in | ||
| 9737 | the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code> | ||
| 9738 | definition starting with "commercial" such as | ||
| 9739 | "commercial_foo" and "commercial_bar", which are the | ||
| 9740 | strings that would be automatically generated for | ||
| 9741 | hypothetical "foo" and "bar" recipes assuming those | ||
| 9742 | recipes had simply specified the following: | ||
| 9743 | </p><pre class="literallayout"> | ||
| 9744 | LICENSE_FLAGS = "commercial" | ||
| 9745 | </pre><p> | ||
| 9746 | </p><p> | ||
| 9747 | Broadening the match allows for a range of specificity for the items | ||
| 9748 | in the whitelist, from more general to perfectly | ||
| 9749 | specific. | ||
| 9750 | So you have the choice of exhaustively | ||
| 9751 | enumerating each license flag in the whitelist to | ||
| 9752 | allow only those specific recipes into the image, or | ||
| 9753 | of using a more general string to pick up anything | ||
| 9754 | matching just the first component or components of the specified | ||
| 9755 | string. | ||
| 9756 | </p><p> | ||
| 9757 | This scheme works even if the flag already | ||
| 9758 | has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is | ||
| 9759 | redundant, but does not affect the outcome. | ||
| 9760 | For example, a license flag of "commercial_1.2_foo" would | ||
| 9761 | turn into "commercial_1.2_foo_foo" and would match | ||
| 9762 | both the general "commercial" and the specific | ||
| 9763 | "commercial_1.2_foo", as expected. | ||
| 9764 | The flag would also match | ||
| 9765 | "commercial_1.2_foo_foo" and "commercial_1.2", which | ||
| 9766 | does not make much sense regarding use in the whitelist. | ||
| 9767 | </p><p> | ||
| 9768 | For a versioned string, you could instead specify | ||
| 9769 | "commercial_foo_1.2", which would turn into | ||
| 9770 | "commercial_foo_1.2_foo". | ||
| 9771 | And, as expected, this flag allows | ||
| 9772 | you to pick up this package along with | ||
| 9773 | anything else "commercial" when you specify "commercial" | ||
| 9774 | in the whitelist. | ||
| 9775 | Or, the flag allows you to pick up this package along with anything "commercial_foo" | ||
| 9776 | regardless of version when you use "commercial_foo" in the whitelist. | ||
| 9777 | Finally, you can be completely specific about the package and version and specify | ||
| 9778 | "commercial_foo_1.2" package and version. | ||
| 9779 | </p></div><div class="section" title="3.4.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title"><a id="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div><p> | ||
| 9780 | Other helpful variables related to commercial | ||
| 9781 | license handling exist and are defined in the | ||
| 9782 | <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file: | ||
| 9783 | </p><pre class="literallayout"> | ||
| 9784 | COMMERCIAL_AUDIO_PLUGINS ?= "" | ||
| 9785 | COMMERCIAL_VIDEO_PLUGINS ?= "" | ||
| 9786 | COMMERCIAL_QT = "" | ||
| 9787 | </pre><p> | ||
| 9788 | If you want to enable these components, you can do so by making sure you have | ||
| 9789 | the following statements in your <code class="filename">local.conf</code> configuration file: | ||
| 9790 | </p><pre class="literallayout"> | ||
| 9791 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ | ||
| 9792 | gst-plugins-ugly-mpegaudioparse" | ||
| 9793 | COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ | ||
| 9794 | gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" | ||
| 9795 | COMMERCIAL_QT ?= "qmmp" | ||
| 9796 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | ||
| 9797 | </pre><p> | ||
| 9798 | Of course, you could also create a matching whitelist | ||
| 9799 | for those components using the more general "commercial" | ||
| 9800 | in the whitelist, but that would also enable all the | ||
| 9801 | other packages with <code class="filename">LICENSE_FLAGS</code> containing | ||
| 9802 | "commercial", which you may or may not want: | ||
| 9803 | </p><pre class="literallayout"> | ||
| 9804 | LICENSE_FLAGS_WHITELIST = "commercial" | ||
| 9805 | </pre><p> | ||
| 9806 | </p><p> | ||
| 9807 | Specifying audio and video plug-ins as part of the | ||
| 9808 | <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and | ||
| 9809 | <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements | ||
| 9810 | or commercial qt components as part of | ||
| 9811 | the <code class="filename">COMMERCIAL_QT</code> statement (along | ||
| 9812 | with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the | ||
| 9813 | plug-ins or components into built images, thus adding | ||
| 9814 | support for media formats or components. | ||
| 9815 | </p></div></div></div></div> | ||
| 9816 | |||
| 9817 | <div class="chapter" title="Chapter 4. Source Directory Structure"><div class="titlepage"><div><div><h2 class="title"><a id="ref-structure"></a>Chapter 4. Source Directory Structure</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#structure-core">4.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">4.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">4.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">4.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">4.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-demoapps">4.1.5. <code class="filename">meta-demoapps/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-rt">4.1.6. <code class="filename">meta-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">4.1.7. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">4.1.8. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">4.1.9. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">4.1.10. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">4.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">4.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">4.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">4.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">4.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">4.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">4.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">4.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">4.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">4.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">4.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">4.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">4.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">4.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">4.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">4.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">4.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">4.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">4.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">4.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">4.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">4.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">4.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">4.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">4.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">4.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">4.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">4.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">4.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">4.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">4.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">4.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">4.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">4.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">4.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">4.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">4.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">4.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">4.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">4.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">4.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></div><p> | ||
| 9818 | The <a class="link" href="#source-directory" target="_top">source directory</a> consists of several components. | ||
| 9819 | Understanding them and knowing where they are located is key to using the Yocto Project well. | ||
| 9820 | This chapter describes the source directory and gives information about the various | ||
| 9821 | files and directories. | ||
| 9822 | </p><p> | ||
| 9823 | For information on how to establish a local source directory on your development system, see the | ||
| 9824 | "<a class="link" href="#getting-setup" target="_top">Getting Set Up</a>" | ||
| 9825 | section in the Yocto Project Development Manual. | ||
| 9826 | </p><div class="section" title="4.1. Top level core components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-core"></a>4.1. Top level core components</h2></div></div></div><div class="section" title="4.1.1. bitbake/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-bitbake"></a>4.1.1. <code class="filename">bitbake/</code></h3></div></div></div><p> | ||
| 9827 | The <a class="ulink" href="source-directory" target="_top">source directory</a> | ||
| 9828 | includes a copy of BitBake for ease of use. | ||
| 9829 | The copy usually matches the current stable BitBake release from the BitBake project. | ||
| 9830 | BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks | ||
| 9831 | defined by that data. | ||
| 9832 | Failures are usually from the metadata and not from BitBake itself. | ||
| 9833 | Consequently, most users do not need to worry about BitBake. | ||
| 9834 | </p><p> | ||
| 9835 | When you run the <code class="filename">bitbake</code> command, the wrapper script in | ||
| 9836 | <code class="filename">scripts/</code> is executed to run the main BitBake executable, | ||
| 9837 | which resides in the <code class="filename">bitbake/bin/</code> directory. | ||
| 9838 | Sourcing the <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a> | ||
| 9839 | script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code> | ||
| 9840 | directories (in that order) into the shell's <code class="filename">PATH</code> environment | ||
| 9841 | variable. | ||
| 9842 | </p><p> | ||
| 9843 | For more information on BitBake, see the BitBake on-line manual at | ||
| 9844 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">http://docs.openembedded.org/bitbake/html/</a>. | ||
| 9845 | </p></div><div class="section" title="4.1.2. build/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-build"></a>4.1.2. <code class="filename">build/</code></h3></div></div></div><p> | ||
| 9846 | This directory contains user configuration files and the output | ||
| 9847 | generated by the OpenEmbedded build system in its standard configuration where | ||
| 9848 | the source tree is combined with the output. | ||
| 9849 | The <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 9850 | is created initially when you <code class="filename">source</code> | ||
| 9851 | the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>. | ||
| 9852 | </p><p> | ||
| 9853 | It is also possible to place output and configuration | ||
| 9854 | files in a directory separate from the | ||
| 9855 | <a class="link" href="#source-directory" target="_top">source directory</a> | ||
| 9856 | by providing a directory name when you <code class="filename">source</code> | ||
| 9857 | the setup script. | ||
| 9858 | For information on separating output from your local source directory files, see <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a>. | ||
| 9859 | </p></div><div class="section" title="4.1.3. documentation"><div class="titlepage"><div><div><h3 class="title"><a id="handbook"></a>4.1.3. <code class="filename">documentation</code></h3></div></div></div><p> | ||
| 9860 | This directory holds the source for the Yocto Project documentation | ||
| 9861 | as well as templates and tools that allow you to generate PDF and HTML | ||
| 9862 | versions of the manuals. | ||
| 9863 | Each manual is contained in a sub-folder. | ||
| 9864 | For example, the files for this manual reside in | ||
| 9865 | <code class="filename">poky-ref-manual</code>. | ||
| 9866 | </p></div><div class="section" title="4.1.4. meta/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta"></a>4.1.4. <code class="filename">meta/</code></h3></div></div></div><p> | ||
| 9867 | This directory contains the OpenEmbedded Core metadata. | ||
| 9868 | The directory holds machine definitions, the Yocto Project distribution, | ||
| 9869 | and the packages that make up a given system. | ||
| 9870 | </p></div><div class="section" title="4.1.5. meta-demoapps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-demoapps"></a>4.1.5. <code class="filename">meta-demoapps/</code></h3></div></div></div><p> | ||
| 9871 | This directory contains recipes for applications and demos that are not part of the | ||
| 9872 | OpenEmbedded core. | ||
| 9873 | </p></div><div class="section" title="4.1.6. meta-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-rt"></a>4.1.6. <code class="filename">meta-rt/</code></h3></div></div></div><p> | ||
| 9874 | This directory contains recipes for real-time kernels. | ||
| 9875 | </p></div><div class="section" title="4.1.7. meta-skeleton/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-skeleton"></a>4.1.7. <code class="filename">meta-skeleton/</code></h3></div></div></div><p> | ||
| 9876 | This directory contains template recipes for BSP and kernel development. | ||
| 9877 | </p></div><div class="section" title="4.1.8. scripts/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-scripts"></a>4.1.8. <code class="filename">scripts/</code></h3></div></div></div><p> | ||
| 9878 | This directory contains various integration scripts that implement | ||
| 9879 | extra functionality in the Yocto Project environment (e.g. QEMU scripts). | ||
| 9880 | The <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a> script appends this | ||
| 9881 | directory to the shell's <code class="filename">PATH</code> environment variable. | ||
| 9882 | </p><p> | ||
| 9883 | The <code class="filename">scripts</code> directory has useful scripts that assist contributing | ||
| 9884 | back to the Yocto Project, such as <code class="filename">create_pull_request</code> and | ||
| 9885 | <code class="filename">send_pull_request</code>. | ||
| 9886 | </p></div><div class="section" title="4.1.9. oe-init-build-env"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-script"></a>4.1.9. <code class="filename">oe-init-build-env</code></h3></div></div></div><p> | ||
| 9887 | This script sets up the OpenEmbedded build environment. | ||
| 9888 | Running this script with the <code class="filename">source</code> command in | ||
| 9889 | a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the | ||
| 9890 | current working directory. | ||
| 9891 | You need to run this script before running BitBake commands. | ||
| 9892 | The script uses other scripts within the <code class="filename">scripts</code> directory to do | ||
| 9893 | the bulk of the work. | ||
| 9894 | </p><p> | ||
| 9895 | By default, running this script without a build directory argument creates the | ||
| 9896 | <code class="filename">build</code> directory. | ||
| 9897 | If you provide a build directory argument when you <code class="filename">source</code> | ||
| 9898 | the script, you direct OpenEmbedded build system to create a | ||
| 9899 | <a class="link" href="#build-directory" target="_top">build directory</a> of your choice. | ||
| 9900 | For example, the following command creates a build directory named | ||
| 9901 | <code class="filename">mybuilds</code> that is outside of the | ||
| 9902 | <a class="link" href="#source-directory" target="_top">source directory</a>: | ||
| 9903 | </p><pre class="literallayout"> | ||
| 9904 | $ source oe-init-build-env ~/mybuilds | ||
| 9905 | </pre><p> | ||
| 9906 | </p></div><div class="section" title="4.1.10. LICENSE, README, and README.hardware"><div class="titlepage"><div><div><h3 class="title"><a id="structure-basic-top-level"></a>4.1.10. <code class="filename">LICENSE, README, and README.hardware</code></h3></div></div></div><p> | ||
| 9907 | These files are standard top-level files. | ||
| 9908 | </p></div></div><div class="section" title="4.2. The Build Directory - build/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-build"></a>4.2. The Build Directory - <code class="filename">build/</code></h2></div></div></div><div class="section" title="4.2.1. build/pseudodone"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-pseudodone"></a>4.2.1. <code class="filename">build/pseudodone</code></h3></div></div></div><p> | ||
| 9909 | This tag file indicates that the initial pseudo binary was created. | ||
| 9910 | The file is built the first time BitBake is invoked. | ||
| 9911 | </p></div><div class="section" title="4.2.2. build/conf/local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-local.conf"></a>4.2.2. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p> | ||
| 9912 | This file contains all the local user configuration for your build environment. | ||
| 9913 | If there is no <code class="filename">local.conf</code> present, it is created from | ||
| 9914 | <code class="filename">local.conf.sample</code>. | ||
| 9915 | The <code class="filename">local.conf</code> file contains documentation on the various configuration options. | ||
| 9916 | Any variable set here overrides any variable set elsewhere within the environment unless | ||
| 9917 | that variable is hard-coded within a file (e.g. by using '=' instead of '?='). | ||
| 9918 | Some variables are hard-coded for various reasons but these variables are | ||
| 9919 | relatively rare. | ||
| 9920 | </p><p> | ||
| 9921 | Edit this file to set the <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> | ||
| 9922 | for which you want to build, which package types you | ||
| 9923 | wish to use (<code class="filename">PACKAGE_CLASSES</code>), or where you want to downloaded files | ||
| 9924 | (<code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>). | ||
| 9925 | </p></div><div class="section" title="4.2.3. build/conf/bblayers.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-bblayers.conf"></a>4.2.3. <code class="filename">build/conf/bblayers.conf</code></h3></div></div></div><p> | ||
| 9926 | This file defines layers, which is a directory tree, traversed (or walked) by BitBake. | ||
| 9927 | If <code class="filename">bblayers.conf</code> | ||
| 9928 | is not present, it is created from <code class="filename">bblayers.conf.sample</code> when | ||
| 9929 | you <code class="filename">source</code> the environment setup script. | ||
| 9930 | </p></div><div class="section" title="4.2.4. build/conf/sanity_info"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-sanity_info"></a>4.2.4. <code class="filename">build/conf/sanity_info</code></h3></div></div></div><p> | ||
| 9931 | This file is created during the build to indicate the state of the sanity checks. | ||
| 9932 | </p></div><div class="section" title="4.2.5. build/downloads/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-downloads"></a>4.2.5. <code class="filename">build/downloads/</code></h3></div></div></div><p> | ||
| 9933 | This directory is used for the upstream source tarballs. | ||
| 9934 | The directory can be reused by multiple builds or moved to another location. | ||
| 9935 | You can control the location of this directory through the | ||
| 9936 | <code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable. | ||
| 9937 | </p></div><div class="section" title="4.2.6. build/sstate-cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-sstate-cache"></a>4.2.6. <code class="filename">build/sstate-cache/</code></h3></div></div></div><p> | ||
| 9938 | This directory is used for the shared state cache. | ||
| 9939 | The directory can be reused by multiple builds or moved to another location. | ||
| 9940 | You can control the location of this directory through the | ||
| 9941 | <code class="filename"><a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable. | ||
| 9942 | </p></div><div class="section" title="4.2.7. build/tmp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp"></a>4.2.7. <code class="filename">build/tmp/</code></h3></div></div></div><p> | ||
| 9943 | This directory receives all the OpenEmbedded build system's output. | ||
| 9944 | BitBake creates this directory if it does not exist. | ||
| 9945 | As a last resort, to clean up a build and start it from scratch (other than the downloads), | ||
| 9946 | you can remove everything in the <code class="filename">tmp</code> directory or get rid of the | ||
| 9947 | directory completely. | ||
| 9948 | If you do, you should also completely remove the <code class="filename">build/sstate-cache</code> | ||
| 9949 | directory as well. | ||
| 9950 | </p></div><div class="section" title="4.2.8. build/tmp/buildstats/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-buildstats"></a>4.2.8. <code class="filename">build/tmp/buildstats/</code></h3></div></div></div><p> | ||
| 9951 | This directory stores the build statistics. | ||
| 9952 | </p></div><div class="section" title="4.2.9. build/tmp/cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-cache"></a>4.2.9. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p> | ||
| 9953 | When BitBake parses the metadata, it creates a cache file of the result that can | ||
| 9954 | be used when subsequently running commands. | ||
| 9955 | These results are stored here on a per-machine basis. | ||
| 9956 | </p></div><div class="section" title="4.2.10. build/tmp/deploy/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy"></a>4.2.10. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p> | ||
| 9957 | This directory contains any 'end result' output from the OpenEmbedded build process. | ||
| 9958 | </p></div><div class="section" title="4.2.11. build/tmp/deploy/deb/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-deb"></a>4.2.11. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p> | ||
| 9959 | This directory receives any <code class="filename">.deb</code> packages produced by | ||
| 9960 | the build process. | ||
| 9961 | The packages are sorted into feeds for different architecture types. | ||
| 9962 | </p></div><div class="section" title="4.2.12. build/tmp/deploy/rpm/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-rpm"></a>4.2.12. <code class="filename">build/tmp/deploy/rpm/</code></h3></div></div></div><p> | ||
| 9963 | This directory receives any <code class="filename">.rpm</code> packages produced by | ||
| 9964 | the build process. | ||
| 9965 | The packages are sorted into feeds for different architecture types. | ||
| 9966 | </p></div><div class="section" title="4.2.13. build/tmp/deploy/licenses/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-licenses"></a>4.2.13. <code class="filename">build/tmp/deploy/licenses/</code></h3></div></div></div><p> | ||
| 9967 | This directory receives package licensing information. | ||
| 9968 | For example, the directory contains sub-directories for <code class="filename">bash</code>, | ||
| 9969 | <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn | ||
| 9970 | contain appropriate <code class="filename">COPYING</code> license files with other licensing information. | ||
| 9971 | </p></div><div class="section" title="4.2.14. build/tmp/deploy/images/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-images"></a>4.2.14. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p> | ||
| 9972 | This directory receives complete filesystem images. | ||
| 9973 | If you want to flash the resulting image from a build onto a device, look here for the image. | ||
| 9974 | </p><p> | ||
| 9975 | Be careful when deleting files in this directory. | ||
| 9976 | You can safely delete old images from this directory (e.g. | ||
| 9977 | <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>, | ||
| 9978 | etc.). | ||
| 9979 | However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.), | ||
| 9980 | bootloader and other supplementary files might be deployed here prior to building an | ||
| 9981 | image. | ||
| 9982 | Because these files, however, are not directly produced from the image, if you | ||
| 9983 | delete them they will not be automatically re-created when you build the image again. | ||
| 9984 | </p><p> | ||
| 9985 | If you do accidentally delete files here, you will need to force them to be | ||
| 9986 | re-created. | ||
| 9987 | In order to do that, you will need to know the target that produced them. | ||
| 9988 | For example, these commands rebuild and re-create the kernel files: | ||
| 9989 | </p><pre class="literallayout"> | ||
| 9990 | $ bitbake -c clean virtual/kernel | ||
| 9991 | $ bitbake virtual/kernel | ||
| 9992 | </pre><p> | ||
| 9993 | </p></div><div class="section" title="4.2.15. build/tmp/deploy/ipk/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-ipk"></a>4.2.15. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p> | ||
| 9994 | This directory receives <code class="filename">.ipk</code> packages produced by | ||
| 9995 | the build process.</p></div><div class="section" title="4.2.16. build/tmp/sysroots/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-sysroots"></a>4.2.16. <code class="filename">build/tmp/sysroots/</code></h3></div></div></div><p> | ||
| 9996 | This directory contains shared header files and libraries as well as other shared | ||
| 9997 | data. | ||
| 9998 | Packages that need to share output with other packages do so within this directory. | ||
| 9999 | The directory is subdivided by architecture so multiple builds can run within | ||
| 10000 | the one build directory. | ||
| 10001 | </p></div><div class="section" title="4.2.17. build/tmp/stamps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-stamps"></a>4.2.17. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p> | ||
| 10002 | This directory holds information that that BitBake uses for accounting purposes | ||
| 10003 | to track what tasks have run and when they have run. | ||
| 10004 | The directory is sub-divided by architecture. | ||
| 10005 | The files in the directory are empty of data. | ||
| 10006 | However, BitBake uses the filenames and timestamps for tracking purposes. | ||
| 10007 | </p></div><div class="section" title="4.2.18. build/tmp/log/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-log"></a>4.2.18. <code class="filename">build/tmp/log/</code></h3></div></div></div><p> | ||
| 10008 | This directory contains general logs that are not otherwise placed using the | ||
| 10009 | package's <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>. | ||
| 10010 | Examples of logs are the output from the <code class="filename">check_pkg</code> or | ||
| 10011 | <code class="filename">distro_check</code> tasks. | ||
| 10012 | Running a build does not necessarily mean this directory is created. | ||
| 10013 | </p></div><div class="section" title="4.2.19. build/tmp/pkgdata/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-pkgdata"></a>4.2.19. <code class="filename">build/tmp/pkgdata/</code></h3></div></div></div><p> | ||
| 10014 | This directory contains intermediate packaging data that is used later in the packaging process. | ||
| 10015 | For more information, see the "<a class="link" href="#ref-classes-package" title="6.12. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section. | ||
| 10016 | </p></div><div class="section" title="4.2.20. build/tmp/work/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-work"></a>4.2.20. <code class="filename">build/tmp/work/</code></h3></div></div></div><p> | ||
| 10017 | This directory contains architecture-specific work sub-directories for packages built by BitBake. | ||
| 10018 | All tasks execute from a work directory. | ||
| 10019 | For example, the source for a particular package is unpacked, patched, configured and compiled all | ||
| 10020 | within its own work directory. | ||
| 10021 | Within the work directory, organization is based on the package group for which the source | ||
| 10022 | is being compiled. | ||
| 10023 | </p><p> | ||
| 10024 | It is worth considering the structure of a typical work directory. | ||
| 10025 | As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code> | ||
| 10026 | on the machine <code class="filename">qemux86</code> | ||
| 10027 | built within the Yocto Project. | ||
| 10028 | For this package, a work directory of | ||
| 10029 | <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+<.....></code>, | ||
| 10030 | referred to as <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created. | ||
| 10031 | Within this directory, the source is unpacked to | ||
| 10032 | <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt | ||
| 10033 | (see the | ||
| 10034 | "<a class="link" href="#using-a-quilt-workflow" target="_top">Modifying Package | ||
| 10035 | Source Code with Quilt</a>" section in the Yocto Project Development Manual. | ||
| 10036 | Within the <code class="filename">linux-qemux86-standard-build</code> directory, | ||
| 10037 | standard Quilt directories <code class="filename">linux-3.0/patches</code> | ||
| 10038 | and <code class="filename">linux-3.0/.pc</code> are created, | ||
| 10039 | and standard Quilt commands can be used. | ||
| 10040 | </p><p> | ||
| 10041 | There are other directories generated within WORKDIR. | ||
| 10042 | The most important directory is WORKDIR<code class="filename">/temp/</code>, which has log files for each | ||
| 10043 | task (<code class="filename">log.do_*.pid</code>) and contains the scripts BitBake runs for | ||
| 10044 | each task (<code class="filename">run.do_*.pid</code>). | ||
| 10045 | The WORKDIR<code class="filename">/image/</code> directory is where "make | ||
| 10046 | install" places its output that is then split into sub-packages | ||
| 10047 | within WORKDIR<code class="filename">/packages-split/</code>. | ||
| 10048 | </p></div></div><div class="section" title="4.3. The Metadata - meta/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-meta"></a>4.3. The Metadata - <code class="filename">meta/</code></h2></div></div></div><p> | ||
| 10049 | As mentioned previously, metadata is the core of the Yocto Project. | ||
| 10050 | Metadata has several important subdivisions: | ||
| 10051 | </p><div class="section" title="4.3.1. meta/classes/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-classes"></a>4.3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p> | ||
| 10052 | This directory contains the <code class="filename">*.bbclass</code> files. | ||
| 10053 | Class files are used to abstract common code so it can be reused by multiple | ||
| 10054 | packages. | ||
| 10055 | Every package inherits the <code class="filename">base.bbclass</code> file. | ||
| 10056 | Examples of other important classes are <code class="filename">autotools.bbclass</code>, which | ||
| 10057 | in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. | ||
| 10058 | Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions | ||
| 10059 | for working with the Linux kernel. | ||
| 10060 | Functions like image generation or packaging also have their specific class files | ||
| 10061 | such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and | ||
| 10062 | <code class="filename">package*.bbclass</code>. | ||
| 10063 | </p></div><div class="section" title="4.3.2. meta/conf/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf"></a>4.3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p> | ||
| 10064 | This directory contains the core set of configuration files that start from | ||
| 10065 | <code class="filename">bitbake.conf</code> and from which all other configuration | ||
| 10066 | files are included. | ||
| 10067 | See the include statements at the end of the file and you will note that even | ||
| 10068 | <code class="filename">local.conf</code> is loaded from there. | ||
| 10069 | While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override | ||
| 10070 | these by using the (<code class="filename">local.conf</code>) file, machine file or | ||
| 10071 | the distribution configuration file. | ||
| 10072 | </p></div><div class="section" title="4.3.3. meta/conf/machine/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-machine"></a>4.3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p> | ||
| 10073 | This directory contains all the machine configuration files. | ||
| 10074 | If you set <code class="filename">MACHINE="qemux86"</code>, | ||
| 10075 | the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this | ||
| 10076 | directory. | ||
| 10077 | The <code class="filename">include</code> directory contains various data common to multiple machines. | ||
| 10078 | If you want to add support for a new machine to the Yocto Project, look in this directory. | ||
| 10079 | </p></div><div class="section" title="4.3.4. meta/conf/distro/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-distro"></a>4.3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p> | ||
| 10080 | Any distribution-specific configuration is controlled from this directory. | ||
| 10081 | For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here. | ||
| 10082 | This directory includes the versions and the | ||
| 10083 | <code class="filename">SRCDATE</code> definitions for applications that are configured here. | ||
| 10084 | An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>. | ||
| 10085 | Although this file mainly inherits its configuration from Poky. | ||
| 10086 | </p></div><div class="section" title="4.3.5. meta/recipes-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-bsp"></a>4.3.5. <code class="filename">meta/recipes-bsp/</code></h3></div></div></div><p> | ||
| 10087 | This directory contains anything linking to specific hardware or hardware | ||
| 10088 | configuration information such as "u-boot" and "grub". | ||
| 10089 | </p></div><div class="section" title="4.3.6. meta/recipes-connectivity/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-connectivity"></a>4.3.6. <code class="filename">meta/recipes-connectivity/</code></h3></div></div></div><p> | ||
| 10090 | This directory contains libraries and applications related to communication with other devices. | ||
| 10091 | </p></div><div class="section" title="4.3.7. meta/recipes-core/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-core"></a>4.3.7. <code class="filename">meta/recipes-core/</code></h3></div></div></div><p> | ||
| 10092 | This directory contains what is needed to build a basic working Linux image | ||
| 10093 | including commonly used dependencies. | ||
| 10094 | </p></div><div class="section" title="4.3.8. meta/recipes-devtools/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-devtools"></a>4.3.8. <code class="filename">meta/recipes-devtools/</code></h3></div></div></div><p> | ||
| 10095 | This directory contains tools that are primarily used by the build system. | ||
| 10096 | The tools, however, can also be used on targets. | ||
| 10097 | </p></div><div class="section" title="4.3.9. meta/recipes-extended/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-extended"></a>4.3.9. <code class="filename">meta/recipes-extended/</code></h3></div></div></div><p> | ||
| 10098 | This directory contains non-essential applications that add features compared to the | ||
| 10099 | alternatives in core. | ||
| 10100 | You might need this directory for full tool functionality or for Linux Standard Base (LSB) | ||
| 10101 | compliance. | ||
| 10102 | </p></div><div class="section" title="4.3.10. meta/recipes-gnome/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-gnome"></a>4.3.10. <code class="filename">meta/recipes-gnome/</code></h3></div></div></div><p> | ||
| 10103 | This directory contains all things related to the GTK+ application framework. | ||
| 10104 | </p></div><div class="section" title="4.3.11. meta/recipes-graphics/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-graphics"></a>4.3.11. <code class="filename">meta/recipes-graphics/</code></h3></div></div></div><p> | ||
| 10105 | This directory contains X and other graphically related system libraries | ||
| 10106 | </p></div><div class="section" title="4.3.12. meta/recipes-kernel/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-kernel"></a>4.3.12. <code class="filename">meta/recipes-kernel/</code></h3></div></div></div><p> | ||
| 10107 | This directory contains the kernel and generic applications and libraries that | ||
| 10108 | have strong kernel dependencies. | ||
| 10109 | </p></div><div class="section" title="4.3.13. meta/recipes-multimedia/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-multimedia"></a>4.3.13. <code class="filename">meta/recipes-multimedia/</code></h3></div></div></div><p> | ||
| 10110 | This directory contains codecs and support utilities for audio, images and video. | ||
| 10111 | </p></div><div class="section" title="4.3.14. meta/recipes-qt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-qt"></a>4.3.14. <code class="filename">meta/recipes-qt/</code></h3></div></div></div><p> | ||
| 10112 | This directory contains all things related to the Qt application framework. | ||
| 10113 | </p></div><div class="section" title="4.3.15. meta/recipes-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-rt"></a>4.3.15. <code class="filename">meta/recipes-rt/</code></h3></div></div></div><p> | ||
| 10114 | This directory contains package and image recipes for using and testing | ||
| 10115 | the <code class="filename">PREEMPT_RT</code> kernel. | ||
| 10116 | </p></div><div class="section" title="4.3.16. meta/recipes-sato/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-sato"></a>4.3.16. <code class="filename">meta/recipes-sato/</code></h3></div></div></div><p> | ||
| 10117 | This directory contains the Sato demo/reference UI/UX and its associated applications | ||
| 10118 | and configuration data. | ||
| 10119 | </p></div><div class="section" title="4.3.17. meta/recipes-support/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-support"></a>4.3.17. <code class="filename">meta/recipes-support/</code></h3></div></div></div><p> | ||
| 10120 | This directory contains recipes that used by other recipes, but that are not directly | ||
| 10121 | included in images (i.e. dependencies of other recipes). | ||
| 10122 | </p></div><div class="section" title="4.3.18. meta/site/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-site"></a>4.3.18. <code class="filename">meta/site/</code></h3></div></div></div><p> | ||
| 10123 | This directory contains a list of cached results for various architectures. | ||
| 10124 | Because certain "autoconf" test results cannot be determined when cross-compiling due to | ||
| 10125 | the tests not able to run on a live system, the information in this directory is | ||
| 10126 | passed to "autoconf" for the various architectures. | ||
| 10127 | </p></div><div class="section" title="4.3.19. meta/recipes.txt"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-txt"></a>4.3.19. <code class="filename">meta/recipes.txt</code></h3></div></div></div><p> | ||
| 10128 | This file is a description of the contents of <code class="filename">recipes-*</code>. | ||
| 10129 | </p></div></div></div> | ||
| 10130 | |||
| 10131 | <div class="chapter" title="Chapter 5. BitBake"><div class="titlepage"><div><div><h2 class="title"><a id="ref-bitbake"></a>Chapter 5. BitBake</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-bitbake-parsing">5.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">5.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">5.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">5.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">5.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">5.7. Fetchers</a></span></dt></dl></div><p> | ||
| 10132 | BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded | ||
| 10133 | build system. | ||
| 10134 | At some point, developers wonder what actually happens when you enter: | ||
| 10135 | </p><pre class="literallayout"> | ||
| 10136 | $ bitbake core-image-sato | ||
| 10137 | </pre><p> | ||
| 10138 | </p><p> | ||
| 10139 | This chapter provides an overview of what happens behind the scenes from BitBake's perspective. | ||
| 10140 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 10141 | BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships. | ||
| 10142 | As such, it has no real knowledge of what the tasks being executed actually do. | ||
| 10143 | BitBake just considers a list of tasks with dependencies and handles metadata | ||
| 10144 | that consists of variables in a certain format that get passed to the tasks. | ||
| 10145 | </div><div class="section" title="5.1. Parsing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-parsing"></a>5.1. Parsing</h2></div></div></div><p> | ||
| 10146 | BitBake parses configuration files, classes, and <code class="filename">.bb</code> files. | ||
| 10147 | </p><p> | ||
| 10148 | The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file. | ||
| 10149 | This file resides in the | ||
| 10150 | <a class="link" href="#source-directory" target="_top">source directory</a> | ||
| 10151 | within the <code class="filename">meta/conf/</code> directory. | ||
| 10152 | BitBake finds it by examining its | ||
| 10153 | <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment | ||
| 10154 | variable and looking for the <code class="filename">meta/conf/</code> | ||
| 10155 | directory. | ||
| 10156 | </p><p> | ||
| 10157 | The <code class="filename">bitbake.conf</code> file lists other configuration | ||
| 10158 | files to include from a <code class="filename">conf/</code> | ||
| 10159 | directory below the directories listed in <code class="filename">BBPATH</code>. | ||
| 10160 | In general, the most important configuration file from a user's perspective | ||
| 10161 | is <code class="filename">local.conf</code>, which contains a user's customized | ||
| 10162 | settings for the OpenEmbedded build environment. | ||
| 10163 | Other notable configuration files are the distribution | ||
| 10164 | configuration file (set by the | ||
| 10165 | <code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> variable) | ||
| 10166 | and the machine configuration file | ||
| 10167 | (set by the | ||
| 10168 | <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> variable). | ||
| 10169 | The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment | ||
| 10170 | variables are both usually set in | ||
| 10171 | the <code class="filename">local.conf</code> file. | ||
| 10172 | Valid distribution | ||
| 10173 | configuration files are available in the <code class="filename">meta/conf/distro/</code> directory | ||
| 10174 | and valid machine configuration | ||
| 10175 | files in the <code class="filename">meta/conf/machine/</code> directory. | ||
| 10176 | Within the <code class="filename">meta/conf/machine/include/</code> | ||
| 10177 | directory are various <code class="filename">tune-*.inc</code> configuration files that provide common | ||
| 10178 | "tuning" settings specific to and shared between particular architectures and machines. | ||
| 10179 | </p><p> | ||
| 10180 | After the parsing of the configuration files, some standard classes are included. | ||
| 10181 | The <code class="filename">base.bbclass</code> file is always included. | ||
| 10182 | Other classes that are specified in the configuration using the | ||
| 10183 | <code class="filename"><a class="link" href="#var-INHERIT" title="INHERIT">INHERIT</a></code> | ||
| 10184 | variable are also included. | ||
| 10185 | Class files are searched for in a <code class="filename">classes</code> subdirectory | ||
| 10186 | under the paths in <code class="filename">BBPATH</code> in the same way as | ||
| 10187 | configuration files. | ||
| 10188 | </p><p> | ||
| 10189 | After classes are included, the variable | ||
| 10190 | <code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code> | ||
| 10191 | is set, usually in | ||
| 10192 | <code class="filename">local.conf</code>, and defines the list of places to search for | ||
| 10193 | <code class="filename">.bb</code> files. | ||
| 10194 | By default, the <code class="filename">BBFILES</code> variable specifies the | ||
| 10195 | <code class="filename">meta/recipes-*/</code> directory within Poky. | ||
| 10196 | Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of | ||
| 10197 | BitBake layers as described in the | ||
| 10198 | "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding and | ||
| 10199 | Creating Layers</a>" section of the Yocto Project Development Manual. | ||
| 10200 | </p><p> | ||
| 10201 | BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and | ||
| 10202 | stores the values of various variables. | ||
| 10203 | In summary, for each <code class="filename">.bb</code> | ||
| 10204 | file the configuration plus the base class of variables are set, followed | ||
| 10205 | by the data in the <code class="filename">.bb</code> file | ||
| 10206 | itself, followed by any inherit commands that | ||
| 10207 | <code class="filename">.bb</code> file might contain. | ||
| 10208 | </p><p> | ||
| 10209 | Because parsing <code class="filename">.bb</code> files is a time | ||
| 10210 | consuming process, a cache is kept to speed up subsequent parsing. | ||
| 10211 | This cache is invalid if the timestamp of the <code class="filename">.bb</code> | ||
| 10212 | file itself changes, or if the timestamps of any of the include, | ||
| 10213 | configuration or class files the <code class="filename">.bb</code> | ||
| 10214 | file depends on changes. | ||
| 10215 | </p></div><div class="section" title="5.2. Preferences and Providers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-providers"></a>5.2. Preferences and Providers</h2></div></div></div><p> | ||
| 10216 | Once all the <code class="filename">.bb</code> files have been | ||
| 10217 | parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code> | ||
| 10218 | in the previous section's example) and looks for providers of that target. | ||
| 10219 | Once a provider is selected, BitBake resolves all the dependencies for | ||
| 10220 | the target. | ||
| 10221 | In the case of <code class="filename">core-image-sato</code>, it would lead to | ||
| 10222 | <code class="filename">task-base.bb</code>, | ||
| 10223 | which in turn leads to packages like <code class="filename">Contacts</code>, | ||
| 10224 | <code class="filename">Dates</code> and <code class="filename">BusyBox</code>. | ||
| 10225 | These packages in turn depend on <code class="filename">eglibc</code> and the toolchain. | ||
| 10226 | </p><p> | ||
| 10227 | Sometimes a target might have multiple providers. | ||
| 10228 | A common example is "virtual/kernel", which is provided by each kernel package. | ||
| 10229 | Each machine often selects the best kernel provider by using a line similar to the | ||
| 10230 | following in the machine configuration file: | ||
| 10231 | </p><pre class="literallayout"> | ||
| 10232 | PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" | ||
| 10233 | </pre><p> | ||
| 10234 | The default <code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code> | ||
| 10235 | is the provider with the same name as the target. | ||
| 10236 | </p><p> | ||
| 10237 | Understanding how providers are chosen is made complicated by the fact | ||
| 10238 | that multiple versions might exist. | ||
| 10239 | BitBake defaults to the highest version of a provider. | ||
| 10240 | Version comparisons are made using the same method as Debian. | ||
| 10241 | You can use the | ||
| 10242 | <code class="filename"><a class="link" href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code> | ||
| 10243 | variable to specify a particular version (usually in the distro configuration). | ||
| 10244 | You can influence the order by using the | ||
| 10245 | <code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code> | ||
| 10246 | variable. | ||
| 10247 | By default, files have a preference of "0". | ||
| 10248 | Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the | ||
| 10249 | package unlikely to be used unless it is explicitly referenced. | ||
| 10250 | Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used. | ||
| 10251 | <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting. | ||
| 10252 | <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package | ||
| 10253 | versions until they have undergone sufficient testing to be considered stable. | ||
| 10254 | </p><p> | ||
| 10255 | In summary, BitBake has created a list of providers, which is prioritized, for each target. | ||
| 10256 | </p></div><div class="section" title="5.3. Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-dependencies"></a>5.3. Dependencies</h2></div></div></div><p> | ||
| 10257 | Each target BitBake builds consists of multiple tasks such as | ||
| 10258 | <code class="filename">fetch</code>, <code class="filename">unpack</code>, | ||
| 10259 | <code class="filename">patch</code>, <code class="filename">configure</code>, | ||
| 10260 | and <code class="filename">compile</code>. | ||
| 10261 | For best performance on multi-core systems, BitBake considers each task as an independent | ||
| 10262 | entity with its own set of dependencies. | ||
| 10263 | </p><p> | ||
| 10264 | Dependencies are defined through several variables. | ||
| 10265 | You can find information about variables BitBake uses in the | ||
| 10266 | <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">BitBake manual</a>. | ||
| 10267 | At a basic level, it is sufficient to know that BitBake uses the | ||
| 10268 | <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and | ||
| 10269 | <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when | ||
| 10270 | calculating dependencies. | ||
| 10271 | </p></div><div class="section" title="5.4. The Task List"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-tasklist"></a>5.4. The Task List</h2></div></div></div><p> | ||
| 10272 | Based on the generated list of providers and the dependency information, | ||
| 10273 | BitBake can now calculate exactly what tasks it needs to run and in what | ||
| 10274 | order it needs to run them. | ||
| 10275 | The build now starts with BitBake forking off threads up to the limit set in the | ||
| 10276 | <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></code> variable. | ||
| 10277 | BitBake continues to fork threads as long as there are tasks ready to run, | ||
| 10278 | those tasks have all their dependencies met, and the thread threshold has not been | ||
| 10279 | exceeded. | ||
| 10280 | </p><p> | ||
| 10281 | It is worth noting that you can greatly speed up the build time by properly setting | ||
| 10282 | the <code class="filename">BB_NUMBER_THREADS</code> variable. | ||
| 10283 | See the | ||
| 10284 | "<a class="link" href="#building-image" target="_top">Building an Image</a>" | ||
| 10285 | section in the Yocto Project Quick Start for more information. | ||
| 10286 | </p><p> | ||
| 10287 | As each task completes, a timestamp is written to the directory specified by the | ||
| 10288 | <code class="filename"><a class="link" href="#var-STAMP" title="STAMP">STAMP</a></code> variable (usually | ||
| 10289 | <code class="filename">build/tmp/stamps/*/</code>). | ||
| 10290 | On subsequent runs, BitBake looks at the <code class="filename">/build/tmp/stamps</code> | ||
| 10291 | directory and does not rerun | ||
| 10292 | tasks that are already completed unless a timestamp is found to be invalid. | ||
| 10293 | Currently, invalid timestamps are only considered on a per | ||
| 10294 | <code class="filename">.bb</code> file basis. | ||
| 10295 | So, for example, if the configure stamp has a timestamp greater than the | ||
| 10296 | compile timestamp for a given target, then the compile task would rerun. | ||
| 10297 | Running the compile task again, however, has no effect on other providers | ||
| 10298 | that depend on that target. | ||
| 10299 | This behavior could change or become configurable in future versions of BitBake. | ||
| 10300 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 10301 | Some tasks are marked as "nostamp" tasks. | ||
| 10302 | No timestamp file is created when these tasks are run. | ||
| 10303 | Consequently, "nostamp" tasks are always rerun. | ||
| 10304 | </div></div><div class="section" title="5.5. Running a Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-runtask"></a>5.5. Running a Task</h2></div></div></div><p> | ||
| 10305 | Tasks can either be a shell task or a Python task. | ||
| 10306 | For shell tasks, BitBake writes a shell script to | ||
| 10307 | <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> and then executes the script. | ||
| 10308 | The generated shell script contains all the exported variables, and the shell functions | ||
| 10309 | with all variables expanded. | ||
| 10310 | Output from the shell script goes to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. | ||
| 10311 | Looking at the expanded shell functions in the run file and the output in the log files | ||
| 10312 | is a useful debugging technique. | ||
| 10313 | </p><p> | ||
| 10314 | For Python tasks, BitBake executes the task internally and logs information to the | ||
| 10315 | controlling terminal. | ||
| 10316 | Future versions of BitBake will write the functions to files similar to the way | ||
| 10317 | shell tasks are handled. | ||
| 10318 | Logging will be handled in way similar to shell tasks as well. | ||
| 10319 | </p><p> | ||
| 10320 | Once all the tasks have been completed BitBake exits. | ||
| 10321 | </p><p> | ||
| 10322 | When running a task, BitBake tightly controls the execution environment | ||
| 10323 | of the build tasks to make sure unwanted contamination from the build machine | ||
| 10324 | cannot influence the build. | ||
| 10325 | Consequently, if you do want something to get passed into the build | ||
| 10326 | task's environment, you must take a few steps: | ||
| 10327 | </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Tell BitBake to load what you want from the environment | ||
| 10328 | into the data store. | ||
| 10329 | You can do so through the <code class="filename">BB_ENV_WHITELIST</code> | ||
| 10330 | variable. | ||
| 10331 | For example, assume you want to prevent the build system from | ||
| 10332 | accessing your <code class="filename">$HOME/.ccache</code> directory. | ||
| 10333 | The following command tells BitBake to load | ||
| 10334 | <code class="filename">CCACHE_DIR</code> from the environment into the data | ||
| 10335 | store: | ||
| 10336 | </p><pre class="literallayout"> | ||
| 10337 | export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" | ||
| 10338 | </pre></li><li class="listitem"><p>Tell BitBake to export what you have loaded into the | ||
| 10339 | environment store to the task environment of every running task. | ||
| 10340 | Loading something from the environment into the data store | ||
| 10341 | (previous step) only makes it available in the datastore. | ||
| 10342 | To export it to the task environment of every running task, | ||
| 10343 | use a command similar to the following in your | ||
| 10344 | <code class="filename">local.conf</code> or distro configuration file: | ||
| 10345 | </p><pre class="literallayout"> | ||
| 10346 | export CCACHE_DIR | ||
| 10347 | </pre></li></ol></div><p> | ||
| 10348 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 10349 | A side effect of the previous steps is that BitBake records the variable | ||
| 10350 | as a dependency of the build process in things like the shared state | ||
| 10351 | checksums. | ||
| 10352 | If doing so results in unnecessary rebuilds of tasks, you can whitelist the | ||
| 10353 | variable so that the shared state code ignores the dependency when it creates | ||
| 10354 | checksums. | ||
| 10355 | For information on this process, see the <code class="filename">BB_HASHBASE_WHITELIST</code> | ||
| 10356 | example in the "<a class="link" href="#checksums" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section. | ||
| 10357 | </div></div><div class="section" title="5.6. BitBake Command Line"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-commandline"></a>5.6. BitBake Command Line</h2></div></div></div><p> | ||
| 10358 | Following is the BitBake help output: | ||
| 10359 | </p><pre class="screen"> | ||
| 10360 | $ bitbake --help | ||
| 10361 | Usage: bitbake [options] [package ...] | ||
| 10362 | |||
| 10363 | Executes the specified task (default is 'build') for a given set of BitBake files. | ||
| 10364 | It expects that BBFILES is defined, which is a space separated list of files to | ||
| 10365 | be executed. BBFILES does support wildcards. | ||
| 10366 | Default BBFILES are the .bb files in the current directory. | ||
| 10367 | |||
| 10368 | Options: | ||
| 10369 | --version show program's version number and exit | ||
| 10370 | -h, --help show this help message and exit | ||
| 10371 | -b BUILDFILE, --buildfile=BUILDFILE | ||
| 10372 | execute the task against this .bb file, rather than a | ||
| 10373 | package from BBFILES. Does not handle any | ||
| 10374 | dependencies. | ||
| 10375 | -k, --continue continue as much as possible after an error. While the | ||
| 10376 | target that failed, and those that depend on it, | ||
| 10377 | cannot be remade, the other dependencies of these | ||
| 10378 | targets can be processed all the same. | ||
| 10379 | -a, --tryaltconfigs continue with builds by trying to use alternative | ||
| 10380 | providers where possible. | ||
| 10381 | -f, --force force run of specified cmd, regardless of stamp status | ||
| 10382 | -c CMD, --cmd=CMD Specify task to execute. Note that this only executes | ||
| 10383 | the specified task for the providee and the packages | ||
| 10384 | it depends on, i.e. 'compile' does not implicitly call | ||
| 10385 | stage for the dependencies (IOW: use only if you know | ||
| 10386 | what you are doing). Depending on the base.bbclass a | ||
| 10387 | listtasks tasks is defined and will show available | ||
| 10388 | tasks | ||
| 10389 | -r PREFILE, --read=PREFILE | ||
| 10390 | read the specified file before bitbake.conf | ||
| 10391 | -R POSTFILE, --postread=POSTFILE | ||
| 10392 | read the specified file after bitbake.conf | ||
| 10393 | -v, --verbose output more chit-chat to the terminal | ||
| 10394 | -D, --debug Increase the debug level. You can specify this more | ||
| 10395 | than once. | ||
| 10396 | -n, --dry-run don't execute, just go through the motions | ||
| 10397 | -S, --dump-signatures | ||
| 10398 | don't execute, just dump out the signature | ||
| 10399 | construction information | ||
| 10400 | -p, --parse-only quit after parsing the BB files (developers only) | ||
| 10401 | -s, --show-versions show current and preferred versions of all packages | ||
| 10402 | -e, --environment show the global or per-package environment (this is | ||
| 10403 | what used to be bbread) | ||
| 10404 | -g, --graphviz emit the dependency trees of the specified packages in | ||
| 10405 | the dot syntax | ||
| 10406 | -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED | ||
| 10407 | Assume these dependencies don't exist and are already | ||
| 10408 | provided (equivalent to ASSUME_PROVIDED). Useful to | ||
| 10409 | make dependency graphs more appealing | ||
| 10410 | -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS | ||
| 10411 | Show debug logging for the specified logging domains | ||
| 10412 | -P, --profile profile the command and print a report | ||
| 10413 | -u UI, --ui=UI userinterface to use | ||
| 10414 | -t SERVERTYPE, --servertype=SERVERTYPE | ||
| 10415 | Choose which server to use, none, process or xmlrpc | ||
| 10416 | --revisions-changed Set the exit code depending on whether upstream | ||
| 10417 | floating revisions have changed or not | ||
| 10418 | </pre></div><div class="section" title="5.7. Fetchers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-fetchers"></a>5.7. Fetchers</h2></div></div></div><p> | ||
| 10419 | BitBake also contains a set of "fetcher" modules that allow | ||
| 10420 | retrieval of source code from various types of sources. | ||
| 10421 | For example, BitBake can get source code from a disk with the metadata, from websites, | ||
| 10422 | from remote shell accounts or from Source Code Management (SCM) systems | ||
| 10423 | like <code class="filename">cvs/subversion/git</code>. | ||
| 10424 | </p><p> | ||
| 10425 | Fetchers are usually triggered by entries in | ||
| 10426 | <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>. | ||
| 10427 | You can find information about the options and formats of entries for specific | ||
| 10428 | fetchers in the <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">BitBake manual</a>. | ||
| 10429 | </p><p> | ||
| 10430 | One useful feature for certain Source Code Manager (SCM) fetchers is the ability to | ||
| 10431 | "auto-update" when the upstream SCM changes version. | ||
| 10432 | Since this ability requires certain functionality from the SCM, not all | ||
| 10433 | systems support it. | ||
| 10434 | Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". | ||
| 10435 | This feature works using the <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code> | ||
| 10436 | variable. | ||
| 10437 | See the | ||
| 10438 | "<a class="link" href="#platdev-appdev-srcrev" target="_top">Using an External SCM</a>" section | ||
| 10439 | in the Yocto Project Development Manual for more information. | ||
| 10440 | </p></div></div> | ||
| 10441 | |||
| 10442 | <div class="chapter" title="Chapter 6. Classes"><div class="titlepage"><div><div><h2 class="title"><a id="ref-classes"></a>Chapter 6. Classes</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-classes-base">6.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">6.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">6.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">6.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">6.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">6.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">6.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">6.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">6.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">6.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">6.12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">6.13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">6.14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">6.15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">6.16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">6.17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">6.18. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">6.19. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">6.20. Other Classes</a></span></dt></dl></div><p> | ||
| 10443 | Class files are used to abstract common functionality and share it amongst multiple | ||
| 10444 | <code class="filename">.bb</code> files. | ||
| 10445 | Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class | ||
| 10446 | file. | ||
| 10447 | Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed | ||
| 10448 | in a <code class="filename">classes/</code> directory beneath the | ||
| 10449 | <code class="filename">meta*/</code> directory found in the | ||
| 10450 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 10451 | Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as | ||
| 10452 | <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. | ||
| 10453 | Class files are searched for in <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> | ||
| 10454 | using the same method by which <code class="filename">.conf</code> files are searched. | ||
| 10455 | </p><p> | ||
| 10456 | In most cases inheriting the class is enough to enable its features, although | ||
| 10457 | for some classes you might need to set variables or override some of the | ||
| 10458 | default behaviour. | ||
| 10459 | </p><div class="section" title="6.1. The base class - base.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-base"></a>6.1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p> | ||
| 10460 | The base class is special in that every <code class="filename">.bb</code> | ||
| 10461 | file inherits it automatically. | ||
| 10462 | This class contains definitions for standard basic | ||
| 10463 | tasks such as fetching, unpacking, configuring (empty by default), compiling | ||
| 10464 | (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging | ||
| 10465 | (empty by default). | ||
| 10466 | These classes are often overridden or extended by other classes | ||
| 10467 | such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>. | ||
| 10468 | The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>. | ||
| 10469 | </p></div><div class="section" title="6.2. Autotooled Packages - autotools.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-autotools"></a>6.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p> | ||
| 10470 | Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>, | ||
| 10471 | and <code class="filename">libtool</code>) bring standardization. | ||
| 10472 | This class defines a set of tasks (configure, compile etc.) that | ||
| 10473 | work for all Autotooled packages. | ||
| 10474 | It should usually be enough to define a few standard variables | ||
| 10475 | and then simply <code class="filename">inherit autotools</code>. | ||
| 10476 | This class can also work with software that emulates Autotools. | ||
| 10477 | For more information, see the | ||
| 10478 | "<a class="link" href="#usingpoky-extend-addpkg-autotools" target="_top">Autotooled Package</a>" | ||
| 10479 | section in the Yocto Project Development Manual. | ||
| 10480 | </p><p> | ||
| 10481 | It's useful to have some idea of how the tasks defined by this class work | ||
| 10482 | and what they do behind the scenes. | ||
| 10483 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">do_configure</code> ‐ regenerates the | ||
| 10484 | configure script (using <code class="filename">autoreconf</code>) and then launches it | ||
| 10485 | with a standard set of arguments used during cross-compilation. | ||
| 10486 | You can pass additional parameters to <code class="filename">configure</code> through the | ||
| 10487 | <code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable. | ||
| 10488 | </p></li><li class="listitem"><p><code class="filename">do_compile</code> ‐ runs <code class="filename">make</code> with | ||
| 10489 | arguments that specify the compiler and linker. | ||
| 10490 | You can pass additional arguments through | ||
| 10491 | the <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable. | ||
| 10492 | </p></li><li class="listitem"><p><code class="filename">do_install</code> ‐ runs <code class="filename">make install</code> | ||
| 10493 | and passes a DESTDIR option, which takes its value from the standard | ||
| 10494 | <code class="filename"><a class="link" href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable. | ||
| 10495 | </p></li></ul></div><p> | ||
| 10496 | </p></div><div class="section" title="6.3. Alternatives - update-alternatives.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-alternatives"></a>6.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p> | ||
| 10497 | Several programs can fulfill the same or similar function and be installed with the same name. | ||
| 10498 | For example, the <code class="filename">ar</code> command is available from the | ||
| 10499 | <code class="filename">busybox</code>, <code class="filename">binutils</code> and | ||
| 10500 | <code class="filename">elfutils</code> packages. | ||
| 10501 | The <code class="filename">update-alternatives.bbclass</code> class handles renaming the | ||
| 10502 | binaries so that multiple packages can be installed without conflicts. | ||
| 10503 | The <code class="filename">ar</code> command still works regardless of which packages are installed | ||
| 10504 | or subsequently removed. | ||
| 10505 | The class renames the conflicting binary in each package and symlinks the highest | ||
| 10506 | priority binary during installation or removal of packages. | ||
| 10507 | </p><p> | ||
| 10508 | Four variables control this class: | ||
| 10509 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> ‐ The name of the | ||
| 10510 | binary that is replaced (<code class="filename">ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> ‐ The path to | ||
| 10511 | the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> ‐ The path to the | ||
| 10512 | real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> ‐ The priority of | ||
| 10513 | the binary. | ||
| 10514 | The version with the most features should have the highest priority.</p></li></ul></div><p> | ||
| 10515 | </p><p> | ||
| 10516 | Currently, the OpenEmbedded build system supports only one binary per package. | ||
| 10517 | </p></div><div class="section" title="6.4. Initscripts - update-rc.d.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-rc.d"></a>6.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p> | ||
| 10518 | This class uses <code class="filename">update-rc.d</code> to safely install an | ||
| 10519 | initialization script on behalf of the package. | ||
| 10520 | The OpenEmbedded build system takes care of details such as making sure the script is stopped before | ||
| 10521 | a package is removed and started when the package is installed. | ||
| 10522 | Three variables control this class: | ||
| 10523 | <code class="filename"><a class="link" href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>, | ||
| 10524 | <code class="filename"><a class="link" href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and | ||
| 10525 | <code class="filename"><a class="link" href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>. | ||
| 10526 | See the variable links for details. | ||
| 10527 | </p></div><div class="section" title="6.5. Binary config scripts - binconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-binconfig"></a>6.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p> | ||
| 10528 | Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell | ||
| 10529 | scripts to give information about the libraries and include paths needed | ||
| 10530 | to build software (usually named <code class="filename">LIBNAME-config</code>). | ||
| 10531 | This class assists any recipe using such scripts. | ||
| 10532 | </p><p> | ||
| 10533 | During staging, BitBake installs such scripts into the | ||
| 10534 | <code class="filename">sysroots/</code> directory. | ||
| 10535 | BitBake also changes all paths to point into the <code class="filename">sysroots/</code> | ||
| 10536 | directory so all builds that use the script will use the correct | ||
| 10537 | directories for the cross compiling layout. | ||
| 10538 | </p></div><div class="section" title="6.6. Debian renaming - debian.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-debian"></a>6.6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p> | ||
| 10539 | This class renames packages so that they follow the Debian naming | ||
| 10540 | policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code> | ||
| 10541 | and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>. | ||
| 10542 | </p></div><div class="section" title="6.7. Pkg-config - pkgconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-pkgconfig"></a>6.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p> | ||
| 10543 | <code class="filename">pkg-config</code> brought standardization and this class aims to make its | ||
| 10544 | integration smooth for all libraries that make use of it. | ||
| 10545 | </p><p> | ||
| 10546 | During staging, BitBake installs <code class="filename">pkg-config</code> data into the | ||
| 10547 | <code class="filename">sysroots/</code> directory. | ||
| 10548 | By making use of sysroot functionality within <code class="filename">pkg-config</code>, | ||
| 10549 | this class no longer has to manipulate the files. | ||
| 10550 | </p></div><div class="section" title="6.8. Distribution of sources - src_distribute_local.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-src-distribute"></a>6.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p> | ||
| 10551 | Many software licenses require that source files be provided along with the binaries. | ||
| 10552 | To simplify this process, two classes were created: | ||
| 10553 | <code class="filename">src_distribute.bbclass</code> and | ||
| 10554 | <code class="filename">src_distribute_local.bbclass</code>. | ||
| 10555 | </p><p> | ||
| 10556 | The results of these classes are <code class="filename">tmp/deploy/source/</code> | ||
| 10557 | subdirs with sources sorted by | ||
| 10558 | <code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a></code> field. | ||
| 10559 | If recipes list few licenses (or have entries like "Bitstream Vera"), | ||
| 10560 | the source archive is placed in each license directory. | ||
| 10561 | </p><p> | ||
| 10562 | This class operates using three modes: | ||
| 10563 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the | ||
| 10564 | distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the | ||
| 10565 | distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into | ||
| 10566 | the distribute directory and then symlinks them back.</p></li></ul></div><p> | ||
| 10567 | </p></div><div class="section" title="6.9. Perl modules - cpan.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-perl"></a>6.9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p> | ||
| 10568 | Recipes for Perl modules are simple. | ||
| 10569 | These recipes usually only need to point to the source's archive and then inherit the | ||
| 10570 | proper <code class="filename">.bbclass</code> file. | ||
| 10571 | Building is split into two methods depending on which method the module authors used. | ||
| 10572 | </p><p> | ||
| 10573 | Modules that use old <code class="filename">Makefile.PL</code>-based build system require | ||
| 10574 | <code class="filename">cpan.bbclass</code> in their recipes. | ||
| 10575 | </p><p> | ||
| 10576 | Modules that use <code class="filename">Build.PL</code>-based build system require | ||
| 10577 | using <code class="filename">cpan_build.bbclass</code> in their recipes. | ||
| 10578 | </p></div><div class="section" title="6.10. Python extensions - distutils.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-distutils"></a>6.10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p> | ||
| 10579 | Recipes for Python extensions are simple. | ||
| 10580 | These recipes usually only need to point to the source's archive and then inherit | ||
| 10581 | the proper <code class="filename">.bbclass</code> file. | ||
| 10582 | Building is split into two methods dependling on which method the module authors used. | ||
| 10583 | </p><p> | ||
| 10584 | Extensions that use an Autotools-based build system require Autotools and | ||
| 10585 | <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes. | ||
| 10586 | </p><p> | ||
| 10587 | Extensions that use <code class="filename">distutils</code>-based build systems require | ||
| 10588 | <code class="filename">distutils.bbclass</code> in their recipes. | ||
| 10589 | </p></div><div class="section" title="6.11. Developer Shell - devshell.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-devshell"></a>6.11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p> | ||
| 10590 | This class adds the <code class="filename">devshell</code> task. | ||
| 10591 | Distribution policy dictates whether to include this class. | ||
| 10592 | See the | ||
| 10593 | "<a class="link" href="#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section | ||
| 10594 | in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>. | ||
| 10595 | </p></div><div class="section" title="6.12. Packaging - package*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-package"></a>6.12. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p> | ||
| 10596 | The packaging classes add support for generating packages from a build's | ||
| 10597 | output. | ||
| 10598 | The core generic functionality is in <code class="filename">package.bbclass</code>. | ||
| 10599 | The code specific to particular package types is contained in various sub-classes such as | ||
| 10600 | <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>, | ||
| 10601 | and <code class="filename">package_rpm.bbclass</code>. | ||
| 10602 | Most users will want one or more of these classes. | ||
| 10603 | </p><p> | ||
| 10604 | You can control the list of resulting package formats by using the | ||
| 10605 | <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code> | ||
| 10606 | variable defined in the <code class="filename">local.conf</code> configuration file, | ||
| 10607 | which is located in the <code class="filename">conf</code> folder of the | ||
| 10608 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 10609 | When defining the variable, you can specify one or more package types. | ||
| 10610 | Since images are generated from packages, a packaging class is | ||
| 10611 | needed to enable image generation. | ||
| 10612 | The first class listed in this variable is used for image generation. | ||
| 10613 | </p><p> | ||
| 10614 | The package class you choose can affect build-time performance and has space | ||
| 10615 | ramifications. | ||
| 10616 | In general, building a package with RPM takes about thirty percent more time as | ||
| 10617 | compared to using IPK to build the same or similar package. | ||
| 10618 | This comparison takes into account a complete build of the package with all | ||
| 10619 | dependencies previously built. | ||
| 10620 | The reason for this discrepancy is because the RPM package manager creates and | ||
| 10621 | processes more metadata than the IPK package manager. | ||
| 10622 | Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code> | ||
| 10623 | to "package_ipk" if you are building smaller systems. | ||
| 10624 | </p><p> | ||
| 10625 | Keep in mind, however, that RPM starts to provide more abilities than IPK due to | ||
| 10626 | the fact that it processes more metadata. | ||
| 10627 | For example, this information includes individual file types, file checksum generation | ||
| 10628 | and evaluation on install, sparse file support, conflict detection and resolution | ||
| 10629 | for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks. | ||
| 10630 | </p><p> | ||
| 10631 | Another consideration for packages built using the RPM package manager is space. | ||
| 10632 | For smaller systems, the extra space used for the Berkley Database and the amount | ||
| 10633 | of metadata can affect your ability to do on-device upgrades. | ||
| 10634 | </p><p> | ||
| 10635 | You can find additional information on the effects of the package class at these | ||
| 10636 | two Yocto Project mailing list links: | ||
| 10637 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_top"> | ||
| 10638 | https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_top"> | ||
| 10639 | https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li></ul></div><p> | ||
| 10640 | </p></div><div class="section" title="6.13. Building kernels - kernel.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-kernel"></a>6.13. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p> | ||
| 10641 | This class handles building Linux kernels. | ||
| 10642 | The class contains code to build all kernel trees. | ||
| 10643 | All needed headers are staged into the | ||
| 10644 | <code class="filename"><a class="link" href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code> | ||
| 10645 | directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>. | ||
| 10646 | </p><p> | ||
| 10647 | This means that each built kernel module is packaged separately and inter-module | ||
| 10648 | dependencies are created by parsing the <code class="filename">modinfo</code> output. | ||
| 10649 | If all modules are required, then installing the <code class="filename">kernel-modules</code> | ||
| 10650 | package installs all packages with modules and various other kernel packages | ||
| 10651 | such as <code class="filename">kernel-vmlinux</code>. | ||
| 10652 | </p><p> | ||
| 10653 | Various other classes are used by the kernel and module classes internally including | ||
| 10654 | <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>, | ||
| 10655 | <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>. | ||
| 10656 | </p></div><div class="section" title="6.14. Creating images - image.bbclass and rootfs*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-image"></a>6.14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p> | ||
| 10657 | These classes add support for creating images in several formats. | ||
| 10658 | First, the root filesystem is created from packages using | ||
| 10659 | one of the <code class="filename">rootfs_*.bbclass</code> | ||
| 10660 | files (depending on the package format used) and then the image is created. | ||
| 10661 | </p><p> | ||
| 10662 | The <code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code> | ||
| 10663 | variable controls the types of images to generate. | ||
| 10664 | </p><p> | ||
| 10665 | The <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code> | ||
| 10666 | variable controls the list of packages to install into the image. | ||
| 10667 | </p></div><div class="section" title="6.15. Host System sanity checks - sanity.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-sanity"></a>6.15. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p> | ||
| 10668 | This class checks to see if prerequisite software is present so that | ||
| 10669 | users can be notified of potential problems that might affect their build. | ||
| 10670 | The class also performs basic user configuration checks from | ||
| 10671 | the <code class="filename">local.conf</code> configuration file to | ||
| 10672 | prevent common mistakes that cause build failures. | ||
| 10673 | Distribution policy usually determines whether to include this class. | ||
| 10674 | </p></div><div class="section" title="6.16. Generated output quality assurance checks - insane.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-insane"></a>6.16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p> | ||
| 10675 | This class adds a step to the package generation process that sanity checks the | ||
| 10676 | packages generated by the OpenEmbedded build system. | ||
| 10677 | A range of checks are performed that check the build's output | ||
| 10678 | for common problems that show up during runtime. | ||
| 10679 | Distribution policy usually dictates whether to include this class. | ||
| 10680 | </p><p> | ||
| 10681 | You can configure the sanity checks so that specific test failures either raise a warning or | ||
| 10682 | an error message. | ||
| 10683 | Typically, failures for new tests generate a warning. | ||
| 10684 | Subsequent failures for the same test would then generate an error message | ||
| 10685 | once the metadata is in a known and good condition. | ||
| 10686 | You use the <code class="filename">WARN_QA</code> variable to specify tests for which you | ||
| 10687 | want to generate a warning message on failure. | ||
| 10688 | You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you | ||
| 10689 | want to generate an error message on failure. | ||
| 10690 | </p><p> | ||
| 10691 | The following list shows the tests you can list with the <code class="filename">WARN_QA</code> | ||
| 10692 | and <code class="filename">ERROR_QA</code> variables: | ||
| 10693 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span> | ||
| 10694 | Ensures that the binaries were linked with the | ||
| 10695 | <code class="filename">LDFLAGS</code> options provided by the build system. | ||
| 10696 | If this test fails, check that the <code class="filename">LDFLAGS</code> variable | ||
| 10697 | is being passed to the linker command.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span> | ||
| 10698 | Checks for dynamic library load paths (rpaths) in the binaries that | ||
| 10699 | by default on a standard system are searched by the linker (e.g. | ||
| 10700 | <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>). | ||
| 10701 | While these paths will not cause any breakage, they do waste space and | ||
| 10702 | are unnecessary.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span> | ||
| 10703 | Checks for rpaths in the binaries that contain build system paths such | ||
| 10704 | as <code class="filename">TMPDIR</code>. | ||
| 10705 | If this test fails, bad <code class="filename">-rpath</code> options are being | ||
| 10706 | passed to the linker commands and your binaries have potential security | ||
| 10707 | issues.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span> | ||
| 10708 | Checks that the <code class="filename">.so</code> symbolic links are in the | ||
| 10709 | <code class="filename">-dev</code> package and not in any of the other packages. | ||
| 10710 | In general, these symlinks are only useful for development purposes. | ||
| 10711 | Thus, the <code class="filename">-dev</code> package is the correct location for | ||
| 10712 | them. | ||
| 10713 | Some very rare cases do exist for dynamically loaded modules where | ||
| 10714 | these symlinks are needed instead in the main package. | ||
| 10715 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span> | ||
| 10716 | Checks for <code class="filename">.debug</code> directories in anything but the | ||
| 10717 | <code class="filename">-dbg</code> package. | ||
| 10718 | The debug files should all be in the <code class="filename">-dbg</code> package. | ||
| 10719 | Thus, anything packaged elsewhere is incorrect packaging.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span> | ||
| 10720 | Checks the Executable and Linkable Format (ELF) type, bit size and endianness | ||
| 10721 | of any binaries to ensure it matches the target architecture. | ||
| 10722 | This test fails if any binaries don't match the type since there would be an | ||
| 10723 | incompatibility. | ||
| 10724 | Sometimes software, like bootloaders, might need to bypass this check. | ||
| 10725 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span> | ||
| 10726 | Checks that <code class="filename">-dbg</code> packages only depend on other | ||
| 10727 | <code class="filename">-dbg</code> packages and not on any other types of packages, | ||
| 10728 | which would cause a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span> | ||
| 10729 | Checks that <code class="filename">-dev</code> packages only depend on other | ||
| 10730 | <code class="filename">-dev</code> packages and not on any other types of packages, | ||
| 10731 | which would be a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span> | ||
| 10732 | Checks <code class="filename">.pc</code> files for any | ||
| 10733 | <code class="filename">TMPDIR/WORKDIR</code> paths. | ||
| 10734 | Any <code class="filename">.pc</code> file containing these paths is incorrect | ||
| 10735 | since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix | ||
| 10736 | when the files are accessed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span> | ||
| 10737 | Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code> | ||
| 10738 | paths. | ||
| 10739 | Any <code class="filename">.la</code> file continaing these paths is incorrect since | ||
| 10740 | <code class="filename">libtool</code> adds the correct sysroot prefix when using the | ||
| 10741 | files automatically itself.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span> | ||
| 10742 | Runs the <code class="filename">desktop-file-validate</code> program against any | ||
| 10743 | <code class="filename">.desktop</code> files to validate their contents against | ||
| 10744 | the specification for <code class="filename">.desktop</code> files.</p></li></ul></div><p> | ||
| 10745 | </p></div><div class="section" title="6.17. Autotools configuration data cache - siteinfo.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-siteinfo"></a>6.17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p> | ||
| 10746 | Autotools can require tests that must execute on the target hardware. | ||
| 10747 | Since this is not possible in general when cross compiling, site information is | ||
| 10748 | used to provide cached test results so these tests can be skipped over but | ||
| 10749 | still make the correct values available. | ||
| 10750 | The <code class="filename"><a class="link" href="#structure-meta-site" title="4.3.18. meta/site/">meta/site directory</a></code> | ||
| 10751 | contains test results sorted into different categories such as architecture, endianness, and | ||
| 10752 | the <code class="filename">libc</code> used. | ||
| 10753 | Site information provides a list of files containing data relevant to | ||
| 10754 | the current build in the | ||
| 10755 | <code class="filename"><a class="link" href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable | ||
| 10756 | that Autotools automatically picks up. | ||
| 10757 | </p><p> | ||
| 10758 | The class also provides variables like | ||
| 10759 | <code class="filename"><a class="link" href="#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code> | ||
| 10760 | and <code class="filename"><a class="link" href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code> | ||
| 10761 | that can be used elsewhere in the metadata. | ||
| 10762 | </p><p> | ||
| 10763 | Because this class is included from <code class="filename">base.bbclass</code>, it is always active. | ||
| 10764 | </p></div><div class="section" title="6.18. Adding Users - useradd.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-useradd"></a>6.18. Adding Users - <code class="filename">useradd.bbclass</code></h2></div></div></div><p> | ||
| 10765 | If you have packages that install files that are owned by custom users or groups, | ||
| 10766 | you can use this class to specify those packages and associate the users and groups | ||
| 10767 | with those packages. | ||
| 10768 | The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code> | ||
| 10769 | recipe in the <a class="link" href="#source-directory" target="_top">source directory</a> | ||
| 10770 | provides a simple exmample that shows how to add three | ||
| 10771 | users and groups to two packages. | ||
| 10772 | See the <code class="filename">useradd-example.bb</code> for more information on how to | ||
| 10773 | use this class. | ||
| 10774 | </p></div><div class="section" title="6.19. Using External Source - externalsrc.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-externalsrc"></a>6.19. Using External Source - <code class="filename">externalsrc.bbclass</code></h2></div></div></div><p> | ||
| 10775 | You can use this class to build software from source code that is external to the | ||
| 10776 | OpenEmbedded build system. | ||
| 10777 | In other words, your source code resides in an external tree outside of the Yocto Project. | ||
| 10778 | Building software from an external source tree means that the normal fetch, unpack, and | ||
| 10779 | patch process is not used. | ||
| 10780 | </p><p> | ||
| 10781 | To use the class, you need to define the | ||
| 10782 | <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> variable to point to the directory that contains the source files. | ||
| 10783 | You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class. | ||
| 10784 | </p><p> | ||
| 10785 | This class expects the source code to support recipe builds that use the | ||
| 10786 | <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable to point to the directory in | ||
| 10787 | which the OpenEmbedded build system places the generated objects built from the recipes. | ||
| 10788 | By default, the <code class="filename">B</code> directory is set to the following, which is separate from the | ||
| 10789 | source directory (<code class="filename">S</code>): | ||
| 10790 | </p><pre class="literallayout"> | ||
| 10791 | ${WORKDIR}/${BPN}-{PV}/ | ||
| 10792 | </pre><p> | ||
| 10793 | See the glossary entries for the | ||
| 10794 | <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>, | ||
| 10795 | <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a>, | ||
| 10796 | <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>, | ||
| 10797 | <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>, and | ||
| 10798 | <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> for more information. | ||
| 10799 | </p><p> | ||
| 10800 | You can build object files in the external tree by setting the | ||
| 10801 | <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>. | ||
| 10802 | However, this practice does not work well if you use the source for more than one variant | ||
| 10803 | (i.e., "natives" such as <code class="filename">quilt-native</code>, | ||
| 10804 | or "crosses" such as <code class="filename">gcc-cross</code>). | ||
| 10805 | So, be sure there are no "native", "cross", or "multilib" variants of the recipe. | ||
| 10806 | </p><p> | ||
| 10807 | If you do want to build different variants of a recipe, you can use the | ||
| 10808 | <a class="link" href="#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable. | ||
| 10809 | When you do, the <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable must support the | ||
| 10810 | recipe's ability to build variants in different working directories. | ||
| 10811 | Most autotools-based recipes support separating these directories. | ||
| 10812 | The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code> | ||
| 10813 | and some kernel recipes. | ||
| 10814 | Alternatively, you can make sure that separate recipes exist that each | ||
| 10815 | use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant. | ||
| 10816 | The separate recipes can inherit a single target recipe. | ||
| 10817 | </p><p> | ||
| 10818 | For information on how to use this class, see the | ||
| 10819 | "<a class="link" href="#building-software-from-an-external-source" target="_top">Building | ||
| 10820 | Software from an External Source</a>" section in the Yocto Project Development Manual. | ||
| 10821 | </p></div><div class="section" title="6.20. Other Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-others"></a>6.20. Other Classes</h2></div></div></div><p> | ||
| 10822 | Thus far, this chapter has discussed only the most useful and important | ||
| 10823 | classes. | ||
| 10824 | However, other classes exist within the <code class="filename">meta/classes</code> directory | ||
| 10825 | in the <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 10826 | You can examine the <code class="filename">.bbclass</code> files directly for more | ||
| 10827 | information. | ||
| 10828 | </p></div></div> | ||
| 10829 | |||
| 10830 | <div class="chapter" title="Chapter 7. Images"><div class="titlepage"><div><div><h2 class="title"><a id="ref-images"></a>Chapter 7. Images</h2></div></div></div><p> | ||
| 10831 | The OpenEmbedded build process supports several types of images to satisfy different needs. | ||
| 10832 | When you issue the <code class="filename">bitbake</code> command you provide a “top-level” recipe | ||
| 10833 | that essentially begins the build for the type of image you want. | ||
| 10834 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 10835 | Building an image without GNU Public License Version 3 (GPLv3) components is | ||
| 10836 | only supported for minimal and base images. | ||
| 10837 | Furthermore, if you are going to build an image using non-GPLv3 components, | ||
| 10838 | you must make the following changes in the <code class="filename">local.conf</code> file | ||
| 10839 | before using the BitBake command to build the minimal or base image: | ||
| 10840 | <pre class="literallayout"> | ||
| 10841 | 1. Comment out the EXTRA_IMAGE_FEATURES line | ||
| 10842 | 2. Set INCOMPATIBLE_LICENSE = "GPLv3" | ||
| 10843 | </pre></div><p> | ||
| 10844 | From within the <code class="filename">poky</code> Git repository, use the following command to list | ||
| 10845 | the supported images: | ||
| 10846 | </p><pre class="literallayout"> | ||
| 10847 | $ ls meta*/recipes*/images/*.bb | ||
| 10848 | </pre><p> | ||
| 10849 | These recipes reside in the <code class="filename">meta/recipes-core/images</code>, | ||
| 10850 | <code class="filename">meta/recipes-extended/images</code>, | ||
| 10851 | <code class="filename">meta/recipes-graphics/images</code>, and | ||
| 10852 | <code class="filename">meta/recipes-sato/images</code> directories | ||
| 10853 | within the <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 10854 | Although the recipe names are somewhat explanatory, here is a list that describes them: | ||
| 10855 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span> | ||
| 10856 | A console-only image that fully supports the target device hardware.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-core</code>:</em></span> | ||
| 10857 | An X11 image with simple applications such as terminal, editor, and file manager. | ||
| 10858 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span> | ||
| 10859 | A small image just capable of allowing a device to boot.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span> | ||
| 10860 | A <code class="filename">core-image-minimal</code> image suitable for development work | ||
| 10861 | using the host. | ||
| 10862 | The image includes headers and libraries you can use in a host development | ||
| 10863 | environment. | ||
| 10864 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span> | ||
| 10865 | A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based | ||
| 10866 | Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel, | ||
| 10867 | which allows the system to find the first “init” program more efficiently. | ||
| 10868 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span> | ||
| 10869 | A <code class="filename">core-image-minimal</code> image that has support | ||
| 10870 | for the Minimal MTD Utilities, which let the user interact with the | ||
| 10871 | MTD subsystem in the kernel to perform operations on flash devices. | ||
| 10872 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span> | ||
| 10873 | A foundational basic image without support for X that can be reasonably used for | ||
| 10874 | customization.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span> | ||
| 10875 | A <code class="filename">core-image-basic</code> image suitable for implementations | ||
| 10876 | that conform to Linux Standard Base (LSB).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span> | ||
| 10877 | A <code class="filename">core-image-lsb</code> image that is suitable for development work | ||
| 10878 | using the host. | ||
| 10879 | The image includes headers and libraries you can use in a host development | ||
| 10880 | environment. | ||
| 10881 | </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span> | ||
| 10882 | A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain | ||
| 10883 | but also includes development headers and libraries to form a complete standalone SDK. | ||
| 10884 | This image is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span> | ||
| 10885 | An image with support for the Open GL-based toolkit Clutter, which enables development of | ||
| 10886 | rich and animated graphical user interfaces.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span> | ||
| 10887 | An image with Sato support, a mobile environment and visual style that works well | ||
| 10888 | with mobile devices. | ||
| 10889 | The image supports X11 with a Sato theme and Pimlico applications and also | ||
| 10890 | contains terminal, editor, and file manager.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span> | ||
| 10891 | A <code class="filename">core-image-sato</code> image suitable for development | ||
| 10892 | using the host. | ||
| 10893 | The image includes libraries needed to build applications on the device itself, | ||
| 10894 | testing and profiling tools, and debug symbols. | ||
| 10895 | This image was formerly <code class="filename">core-image-sdk</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span> | ||
| 10896 | A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain. | ||
| 10897 | The image also includes development headers and libraries to form a complete standalone SDK | ||
| 10898 | and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span> | ||
| 10899 | A <code class="filename">core-image-minimal</code> image plus a real-time test suite and | ||
| 10900 | tools appropriate for real-time use.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span> | ||
| 10901 | A <code class="filename">core-image-rt</code> image that includes everything in | ||
| 10902 | <code class="filename">meta-toolchain</code>. | ||
| 10903 | The image also includes development headers and libraries to form a complete | ||
| 10904 | stand-alone SDK and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span> | ||
| 10905 | An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code> | ||
| 10906 | instead of X11. | ||
| 10907 | In order to build, this image requires specific distro configuration that enables | ||
| 10908 | <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span> | ||
| 10909 | An image you can boot and run using either the | ||
| 10910 | <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_top">VMware Player</a> | ||
| 10911 | or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_top">VMware Workstation</a>. | ||
| 10912 | For more information on this image, see the | ||
| 10913 | <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> page on | ||
| 10914 | the Yocto Project website.</p></li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> | ||
| 10915 | From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and | ||
| 10916 | <code class="filename">-directdisk</code> images have been replaced by a "live" | ||
| 10917 | option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an | ||
| 10918 | image file that can be | ||
| 10919 | copied directly to a CD or USB device and run as is. | ||
| 10920 | To build a live image, simply add | ||
| 10921 | "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code> | ||
| 10922 | file or wherever appropriate and then build the desired image as normal. | ||
| 10923 | </div></div> | ||
| 10924 | |||
| 10925 | <div class="chapter" title="Chapter 8. Reference: Features"><div class="titlepage"><div><div><h2 class="title"><a id="ref-features"></a>Chapter 8. Reference: Features</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-features-distro">8.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">8.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">8.3. Reference: Images</a></span></dt></dl></div><p> | ||
| 10926 | Features provide a mechanism for working out which packages | ||
| 10927 | should be included in the generated images. | ||
| 10928 | Distributions can select which features they want to support through the | ||
| 10929 | <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code> | ||
| 10930 | variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file. | ||
| 10931 | Machine features are set in the | ||
| 10932 | <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code> | ||
| 10933 | variable, which is set in the machine configuration file and | ||
| 10934 | specifies the hardware features for a given machine. | ||
| 10935 | </p><p> | ||
| 10936 | These two variables combine to work out which kernel modules, | ||
| 10937 | utilities, and other packages to include. | ||
| 10938 | A given distribution can support a selected subset of features so some machine features might not | ||
| 10939 | be included if the distribution itself does not support them. | ||
| 10940 | </p><div class="section" title="8.1. Distro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-distro"></a>8.1. Distro</h2></div></div></div><p> | ||
| 10941 | The items below are valid options for | ||
| 10942 | <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>: | ||
| 10943 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility | ||
| 10944 | kernel modules will be installed if available).</p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only) | ||
| 10945 | </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal | ||
| 10946 | HDD/Microdrive for storing files (instead of Flash only devices) | ||
| 10947 | </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support | ||
| 10948 | </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be | ||
| 10949 | loaded during boot). | ||
| 10950 | </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support | ||
| 10951 | </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support | ||
| 10952 | </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB | ||
| 10953 | networking/serial/storage) | ||
| 10954 | </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external | ||
| 10955 | keyboard, mouse, storage, network etc) | ||
| 10956 | </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only) | ||
| 10957 | </p></li><li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support | ||
| 10958 | </p></li><li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support | ||
| 10959 | </p></li><li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support | ||
| 10960 | </p></li><li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on | ||
| 10961 | device)</p></li><li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li><li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting | ||
| 10962 | Samba/Microsoft Windows shares on device)</p></li></ul></div><p> | ||
| 10963 | </p></div><div class="section" title="8.2. Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-machine"></a>8.2. Machine</h2></div></div></div><p> | ||
| 10964 | The items below are valid options for | ||
| 10965 | <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>: | ||
| 10966 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only) | ||
| 10967 | </p></li><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers | ||
| 10968 | </p></li><li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation) | ||
| 10969 | </p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT | ||
| 10970 | </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive | ||
| 10971 | </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support | ||
| 10972 | </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard | ||
| 10973 | </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus | ||
| 10974 | </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets | ||
| 10975 | </p></li><li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen | ||
| 10976 | </p></li><li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232) | ||
| 10977 | </p></li><li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen | ||
| 10978 | </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable | ||
| 10979 | </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable | ||
| 10980 | </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi | ||
| 10981 | </p></li></ul></div><p> | ||
| 10982 | </p></div><div class="section" title="8.3. Reference: Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-image"></a>8.3. Reference: Images</h2></div></div></div><p> | ||
| 10983 | The contents of images generated by the OpenEmbedded build system can be controlled by the | ||
| 10984 | <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> | ||
| 10985 | and <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> | ||
| 10986 | variables that you typically configure in your image recipes. | ||
| 10987 | Through these variables you can add several different | ||
| 10988 | predefined packages such as development utilities or packages with debug | ||
| 10989 | information needed to investigate application problems or profile applications. | ||
| 10990 | </p><p> | ||
| 10991 | Current list of | ||
| 10992 | <code class="filename">IMAGE_FEATURES</code> contains the following: | ||
| 10993 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>apps-console-core:</em></span> Core console applications such as | ||
| 10994 | <code class="filename">ssh</code>, <code class="filename">daemon</code>, <code class="filename">avahi daemon</code>, | ||
| 10995 | <code class="filename">portmap</code> (for mounting NFS shares)</p></li><li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> X11 server + minimal desktop</p></li><li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> OpenedHand Sato environment</p></li><li class="listitem"><p><span class="emphasis"><em>apps-x11-core:</em></span> Core X11 applications such as an | ||
| 10996 | X Terminal, file manager, and file editor</p></li><li class="listitem"><p><span class="emphasis"><em>apps-x11-games:</em></span> A set of X11 games</p></li><li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> A full SDK that runs on the device | ||
| 10997 | </p></li><li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Debugging tools such as | ||
| 10998 | <code class="filename">strace</code> and <code class="filename">gdb</code> | ||
| 10999 | </p></li><li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Profiling tools such as | ||
| 11000 | <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and | ||
| 11001 | <code class="filename">LTTng</code></p></li><li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Device testing tools (e.g. | ||
| 11002 | touchscreen debugging)</p></li><li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> NFS server (exports / over NFS | ||
| 11003 | to everybody)</p></li><li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Development packages (headers and | ||
| 11004 | extra library links) for all packages installed in a given image</p></li><li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Debug packages for all packages | ||
| 11005 | installed in a given image</p></li></ul></div><p> | ||
| 11006 | </p></div></div> | ||
| 11007 | |||
| 11008 | <div class="chapter" title="Chapter 9. Variables Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glos"></a>Chapter 9. Variables Glossary</h2></div></div></div><div class="toc"><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p> | ||
| 11009 | This chapter lists common variables used in the OpenEmbedded build system and gives an overview | ||
| 11010 | of their function and contents. | ||
| 11011 | </p><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glossary"></a>Glossary</h2></div></div></div><p> | ||
| 11012 | <a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a> | ||
| 11013 | <a class="link" href="#var-B" title="B">B</a> | ||
| 11014 | <a class="link" href="#var-CFLAGS" title="CFLAGS">C</a> | ||
| 11015 | <a class="link" href="#var-D" title="D">D</a> | ||
| 11016 | <a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a> | ||
| 11017 | <a class="link" href="#var-FILES" title="FILES">F</a> | ||
| 11018 | |||
| 11019 | <a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">H</a> | ||
| 11020 | <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a> | ||
| 11021 | |||
| 11022 | <a class="link" href="#var-KBRANCH" title="KBRANCH">K</a> | ||
| 11023 | <a class="link" href="#var-LAYERDIR" title="LAYERDIR">L</a> | ||
| 11024 | <a class="link" href="#var-MACHINE" title="MACHINE">M</a> | ||
| 11025 | |||
| 11026 | |||
| 11027 | <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">P</a> | ||
| 11028 | |||
| 11029 | <a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">R</a> | ||
| 11030 | <a class="link" href="#var-S" title="S">S</a> | ||
| 11031 | <a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">T</a> | ||
| 11032 | |||
| 11033 | |||
| 11034 | <a class="link" href="#var-WORKDIR" title="WORKDIR">W</a> | ||
| 11035 | |||
| 11036 | |||
| 11037 | |||
| 11038 | </p><div class="glossdiv" title="A"><h3 class="title">A</h3><dl><dt><a id="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt><dd><p> | ||
| 11039 | Specifies if an output package should still be produced if it is empty. | ||
| 11040 | By default, BitBake does not produce empty packages. | ||
| 11041 | This default behavior can cause issues when there is an | ||
| 11042 | <a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or | ||
| 11043 | some other runtime hard-requirement on the existence of the package. | ||
| 11044 | </p><p> | ||
| 11045 | Like all package-controlling variables, you must always use them in | ||
| 11046 | conjunction with a package name override. | ||
| 11047 | Here is an example: | ||
| 11048 | </p><pre class="literallayout"> | ||
| 11049 | ALLOW_EMPTY_${PN} | ||
| 11050 | </pre><p> | ||
| 11051 | </p></dd><dt><a id="var-AUTHOR"></a>AUTHOR</dt><dd><p>The email address used to contact the original author or authors in | ||
| 11052 | order to send patches, forward bugs, etc.</p></dd><dt><a id="var-AUTOREV"></a>AUTOREV</dt><dd><p>Specifies to use the current (newest) source revision. | ||
| 11053 | This variable is with the <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code> | ||
| 11054 | variable.</p></dd></dl></div><div class="glossdiv" title="B"><h3 class="title">B</h3><dl><dt><a id="var-B"></a>B</dt><dd><p> | ||
| 11055 | The directory in which the OpenEmbedded build system places | ||
| 11056 | generated objects during a recipe's build process. | ||
| 11057 | By default, this directory is the same as the <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> | ||
| 11058 | directory: | ||
| 11059 | </p><pre class="literallayout"> | ||
| 11060 | B = ${WORKDIR}/${BPN}-{PV}/ | ||
| 11061 | </pre><p> | ||
| 11062 | You can separate the source directory (<code class="filename">S</code>) and the directory pointed to | ||
| 11063 | by the <code class="filename">B</code> variable. | ||
| 11064 | Most autotools-based recipes support separating these directories. | ||
| 11065 | The build system defaults to using separate directories for <code class="filename">gcc</code> | ||
| 11066 | and some kernel recipes. | ||
| 11067 | </p></dd><dt><a id="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt><dd><p> | ||
| 11068 | A list of packages not to install despite being recommended by a recipe. | ||
| 11069 | Support for this variable exists only for images that use the | ||
| 11070 | <code class="filename">ipkg</code> packaging system. | ||
| 11071 | </p></dd><dt><a id="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt><dd><p> | ||
| 11072 | Allows you to extend a recipe so that it builds variants of the software. | ||
| 11073 | Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>, | ||
| 11074 | which is a copy of quilt built to run on the build system; | ||
| 11075 | "crosses" such as <code class="filename">gcc-cross</code>, | ||
| 11076 | which is a compiler built to run on the build machine but produces binaries | ||
| 11077 | that run on the target <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>; | ||
| 11078 | "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>; | ||
| 11079 | and "mulitlibs" in the form "<code class="filename">multilib:<multilib_name></code>". | ||
| 11080 | </p><p> | ||
| 11081 | To build a different variant of the recipe with a minimal amount of code, it usually | ||
| 11082 | is as simple as adding the following to your recipe: | ||
| 11083 | </p><pre class="literallayout"> | ||
| 11084 | BBCLASSEXTEND =+ "native nativesdk" | ||
| 11085 | BBCLASSEXTEND =+ "multilib:<multilib_name>" | ||
| 11086 | </pre><p> | ||
| 11087 | </p></dd><dt><a id="var-BBMASK"></a>BBMASK</dt><dd><p>Prevents BitBake from processing recipes and recipe append files. | ||
| 11088 | You can use the <code class="filename">BBMASK</code> variable to "hide" | ||
| 11089 | these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files. | ||
| 11090 | BitBake ignores any recipe or recipe append files that match the expression. | ||
| 11091 | It is as if BitBake does not see them at all. | ||
| 11092 | Consequently, matching files are not parsed or otherwise used by | ||
| 11093 | BitBake.</p><p>The value you provide is passed to python's regular expression compiler. | ||
| 11094 | For complete syntax information, see python's documentation at | ||
| 11095 | <a class="ulink" href="http://docs.python.org/release/2.3/lib/re-syntax.html" target="_top">http://docs.python.org/release/2.3/lib/re-syntax.html</a>. | ||
| 11096 | The expression is compared against the full paths to the files. | ||
| 11097 | For example, the following uses a complete regular expression to tell | ||
| 11098 | BitBake to ignore all recipe and recipe append files in the | ||
| 11099 | <code class="filename">.*/meta-ti/recipes-misc/</code> directory: | ||
| 11100 | </p><pre class="literallayout"> | ||
| 11101 | BBMASK = ".*/meta-ti/recipes-misc/" | ||
| 11102 | </pre><p>Use the <code class="filename">BBMASK</code> variable from within the | ||
| 11103 | <code class="filename">conf/local.conf</code> file found | ||
| 11104 | in the <a class="link" href="#build-directory" target="_top">build directory</a>.</p></dd><dt><a id="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>The maximum number of tasks BitBake should run in parallel at any one time. | ||
| 11105 | If your host development system supports multiple cores a good rule of thumb | ||
| 11106 | is to set this variable to twice the number of cores.</p></dd><dt><a id="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt><dd><p>Lists the names of configured layers. | ||
| 11107 | These names are used to find the other <code class="filename">BBFILE_*</code> | ||
| 11108 | variables. | ||
| 11109 | Typically, each layer will append its name to this variable in its | ||
| 11110 | <code class="filename">conf/layer.conf</code> file. | ||
| 11111 | </p></dd><dt><a id="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt><dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer. | ||
| 11112 | This variable is used in the <code class="filename">conf/layer.conf</code> file and must | ||
| 11113 | be suffixed with the name of the specific layer (e.g. | ||
| 11114 | <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd><dt><a id="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt><dd><p>Assigns the priority for recipe files in each layer.</p><p>This variable is useful in situations where the same package appears in | ||
| 11115 | more than one layer. | ||
| 11116 | Setting this variable allows you to prioritize a | ||
| 11117 | layer against other layers that contain the same package - effectively | ||
| 11118 | letting you control the precedence for the multiple layers. | ||
| 11119 | The precedence established through this variable stands regardless of a | ||
| 11120 | layer's package version (<code class="filename">PV</code> variable). | ||
| 11121 | For example, a layer that has a package with a higher <code class="filename">PV</code> value but for | ||
| 11122 | which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a | ||
| 11123 | lower precedence.</p><p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher | ||
| 11124 | precedence. | ||
| 11125 | For example, the value 6 has a higher precedence than the value 5. | ||
| 11126 | If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer | ||
| 11127 | dependencies (see the | ||
| 11128 | <code class="filename"><a class="link" href="#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for | ||
| 11129 | more information. | ||
| 11130 | The default priority, if unspecified | ||
| 11131 | for a layer with no dependencies, is the lowest defined priority + 1 | ||
| 11132 | (or 1 if no priorities are defined).</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> | ||
| 11133 | You can use the command <code class="filename">bitbake-layers show_layers</code> to list | ||
| 11134 | all configured layers along with their priorities. | ||
| 11135 | </div></dd><dt><a id="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipe files used by BitBake to build software</p></dd><dt><a id="var-BBPATH"></a>BBPATH</dt><dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files. | ||
| 11136 | This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd><dt><a id="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd><dt><a id="var-BBLAYERS"></a>BBLAYERS</dt><dd><p>Lists the layers to enable during the build. | ||
| 11137 | This variable is defined in the <code class="filename">bblayers.conf</code> configuration | ||
| 11138 | file in the <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 11139 | Here is an example: | ||
| 11140 | </p><pre class="literallayout"> | ||
| 11141 | BBLAYERS = " \ | ||
| 11142 | /home/scottrif/poky/meta \ | ||
| 11143 | /home/scottrif/poky/meta-yocto \ | ||
| 11144 | /home/scottrif/poky/meta-mykernel \ | ||
| 11145 | " | ||
| 11146 | </pre><p> | ||
| 11147 | This example enables three layers, one of which is a custom, user-defined layer | ||
| 11148 | named <code class="filename">meta-mykernel</code>. | ||
| 11149 | </p></dd><dt><a id="var-BPN"></a>BPN</dt><dd><p>Bare name of package with any suffixes like -cross -native removed.</p></dd></dl></div><div class="glossdiv" title="C"><h3 class="title">C</h3><dl><dt><a id="var-CFLAGS"></a>CFLAGS</dt><dd><p> | ||
| 11150 | Flags passed to C compiler for the target system. | ||
| 11151 | This variable evaluates to the same as | ||
| 11152 | <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>. | ||
| 11153 | </p></dd><dt><a id="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt><dd><p>A regular expression which evaluates to match the machines the recipe | ||
| 11154 | works with. | ||
| 11155 | It stops recipes being run on machines for which they are not compatible. | ||
| 11156 | This is particularly useful with kernels. | ||
| 11157 | It also helps to increase parsing speed as further parsing of the recipe is skipped | ||
| 11158 | if it is found the current machine is not compatible.</p></dd><dt><a id="var-CONFFILES"></a>CONFFILES</dt><dd><p> | ||
| 11159 | Identifies editable or configurable files that are part of a package. | ||
| 11160 | If the Package Management System (PMS) is being used to update | ||
| 11161 | packages on the target system, it is possible that | ||
| 11162 | configuration files you have changed after the original installation | ||
| 11163 | and that you now want to remain unchanged are overwritten. | ||
| 11164 | In other words, editable files might exist in the package that you do not | ||
| 11165 | want reset as part of the package update process. | ||
| 11166 | You can use the <code class="filename">CONFFILES</code> variable to list the files in the | ||
| 11167 | package that you wish to prevent the PMS from overwriting during this update process. | ||
| 11168 | </p><p> | ||
| 11169 | To use the <code class="filename">CONFFILES</code> variable, provide a package name | ||
| 11170 | override that identifies the package. | ||
| 11171 | Then, provide a space-separated list of files. | ||
| 11172 | Here is an example: | ||
| 11173 | </p><pre class="literallayout"> | ||
| 11174 | CONFFILES_${PN} += "${sysconfdir}/file1 \ | ||
| 11175 | ${sysconfdir}/file2 ${sysconfdir}/file3" | ||
| 11176 | </pre><p> | ||
| 11177 | </p><p> | ||
| 11178 | A relationship exists between the <code class="filename">CONFFILES</code> and | ||
| 11179 | <code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a></code> variables. | ||
| 11180 | The files listed within <code class="filename">CONFFILES</code> must be a subset of | ||
| 11181 | the files listed within <code class="filename">FILES</code>. | ||
| 11182 | Because the configuration files you provide with <code class="filename">CONFFILES</code> | ||
| 11183 | are simply being identified so that the PMS will not overwrite them, | ||
| 11184 | it makes sense that | ||
| 11185 | the files must already be included as part of the package through the | ||
| 11186 | <code class="filename">FILES</code> variable. | ||
| 11187 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 11188 | When specifying paths as part of the <code class="filename">CONFFILES</code> variable, | ||
| 11189 | it is good practice to use appropriate path variables. | ||
| 11190 | For example, <code class="filename">${sysconfdir}</code> rather than | ||
| 11191 | <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather | ||
| 11192 | than <code class="filename">/usr/bin</code>. | ||
| 11193 | You can find a list of these variables at the top of the | ||
| 11194 | <code class="filename">/meta/conf/bitbake.conf</code> file in the | ||
| 11195 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 11196 | </div></dd><dt><a id="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p> | ||
| 11197 | A list of files that contains <code class="filename">autoconf</code> test results relevant | ||
| 11198 | to the current build. | ||
| 11199 | This variable is used by the Autotools utilities when running | ||
| 11200 | <code class="filename">configure</code>. | ||
| 11201 | </p></dd><dt><a id="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt><dd><p> | ||
| 11202 | Specifies the list of packages to be added to the image. | ||
| 11203 | This variable should only be set in the <code class="filename">local.conf</code> | ||
| 11204 | configuration file found in the | ||
| 11205 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 11206 | </p><p> | ||
| 11207 | This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported. | ||
| 11208 | </p></dd></dl></div><div class="glossdiv" title="D"><h3 class="title">D</h3><dl><dt><a id="var-D"></a>D</dt><dd><p>The destination directory.</p></dd><dt><a id="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p> | ||
| 11209 | Specifies to build packages with debugging information. | ||
| 11210 | This influences the value of the | ||
| 11211 | <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code> | ||
| 11212 | variable. | ||
| 11213 | </p></dd><dt><a id="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p> | ||
| 11214 | The options to pass in | ||
| 11215 | <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> | ||
| 11216 | and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling | ||
| 11217 | a system for debugging. | ||
| 11218 | This variable defaults to "-O -fno-omit-frame-pointer -g". | ||
| 11219 | </p></dd><dt><a id="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Specifies the priority of recipes.</p></dd><dt><a id="var-DEPENDS"></a>DEPENDS</dt><dd><p> | ||
| 11220 | A list of build-time dependencies for a given recipe. | ||
| 11221 | The variable indicates recipes that must have been staged before a | ||
| 11222 | particular recipe can configure. | ||
| 11223 | </p></dd><dt><a id="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>The package description used by package managers.</p></dd><dt><a id="var-DESTDIR"></a>DESTDIR</dt><dd><p>the destination directory.</p></dd><dt><a id="var-DISTRO"></a>DISTRO</dt><dd><p>The short name of the distribution.</p></dd><dt><a id="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p></p><p>The list of packages which extend usability of the image. | ||
| 11224 | Those packages will automatically be installed but can be removed by user.</p></dd><dt><a id="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>The features of the distribution.</p></dd><dt><a id="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>The long name of the distribution.</p></dd><dt><a id="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt><dd><p>Alias names used for the recipe in various Linux distributions.</p><p>See the | ||
| 11225 | "<a class="link" href="#usingpoky-configuring-DISTRO_PN_ALIAS" target="_top">Handling | ||
| 11226 | a Package Name Alias</a>" section in the Yocto Project Development | ||
| 11227 | Manual for more information.</p></dd><dt><a id="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>the version of the distribution.</p></dd><dt><a id="var-DL_DIR"></a>DL_DIR</dt><dd><p> | ||
| 11228 | The central download directory used by the build process to store downloads. | ||
| 11229 | You can set this directory by defining the <code class="filename">DL_DIR</code> | ||
| 11230 | variable in the <code class="filename">/conf/local.conf</code> file. | ||
| 11231 | This directory is self-maintaining and you should not have | ||
| 11232 | to touch it. | ||
| 11233 | By default, the directory is <code class="filename">downloads</code> in the | ||
| 11234 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 11235 | </p><pre class="literallayout"> | ||
| 11236 | #DL_DIR ?= "${TOPDIR}/downloads" | ||
| 11237 | </pre><p> | ||
| 11238 | To specify a different download directory, simply uncomment the line | ||
| 11239 | and provide your directory. | ||
| 11240 | </p><p> | ||
| 11241 | During a first build, the system downloads many different source code | ||
| 11242 | tarballs from various upstream projects. | ||
| 11243 | Downloading can take a while, particularly if your network | ||
| 11244 | connection is slow. | ||
| 11245 | Tarballs are all stored in the directory defined by | ||
| 11246 | <code class="filename">DL_DIR</code> and the build system looks there first | ||
| 11247 | to find source tarballs. | ||
| 11248 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 11249 | When wiping and rebuilding, you can preserve this directory to speed | ||
| 11250 | up this part of subsequent builds. | ||
| 11251 | </div><p> | ||
| 11252 | </p><p> | ||
| 11253 | You can safely share this directory between multiple builds on the | ||
| 11254 | same development machine. | ||
| 11255 | For additional information on how the build process gets source files | ||
| 11256 | when working behind a firewall or proxy server, see the | ||
| 11257 | "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server">FAQ</a>" | ||
| 11258 | chapter. | ||
| 11259 | </p></dd></dl></div><div class="glossdiv" title="E"><h3 class="title">E</h3><dl><dt><a id="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p></p><p>Variable that controls which locales for <code class="filename">eglibc</code> are | ||
| 11260 | to be generated during the build (useful if the target device has 64Mbytes | ||
| 11261 | of RAM or less).</p></dd><dt><a id="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt><dd><p>Allows extra packages to be added to the generated images. | ||
| 11262 | You set this variable in the <code class="filename">local.conf</code> | ||
| 11263 | configuration file. | ||
| 11264 | Note that some image features are also added using the | ||
| 11265 | <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> | ||
| 11266 | variable generally configured in image recipes. | ||
| 11267 | You can use this variable to add more features in addition to those. | ||
| 11268 | Here are some examples of features you can add:</p><pre class="literallayout"> | ||
| 11269 | "dbg-pkgs" - Adds -dbg packages for all installed packages | ||
| 11270 | including symbol information for debugging and | ||
| 11271 | profiling. | ||
| 11272 | |||
| 11273 | "dev-pkgs" - Adds -dev packages for all installed packages. | ||
| 11274 | This is useful if you want to develop against | ||
| 11275 | the libraries in the image. | ||
| 11276 | |||
| 11277 | "tools-sdk" - Adds development tools such as gcc, make, | ||
| 11278 | pkgconfig and so forth. | ||
| 11279 | |||
| 11280 | "tools-debug" - Adds debugging tools such as gdb and | ||
| 11281 | strace. | ||
| 11282 | |||
| 11283 | "tools-profile" - Adds profiling tools such as oprofile, | ||
| 11284 | exmap, lttng and valgrind (x86 only). | ||
| 11285 | |||
| 11286 | "tools-testapps" - Adds useful testing tools such as | ||
| 11287 | ts_print, aplay, arecord and so | ||
| 11288 | forth. | ||
| 11289 | |||
| 11290 | "debug-tweaks" - Makes an image suitable for development. | ||
| 11291 | For example, ssh root access has a blank | ||
| 11292 | password. You should remove this feature | ||
| 11293 | before you produce a production image. | ||
| 11294 | |||
| 11295 | There are other application targets too, see | ||
| 11296 | <code class="filename">meta/classes/poky-image.bbclass</code> | ||
| 11297 | and <code class="filename">meta/packages/tasks/task-poky.bb</code> | ||
| 11298 | for more details. | ||
| 11299 | </pre></dd><dt><a id="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt><dd><p>A list of recipes to be built that do not provide packages to be installed in | ||
| 11300 | the root filesystem. | ||
| 11301 | </p><p>Sometimes a recipe is required to build the final image but is not | ||
| 11302 | needed in the root filesystem. | ||
| 11303 | You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to | ||
| 11304 | list these recipes and thus, specify the dependencies. | ||
| 11305 | A typical example is a required bootloader in a machine configuration. | ||
| 11306 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 11307 | To add packages to the root filesystem, see the various | ||
| 11308 | <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code> | ||
| 11309 | variables. | ||
| 11310 | </div></dd><dt><a id="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt><dd><p>Additional <code class="filename">cmake</code> options.</p></dd><dt><a id="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional <code class="filename">configure</code> script options.</p></dd><dt><a id="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU <code class="filename">make</code> options.</p></dd></dl></div><div class="glossdiv" title="F"><h3 class="title">F</h3><dl><dt><a id="var-FILES"></a>FILES</dt><dd><p> | ||
| 11311 | The list of directories or files that are placed in packages. | ||
| 11312 | </p><p> | ||
| 11313 | To use the <code class="filename">FILES</code> variable, provide a package name | ||
| 11314 | override that identifies the package. | ||
| 11315 | Then, provide a space-separated list of files or paths that identifies the | ||
| 11316 | files you want included as part of the package. | ||
| 11317 | Here is an example: | ||
| 11318 | </p><pre class="literallayout"> | ||
| 11319 | FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" | ||
| 11320 | </pre><p> | ||
| 11321 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 11322 | When specifying paths as part of the <code class="filename">FILES</code> variable, | ||
| 11323 | it is good practice to use appropriate path variables. | ||
| 11324 | For example, <code class="filename">${sysconfdir}</code> rather than | ||
| 11325 | <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather | ||
| 11326 | than <code class="filename">/usr/bin</code>. | ||
| 11327 | You can find a list of these variables at the top of the | ||
| 11328 | <code class="filename">/meta/conf/bitbake.conf</code> file in the | ||
| 11329 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 11330 | </div><p> | ||
| 11331 | If some of the files you provide with the <code class="filename">FILES</code> variable | ||
| 11332 | are editable and you know they should not be | ||
| 11333 | overwritten during the package update process by the Package Management | ||
| 11334 | System (PMS), you can identify these files so that the PMS will not | ||
| 11335 | overwrite them. | ||
| 11336 | See the <code class="filename"><a class="link" href="#var-CONFFILES" title="CONFFILES">CONFFILES</a></code> | ||
| 11337 | variable for information on how to identify these files to the PMS. | ||
| 11338 | </p></dd><dt><a id="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt><dd><p> | ||
| 11339 | Extends the search path the OpenEmbedded build system uses when | ||
| 11340 | looking for files and patches as it processes recipes. | ||
| 11341 | The directories BitBake uses when it processes recipes is defined by the | ||
| 11342 | <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable. | ||
| 11343 | You can add directories to the search path by defining the | ||
| 11344 | <code class="filename">FILESEXTRAPATHS</code> variable. | ||
| 11345 | </p><p> | ||
| 11346 | To add paths to the search order, provide a list of directories and separate | ||
| 11347 | each path using a colon character as follows: | ||
| 11348 | </p><pre class="literallayout"> | ||
| 11349 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" | ||
| 11350 | </pre><p> | ||
| 11351 | Typically, you want your directories search first. | ||
| 11352 | To make sure that happens, use <code class="filename">_prepend</code> and | ||
| 11353 | the immediate expansion (<code class="filename">:=</code>) operator as shown in the | ||
| 11354 | previous example. | ||
| 11355 | Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable, | ||
| 11356 | you must include the appropriate beginning or ending (as needed) colon character. | ||
| 11357 | </p><p> | ||
| 11358 | The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in | ||
| 11359 | <code class="filename">.bbappend</code> files to include any additional files provided in that layer. | ||
| 11360 | You typically accomplish this with the following: | ||
| 11361 | </p><pre class="literallayout"> | ||
| 11362 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 11363 | </pre><p> | ||
| 11364 | </p></dd><dt><a id="var-FILESPATH"></a>FILESPATH</dt><dd><p> | ||
| 11365 | The default set of directories the OpenEmbedded build system uses | ||
| 11366 | when searching for patches and files. | ||
| 11367 | During the build process, BitBake searches each directory in | ||
| 11368 | <code class="filename">FILESPATH</code> in the specified order when looking for | ||
| 11369 | files and patches specified by each <code class="filename">file://</code> URI in a recipe. | ||
| 11370 | </p><p> | ||
| 11371 | The default value for the <code class="filename">FILESPATH</code> variable is defined | ||
| 11372 | in the <code class="filename">base.bbclass</code> class found in | ||
| 11373 | <code class="filename">meta/classes</code> in the | ||
| 11374 | <a class="link" href="#source-directory" target="_top">source directory</a>: | ||
| 11375 | </p><pre class="literallayout"> | ||
| 11376 | FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ | ||
| 11377 | "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \ | ||
| 11378 | "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ | ||
| 11379 | "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" | ||
| 11380 | </pre><p> | ||
| 11381 | Do not hand-edit the <code class="filename">FILESPATH</code> variable. | ||
| 11382 | If you want to extend the set of pathnames that BitBake uses when searching for | ||
| 11383 | files and patches, use the | ||
| 11384 | <a class="link" href="#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable. | ||
| 11385 | </p></dd><dt><a id="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt><dd><p>Allows you to define your own file permissions settings table as part of | ||
| 11386 | your configuration for the packaging process. | ||
| 11387 | For example, suppose you need a consistent set of custom permissions for | ||
| 11388 | a set of groups and users across an entire work project. | ||
| 11389 | It is best to do this in the packages themselves but this is not always | ||
| 11390 | possible. | ||
| 11391 | </p><p> | ||
| 11392 | By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which | ||
| 11393 | is located in the <code class="filename">meta/files</code> folder in the | ||
| 11394 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 11395 | If you create your own file permissions setting table, you should place it in your | ||
| 11396 | layer or the distros layer. | ||
| 11397 | </p><p> | ||
| 11398 | You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the | ||
| 11399 | <code class="filename">conf/local.conf</code> file, which is found in the | ||
| 11400 | <a class="link" href="#build-directory" target="_top">build directory</a>, to | ||
| 11401 | point to your custom <code class="filename">fs-perms.txt</code>. | ||
| 11402 | You can specify more than a single file permissions setting table. | ||
| 11403 | The paths you specify to these files must be defined within the | ||
| 11404 | <code class="filename">BBPATH</code> variable. | ||
| 11405 | </p><p> | ||
| 11406 | For guidance on how to create your own file permissions settings table file, | ||
| 11407 | examine the existing <code class="filename">fs-perms.txt</code>. | ||
| 11408 | </p></dd><dt><a id="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p> | ||
| 11409 | The options to pass in | ||
| 11410 | <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> | ||
| 11411 | and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> | ||
| 11412 | when compiling an optimized system. | ||
| 11413 | This variable defaults to | ||
| 11414 | "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". | ||
| 11415 | </p></dd></dl></div><div class="glossdiv" title="H"><h3 class="title">H</h3><dl><dt><a id="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more info about package can be found</p></dd></dl></div><div class="glossdiv" title="I"><h3 class="title">I</h3><dl><dt><a id="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p>The list of features present in images. | ||
| 11416 | Typically, you configure this variable in image recipes. | ||
| 11417 | Note that you can add extra features to the image by using the | ||
| 11418 | <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> variable. | ||
| 11419 | See the "<a class="link" href="#ref-features-image" title="8.3. Reference: Images">Images</a>" chapter for the | ||
| 11420 | list of features present in images built by the OpenEmbedded build system.</p></dd><dt><a id="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of root filesystem images that you want to have created.</p></dd><dt><a id="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p> | ||
| 11421 | Specifies the packages to install into an image. | ||
| 11422 | The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image | ||
| 11423 | recipe and you should use it with care to avoid ordering issues. | ||
| 11424 | </p><p> | ||
| 11425 | Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the | ||
| 11426 | packages to install into an image through <code class="filename">image.bbclass</code>. | ||
| 11427 | Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>, | ||
| 11428 | that can take | ||
| 11429 | <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists | ||
| 11430 | and turn these into auto-generated entries in | ||
| 11431 | <code class="filename">IMAGE_INSTALL</code> in addition to its default contents. | ||
| 11432 | </p><p> | ||
| 11433 | Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code> | ||
| 11434 | operator from the <code class="filename">/conf/local.conf</code> file or from within | ||
| 11435 | an image recipe is not recommended as it can cause ordering issues. | ||
| 11436 | Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code> | ||
| 11437 | to a default value using the <code class="filename">?=</code> operator, using a | ||
| 11438 | <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code> | ||
| 11439 | will result in unexpected behavior when used in | ||
| 11440 | <code class="filename">/conf/local.conf</code>. | ||
| 11441 | Furthermore, the same operation from with an image recipe may or may not | ||
| 11442 | succeed depending on the specific situation. | ||
| 11443 | In both these cases, the behavior is contrary to how most users expect | ||
| 11444 | the <code class="filename">+=</code> operator to work. | ||
| 11445 | </p><p> | ||
| 11446 | When you use this variable, it is best to use it as follows: | ||
| 11447 | </p><pre class="literallayout"> | ||
| 11448 | IMAGE_INSTALL_append = " package-name" | ||
| 11449 | </pre><p> | ||
| 11450 | Be sure to include the space between the quotation character and the start of the | ||
| 11451 | package name. | ||
| 11452 | </p></dd><dt><a id="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt><dd><p> | ||
| 11453 | Defines a multiplier that the build system applies to the initial image | ||
| 11454 | size for cases when the multiplier times the returned disk usage value | ||
| 11455 | for the image is greater than the sum of | ||
| 11456 | <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> | ||
| 11457 | and | ||
| 11458 | <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>. | ||
| 11459 | The result of the multiplier applied to the initial image size creates | ||
| 11460 | free disk space in the image as overhead. | ||
| 11461 | By default, the build process uses a multiplier of 1.3 for this variable. | ||
| 11462 | This default value results in 30% free disk space added to the image when this | ||
| 11463 | method is used to determine the final generated image size. | ||
| 11464 | You should be aware that post install scripts and the package management | ||
| 11465 | system uses disk space inside this overhead area. | ||
| 11466 | Consequently, the multiplier does not produce an image with | ||
| 11467 | all the theoretical free disk space. | ||
| 11468 | See <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> | ||
| 11469 | for information on how the build system determines the overall image size. | ||
| 11470 | </p><p> | ||
| 11471 | The default 30% free disk space typically gives the image enough room to boot | ||
| 11472 | and allows for basic post installs while still leaving a small amount of | ||
| 11473 | free disk space. | ||
| 11474 | If 30% free space is inadequate, you can increase the default value. | ||
| 11475 | For example, the following setting gives you 50% free space added to the image: | ||
| 11476 | </p><pre class="literallayout"> | ||
| 11477 | IMAGE_OVERHEAD_FACTOR = "1.5" | ||
| 11478 | </pre><p> | ||
| 11479 | </p><p> | ||
| 11480 | Alternatively, you can ensure a specific amount of free disk space is added | ||
| 11481 | to the image by using | ||
| 11482 | <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code> | ||
| 11483 | the variable. | ||
| 11484 | </p></dd><dt><a id="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt><dd><p> | ||
| 11485 | Defines additional free disk space created in the image in Kbytes. | ||
| 11486 | By default, this variable is set to "0". | ||
| 11487 | This free disk space is added to the image after the build system determines | ||
| 11488 | the image size as described in | ||
| 11489 | <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>. | ||
| 11490 | </p><p> | ||
| 11491 | This variable is particularly useful when you want to ensure that a | ||
| 11492 | specific amount of free disk space is available on a device after an image | ||
| 11493 | is installed and running. | ||
| 11494 | For example, to be sure 5 Gbytes of free disk space is available, set the | ||
| 11495 | variable as follows: | ||
| 11496 | </p><pre class="literallayout"> | ||
| 11497 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" | ||
| 11498 | </pre><p> | ||
| 11499 | </p></dd><dt><a id="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt><dd><p> | ||
| 11500 | Defines the size in Kbytes for the generated image. | ||
| 11501 | The OpenEmbedded build system determines the final size for the generated | ||
| 11502 | image using an algorithm that takes into account the initial disk space used | ||
| 11503 | for the generated image, a requested size for the image, and requested | ||
| 11504 | additional free disk space to be added to the image. | ||
| 11505 | Programatically, the build system determines the final size of the | ||
| 11506 | generated image as follows: | ||
| 11507 | </p><pre class="literallayout"> | ||
| 11508 | if (image-du * overhead) < rootfs-size: | ||
| 11509 | internal-rootfs-size = rootfs-size + xspace | ||
| 11510 | else: | ||
| 11511 | internal-rootfs-size = (image-du * overhead) + xspace | ||
| 11512 | |||
| 11513 | where: | ||
| 11514 | |||
| 11515 | image-du = Returned value of the du command on | ||
| 11516 | the image. | ||
| 11517 | |||
| 11518 | overhead = IMAGE_OVERHEAD_FACTOR | ||
| 11519 | |||
| 11520 | rootfs-size = IMAGE_ROOTFS_SIZE | ||
| 11521 | |||
| 11522 | internal-rootfs-size = Initial root filesystem | ||
| 11523 | size before any modifications. | ||
| 11524 | |||
| 11525 | xspace = IMAGE_ROOTFS_EXTRA_SPACE | ||
| 11526 | </pre><p> | ||
| 11527 | |||
| 11528 | </p></dd><dt><a id="var-INC_PR"></a>INC_PR</dt><dd><p>Defines the Package revision. | ||
| 11529 | You manually combine values for <code class="filename">INC_PR</code> into the | ||
| 11530 | <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> field of the parent recipe. | ||
| 11531 | When you change this variable, you change the <code class="filename">PR</code> | ||
| 11532 | value for every person that includes the file.</p><p> | ||
| 11533 | The following example shows how to use the <code class="filename">INC_PR</code> variable | ||
| 11534 | given a common <code class="filename">.inc</code> file that defines the variable. | ||
| 11535 | Once defined, you can use the variable to set the | ||
| 11536 | <code class="filename">PR</code> value: | ||
| 11537 | </p><pre class="literallayout"> | ||
| 11538 | recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" | ||
| 11539 | recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" | ||
| 11540 | recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | ||
| 11541 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" | ||
| 11542 | </pre></dd><dt><a id="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p> | ||
| 11543 | Causes the build to not strip binaries in resulting packages. | ||
| 11544 | </p></dd><dt><a id="var-INHERIT"></a>INHERIT</dt><dd><p> | ||
| 11545 | Causes the named class to be inherited at | ||
| 11546 | this point during parsing. | ||
| 11547 | The variable is only valid in configuration files. | ||
| 11548 | </p></dd><dt><a id="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p> | ||
| 11549 | A list of the packages that contain initscripts. | ||
| 11550 | If multiple packages are specified, you need to append the package name | ||
| 11551 | to the other <code class="filename">INITSCRIPT_*</code> as an override.</p><p> | ||
| 11552 | This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. | ||
| 11553 | The variable is optional and defaults to the <code class="filename">PN</code> variable. | ||
| 11554 | </p></dd><dt><a id="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p> | ||
| 11555 | The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>. | ||
| 11556 | </p><p> | ||
| 11557 | This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. | ||
| 11558 | The variable is Mandatory. | ||
| 11559 | </p></dd><dt><a id="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p> | ||
| 11560 | Specifies the options to pass to <code class="filename">update-rc.d</code>. | ||
| 11561 | An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a | ||
| 11562 | runlevel of 99, starts the script in initlevels 2 and 5, and | ||
| 11563 | stops the script in levels 0, 1 and 6. | ||
| 11564 | </p><p> | ||
| 11565 | The variable is mandatory and is used in recipes when using | ||
| 11566 | <code class="filename">update-rc.d.bbclass</code>. | ||
| 11567 | </p></dd></dl></div><div class="glossdiv" title="K"><h3 class="title">K</h3><dl><dt><a id="var-KBRANCH"></a>KBRANCH</dt><dd><p> | ||
| 11568 | A regular expression used by the build process to explicitly identify the kernel | ||
| 11569 | branch that is validated, patched and configured during a build. | ||
| 11570 | The <code class="filename">KBRANCH</code> variable is optional. | ||
| 11571 | You can use it to trigger checks to ensure the exact kernel branch you want is | ||
| 11572 | being used by the build process. | ||
| 11573 | </p><p> | ||
| 11574 | Values for this variable are set in the kernel's recipe file and the kernel's | ||
| 11575 | append file. | ||
| 11576 | For example, if you are using the Yocto Project kernel that is based on the | ||
| 11577 | Linux 3.2 kernel, the kernel recipe file is the | ||
| 11578 | <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.2.bb</code> file. | ||
| 11579 | Following is the default value for <code class="filename">KBRANCH</code> and the five overrides | ||
| 11580 | for the architectures the Yocto Project supports: | ||
| 11581 | </p><pre class="literallayout"> | ||
| 11582 | KBRANCH = "standard/default/base" | ||
| 11583 | KBRANCH_qemux86 = "standard/default/common-pc/base" | ||
| 11584 | KBRANCH_qemux86-64 = "standard/default/common-pc-64/base" | ||
| 11585 | KBRANCH_qemuppc = "standard/default/qemu-ppc32" | ||
| 11586 | KBRANCH_qemumips = "standard/default/mti-malta32-be" | ||
| 11587 | KBRANCH_qemuarm = "standard/default/arm-versatile-926ejs" | ||
| 11588 | </pre><p> | ||
| 11589 | Each of the above branches exist in the <code class="filename">linux-yocto-3.2</code> kernel Git | ||
| 11590 | repository <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.2/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.2/refs/heads</a>. | ||
| 11591 | </p><p> | ||
| 11592 | This variable is also used from the kernel's append file to identify the kernel | ||
| 11593 | branch specific to a particular machine or target hardware. | ||
| 11594 | The kernel's append file is located in the BSP layer for a given machine. | ||
| 11595 | For example, the kernel append file for the Crown Bay BSP is in the | ||
| 11596 | <code class="filename">meta-intel</code> Git repository and is named | ||
| 11597 | <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.2.bbappend</code>. | ||
| 11598 | Here are the related statements from the append file: | ||
| 11599 | </p><pre class="literallayout"> | ||
| 11600 | COMPATIBLE_MACHINE_crownbay = "crownbay" | ||
| 11601 | KMACHINE_crownbay = "crownbay" | ||
| 11602 | KBRANCH_crownbay = "standard/default/crownbay" | ||
| 11603 | |||
| 11604 | COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" | ||
| 11605 | KMACHINE_crownbay-noemgd = "crownbay" | ||
| 11606 | KBRANCH_crownbay-noemgd = "standard/default/crownbay" | ||
| 11607 | </pre><p> | ||
| 11608 | The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to | ||
| 11609 | use when building for the Crown Bay BSP. | ||
| 11610 | In this case there are two identical statements: one for each type of | ||
| 11611 | Crown Bay machine. | ||
| 11612 | </p></dd><dt><a id="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt><dd><p>Includes additional metadata from the Yocto Project kernel Git repository. | ||
| 11613 | In the OpenEmbedded build system, the default Board Support Packages (BSPs) | ||
| 11614 | metadata is provided through | ||
| 11615 | the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables. | ||
| 11616 | You can use the <code class="filename">KERNEL_FEATURES</code> variable to further | ||
| 11617 | add metadata for all BSPs.</p><p>The metadata you add through this variable includes config fragments and | ||
| 11618 | features descriptions, | ||
| 11619 | which usually includes patches as well as config fragments. | ||
| 11620 | You typically override the <code class="filename">KERNEL_FEATURES</code> variable | ||
| 11621 | for a specific machine. | ||
| 11622 | In this way, you can provide validated, but optional, sets of kernel | ||
| 11623 | configurations and features.</p><p>For example, the following adds <code class="filename">netfilter</code> to all | ||
| 11624 | the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code> | ||
| 11625 | machine: | ||
| 11626 | </p><pre class="literallayout"> | ||
| 11627 | # Add netfilter to all linux-yocto kernels | ||
| 11628 | KERNEL_FEATURES="features/netfilter" | ||
| 11629 | |||
| 11630 | # Add sound support to the qemux86 machine | ||
| 11631 | KERNEL_FEATURES_append_qemux86="cfg/sound" | ||
| 11632 | </pre></dd><dt><a id="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the | ||
| 11633 | machine configuration files and defaults to "zImage". | ||
| 11634 | This variable is used | ||
| 11635 | when building the kernel and is passed to <code class="filename">make</code> as the target to | ||
| 11636 | build.</p></dd><dt><a id="var-KMACHINE"></a>KMACHINE</dt><dd><p> | ||
| 11637 | The machine as known by the kernel. | ||
| 11638 | Sometimes the machine name used by the kernel does not match the machine name | ||
| 11639 | used by the OpenEmbedded build system. | ||
| 11640 | For example, the machine name that the OpenEmbedded build system understands as | ||
| 11641 | <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel. | ||
| 11642 | The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>. | ||
| 11643 | For cases like these, the <code class="filename">KMACHINE</code> variable maps the | ||
| 11644 | kernel machine name to the OpenEmbedded build system machine name. | ||
| 11645 | </p><p> | ||
| 11646 | Kernel machine names are initially defined in the | ||
| 11647 | <a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a> in | ||
| 11648 | the <code class="filename">meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</code> file. | ||
| 11649 | For example, in the <code class="filename">linux-yocto-3.4</code> kernel in the | ||
| 11650 | <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file, | ||
| 11651 | has the following: | ||
| 11652 | </p><pre class="literallayout"> | ||
| 11653 | define KMACHINE cedartrail | ||
| 11654 | define KTYPE standard | ||
| 11655 | define KARCH i386 | ||
| 11656 | |||
| 11657 | include ktypes/standard | ||
| 11658 | branch cedartrail | ||
| 11659 | |||
| 11660 | include cedartrail.scc | ||
| 11661 | </pre><p> | ||
| 11662 | You can see that the kernel understands the machine name for the Cedar Trail BSP as | ||
| 11663 | <code class="filename">cedartrail</code>. | ||
| 11664 | </p><p> | ||
| 11665 | If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source | ||
| 11666 | repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>, | ||
| 11667 | you will find the following statements among others: | ||
| 11668 | </p><pre class="literallayout"> | ||
| 11669 | COMPATIBLE_MACHINE_cedartrail = "cedartrail" | ||
| 11670 | KMACHINE_cedartrail = "cedartrail" | ||
| 11671 | KBRANCH_cedartrail = "yocto/standard/cedartrail" | ||
| 11672 | KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" | ||
| 11673 | KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" | ||
| 11674 | |||
| 11675 | COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" | ||
| 11676 | KMACHINE_cedartrail-nopvr = "cedartrail" | ||
| 11677 | KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" | ||
| 11678 | KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" | ||
| 11679 | </pre><p> | ||
| 11680 | The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that | ||
| 11681 | the OpenEmbedded build system and the Yocto Linux kernel understand the same machine | ||
| 11682 | names. | ||
| 11683 | </p><p> | ||
| 11684 | This append file uses two <code class="filename">KMACHINE</code> statements. | ||
| 11685 | The first is not really necessary but does ensure that the machine known to the | ||
| 11686 | OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine | ||
| 11687 | in the kernel also known as <code class="filename">cedartrail</code>: | ||
| 11688 | </p><pre class="literallayout"> | ||
| 11689 | KMACHINE_cedartrail = "cedartrail" | ||
| 11690 | </pre><p> | ||
| 11691 | </p><p> | ||
| 11692 | The second statement is a good example of why the <code class="filename">KMACHINE</code> variable | ||
| 11693 | is needed. | ||
| 11694 | In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code> | ||
| 11695 | machine name to refer to the Cedar Trail BSP that does not support the propriatory | ||
| 11696 | PowerVR driver. | ||
| 11697 | The kernel, however, uses the machine name <code class="filename">cedartrail</code>. | ||
| 11698 | Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to | ||
| 11699 | the kernel's <code class="filename">cedartrail</code> name: | ||
| 11700 | </p><pre class="literallayout"> | ||
| 11701 | KMACHINE_cedartrail-nopvr = "cedartrail" | ||
| 11702 | </pre><p> | ||
| 11703 | </p><p> | ||
| 11704 | BSPs that ship with the Yocto Project release provide all mappings between the Yocto | ||
| 11705 | Project kernel machine names and the OpenEmbedded machine names. | ||
| 11706 | Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine | ||
| 11707 | name you use is different than that used in the kernel. | ||
| 11708 | </p></dd></dl></div><div class="glossdiv" title="L"><h3 class="title">L</h3><dl><dt><a id="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt><dd><p>Lists the layers that this recipe depends upon, separated by spaces. | ||
| 11709 | Optionally, you can specify a specific layer version for a dependency | ||
| 11710 | by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" | ||
| 11711 | to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case). | ||
| 11712 | An error will be produced if any dependency is missing or | ||
| 11713 | the version numbers do not match exactly (if specified). | ||
| 11714 | This variable is used in the <code class="filename">conf/layer.conf</code> file | ||
| 11715 | and must be suffixed with the name of the specific layer (e.g. | ||
| 11716 | <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd><dt><a id="var-LAYERDIR"></a>LAYERDIR</dt><dd><p>When used inside the <code class="filename">layer.conf</code> configuration | ||
| 11717 | file, this variable provides the path of the current layer. | ||
| 11718 | This variable requires immediate expansion | ||
| 11719 | (see the BitBake manual) as lazy expansion can result in | ||
| 11720 | the expansion happening in the wrong directory and therefore | ||
| 11721 | giving the wrong value.</p></dd><dt><a id="var-LAYERVERSION"></a>LAYERVERSION</dt><dd><p>Optionally specifies the version of a layer as a single number. | ||
| 11722 | You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to | ||
| 11723 | depend on a specific version of the layer. | ||
| 11724 | This variable is used in the <code class="filename">conf/layer.conf</code> file | ||
| 11725 | and must be suffixed with the name of the specific layer (e.g. | ||
| 11726 | <code class="filename">LAYERVERSION_mylayer</code>).</p></dd><dt><a id="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt><dd><p>Checksums of the license text in the recipe source code.</p><p>This variable tracks changes in license text of the source | ||
| 11727 | code files. | ||
| 11728 | If the license text is changed, it will trigger a build | ||
| 11729 | failure, which gives the developer an opportunity to review any | ||
| 11730 | license change.</p><p> | ||
| 11731 | This variable must be defined for all recipes (unless <code class="filename">LICENSE</code> | ||
| 11732 | is set to "CLOSED")</p><p>For more information, see the | ||
| 11733 | <a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" title="3.4.1. Tracking License Changes"> | ||
| 11734 | Tracking License Changes</a> section</p></dd><dt><a id="var-LICENSE"></a>LICENSE</dt><dd><p>The list of package source licenses.</p></dd><dt><a id="var-LICENSE_DIR"></a>LICENSE_DIR</dt><dd><p>Path to additional licenses used during the build. | ||
| 11735 | By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code> | ||
| 11736 | to define the directory that holds common license text used during the build. | ||
| 11737 | The <code class="filename">LICENSE_DIR</code> variable allows you to extend that | ||
| 11738 | location to other areas that have additional licenses: | ||
| 11739 | </p><pre class="literallayout"> | ||
| 11740 | LICENSE_DIR += "/path/to/additional/common/licenses" | ||
| 11741 | </pre></dd></dl></div><div class="glossdiv" title="M"><h3 class="title">M</h3><dl><dt><a id="var-MACHINE"></a>MACHINE</dt><dd><p>Specifies the target device.</p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt><dd><p></p><p> | ||
| 11742 | A list of required packages to install as part of the package being | ||
| 11743 | built. | ||
| 11744 | The build process depends on these packages being present. | ||
| 11745 | Furthermore, because this is a "machine essential" variable, the list of | ||
| 11746 | packages are essential for the machine to boot. | ||
| 11747 | The impact of this variable affects images based on <code class="filename">task-core-boot</code>, | ||
| 11748 | including the <code class="filename">core-image-minimal</code> image. | ||
| 11749 | </p><p> | ||
| 11750 | This variable is similar to the | ||
| 11751 | <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code> | ||
| 11752 | variable with the exception that the package being built has a build | ||
| 11753 | dependency on the variable's list of packages. | ||
| 11754 | In other words, the image will not build if a file in this list is not found. | ||
| 11755 | </p><p> | ||
| 11756 | For example, suppose you are building a runtime package that depends | ||
| 11757 | on a certain disk driver. | ||
| 11758 | In this case, you would use the following: | ||
| 11759 | </p><pre class="literallayout"> | ||
| 11760 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "<disk_driver>" | ||
| 11761 | </pre><p> | ||
| 11762 | </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt><dd><p></p><p> | ||
| 11763 | A list of recommended packages to install as part of the package being | ||
| 11764 | built. | ||
| 11765 | The build process does not depend on these packages being present. | ||
| 11766 | Furthermore, because this is a "machine essential" variable, the list of | ||
| 11767 | packages are essential for the machine to boot. | ||
| 11768 | The impact of this variable affects images based on <code class="filename">task-core-boot</code>, | ||
| 11769 | including the <code class="filename">core-image-minimal</code> image. | ||
| 11770 | </p><p> | ||
| 11771 | This variable is similar to the | ||
| 11772 | <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS</a></code> | ||
| 11773 | variable with the exception that the package being built does not have a build | ||
| 11774 | dependency on the variable's list of packages. | ||
| 11775 | In other words, the image will build if a file in this list is not found. | ||
| 11776 | However, because this is one of the "essential" variables, the resulting image | ||
| 11777 | might not boot on the machine. | ||
| 11778 | Or, if the machine does boot using the image, the machine might not be fully | ||
| 11779 | functional. | ||
| 11780 | </p><p> | ||
| 11781 | Consider an example where you have a custom kernel with a disk driver | ||
| 11782 | built into the kernel itself, rather than using the driver built as a module. | ||
| 11783 | If you include the package that has the driver module as part of | ||
| 11784 | the variable's list, the | ||
| 11785 | build process will not find that package. | ||
| 11786 | However, because these packages are "recommends" packages, the build will | ||
| 11787 | not fail due to the missing package. | ||
| 11788 | Not accounting for any other problems, the custom kernel would still boot the machine. | ||
| 11789 | </p><p> | ||
| 11790 | Some example packages of these machine essentials are flash, screen, keyboard, mouse, | ||
| 11791 | or touchscreen drivers (depending on the machine). | ||
| 11792 | </p><p> | ||
| 11793 | For example, suppose you are building a runtime package that depends | ||
| 11794 | on a mouse driver. | ||
| 11795 | In this case, you would use the following: | ||
| 11796 | </p><pre class="literallayout"> | ||
| 11797 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "<mouse_driver>" | ||
| 11798 | </pre><p> | ||
| 11799 | </p></dd><dt><a id="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p> | ||
| 11800 | A list of optional but non-machine essential packages to install as | ||
| 11801 | part of the package being built. | ||
| 11802 | Even though these packages are not essential for the machine to boot, | ||
| 11803 | the build process depends on them being present. | ||
| 11804 | The impact of this variable affects all images based on | ||
| 11805 | <code class="filename">task-base</code>, which does not include the | ||
| 11806 | <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> | ||
| 11807 | images. | ||
| 11808 | </p><p> | ||
| 11809 | This variable is similar to the | ||
| 11810 | <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code> | ||
| 11811 | variable with the exception that the package being built has a build | ||
| 11812 | dependency on the variable's list of packages. | ||
| 11813 | In other words, the image will not build if a file in this list is not found. | ||
| 11814 | </p><p> | ||
| 11815 | An example is a machine that might or might not have a WiFi card. | ||
| 11816 | The package containing the WiFi support is not essential for the | ||
| 11817 | machine to boot the image. | ||
| 11818 | If it is not there, the machine will boot but not be able to use the | ||
| 11819 | WiFi functionality. | ||
| 11820 | However, if you include the package with the WiFi support as part of the | ||
| 11821 | variable's package list, the build | ||
| 11822 | process depends on finding the package. | ||
| 11823 | In this case, you would use the following: | ||
| 11824 | </p><pre class="literallayout"> | ||
| 11825 | MACHINE_EXTRA_RDEPENDS += "<wifi_driver>" | ||
| 11826 | </pre><p> | ||
| 11827 | </p></dd><dt><a id="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt><dd><p></p><p> | ||
| 11828 | A list of optional but non-machine essential packages to install as | ||
| 11829 | part of the package being built. | ||
| 11830 | The package being built has no build dependency on the list of packages | ||
| 11831 | with this variable. | ||
| 11832 | The impact of this variable affects only images based on | ||
| 11833 | <code class="filename">task-base</code>, which does not include the | ||
| 11834 | <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> | ||
| 11835 | images. | ||
| 11836 | </p><p> | ||
| 11837 | This variable is similar to the | ||
| 11838 | <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code> | ||
| 11839 | variable with the exception that the package being built does not have a build | ||
| 11840 | dependency on the variable's list of packages. | ||
| 11841 | In other words, the image will build if a file in this list is not found. | ||
| 11842 | </p><p> | ||
| 11843 | An example is a machine that might or might not have a WiFi card. | ||
| 11844 | The package containing the WiFi support is not essential for the | ||
| 11845 | machine to boot the image. | ||
| 11846 | If it is not there, the machine will boot but not be able to use the | ||
| 11847 | WiFi functionality. | ||
| 11848 | You are free to either include or not include the | ||
| 11849 | the package with the WiFi support as part of the | ||
| 11850 | variable's package list, the build | ||
| 11851 | process does not depend on finding the package. | ||
| 11852 | If you include the package, you would use the following: | ||
| 11853 | </p><pre class="literallayout"> | ||
| 11854 | MACHINE_EXTRA_RRECOMMENDS += "<wifi_driver>" | ||
| 11855 | </pre><p> | ||
| 11856 | </p></dd><dt><a id="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>Specifies the list of device features. | ||
| 11857 | See the <a class="link" href="#ref-features-machine" title="8.2. Machine">Machine</a> section for | ||
| 11858 | more information.</p></dd><dt><a id="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>The email address of the distribution maintainer.</p></dd></dl></div><div class="glossdiv" title="P"><h3 class="title">P</h3><dl><dt><a id="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>The architecture of the resulting package.</p></dd><dt><a id="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>This variable, which is set in the <code class="filename">local.conf</code> configuration | ||
| 11859 | file found in the <code class="filename">conf</code> folder of the | ||
| 11860 | <a class="link" href="#source-directory" target="_top">source directory</a>, | ||
| 11861 | specifies the package manager to use when packaging data. | ||
| 11862 | You can provide one or more arguments for the variable with the first | ||
| 11863 | argument being the package manager used to create images: | ||
| 11864 | </p><pre class="literallayout"> | ||
| 11865 | PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" | ||
| 11866 | </pre><p> | ||
| 11867 | For information on build performance effects as a result of the | ||
| 11868 | package manager use, see | ||
| 11869 | <a class="link" href="#ref-classes-package" title="6.12. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a> | ||
| 11870 | in this manual. | ||
| 11871 | </p></dd><dt><a id="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>Specifies the list of architectures compatible with the device CPU. | ||
| 11872 | This variable is useful when you build for several different devices that use | ||
| 11873 | miscellaneous processors such as XScale and ARM926-EJS).</p></dd><dt><a id="var-PACKAGES"></a>PACKAGES</dt><dd><p>The list of packages to be created from the recipe. | ||
| 11874 | The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev".</p></dd><dt><a id="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt><dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the | ||
| 11875 | compile tasks. | ||
| 11876 | This variable is usually in the form <code class="filename">-j 4</code>, where the number | ||
| 11877 | represents the maximum number of parallel threads make can run. | ||
| 11878 | If you development host supports multiple cores a good rule of thumb is to set | ||
| 11879 | this variable to twice the number of cores on the host.</p></dd><dt><a id="var-PN"></a>PN</dt><dd><p>The name of the package. | ||
| 11880 | </p></dd><dt><a id="var-PR"></a>PR</dt><dd><p>The revision of the package. | ||
| 11881 | The default value for this variable is "r0". | ||
| 11882 | </p></dd><dt><a id="var-PV"></a>PV</dt><dd><p>The version of the package. | ||
| 11883 | The version is normally extracted from the recipe name. | ||
| 11884 | For example, if the recipe is named | ||
| 11885 | <code class="filename">expat_2.0.1.bb</code>, then <code class="filename">PV</code> | ||
| 11886 | will be <code class="filename">2.0.1</code>. | ||
| 11887 | <code class="filename">PV</code> is generally not overridden within | ||
| 11888 | a recipe unless it is building an unstable version from a source code repository | ||
| 11889 | (e.g. Git or Subversion). | ||
| 11890 | </p></dd><dt><a id="var-PE"></a>PE</dt><dd><p> | ||
| 11891 | the epoch of the package. | ||
| 11892 | The default value is "0". | ||
| 11893 | The field is used to make upgrades possible when the versioning scheme changes in | ||
| 11894 | some backwards incompatible way. | ||
| 11895 | </p></dd><dt><a id="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p> | ||
| 11896 | If multiple recipes provide an item, this variable | ||
| 11897 | determines which recipe should be given preference. | ||
| 11898 | The variable must always be suffixed with the name of the | ||
| 11899 | provided item, and should be set to the | ||
| 11900 | <code class="filename">$PN</code> of the recipe | ||
| 11901 | to which you want to give precedence. | ||
| 11902 | Here is an example: | ||
| 11903 | </p><pre class="literallayout"> | ||
| 11904 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | ||
| 11905 | </pre><p> | ||
| 11906 | </p></dd><dt><a id="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p> | ||
| 11907 | If there are multiple versions of recipes available, this | ||
| 11908 | variable determines which recipe should be given preference. | ||
| 11909 | The variable must always be suffixed with the <code class="filename">$PN</code> | ||
| 11910 | for which to select, and should be set to the | ||
| 11911 | <code class="filename">$PV</code> to which you want to give precedence. | ||
| 11912 | You can use the "<code class="filename">%</code>" character as a wildcard | ||
| 11913 | to match any number of characters, which can be useful when | ||
| 11914 | specifying versions that contain long revision number that could | ||
| 11915 | potentially change. | ||
| 11916 | Here are two examples: | ||
| 11917 | </p><pre class="literallayout"> | ||
| 11918 | PREFERRED_VERSION_python = "2.6.6" | ||
| 11919 | PREFERRED_VERSION_linux-yocto = "3.0+git%" | ||
| 11920 | </pre><p> | ||
| 11921 | </p></dd></dl></div><div class="glossdiv" title="R"><h3 class="title">R</h3><dl><dt><a id="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>The list of packages that conflict with this package. | ||
| 11922 | Note that the package will not be installed if the conflicting packages are not | ||
| 11923 | first removed.</p></dd><dt><a id="var-RDEPENDS"></a>RDEPENDS</dt><dd><p> | ||
| 11924 | A list of packages that must be installed as part of a package being built. | ||
| 11925 | The package being built has a runtime dependency on the packages in the | ||
| 11926 | variable's list. | ||
| 11927 | In other words, in order for the package being built to run correctly, | ||
| 11928 | it depends on these listed packages. | ||
| 11929 | If a package in this list cannot be found during the build, the build | ||
| 11930 | will not complete. | ||
| 11931 | </p><p> | ||
| 11932 | Because the <code class="filename">RDEPENDS</code> variable applies to packages | ||
| 11933 | being built, you should | ||
| 11934 | always attach an override to the variable to specify the particular runtime package | ||
| 11935 | that has the dependency. | ||
| 11936 | For example, suppose you are building a development package that depends | ||
| 11937 | on the <code class="filename">perl</code> package. | ||
| 11938 | In this case, you would use the following <code class="filename">RDEPENDS</code> | ||
| 11939 | statement: | ||
| 11940 | </p><pre class="literallayout"> | ||
| 11941 | RDEPENDS_${PN}-dev += "perl" | ||
| 11942 | </pre><p> | ||
| 11943 | In the example, the package name (<code class="filename">${PN}-dev</code>) must | ||
| 11944 | appear as it would in the | ||
| 11945 | <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any | ||
| 11946 | renaming of the output package by classes like <code class="filename">debian.bbclass</code>. | ||
| 11947 | </p><p> | ||
| 11948 | Some automatic handling occurs around the <code class="filename">RDEPENDS</code> | ||
| 11949 | variable: | ||
| 11950 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If a runtime | ||
| 11951 | package contains a shared library (<code class="filename">.so</code>), the build | ||
| 11952 | processes the library in order to determine other libraries to which it | ||
| 11953 | is dynamically linked. | ||
| 11954 | The build process adds these libraries to <code class="filename">RDEPENDS</code> | ||
| 11955 | to create the runtime package.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If the package | ||
| 11956 | ships a <code class="filename">pkg-config</code> information file, the build process | ||
| 11957 | uses this file to add items to the <code class="filename">RDEPENDS</code> | ||
| 11958 | variable to create the runtime packages. | ||
| 11959 | </p></li></ul></div><p> | ||
| 11960 | </p></dd><dt><a id="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p> | ||
| 11961 | A list of packages that extend the usability of a package being | ||
| 11962 | built. | ||
| 11963 | The package being built does not depend on this list of packages in | ||
| 11964 | order to successfully build, but needs them for the extended usability. | ||
| 11965 | To specify runtime dependencies for packages, see the | ||
| 11966 | <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable. | ||
| 11967 | </p><p> | ||
| 11968 | The OpenEmbedded build process automatically installs the list of packages | ||
| 11969 | as part of the built package. | ||
| 11970 | However, you can remove them later if you want. | ||
| 11971 | If, during the build, a package from the list cannot be found, the build | ||
| 11972 | process continues without an error. | ||
| 11973 | </p><p> | ||
| 11974 | Because the <code class="filename">RRECOMMENDS</code> variable applies to packages | ||
| 11975 | being built, you should | ||
| 11976 | always attach an override to the variable to specify the particular package | ||
| 11977 | whose usability is being extended. | ||
| 11978 | For example, suppose you are building a development package that is extended | ||
| 11979 | to support wireless functionality. | ||
| 11980 | In this case, you would use the following: | ||
| 11981 | </p><pre class="literallayout"> | ||
| 11982 | RRECOMMENDS_${PN}-dev += "<wireless_package_name>" | ||
| 11983 | </pre><p> | ||
| 11984 | In the example, the package name (<code class="filename">${PN}-dev</code>) must | ||
| 11985 | appear as it would in the | ||
| 11986 | <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any | ||
| 11987 | renaming of the output package by classes like <code class="filename">debian.bbclass</code>. | ||
| 11988 | </p></dd><dt><a id="var-RREPLACES"></a>RREPLACES</dt><dd><p>The list of packages that are replaced with this package.</p></dd></dl></div><div class="glossdiv" title="S"><h3 class="title">S</h3><dl><dt><a id="var-S"></a>S</dt><dd><p> | ||
| 11989 | The location in the <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 11990 | where unpacked package source code resides. | ||
| 11991 | This location is within the working directory | ||
| 11992 | (<code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which | ||
| 11993 | is not static. | ||
| 11994 | The unpacked source location depends on the package name | ||
| 11995 | (<code class="filename"><a class="link" href="#var-PN" title="PN">PN</a></code>) and | ||
| 11996 | package version (<code class="filename"><a class="link" href="#var-PV" title="PV">PV</a></code>) as | ||
| 11997 | follows: | ||
| 11998 | </p><pre class="literallayout"> | ||
| 11999 | ${WORKDIR}/${PN}-${PV} | ||
| 12000 | </pre><p> | ||
| 12001 | As an example, assume a | ||
| 12002 | <a class="link" href="#source-directory" target="_top">source directory</a> top-level | ||
| 12003 | folder named <code class="filename">poky</code> | ||
| 12004 | and a default <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 12005 | at <code class="filename">poky/build</code>. | ||
| 12006 | In this case, the working directory the build system uses to build | ||
| 12007 | the <code class="filename">db</code> package is the following: | ||
| 12008 | </p><pre class="literallayout"> | ||
| 12009 | ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19 | ||
| 12010 | </pre><p> | ||
| 12011 | </p></dd><dt><a id="var-SECTION"></a>SECTION</dt><dd><p>The section where package should be put. | ||
| 12012 | Package managers use this variable.</p></dd><dt><a id="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p> | ||
| 12013 | The variable takes the value of | ||
| 12014 | <code class="filename"><a class="link" href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code> | ||
| 12015 | unless <code class="filename"><a class="link" href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1". | ||
| 12016 | In this case the value of | ||
| 12017 | <code class="filename"><a class="link" href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used. | ||
| 12018 | </p></dd><dt><a id="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>The speed and device for the serial port used to attach the serial console. | ||
| 12019 | This variable is given to the kernel as the "console" | ||
| 12020 | parameter and after booting occurs <code class="filename">getty</code> is started on that port | ||
| 12021 | so remote login is possible.</p></dd><dt><a id="var-SSTATE_DIR"></a>SSTATE_DIR</dt><dd><p>The directory for the shared state.</p></dd><dt><a id="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt><dd><p> | ||
| 12022 | Specifies the endian byte order of the target system. | ||
| 12023 | The variable is either "le" for little-endian or "be" for big-endian. | ||
| 12024 | </p></dd><dt><a id="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p> | ||
| 12025 | Specifies the number of bits for the target system CPU. | ||
| 12026 | The variable is either "32" or "64". | ||
| 12027 | </p></dd><dt><a id="var-SRC_URI"></a>SRC_URI</dt><dd><p>The list of source files - local or remote.</p></dd><dt><a id="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p></p><p> | ||
| 12028 | By default, the OpenEmbedded build system automatically detects whether | ||
| 12029 | <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> | ||
| 12030 | contains files that are machine-specific. | ||
| 12031 | If so, the build system automatically changes | ||
| 12032 | <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>. | ||
| 12033 | Setting this variable to "0" disables this behavior. | ||
| 12034 | </p></dd><dt><a id="var-SRCDATE"></a>SRCDATE</dt><dd><p> | ||
| 12035 | The date of the source code used to build the package. | ||
| 12036 | This variable applies only if the source was fetched from a Source Code Manager (SCM). | ||
| 12037 | </p></dd><dt><a id="var-SRCREV"></a>SRCREV</dt><dd><p> | ||
| 12038 | The revision of the source code used to build the package. | ||
| 12039 | This variable applies to Subversion, Git, Mercurial and Bazaar | ||
| 12040 | only. | ||
| 12041 | Note that if you wish to build a fixed revision and you wish | ||
| 12042 | to avoid performing a query on the remote repository every time | ||
| 12043 | BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a | ||
| 12044 | full revision identifier and not just a tag. | ||
| 12045 | </p></dd><dt><a id="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p> | ||
| 12046 | The directory with kernel headers that are required to build out-of-tree | ||
| 12047 | modules. | ||
| 12048 | </p></dd><dt><a id="var-STAMP"></a>STAMP</dt><dd><p> | ||
| 12049 | The directory (usually <code class="filename">TMPDIR/stamps</code>) with timestamps of | ||
| 12050 | executed tasks. | ||
| 12051 | </p></dd><dt><a id="var-SUMMARY"></a>SUMMARY</dt><dd><p>The short (72 characters or less) summary of the binary package for packaging | ||
| 12052 | systems such as <code class="filename">ipkg</code>, <code class="filename">rpm</code> or | ||
| 12053 | <code class="filename">debian</code>. | ||
| 12054 | By default, this variable inherits <code class="filename">DESCRIPTION</code>.</p></dd></dl></div><div class="glossdiv" title="T"><h3 class="title">T</h3><dl><dt><a id="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device being built. | ||
| 12055 | While a number of values are possible, the OpenEmbedded build system primarily supports | ||
| 12056 | <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd><dt><a id="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p> | ||
| 12057 | Flags passed to the C compiler for the target system. | ||
| 12058 | This variable evaluates to the same as | ||
| 12059 | <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>. | ||
| 12060 | </p></dd><dt><a id="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Specifies the method for handling FPU code. | ||
| 12061 | For FPU-less targets, which include most ARM CPUs, the variable must be | ||
| 12062 | set to "soft". | ||
| 12063 | If not, the kernel emulation gets used, which results in a performance penalty.</p></dd><dt><a id="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Specifies the target's operating system. | ||
| 12064 | The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and | ||
| 12065 | to "linux-uclibc" for <code class="filename">uclibc</code>. | ||
| 12066 | For ARM/EABI targets, there are also "linux-gnueabi" and | ||
| 12067 | "linux-uclibc-gnueabi" values possible.</p></dd><dt><a id="var-TCLIBC"></a>TCLIBC</dt><dd><p> | ||
| 12068 | Specifies which variant of the GNU standard C library (<code class="filename">libc</code>) | ||
| 12069 | to use during the build process. | ||
| 12070 | This variable replaces <code class="filename">POKYLIBC</code>, which is no longer | ||
| 12071 | supported. | ||
| 12072 | </p><p> | ||
| 12073 | You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. | ||
| 12074 | </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> | ||
| 12075 | This release of the Yocto Project does not support the | ||
| 12076 | <code class="filename">glibc</code> implementation of <code class="filename">libc</code>. | ||
| 12077 | </div><p> | ||
| 12078 | </p></dd><dt><a id="var-TCMODE"></a>TCMODE</dt><dd><p> | ||
| 12079 | The toolchain selector. | ||
| 12080 | This variable replaces <code class="filename">POKYMODE</code>, which is no longer | ||
| 12081 | supported. | ||
| 12082 | </p><p> | ||
| 12083 | The <code class="filename">TCMODE</code> variable selects the external toolchain | ||
| 12084 | built using the OpenEmbedded build system or a few supported combinations of | ||
| 12085 | the upstream GCC or CodeSourcery Labs toolchain. | ||
| 12086 | The variable determines which of the <code class="filename">tcmode-*</code> files in | ||
| 12087 | the <code class="filename">meta/conf/distro/include</code> directory, which is found in the | ||
| 12088 | <a class="link" href="#source-directory" target="_top">source directory</a>, | ||
| 12089 | is used. | ||
| 12090 | </p><p> | ||
| 12091 | By default, <code class="filename">TCMODE</code> is set to "default", which | ||
| 12092 | chooses the <code class="filename">tcmode-default.inc</code> file. | ||
| 12093 | The variable is similar to | ||
| 12094 | <a class="link" href="#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls | ||
| 12095 | the variant of the GNU standard C library (<code class="filename">libc</code>) | ||
| 12096 | used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. | ||
| 12097 | </p></dd><dt><a id="var-TMPDIR"></a>TMPDIR</dt><dd><p> | ||
| 12098 | This variable is the temporary directory the OpenEmbedded build system | ||
| 12099 | uses when it does its work building images. | ||
| 12100 | By default, the <code class="filename">TMPDIR</code> variable is named | ||
| 12101 | <code class="filename">tmp</code> within the | ||
| 12102 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 12103 | </p><p> | ||
| 12104 | If you want to establish this directory in a location other than the | ||
| 12105 | default, you can uncomment the following statement in the | ||
| 12106 | <code class="filename">conf/local.conf</code> file in the | ||
| 12107 | <a class="link" href="#source-directory" target="_top">source directory</a>: | ||
| 12108 | </p><pre class="literallayout"> | ||
| 12109 | #TMPDIR = "${TOPDIR}/tmp" | ||
| 12110 | </pre><p> | ||
| 12111 | </p></dd><dt><a id="var-TOPDIR"></a>TOPDIR</dt><dd><p> | ||
| 12112 | This variable is the | ||
| 12113 | <a class="link" href="#build-directory" target="_top">build directory</a>. | ||
| 12114 | BitBake automatically sets this variable. | ||
| 12115 | The OpenEmbedded build system uses the build directory when building images. | ||
| 12116 | </p></dd></dl></div><div class="glossdiv" title="W"><h3 class="title">W</h3><dl><dt><a id="var-WORKDIR"></a>WORKDIR</dt><dd><p> | ||
| 12117 | The pathname of the working directory in which the OpenEmbedded build system | ||
| 12118 | builds packages. | ||
| 12119 | This directory is located within the | ||
| 12120 | <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes | ||
| 12121 | as different packages are built. | ||
| 12122 | </p><p> | ||
| 12123 | The actual <code class="filename">WORKDIR</code> directory depends on several things: | ||
| 12124 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The temporary directory - <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a></li><li class="listitem">The package architecture - <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH"><code class="filename">PACKAGE_ARCH</code></a></li><li class="listitem">The target machine - <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a></li><li class="listitem">The target operating system - <a class="link" href="#var-TARGET_OS" title="TARGET_OS"><code class="filename">TARGET_OS</code></a></li><li class="listitem">The package name - <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a></li><li class="listitem">The package version - <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a></li><li class="listitem">The package revision - <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a></li></ul></div><p> | ||
| 12125 | </p><p> | ||
| 12126 | For packages that are not dependent on a particular machine, | ||
| 12127 | <code class="filename">WORKDIR</code> is defined as follows: | ||
| 12128 | </p><pre class="literallayout"> | ||
| 12129 | ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | ||
| 12130 | </pre><p> | ||
| 12131 | As an example, assume a | ||
| 12132 | <a class="link" href="#source-directory" target="_top">source directory</a> top-level | ||
| 12133 | folder name <code class="filename">poky</code> and a default | ||
| 12134 | <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 12135 | at <code class="filename">poky/build</code>. | ||
| 12136 | In this case, the working directory the build system uses to build | ||
| 12137 | the <code class="filename">v86d</code> package is the following: | ||
| 12138 | </p><pre class="literallayout"> | ||
| 12139 | ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0 | ||
| 12140 | </pre><p> | ||
| 12141 | </p><p> | ||
| 12142 | For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code> | ||
| 12143 | is defined slightly different: | ||
| 12144 | </p><pre class="literallayout"> | ||
| 12145 | ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | ||
| 12146 | </pre><p> | ||
| 12147 | As an example, again assume a source directory top-level folder | ||
| 12148 | named <code class="filename">poky</code> and a default build directory | ||
| 12149 | at <code class="filename">poky/build</code>. | ||
| 12150 | In this case, the working directory the build system uses to build | ||
| 12151 | the <code class="filename">acl</code> package, which is dependent on a | ||
| 12152 | MIPS-based device, is the following: | ||
| 12153 | </p><pre class="literallayout"> | ||
| 12154 | ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 | ||
| 12155 | </pre><p> | ||
| 12156 | </p></dd></dl></div></div></div> | ||
| 12157 | |||
| 12158 | <div class="chapter" title="Chapter 10. Variable Context"><div class="titlepage"><div><div><h2 class="title"><a id="ref-varlocality"></a>Chapter 10. Variable Context</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-varlocality-configuration">10.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">10.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">10.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">10.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">10.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">10.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">10.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">10.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">10.2.4. Extra Build Information</a></span></dt></dl></dd></dl></div><p> | ||
| 12159 | While most variables can be used in almost any context such as | ||
| 12160 | <code class="filename">.conf</code>, <code class="filename">.bbclass</code>, | ||
| 12161 | <code class="filename">.inc</code>, and <code class="filename">.bb</code> files, | ||
| 12162 | some variables are often associated with a particular locality or context. | ||
| 12163 | This chapter describes some common associations. | ||
| 12164 | </p><div class="section" title="10.1. Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-configuration"></a>10.1. Configuration</h2></div></div></div><p> | ||
| 12165 | The following subsections provide lists of variables whose context is | ||
| 12166 | configuration: distribution, machine, and local. | ||
| 12167 | </p><div class="section" title="10.1.1. Distribution (Distro)"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-distro"></a>10.1.1. Distribution (Distro)</h3></div></div></div><p> | ||
| 12168 | This section lists variables whose context is the distribution, or distro. | ||
| 12169 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></code> | ||
| 12170 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a> | ||
| 12171 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code> | ||
| 12172 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> | ||
| 12173 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></code> | ||
| 12174 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></code> | ||
| 12175 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> | ||
| 12176 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCLIBC" title="TCLIBC">TCLIBC</a></code> | ||
| 12177 | </p></li></ul></div><p> | ||
| 12178 | </p></div><div class="section" title="10.1.2. Machine"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-machine"></a>10.1.2. Machine</h3></div></div></div><p> | ||
| 12179 | This section lists variables whose context is the machine. | ||
| 12180 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></code> | ||
| 12181 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a> | ||
| 12182 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a> | ||
| 12183 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a> | ||
| 12184 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a> | ||
| 12185 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS | ||
| 12186 | </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS | ||
| 12187 | </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS | ||
| 12188 | </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"> | ||
| 12189 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li></ul></div><p> | ||
| 12190 | </p></div><div class="section" title="10.1.3. Local"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-local"></a>10.1.3. Local</h3></div></div></div><p> | ||
| 12191 | This section lists variables whose context is the local configuration through the | ||
| 12192 | <code class="filename">local.conf</code> file. | ||
| 12193 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> | ||
| 12194 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> | ||
| 12195 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> | ||
| 12196 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code> | ||
| 12197 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES | ||
| 12198 | </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> | ||
| 12199 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a> | ||
| 12200 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a> | ||
| 12201 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION"> | ||
| 12202 | ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li></ul></div><p> | ||
| 12203 | </p></div></div><div class="section" title="10.2. Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-recipes"></a>10.2. Recipes</h2></div></div></div><p> | ||
| 12204 | The following subsections provide lists of variables whose context is | ||
| 12205 | recipes: required, dependencies, path, and extra build information. | ||
| 12206 | </p><div class="section" title="10.2.1. Required"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-required"></a>10.2.1. Required</h3></div></div></div><p> | ||
| 12207 | This section lists variables that are required for recipes. | ||
| 12208 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DESCRIPTION" title="DESCRIPTION">DESCRIPTION</a> | ||
| 12209 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a> | ||
| 12210 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a> | ||
| 12211 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SECTION" title="SECTION">SECTION</a> | ||
| 12212 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">HOMEPAGE</a> | ||
| 12213 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-AUTHOR" title="AUTHOR">AUTHOR</a> | ||
| 12214 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a> | ||
| 12215 | </code></p></li></ul></div><p> | ||
| 12216 | </p></div><div class="section" title="10.2.2. Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-dependencies"></a>10.2.2. Dependencies</h3></div></div></div><p> | ||
| 12217 | This section lists variables that define recipe dependencies. | ||
| 12218 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a> | ||
| 12219 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a> | ||
| 12220 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a> | ||
| 12221 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a> | ||
| 12222 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RREPLACES" title="RREPLACES">RREPLACES</a> | ||
| 12223 | </code></p></li></ul></div><p> | ||
| 12224 | </p></div><div class="section" title="10.2.3. Paths"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-paths"></a>10.2.3. Paths</h3></div></div></div><p> | ||
| 12225 | This section lists variables that define recipe paths. | ||
| 12226 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a> | ||
| 12227 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-S" title="S">S</a> | ||
| 12228 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a> | ||
| 12229 | </code></p></li></ul></div><p> | ||
| 12230 | </p></div><div class="section" title="10.2.4. Extra Build Information"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-build"></a>10.2.4. Extra Build Information</h3></div></div></div><p> | ||
| 12231 | This section lists variables that define extra build information for recipes. | ||
| 12232 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_PN_ALIAS" title="DISTRO_PN_ALIAS">DISTRO_PN_ALIAS</a> | ||
| 12233 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a> | ||
| 12234 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a> | ||
| 12235 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a> | ||
| 12236 | </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> | ||
| 12237 | </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE | ||
| 12238 | </a></code></p></li></ul></div><p> | ||
| 12239 | </p></div></div></div> | ||
| 12240 | |||
| 12241 | <div class="chapter" title="Chapter 11. FAQ"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Chapter 11. FAQ</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><a id="id1519542"></a><table border="0" width="100%" summary="Q and A Set"><col align="left" width="1%" /><col /><tbody><tr class="question" title="11.1."><td align="left" valign="top"><a id="id1519546"></a><a id="id1519547"></a><p><b>11.1.</b></p></td><td align="left" valign="top"><p> | ||
| 12242 | How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>? | ||
| 12243 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12244 | The term "Poky" is sometimes used to refer to the build system that the | ||
| 12245 | Yocto Project uses. | ||
| 12246 | The build system used in the Yocto project is referred to as the | ||
| 12247 | OpenEmbedded build system because "Poky" was derived from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>. | ||
| 12248 | Poky is a stable, smaller subset focused on the mobile environment. | ||
| 12249 | Development in the Yocto Project using Poky is closely tied to OpenEmbedded with | ||
| 12250 | features being merged regularly between the two for mutual benefit. | ||
| 12251 | For a fuller description of the term "Poky", see the | ||
| 12252 | <a class="link" href="#poky" target="_top">poky</a> term in the Yocto Project | ||
| 12253 | Development Manual. | ||
| 12254 | </p></td></tr><tr class="question" title="11.2."><td align="left" valign="top"><a id="id1519579"></a><a id="id1519580"></a><p><b>11.2.</b></p></td><td align="left" valign="top"><p> | ||
| 12255 | I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. | ||
| 12256 | Can I still use the Yocto Project? | ||
| 12257 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12258 | You can use a stand-alone tarball to provide Python 2.6. | ||
| 12259 | You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations: | ||
| 12260 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2" target="_top">32-bit tarball</a></p></li><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2" target="_top">64-bit tarball</a></p></li></ul></div><p> | ||
| 12261 | </p><p> | ||
| 12262 | These tarballs are self-contained with all required libraries and should work | ||
| 12263 | on most Linux systems. | ||
| 12264 | To use the tarballs extract them into the root | ||
| 12265 | directory and run the appropriate command: | ||
| 12266 | </p><pre class="literallayout"> | ||
| 12267 | $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH | ||
| 12268 | $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH | ||
| 12269 | </pre><p> | ||
| 12270 | </p><p> | ||
| 12271 | Once you run the command, BitBake uses Python 2.6. | ||
| 12272 | </p></td></tr><tr class="question" title="11.3."><td align="left" valign="top"><a id="id1519623"></a><a id="id1519624"></a><p><b>11.3.</b></p></td><td align="left" valign="top"><p> | ||
| 12273 | How can you claim Poky is stable? | ||
| 12274 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12275 | There are three areas that help with stability; | ||
| 12276 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Yocto Project team keeps | ||
| 12277 | <a class="link" href="#poky" target="_top">Poky</a> small and focused. | ||
| 12278 | It contains around 650 packages as compared to over 5000 for full | ||
| 12279 | OpenEmbedded.</p></li><li class="listitem"><p>The Yocto Project only supports hardware that the | ||
| 12280 | team has access to for testing.</p></li><li class="listitem"><p>The Yocto Project uses an an autobuilder, | ||
| 12281 | which provides continuous build and integration tests.</p></li></ul></div><p> | ||
| 12282 | </p></td></tr><tr class="question" title="11.4."><td align="left" valign="top"><a id="id1519656"></a><a id="id1519657"></a><p><b>11.4.</b></p></td><td align="left" valign="top"><p> | ||
| 12283 | How do I get support for my board added to the Yocto Project? | ||
| 12284 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12285 | There are two main ways to get a board supported in the Yocto Project; | ||
| 12286 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Send the Yocto Project team information on the board | ||
| 12287 | and if the team does not have it yet they will consider adding it.</p></li><li class="listitem"><p>Send the Yocto Project team the BitBake recipes if you have them. | ||
| 12288 | </p></li></ul></div><p> | ||
| 12289 | Usually, if the board is not completely exotic, adding support in | ||
| 12290 | the Yocto Project is fairly straightforward. | ||
| 12291 | </p></td></tr><tr class="question" title="11.5."><td align="left" valign="top"><a id="id1519678"></a><a id="id1519679"></a><p><b>11.5.</b></p></td><td align="left" valign="top"><p> | ||
| 12292 | Are there any products using the OpenEmbedded build system (poky)? | ||
| 12293 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12294 | The <a class="ulink" href="http://vernier.com/labquest/" target="_top">Vernier LabQuest</a> is using | ||
| 12295 | the OpenEmbedded build system. | ||
| 12296 | See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_top">Vernier LabQuest</a> | ||
| 12297 | for more information. | ||
| 12298 | There are a number of pre-production devices using the OpenEmbedded build system | ||
| 12299 | and the Yocto Project team | ||
| 12300 | announces them as soon as they are released. | ||
| 12301 | </p></td></tr><tr class="question" title="11.6."><td align="left" valign="top"><a id="id1519700"></a><a id="id1519702"></a><p><b>11.6.</b></p></td><td align="left" valign="top"><p> | ||
| 12302 | What does the OpenEmbedded build system produce as output? | ||
| 12303 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12304 | Because the same set of recipes can be used to create output of various formats, the | ||
| 12305 | output of an OpenEmbedded build depends on how it was started. | ||
| 12306 | Usually, the output is a flashable image ready for the target device. | ||
| 12307 | </p></td></tr><tr class="question" title="11.7."><td align="left" valign="top"><a id="id1519711"></a><a id="id1519712"></a><p><b>11.7.</b></p></td><td align="left" valign="top"><p> | ||
| 12308 | How do I add my package to the Yocto Project? | ||
| 12309 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12310 | To add a package, you need to create a BitBake recipe. | ||
| 12311 | For information on how to add a package, see the section | ||
| 12312 | "<a class="link" href="#usingpoky-extend-addpkg" target="_top">Adding a Package</a>" | ||
| 12313 | in the Yocto Project Development Manual. | ||
| 12314 | </p></td></tr><tr class="question" title="11.8."><td align="left" valign="top"><a id="id1519726"></a><a id="id1519727"></a><p><b>11.8.</b></p></td><td align="left" valign="top"><p> | ||
| 12315 | Do I have to reflash my entire board with a new Yocto Project image when recompiling | ||
| 12316 | a package? | ||
| 12317 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12318 | The OpenEmbedded build system can build packages in various formats such as | ||
| 12319 | <code class="filename">ipk</code> for <code class="filename">ipkg</code>/<code class="filename">opkg</code>, | ||
| 12320 | Debian package (<code class="filename">.deb</code>), or RPM. | ||
| 12321 | The packages can then be upgraded using the package tools on the device, much like | ||
| 12322 | on a desktop distribution such as Ubuntu or Fedora. | ||
| 12323 | </p></td></tr><tr class="question" title="11.9."><td align="left" valign="top"><a id="id1519761"></a><a id="id1519762"></a><p><b>11.9.</b></p></td><td align="left" valign="top"><p> | ||
| 12324 | What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? | ||
| 12325 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12326 | GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_top">GNOME</a> | ||
| 12327 | platform targeted at mobile and embedded devices. | ||
| 12328 | The the main difference between GNOME Mobile and standard GNOME is that | ||
| 12329 | desktop-orientated libraries have been removed, along with deprecated libraries, | ||
| 12330 | creating a much smaller footprint. | ||
| 12331 | </p></td></tr><tr class="question" title="11.10."><td align="left" valign="top"><a id="id1519778"></a><a id="id1519780"></a><p><b>11.10.</b></p></td><td align="left" valign="top"><p> | ||
| 12332 | I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'. | ||
| 12333 | What is wrong? | ||
| 12334 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12335 | You are probably running the build on an NTFS filesystem. | ||
| 12336 | Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead. | ||
| 12337 | </p></td></tr><tr class="question" title="11.11."><td align="left" valign="top"><a id="id1519811"></a><a id="id1519812"></a><p><b>11.11.</b></p></td><td align="left" valign="top"><p> | ||
| 12338 | How do I make the Yocto Project work in RHEL/CentOS? | ||
| 12339 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12340 | To get the Yocto Project working under RHEL/CentOS 5.1 you need to first | ||
| 12341 | install some required packages. | ||
| 12342 | The standard CentOS packages needed are: | ||
| 12343 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>"Development tools" (selected during installation)</p></li><li class="listitem"><p><code class="filename">texi2html</code></p></li><li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li></ul></div><p> | ||
| 12344 | On top of these, you need the following external packages: | ||
| 12345 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">python-sqlite2</code> from | ||
| 12346 | <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG repository</a> | ||
| 12347 | </p></li><li class="listitem"><p><code class="filename">help2man</code> from | ||
| 12348 | <a class="ulink" href="http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html" target="_top">Karan repository</a></p></li></ul></div><p> | ||
| 12349 | </p><p> | ||
| 12350 | Once these packages are installed, the OpenEmbedded build system will be able | ||
| 12351 | to build standard images. | ||
| 12352 | However, there might be a problem with the QEMU emulator segfaulting. | ||
| 12353 | You can either disable the generation of binary locales by setting | ||
| 12354 | <code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a> | ||
| 12355 | </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code> | ||
| 12356 | from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. | ||
| 12357 | </p></td></tr><tr class="question" title="11.12."><td align="left" valign="top"><a id="id1519899"></a><a id="id1519900"></a><p><b>11.12.</b></p></td><td align="left" valign="top"><p> | ||
| 12358 | I see lots of 404 responses for files on | ||
| 12359 | <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong? | ||
| 12360 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12361 | Nothing is wrong. | ||
| 12362 | The OpenEmbedded build system checks any configured source mirrors before downloading | ||
| 12363 | from the upstream sources. | ||
| 12364 | The build system does this searching for both source archives and | ||
| 12365 | pre-checked out versions of SCM managed software. | ||
| 12366 | These checks help in large installations because it can reduce load on the SCM servers | ||
| 12367 | themselves. | ||
| 12368 | The address above is one of the default mirrors configured into the | ||
| 12369 | build system. | ||
| 12370 | Consequently, if an upstream source disappears, the team | ||
| 12371 | can place sources there so builds continue to work. | ||
| 12372 | </p></td></tr><tr class="question" title="11.13."><td align="left" valign="top"><a id="id1519919"></a><a id="id1519920"></a><p><b>11.13.</b></p></td><td align="left" valign="top"><p> | ||
| 12373 | I have machine-specific data in a package for one machine only but the package is | ||
| 12374 | being marked as machine-specific in all cases, how do I prevent this? | ||
| 12375 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12376 | Set <code class="filename"><a class="link" href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a> | ||
| 12377 | </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is | ||
| 12378 | manually marked as | ||
| 12379 | machine-specific in the case that needs it. | ||
| 12380 | The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>. | ||
| 12381 | </p></td></tr><tr class="question" title="11.14."><td align="left" valign="top"><a id="id1519958"></a><a id="id1519959"></a><p><b>11.14.</b></p></td><td align="left" valign="top"><p> | ||
| 12382 | I'm behind a firewall and need to use a proxy server. How do I do that? | ||
| 12383 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12384 | Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code> | ||
| 12385 | and you therefore need to specify the proxy settings in a | ||
| 12386 | <code class="filename">.wgetrc</code> file in your home directory. | ||
| 12387 | Example settings in that file would be | ||
| 12388 | </p><pre class="literallayout"> | ||
| 12389 | http_proxy = http://proxy.yoyodyne.com:18023/ | ||
| 12390 | ftp_proxy = http://proxy.yoyodyne.com:18023/ | ||
| 12391 | </pre><p> | ||
| 12392 | The Yocto Project also includes a <code class="filename">site.conf.sample</code> | ||
| 12393 | file that shows how to configure CVS and Git proxy servers | ||
| 12394 | if needed. | ||
| 12395 | </p></td></tr><tr class="question" title="11.15."><td align="left" valign="top"><a id="id1519996"></a><a id="id1519997"></a><p><b>11.15.</b></p></td><td align="left" valign="top"><p> | ||
| 12396 | I'm using Ubuntu Intrepid and am seeing build failures. What’s wrong? | ||
| 12397 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12398 | In Intrepid, Ubuntu turns on by default the normally optional compile-time security features | ||
| 12399 | and warnings. | ||
| 12400 | There are more details at | ||
| 12401 | <a class="ulink" href="https://wiki.ubuntu.com/CompilerFlags" target="_top">https://wiki.ubuntu.com/CompilerFlags</a>. | ||
| 12402 | You can work around this problem by disabling those options by adding | ||
| 12403 | the following to the <code class="filename">BUILD_CPPFLAGS</code> variable in the | ||
| 12404 | <code class="filename">conf/bitbake.conf</code> file. | ||
| 12405 | </p><pre class="literallayout"> | ||
| 12406 | " -Wno-format-security -U_FORTIFY_SOURCE" | ||
| 12407 | </pre><p> | ||
| 12408 | </p></td></tr><tr class="question" title="11.16."><td align="left" valign="top"><a id="id1520034"></a><a id="id1520035"></a><p><b>11.16.</b></p></td><td align="left" valign="top"><p> | ||
| 12409 | What’s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>? | ||
| 12410 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12411 | The <code class="filename">*-native</code> targets are designed to run on the system | ||
| 12412 | being used for the build. | ||
| 12413 | These are usually tools that are needed to assist the build in some way such as | ||
| 12414 | <code class="filename">quilt-native</code>, which is used to apply patches. | ||
| 12415 | The non-native version is the one that runs on the target device. | ||
| 12416 | </p></td></tr><tr class="question" title="11.17."><td align="left" valign="top"><a id="id1520068"></a><a id="id1520070"></a><p><b>11.17.</b></p></td><td align="left" valign="top"><p> | ||
| 12417 | I'm seeing random build failures. Help?! | ||
| 12418 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12419 | If the same build is failing in totally different and random ways, | ||
| 12420 | the most likely explanation is that either the hardware you're running the | ||
| 12421 | build on has some problem, or, if you are running the build under virtualisation, | ||
| 12422 | the virtualisation probably has bugs. | ||
| 12423 | The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and | ||
| 12424 | CPU activity and is sensitive to even single bit failures in any of these areas. | ||
| 12425 | True random failures have always been traced back to hardware or virtualisation issues. | ||
| 12426 | </p></td></tr><tr class="question" title="11.18."><td align="left" valign="top"><a id="id1520082"></a><a id="id1520083"></a><p><b>11.18.</b></p></td><td align="left" valign="top"><p> | ||
| 12427 | What do we need to ship for license compliance? | ||
| 12428 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12429 | This is a difficult question and you need to consult your lawyer for the answer | ||
| 12430 | for your specific case. | ||
| 12431 | It is worth bearing in mind that for GPL compliance there needs to be enough | ||
| 12432 | information shipped to allow someone else to rebuild the same end result | ||
| 12433 | you are shipping. | ||
| 12434 | This means sharing the source code, any patches applied to it, and also any | ||
| 12435 | configuration information about how that package was configured and built. | ||
| 12436 | </p></td></tr><tr class="question" title="11.19."><td align="left" valign="top"><a id="id1520094"></a><a id="id1520095"></a><p><b>11.19.</b></p></td><td align="left" valign="top"><p> | ||
| 12437 | How do I disable the cursor on my touchscreen device? | ||
| 12438 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12439 | You need to create a form factor file as described in the | ||
| 12440 | "<a class="link" href="#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>" | ||
| 12441 | section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows: | ||
| 12442 | </p><pre class="literallayout"> | ||
| 12443 | HAVE_TOUCHSCREEN=1 | ||
| 12444 | </pre><p> | ||
| 12445 | </p></td></tr><tr class="question" title="11.20."><td align="left" valign="top"><a id="id1520125"></a><a id="id1520126"></a><p><b>11.20.</b></p></td><td align="left" valign="top"><p> | ||
| 12446 | How do I make sure connected network interfaces are brought up by default? | ||
| 12447 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12448 | The default interfaces file provided by the netbase recipe does not | ||
| 12449 | automatically bring up network interfaces. | ||
| 12450 | Therefore, you will need to add a BSP-specific netbase that includes an interfaces | ||
| 12451 | file. | ||
| 12452 | See the "<a class="link" href="#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>" | ||
| 12453 | section for information on creating these types of miscellaneous recipe files. | ||
| 12454 | </p><p> | ||
| 12455 | For example, add the following files to your layer: | ||
| 12456 | </p><pre class="literallayout"> | ||
| 12457 | meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces | ||
| 12458 | meta-MACHINE/recipes-bsp/netbase/netbase_4.44.bbappend | ||
| 12459 | </pre><p> | ||
| 12460 | </p></td></tr><tr class="question" title="11.21."><td align="left" valign="top"><a id="id1520156"></a><a id="id1520157"></a><p><b>11.21.</b></p></td><td align="left" valign="top"><p> | ||
| 12461 | How do I create images with more free space? | ||
| 12462 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12463 | Images are created to be 1.2 times the size of the populated root filesystem. | ||
| 12464 | To modify this ratio so that there is more free space available, you need to | ||
| 12465 | set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>. | ||
| 12466 | For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets | ||
| 12467 | the image size ratio to one and a half times the size of the populated | ||
| 12468 | root filesystem. | ||
| 12469 | </p><pre class="literallayout"> | ||
| 12470 | IMAGE_OVERHEAD_FACTOR = "1.5" | ||
| 12471 | </pre><p> | ||
| 12472 | </p></td></tr><tr class="question" title="11.22."><td align="left" valign="top"><a id="id1520188"></a><a id="id1520190"></a><p><b>11.22.</b></p></td><td align="left" valign="top"><p> | ||
| 12473 | Why don't you support directories with spaces in the pathnames? | ||
| 12474 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12475 | The Yocto Project team has tried to do this before but too many of the tools | ||
| 12476 | the OpenEmbedded build system depends on such as <code class="filename">autoconf</code> | ||
| 12477 | break when they find spaces in pathnames. | ||
| 12478 | Until that situation changes, the team will not support spaces in pathnames. | ||
| 12479 | </p></td></tr><tr class="question" title="11.23."><td align="left" valign="top"><a id="id1520206"></a><a id="id1520207"></a><p><b>11.23.</b></p></td><td align="left" valign="top"><p> | ||
| 12480 | How do I use an external toolchain? | ||
| 12481 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12482 | The toolchain configuration is very flexible and customizable. | ||
| 12483 | It is primarily controlled with the | ||
| 12484 | <code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> variable. | ||
| 12485 | This variable controls which <code class="filename">tcmode-*.inc</code> file to include | ||
| 12486 | from the <code class="filename">meta/conf/distro/include</code> directory within the | ||
| 12487 | <a class="link" href="#source-directory" target="_top">source directory</a>. | ||
| 12488 | </p><p> | ||
| 12489 | The default value of <code class="filename">TCMODE</code> is "default" | ||
| 12490 | (i.e. <code class="filename">tcmode-default.inc</code>). | ||
| 12491 | However, other patterns are accepted. | ||
| 12492 | In particular, "external-*" refers to external toolchains of which there are some | ||
| 12493 | basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>). | ||
| 12494 | You can use your own custom toolchain definition in your own layer | ||
| 12495 | (or as defined in the <code class="filename">local.conf</code> file) at the location | ||
| 12496 | <code class="filename">conf/distro/include/tcmode-*.inc</code>. | ||
| 12497 | </p><p> | ||
| 12498 | In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. | ||
| 12499 | This recipe file needs to package up any pre-built objects in the toolchain such as | ||
| 12500 | <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>, | ||
| 12501 | any locales, and <code class="filename">libc</code>. | ||
| 12502 | An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located | ||
| 12503 | in <code class="filename">meta/recipes-core/meta/</code> within the source directory. | ||
| 12504 | </p></td></tr><tr class="question" title="11.24."><td align="left" valign="top"><a id="id1520281"></a><a id="id1520316"></a><p><b>11.24.</b></p></td><td align="left" valign="top"><p><a id="how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server"></a> | ||
| 12505 | How does the OpenEmbedded build system obtain source code and will it work behind my | ||
| 12506 | firewall or proxy server? | ||
| 12507 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12508 | The way the build system obtains source code is highly configurable. | ||
| 12509 | You can setup the build system to get source code in most environments if | ||
| 12510 | HTTP transport is available. | ||
| 12511 | </p><p> | ||
| 12512 | When the build system searches for source code, it first tries the local download directory. | ||
| 12513 | If that location fails, Poky tries PREMIRRORS, the upstream source, | ||
| 12514 | and then MIRRORS in that order. | ||
| 12515 | </p><p> | ||
| 12516 | By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS | ||
| 12517 | for SCM-based sources, | ||
| 12518 | upstreams for normal tarballs, and then falls back to a number of other mirrors | ||
| 12519 | including the Yocto Project source mirror if those fail. | ||
| 12520 | </p><p> | ||
| 12521 | As an example, you could add a specific server for Poky to attempt before any | ||
| 12522 | others by adding something like the following to the <code class="filename">local.conf</code> | ||
| 12523 | configuration file: | ||
| 12524 | </p><pre class="literallayout"> | ||
| 12525 | PREMIRRORS_prepend = "\ | ||
| 12526 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
| 12527 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
| 12528 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
| 12529 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
| 12530 | </pre><p> | ||
| 12531 | </p><p> | ||
| 12532 | These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS | ||
| 12533 | requests and direct them to the <code class="filename">http://</code> sources mirror. | ||
| 12534 | You can use <code class="filename">file://</code> URLs to point to local directories | ||
| 12535 | or network shares as well. | ||
| 12536 | </p><p> | ||
| 12537 | Aside from the previous technique, these options also exist: | ||
| 12538 | </p><pre class="literallayout"> | ||
| 12539 | BB_NO_NETWORK = "1" | ||
| 12540 | </pre><p> | ||
| 12541 | This statement tells BitBake to throw an error instead of trying to access the | ||
| 12542 | Internet. | ||
| 12543 | This technique is useful if you want to ensure code builds only from local sources. | ||
| 12544 | </p><p> | ||
| 12545 | Here is another technique: | ||
| 12546 | </p><pre class="literallayout"> | ||
| 12547 | BB_FETCH_PREMIRRORONLY = "1" | ||
| 12548 | </pre><p> | ||
| 12549 | This statement limits Poky to pulling source from the PREMIRRORS only. | ||
| 12550 | Again, this technique is useful for reproducing builds. | ||
| 12551 | </p><p> | ||
| 12552 | Here is another technique: | ||
| 12553 | </p><pre class="literallayout"> | ||
| 12554 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
| 12555 | </pre><p> | ||
| 12556 | This statement tells Poky to generate mirror tarballs. | ||
| 12557 | This technique is useful if you want to create a mirror server. | ||
| 12558 | If not, however, the technique can simply waste time during the build. | ||
| 12559 | </p><p> | ||
| 12560 | Finally, consider an example where you are behind an HTTP-only firewall. | ||
| 12561 | You could make the following changes to the <code class="filename">local.conf</code> | ||
| 12562 | configuration file as long as the PREMIRROR server is up to date: | ||
| 12563 | </p><pre class="literallayout"> | ||
| 12564 | PREMIRRORS_prepend = "\ | ||
| 12565 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
| 12566 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
| 12567 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
| 12568 | BB_FETCH_PREMIRRORONLY = "1" | ||
| 12569 | </pre><p> | ||
| 12570 | These changes would cause Poky to successfully fetch source over HTTP and | ||
| 12571 | any network accesses to anything other than the PREMIRROR would fail. | ||
| 12572 | </p><p> | ||
| 12573 | The build system also honors the standard shell environment variables | ||
| 12574 | <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>, | ||
| 12575 | <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code> | ||
| 12576 | to redirect requests through proxy servers. | ||
| 12577 | </p></td></tr><tr class="question" title="11.25."><td align="left" valign="top"><a id="id1520463"></a><a id="id1520464"></a><p><b>11.25.</b></p></td><td align="left" valign="top"><p> | ||
| 12578 | Can I get rid of build output so I can start over? | ||
| 12579 | </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> | ||
| 12580 | Yes - you can easily do this. | ||
| 12581 | When you use BitBake to build an image, all the build output goes into the | ||
| 12582 | directory created when you source the <code class="filename">oe-init-build-env</code> | ||
| 12583 | setup file. | ||
| 12584 | By default, this <a class="link" href="#build-directory" target="_top">build directory</a> | ||
| 12585 | is named <code class="filename">build</code> but can be named | ||
| 12586 | anything you want. | ||
| 12587 | </p><p> | ||
| 12588 | Within the build directory is the <code class="filename">tmp</code> directory. | ||
| 12589 | To remove all the build output yet preserve any source code or downloaded files | ||
| 12590 | from previous builds, simply remove the <code class="filename">tmp</code> directory. | ||
| 12591 | </p></td></tr></tbody></table></div></div> | ||
| 12592 | |||
| 12593 | <div class="chapter" title="Chapter 12. Contributing to the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="resources"></a>Chapter 12. Contributing to the Yocto Project</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#resources-intro">12.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">12.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">12.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">12.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">12.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">12.6. Contributions</a></span></dt></dl></div><div class="section" title="12.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-intro"></a>12.1. Introduction</h2></div></div></div><p> | ||
| 12594 | The Yocto Project team is happy for people to experiment with the Yocto Project. | ||
| 12595 | A number of places exist to find help if you run into difficulties or find bugs. | ||
| 12596 | To find out how to download source code, | ||
| 12597 | see the "<a class="link" href="#local-yp-release" target="_top">Yocto Project Release</a>" | ||
| 12598 | list item in the Yocto Project Development Manual. | ||
| 12599 | </p></div><div class="section" title="12.2. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-bugtracker"></a>12.2. Tracking Bugs</h2></div></div></div><p> | ||
| 12600 | If you find problems with the Yocto Project, you should report them using the | ||
| 12601 | Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>. | ||
| 12602 | </p></div><div class="section" title="12.3. Mailing lists"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-mailinglist"></a>12.3. Mailing lists</h2></div></div></div><p> | ||
| 12603 | There are a number of mailing lists maintained by the Yocto Project as well as | ||
| 12604 | related OpenEmbedded mailing lists for discussion, patch submission and announcements. | ||
| 12605 | To subscribe to one of the following mailing lists, click on the appropriate URL | ||
| 12606 | in the following list and follow the instructions: | ||
| 12607 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> - | ||
| 12608 | General Yocto Project discussion mailing list. </p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core</a> - | ||
| 12609 | Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel</a> - | ||
| 12610 | Discussion mailing list about OpenEmbedded.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel</a> - | ||
| 12611 | Discussion mailing list about the BitBake build tool.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> - | ||
| 12612 | Discussion mailing list about Poky.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> - | ||
| 12613 | Mailing list to receive official Yocto Project release and milestone | ||
| 12614 | announcements.</p></li></ul></div><p> | ||
| 12615 | </p></div><div class="section" title="12.4. Internet Relay Chat (IRC)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-irc"></a>12.4. Internet Relay Chat (IRC)</h2></div></div></div><p> | ||
| 12616 | Two IRC channels on freenode are available for the Yocto Project and Poky discussions: | ||
| 12617 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">#yocto</code></p></li><li class="listitem"><p><code class="filename">#poky</code></p></li></ul></div><p> | ||
| 12618 | </p></div><div class="section" title="12.5. Links"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-links"></a>12.5. Links</h2></div></div></div><p> | ||
| 12619 | Following is a list of resources you will find helpful: | ||
| 12620 | </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_top">The Yocto Project website</a>: | ||
| 12621 | </em></span> The home site for the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span> | ||
| 12622 | The company who acquired OpenedHand in 2008 and began development on the | ||
| 12623 | Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span> | ||
| 12624 | The upstream, generic, embedded distribution used as the basis for the build system in the | ||
| 12625 | Yocto Project. | ||
| 12626 | Poky derives from and contributes back to the OpenEmbedded project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top"> | ||
| 12627 | BitBake</a>:</em></span> The tool used to process metadata.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top"> | ||
| 12628 | BitBake User Manual</a>:</em></span> A comprehensive guide to the BitBake tool. | ||
| 12629 | </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>: | ||
| 12630 | </em></span> An open source machine emulator and virtualizer.</p></li></ul></div><p> | ||
| 12631 | </p></div><div class="section" title="12.6. Contributions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-contributions"></a>12.6. Contributions</h2></div></div></div><p> | ||
| 12632 | The Yocto Project gladly accepts contributions. | ||
| 12633 | You can submit changes to the project either by creating and sending pull requests, | ||
| 12634 | or by submitting patches through email. | ||
| 12635 | For information on how to do both, see the | ||
| 12636 | "<a class="link" href="#how-to-submit-a-change" target="_top">How to Submit a Change</a>" | ||
| 12637 | section in the Yocto Project Development Manual. | ||
| 12638 | </p></div></div> | ||
| 12639 | |||
| 12640 | |||
| 12641 | |||
| 12642 | </div> | ||
| 12643 | |||
| 12644 | |||
| 12645 | |||
| 12646 | </div></body></html> | ||
diff --git a/documentation/mega-manual/mega-manual.tgz b/documentation/mega-manual/mega-manual.tgz new file mode 100644 index 0000000000..5321a0f2bb --- /dev/null +++ b/documentation/mega-manual/mega-manual.tgz | |||
| Binary files differ | |||
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml new file mode 100644 index 0000000000..b3ee590326 --- /dev/null +++ b/documentation/mega-manual/mega-manual.xml | |||
| @@ -0,0 +1,48 @@ | |||
| 1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | |||
| 6 | <book id='mega-manual' lang='en' | ||
| 7 | xmlns:xi="http://www.w3.org/2003/XInclude" | ||
| 8 | xmlns="http://docbook.org/ns/docbook" | ||
| 9 | > | ||
| 10 | |||
| 11 | <xi:include | ||
| 12 | xmlns:xi="http://www.w3.org/2003/XInclude" href="../yocto-project-qs/yocto-project-qs.xml"/> | ||
| 13 | |||
| 14 | <para><imagedata fileref="figures/dev-title.png" width="100%" align="left" scalefit="1" /></para> | ||
| 15 | |||
| 16 | <xi:include | ||
| 17 | xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual.xml"/> | ||
| 18 | |||
| 19 | <para><imagedata fileref="figures/adt-title.png" width="100%" align="left" scalefit="1" /></para> | ||
| 20 | |||
| 21 | <xi:include | ||
| 22 | xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-manual.xml"/> | ||
| 23 | |||
| 24 | <para><imagedata fileref="figures/bsp-title.png" width="100%" align="left" scalefit="1" /></para> | ||
| 25 | |||
| 26 | <xi:include | ||
| 27 | xmlns:xi="http://www.w3.org/2003/XInclude" href="../bsp-guide/bsp-guide.xml"/> | ||
| 28 | |||
| 29 | <para><imagedata fileref="figures/kernel-title.png" width="100%" align="left" scalefit="1" /></para> | ||
| 30 | |||
| 31 | <xi:include | ||
| 32 | xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-manual/kernel-manual.xml"/> | ||
| 33 | |||
| 34 | <para><imagedata fileref="figures/poky-title.png" width="100%" align="left" scalefit="1" /></para> | ||
| 35 | |||
| 36 | <xi:include | ||
| 37 | xmlns:xi="http://www.w3.org/2003/XInclude" href="../poky-ref-manual/poky-ref-manual.xml"/> | ||
| 38 | |||
| 39 | <!-- <index id='index'> | ||
| 40 | <title>Index</title> | ||
| 41 | </index> | ||
| 42 | --> | ||
| 43 | |||
| 44 | </book> | ||
| 45 | |||
| 46 | <!-- | ||
| 47 | vim: expandtab tw=80 ts=4 | ||
| 48 | --> | ||
diff --git a/documentation/mega-manual/mega-style.css b/documentation/mega-manual/mega-style.css new file mode 100644 index 0000000000..a97d691836 --- /dev/null +++ b/documentation/mega-manual/mega-style.css | |||
| @@ -0,0 +1,979 @@ | |||
| 1 | /* | ||
| 2 | Generic XHTML / DocBook XHTML CSS Stylesheet. | ||
| 3 | |||
| 4 | Browser wrangling and typographic design by | ||
| 5 | Oyvind Kolas / pippin@gimp.org | ||
| 6 | |||
| 7 | Customised for Poky by | ||
| 8 | Matthew Allum / mallum@o-hand.com | ||
| 9 | |||
| 10 | Thanks to: | ||
| 11 | Liam R. E. Quin | ||
| 12 | William Skaggs | ||
| 13 | Jakub Steiner | ||
| 14 | |||
| 15 | Structure | ||
| 16 | --------- | ||
| 17 | |||
| 18 | The stylesheet is divided into the following sections: | ||
| 19 | |||
| 20 | Positioning | ||
| 21 | Margins, paddings, width, font-size, clearing. | ||
| 22 | Decorations | ||
| 23 | Borders, style | ||
| 24 | Colors | ||
| 25 | Colors | ||
| 26 | Graphics | ||
| 27 | Graphical backgrounds | ||
| 28 | Nasty IE tweaks | ||
| 29 | Workarounds needed to make it work in internet explorer, | ||
| 30 | currently makes the stylesheet non validating, but up until | ||
| 31 | this point it is validating. | ||
| 32 | Mozilla extensions | ||
| 33 | Transparency for footer | ||
| 34 | Rounded corners on boxes | ||
| 35 | |||
| 36 | */ | ||
| 37 | |||
| 38 | |||
| 39 | /*************** / | ||
| 40 | / Positioning / | ||
| 41 | / ***************/ | ||
| 42 | |||
| 43 | body { | ||
| 44 | font-family: Verdana, Sans, sans-serif; | ||
| 45 | |||
| 46 | min-width: 640px; | ||
| 47 | width: 80%; | ||
| 48 | margin: 0em auto; | ||
| 49 | padding: 2em 5em 5em 5em; | ||
| 50 | color: #333; | ||
| 51 | } | ||
| 52 | |||
| 53 | h1,h2,h3,h4,h5,h6,h7 { | ||
| 54 | font-family: Arial, Sans; | ||
| 55 | color: #00557D; | ||
| 56 | clear: both; | ||
| 57 | } | ||
| 58 | |||
| 59 | h1 { | ||
| 60 | font-size: 2em; | ||
| 61 | text-align: left; | ||
| 62 | padding: 0em 0em 0em 0em; | ||
| 63 | margin: 2em 0em 0em 0em; | ||
| 64 | } | ||
| 65 | |||
| 66 | h2.subtitle { | ||
| 67 | margin: 0.10em 0em 3.0em 0em; | ||
| 68 | padding: 0em 0em 0em 0em; | ||
| 69 | font-size: 1.8em; | ||
| 70 | padding-left: 20%; | ||
| 71 | font-weight: normal; | ||
| 72 | font-style: italic; | ||
| 73 | } | ||
| 74 | |||
| 75 | h2 { | ||
| 76 | margin: 2em 0em 0.66em 0em; | ||
| 77 | padding: 0.5em 0em 0em 0em; | ||
| 78 | font-size: 1.5em; | ||
| 79 | font-weight: bold; | ||
| 80 | } | ||
| 81 | |||
| 82 | h3.subtitle { | ||
| 83 | margin: 0em 0em 1em 0em; | ||
| 84 | padding: 0em 0em 0em 0em; | ||
| 85 | font-size: 142.14%; | ||
| 86 | text-align: right; | ||
| 87 | } | ||
| 88 | |||
| 89 | h3 { | ||
| 90 | margin: 1em 0em 0.5em 0em; | ||
| 91 | padding: 1em 0em 0em 0em; | ||
| 92 | font-size: 140%; | ||
| 93 | font-weight: bold; | ||
| 94 | } | ||
| 95 | |||
| 96 | h4 { | ||
| 97 | margin: 1em 0em 0.5em 0em; | ||
| 98 | padding: 1em 0em 0em 0em; | ||
| 99 | font-size: 120%; | ||
| 100 | font-weight: bold; | ||
| 101 | } | ||
| 102 | |||
| 103 | h5 { | ||
| 104 | margin: 1em 0em 0.5em 0em; | ||
| 105 | padding: 1em 0em 0em 0em; | ||
| 106 | font-size: 110%; | ||
| 107 | font-weight: bold; | ||
| 108 | } | ||
| 109 | |||
| 110 | h6 { | ||
| 111 | margin: 1em 0em 0em 0em; | ||
| 112 | padding: 1em 0em 0em 0em; | ||
| 113 | font-size: 110%; | ||
| 114 | font-weight: bold; | ||
| 115 | } | ||
| 116 | |||
| 117 | .authorgroup { | ||
| 118 | background-color: transparent; | ||
| 119 | background-repeat: no-repeat; | ||
| 120 | padding-top: 256px; | ||
| 121 | background-image: url("../figures/yocto-project-bw.png"); | ||
| 122 | background-position: top; | ||
| 123 | margin-top: -256px; | ||
| 124 | padding-right: 50px; | ||
| 125 | margin-left: 50px; | ||
| 126 | text-align: center; | ||
| 127 | width: 600px; | ||
| 128 | } | ||
| 129 | |||
| 130 | h3.author { | ||
| 131 | margin: 0em 0em 0em 0em; | ||
| 132 | padding: 0em 0em 0em 0em; | ||
| 133 | font-weight: normal; | ||
| 134 | font-size: 100%; | ||
| 135 | color: #333; | ||
| 136 | clear: both; | ||
| 137 | } | ||
| 138 | |||
| 139 | .author tt.email { | ||
| 140 | font-size: 66%; | ||
| 141 | } | ||
| 142 | |||
| 143 | .titlepage hr { | ||
| 144 | width: 0em; | ||
| 145 | clear: both; | ||
| 146 | } | ||
| 147 | |||
| 148 | .revhistory { | ||
| 149 | padding-top: 2em; | ||
| 150 | clear: both; | ||
| 151 | } | ||
| 152 | |||
| 153 | .toc, | ||
| 154 | .list-of-tables, | ||
| 155 | .list-of-examples, | ||
| 156 | .list-of-figures { | ||
| 157 | padding: 1.33em 0em 2.5em 0em; | ||
| 158 | color: #00557D; | ||
| 159 | } | ||
| 160 | |||
| 161 | .toc p, | ||
| 162 | .list-of-tables p, | ||
| 163 | .list-of-figures p, | ||
| 164 | .list-of-examples p { | ||
| 165 | padding: 0em 0em 0em 0em; | ||
| 166 | padding: 0em 0em 0.3em; | ||
| 167 | margin: 1.5em 0em 0em 0em; | ||
| 168 | } | ||
| 169 | |||
| 170 | .toc p b, | ||
| 171 | .list-of-tables p b, | ||
| 172 | .list-of-figures p b, | ||
| 173 | .list-of-examples p b{ | ||
| 174 | font-size: 100.0%; | ||
| 175 | font-weight: bold; | ||
| 176 | } | ||
| 177 | |||
| 178 | .toc dl, | ||
| 179 | .list-of-tables dl, | ||
| 180 | .list-of-figures dl, | ||
| 181 | .list-of-examples dl { | ||
| 182 | margin: 0em 0em 0.5em 0em; | ||
| 183 | padding: 0em 0em 0em 0em; | ||
| 184 | } | ||
| 185 | |||
| 186 | .toc dt { | ||
| 187 | margin: 0em 0em 0em 0em; | ||
| 188 | padding: 0em 0em 0em 0em; | ||
| 189 | } | ||
| 190 | |||
| 191 | .toc dd { | ||
| 192 | margin: 0em 0em 0em 2.6em; | ||
| 193 | padding: 0em 0em 0em 0em; | ||
| 194 | } | ||
| 195 | |||
| 196 | div.glossary dl, | ||
| 197 | div.variablelist dl { | ||
| 198 | } | ||
| 199 | |||
| 200 | .glossary dl dt, | ||
| 201 | .variablelist dl dt, | ||
| 202 | .variablelist dl dt span.term { | ||
| 203 | font-weight: normal; | ||
| 204 | width: 20em; | ||
| 205 | text-align: right; | ||
| 206 | } | ||
| 207 | |||
| 208 | .variablelist dl dt { | ||
| 209 | margin-top: 0.5em; | ||
| 210 | } | ||
| 211 | |||
| 212 | .glossary dl dd, | ||
| 213 | .variablelist dl dd { | ||
| 214 | margin-top: -1em; | ||
| 215 | margin-left: 25.5em; | ||
| 216 | } | ||
| 217 | |||
| 218 | .glossary dd p, | ||
| 219 | .variablelist dd p { | ||
| 220 | margin-top: 0em; | ||
| 221 | margin-bottom: 1em; | ||
| 222 | } | ||
| 223 | |||
| 224 | |||
| 225 | div.calloutlist table td { | ||
| 226 | padding: 0em 0em 0em 0em; | ||
| 227 | margin: 0em 0em 0em 0em; | ||
| 228 | } | ||
| 229 | |||
| 230 | div.calloutlist table td p { | ||
| 231 | margin-top: 0em; | ||
| 232 | margin-bottom: 1em; | ||
| 233 | } | ||
| 234 | |||
| 235 | div p.copyright { | ||
| 236 | text-align: left; | ||
| 237 | } | ||
| 238 | |||
| 239 | div.legalnotice p.legalnotice-title { | ||
| 240 | margin-bottom: 0em; | ||
| 241 | } | ||
| 242 | |||
| 243 | p { | ||
| 244 | line-height: 1.5em; | ||
| 245 | margin-top: 0em; | ||
| 246 | |||
| 247 | } | ||
| 248 | |||
| 249 | dl { | ||
| 250 | padding-top: 0em; | ||
| 251 | } | ||
| 252 | |||
| 253 | hr { | ||
| 254 | border: solid 1px; | ||
| 255 | } | ||
| 256 | |||
| 257 | |||
| 258 | .mediaobject, | ||
| 259 | .mediaobjectco { | ||
| 260 | text-align: center; | ||
| 261 | } | ||
| 262 | |||
| 263 | img { | ||
| 264 | border: none; | ||
| 265 | } | ||
| 266 | |||
| 267 | ul { | ||
| 268 | padding: 0em 0em 0em 1.5em; | ||
| 269 | } | ||
| 270 | |||
| 271 | ul li { | ||
| 272 | padding: 0em 0em 0em 0em; | ||
| 273 | } | ||
| 274 | |||
| 275 | ul li p { | ||
| 276 | text-align: left; | ||
| 277 | } | ||
| 278 | |||
| 279 | table { | ||
| 280 | width :100%; | ||
| 281 | } | ||
| 282 | |||
| 283 | th { | ||
| 284 | padding: 0.25em; | ||
| 285 | text-align: left; | ||
| 286 | font-weight: normal; | ||
| 287 | vertical-align: top; | ||
| 288 | } | ||
| 289 | |||
| 290 | td { | ||
| 291 | padding: 0.25em; | ||
| 292 | vertical-align: top; | ||
| 293 | } | ||
| 294 | |||
| 295 | p a[id] { | ||
| 296 | margin: 0px; | ||
| 297 | padding: 0px; | ||
| 298 | display: inline; | ||
| 299 | background-image: none; | ||
| 300 | } | ||
| 301 | |||
| 302 | a { | ||
| 303 | text-decoration: underline; | ||
| 304 | color: #444; | ||
| 305 | } | ||
| 306 | |||
| 307 | pre { | ||
| 308 | overflow: auto; | ||
| 309 | } | ||
| 310 | |||
| 311 | a:hover { | ||
| 312 | text-decoration: underline; | ||
| 313 | /*font-weight: bold;*/ | ||
| 314 | } | ||
| 315 | |||
| 316 | |||
| 317 | div.informalfigure, | ||
| 318 | div.informalexample, | ||
| 319 | div.informaltable, | ||
| 320 | div.figure, | ||
| 321 | div.table, | ||
| 322 | div.example { | ||
| 323 | margin: 1em 0em; | ||
| 324 | padding: 1em; | ||
| 325 | page-break-inside: avoid; | ||
| 326 | } | ||
| 327 | |||
| 328 | |||
| 329 | div.informalfigure p.title b, | ||
| 330 | div.informalexample p.title b, | ||
| 331 | div.informaltable p.title b, | ||
| 332 | div.figure p.title b, | ||
| 333 | div.example p.title b, | ||
| 334 | div.table p.title b{ | ||
| 335 | padding-top: 0em; | ||
| 336 | margin-top: 0em; | ||
| 337 | font-size: 100%; | ||
| 338 | font-weight: normal; | ||
| 339 | } | ||
| 340 | |||
| 341 | .mediaobject .caption, | ||
| 342 | .mediaobject .caption p { | ||
| 343 | text-align: center; | ||
| 344 | font-size: 80%; | ||
| 345 | padding-top: 0.5em; | ||
| 346 | padding-bottom: 0.5em; | ||
| 347 | } | ||
| 348 | |||
| 349 | .epigraph { | ||
| 350 | padding-left: 55%; | ||
| 351 | margin-bottom: 1em; | ||
| 352 | } | ||
| 353 | |||
| 354 | .epigraph p { | ||
| 355 | text-align: left; | ||
| 356 | } | ||
| 357 | |||
| 358 | .epigraph .quote { | ||
| 359 | font-style: italic; | ||
| 360 | } | ||
| 361 | .epigraph .attribution { | ||
| 362 | font-style: normal; | ||
| 363 | text-align: right; | ||
| 364 | } | ||
| 365 | |||
| 366 | span.application { | ||
| 367 | font-style: italic; | ||
| 368 | } | ||
| 369 | |||
| 370 | .programlisting { | ||
| 371 | font-family: monospace; | ||
| 372 | font-size: 80%; | ||
| 373 | white-space: pre; | ||
| 374 | margin: 1.33em 0em; | ||
| 375 | padding: 1.33em; | ||
| 376 | } | ||
| 377 | |||
| 378 | .tip, | ||
| 379 | .warning, | ||
| 380 | .caution, | ||
| 381 | .note { | ||
| 382 | margin-top: 1em; | ||
| 383 | margin-bottom: 1em; | ||
| 384 | |||
| 385 | } | ||
| 386 | |||
| 387 | /* force full width of table within div */ | ||
| 388 | .tip table, | ||
| 389 | .warning table, | ||
| 390 | .caution table, | ||
| 391 | .note table { | ||
| 392 | border: none; | ||
| 393 | width: 100%; | ||
| 394 | } | ||
| 395 | |||
| 396 | |||
| 397 | .tip table th, | ||
| 398 | .warning table th, | ||
| 399 | .caution table th, | ||
| 400 | .note table th { | ||
| 401 | padding: 0.8em 0.0em 0.0em 0.0em; | ||
| 402 | margin : 0em 0em 0em 0em; | ||
| 403 | } | ||
| 404 | |||
| 405 | .tip p, | ||
| 406 | .warning p, | ||
| 407 | .caution p, | ||
| 408 | .note p { | ||
| 409 | margin-top: 0.5em; | ||
| 410 | margin-bottom: 0.5em; | ||
| 411 | padding-right: 1em; | ||
| 412 | text-align: left; | ||
| 413 | } | ||
| 414 | |||
| 415 | .acronym { | ||
| 416 | text-transform: uppercase; | ||
| 417 | } | ||
| 418 | |||
| 419 | b.keycap, | ||
| 420 | .keycap { | ||
| 421 | padding: 0.09em 0.3em; | ||
| 422 | margin: 0em; | ||
| 423 | } | ||
| 424 | |||
| 425 | .itemizedlist li { | ||
| 426 | clear: none; | ||
| 427 | } | ||
| 428 | |||
| 429 | .filename { | ||
| 430 | font-size: medium; | ||
| 431 | font-family: Courier, monospace; | ||
| 432 | } | ||
| 433 | |||
| 434 | |||
| 435 | div.navheader, div.heading{ | ||
| 436 | position: absolute; | ||
| 437 | left: 0em; | ||
| 438 | top: 0em; | ||
| 439 | width: 100%; | ||
| 440 | background-color: #cdf; | ||
| 441 | width: 100%; | ||
| 442 | } | ||
| 443 | |||
| 444 | div.navfooter, div.footing{ | ||
| 445 | position: fixed; | ||
| 446 | left: 0em; | ||
| 447 | bottom: 0em; | ||
| 448 | background-color: #eee; | ||
| 449 | width: 100%; | ||
| 450 | } | ||
| 451 | |||
| 452 | |||
| 453 | div.navheader td, | ||
| 454 | div.navfooter td { | ||
| 455 | font-size: 66%; | ||
| 456 | } | ||
| 457 | |||
| 458 | div.navheader table th { | ||
| 459 | /*font-family: Georgia, Times, serif;*/ | ||
| 460 | /*font-size: x-large;*/ | ||
| 461 | font-size: 80%; | ||
| 462 | } | ||
| 463 | |||
| 464 | div.navheader table { | ||
| 465 | border-left: 0em; | ||
| 466 | border-right: 0em; | ||
| 467 | border-top: 0em; | ||
| 468 | width: 100%; | ||
| 469 | } | ||
| 470 | |||
| 471 | div.navfooter table { | ||
| 472 | border-left: 0em; | ||
| 473 | border-right: 0em; | ||
| 474 | border-bottom: 0em; | ||
| 475 | width: 100%; | ||
| 476 | } | ||
| 477 | |||
| 478 | div.navheader table td a, | ||
| 479 | div.navfooter table td a { | ||
| 480 | color: #777; | ||
| 481 | text-decoration: none; | ||
| 482 | } | ||
| 483 | |||
| 484 | /* normal text in the footer */ | ||
| 485 | div.navfooter table td { | ||
| 486 | color: black; | ||
| 487 | } | ||
| 488 | |||
| 489 | div.navheader table td a:visited, | ||
| 490 | div.navfooter table td a:visited { | ||
| 491 | color: #444; | ||
| 492 | } | ||
| 493 | |||
| 494 | |||
| 495 | /* links in header and footer */ | ||
| 496 | div.navheader table td a:hover, | ||
| 497 | div.navfooter table td a:hover { | ||
| 498 | text-decoration: underline; | ||
| 499 | background-color: transparent; | ||
| 500 | color: #33a; | ||
| 501 | } | ||
| 502 | |||
| 503 | div.navheader hr, | ||
| 504 | div.navfooter hr { | ||
| 505 | display: none; | ||
| 506 | } | ||
| 507 | |||
| 508 | |||
| 509 | .qandaset tr.question td p { | ||
| 510 | margin: 0em 0em 1em 0em; | ||
| 511 | padding: 0em 0em 0em 0em; | ||
| 512 | } | ||
| 513 | |||
| 514 | .qandaset tr.answer td p { | ||
| 515 | margin: 0em 0em 1em 0em; | ||
| 516 | padding: 0em 0em 0em 0em; | ||
| 517 | } | ||
| 518 | .answer td { | ||
| 519 | padding-bottom: 1.5em; | ||
| 520 | } | ||
| 521 | |||
| 522 | .emphasis { | ||
| 523 | font-weight: bold; | ||
| 524 | } | ||
| 525 | |||
| 526 | |||
| 527 | /************* / | ||
| 528 | / decorations / | ||
| 529 | / *************/ | ||
| 530 | |||
| 531 | .titlepage { | ||
| 532 | } | ||
| 533 | |||
| 534 | .part .title { | ||
| 535 | } | ||
| 536 | |||
| 537 | .subtitle { | ||
| 538 | border: none; | ||
| 539 | } | ||
| 540 | |||
| 541 | /* | ||
| 542 | h1 { | ||
| 543 | border: none; | ||
| 544 | } | ||
| 545 | |||
| 546 | h2 { | ||
| 547 | border-top: solid 0.2em; | ||
| 548 | border-bottom: solid 0.06em; | ||
| 549 | } | ||
| 550 | |||
| 551 | h3 { | ||
| 552 | border-top: 0em; | ||
| 553 | border-bottom: solid 0.06em; | ||
| 554 | } | ||
| 555 | |||
| 556 | h4 { | ||
| 557 | border: 0em; | ||
| 558 | border-bottom: solid 0.06em; | ||
| 559 | } | ||
| 560 | |||
| 561 | h5 { | ||
| 562 | border: 0em; | ||
| 563 | } | ||
| 564 | */ | ||
| 565 | |||
| 566 | .programlisting { | ||
| 567 | border: solid 1px; | ||
| 568 | } | ||
| 569 | |||
| 570 | div.figure, | ||
| 571 | div.table, | ||
| 572 | div.informalfigure, | ||
| 573 | div.informaltable, | ||
| 574 | div.informalexample, | ||
| 575 | div.example { | ||
| 576 | border: 1px solid; | ||
| 577 | } | ||
| 578 | |||
| 579 | |||
| 580 | |||
| 581 | .tip, | ||
| 582 | .warning, | ||
| 583 | .caution, | ||
| 584 | .note { | ||
| 585 | border: 1px solid; | ||
| 586 | } | ||
| 587 | |||
| 588 | .tip table th, | ||
| 589 | .warning table th, | ||
| 590 | .caution table th, | ||
| 591 | .note table th { | ||
| 592 | border-bottom: 1px solid; | ||
| 593 | } | ||
| 594 | |||
| 595 | .question td { | ||
| 596 | border-top: 1px solid black; | ||
| 597 | } | ||
| 598 | |||
| 599 | .answer { | ||
| 600 | } | ||
| 601 | |||
| 602 | |||
| 603 | b.keycap, | ||
| 604 | .keycap { | ||
| 605 | border: 1px solid; | ||
| 606 | } | ||
| 607 | |||
| 608 | |||
| 609 | div.navheader, div.heading{ | ||
| 610 | border-bottom: 1px solid; | ||
| 611 | } | ||
| 612 | |||
| 613 | |||
| 614 | div.navfooter, div.footing{ | ||
| 615 | border-top: 1px solid; | ||
| 616 | } | ||
| 617 | |||
| 618 | /********* / | ||
| 619 | / colors / | ||
| 620 | / *********/ | ||
| 621 | |||
| 622 | body { | ||
| 623 | color: #333; | ||
| 624 | background: white; | ||
| 625 | } | ||
| 626 | |||
| 627 | a { | ||
| 628 | background: transparent; | ||
| 629 | } | ||
| 630 | |||
| 631 | a:hover { | ||
| 632 | background-color: #dedede; | ||
| 633 | } | ||
| 634 | |||
| 635 | |||
| 636 | h1, | ||
| 637 | h2, | ||
| 638 | h3, | ||
| 639 | h4, | ||
| 640 | h5, | ||
| 641 | h6, | ||
| 642 | h7, | ||
| 643 | h8 { | ||
| 644 | background-color: transparent; | ||
| 645 | } | ||
| 646 | |||
| 647 | hr { | ||
| 648 | border-color: #aaa; | ||
| 649 | } | ||
| 650 | |||
| 651 | |||
| 652 | .tip, .warning, .caution, .note { | ||
| 653 | border-color: #fff; | ||
| 654 | } | ||
| 655 | |||
| 656 | |||
| 657 | .tip table th, | ||
| 658 | .warning table th, | ||
| 659 | .caution table th, | ||
| 660 | .note table th { | ||
| 661 | border-bottom-color: #fff; | ||
| 662 | } | ||
| 663 | |||
| 664 | |||
| 665 | .warning { | ||
| 666 | background-color: #f0f0f2; | ||
| 667 | } | ||
| 668 | |||
| 669 | .caution { | ||
| 670 | background-color: #f0f0f2; | ||
| 671 | } | ||
| 672 | |||
| 673 | .tip { | ||
| 674 | background-color: #f0f0f2; | ||
| 675 | } | ||
| 676 | |||
| 677 | .note { | ||
| 678 | background-color: #f0f0f2; | ||
| 679 | } | ||
| 680 | |||
| 681 | .glossary dl dt, | ||
| 682 | .variablelist dl dt, | ||
| 683 | .variablelist dl dt span.term { | ||
| 684 | color: #044; | ||
| 685 | } | ||
| 686 | |||
| 687 | div.figure, | ||
| 688 | div.table, | ||
| 689 | div.example, | ||
| 690 | div.informalfigure, | ||
| 691 | div.informaltable, | ||
| 692 | div.informalexample { | ||
| 693 | border-color: #aaa; | ||
| 694 | } | ||
| 695 | |||
| 696 | pre.programlisting { | ||
| 697 | color: black; | ||
| 698 | background-color: #fff; | ||
| 699 | border-color: #aaa; | ||
| 700 | border-width: 2px; | ||
| 701 | } | ||
| 702 | |||
| 703 | .guimenu, | ||
| 704 | .guilabel, | ||
| 705 | .guimenuitem { | ||
| 706 | background-color: #eee; | ||
| 707 | } | ||
| 708 | |||
| 709 | |||
| 710 | b.keycap, | ||
| 711 | .keycap { | ||
| 712 | background-color: #eee; | ||
| 713 | border-color: #999; | ||
| 714 | } | ||
| 715 | |||
| 716 | |||
| 717 | div.navheader { | ||
| 718 | border-color: black; | ||
| 719 | } | ||
| 720 | |||
| 721 | |||
| 722 | div.navfooter { | ||
| 723 | border-color: black; | ||
| 724 | } | ||
| 725 | |||
| 726 | |||
| 727 | /*********** / | ||
| 728 | / graphics / | ||
| 729 | / ***********/ | ||
| 730 | |||
| 731 | /* | ||
| 732 | body { | ||
| 733 | background-image: url("images/body_bg.jpg"); | ||
| 734 | background-attachment: fixed; | ||
| 735 | } | ||
| 736 | |||
| 737 | .navheader, | ||
| 738 | .note, | ||
| 739 | .tip { | ||
| 740 | background-image: url("images/note_bg.jpg"); | ||
| 741 | background-attachment: fixed; | ||
| 742 | } | ||
| 743 | |||
| 744 | .warning, | ||
| 745 | .caution { | ||
| 746 | background-image: url("images/warning_bg.jpg"); | ||
| 747 | background-attachment: fixed; | ||
| 748 | } | ||
| 749 | |||
| 750 | .figure, | ||
| 751 | .informalfigure, | ||
| 752 | .example, | ||
| 753 | .informalexample, | ||
| 754 | .table, | ||
| 755 | .informaltable { | ||
| 756 | background-image: url("images/figure_bg.jpg"); | ||
| 757 | background-attachment: fixed; | ||
| 758 | } | ||
| 759 | |||
| 760 | */ | ||
| 761 | h1, | ||
| 762 | h2, | ||
| 763 | h3, | ||
| 764 | h4, | ||
| 765 | h5, | ||
| 766 | h6, | ||
| 767 | h7{ | ||
| 768 | } | ||
| 769 | |||
| 770 | /* | ||
| 771 | Example of how to stick an image as part of the title. | ||
| 772 | |||
| 773 | div.article .titlepage .title | ||
| 774 | { | ||
| 775 | background-image: url("figures/white-on-black.png"); | ||
| 776 | background-position: center; | ||
| 777 | background-repeat: repeat-x; | ||
| 778 | } | ||
| 779 | */ | ||
| 780 | |||
| 781 | div.preface .titlepage .title, | ||
| 782 | div.colophon .title, | ||
| 783 | div.chapter .titlepage .title, | ||
| 784 | div.article .titlepage .title | ||
| 785 | { | ||
| 786 | } | ||
| 787 | |||
| 788 | div.section div.section .titlepage .title, | ||
| 789 | div.sect2 .titlepage .title { | ||
| 790 | background: none; | ||
| 791 | } | ||
| 792 | |||
| 793 | |||
| 794 | h1.title { | ||
| 795 | background-color: transparent; | ||
| 796 | background-image: url("figures/yocto-project-bw.png"); | ||
| 797 | background-repeat: no-repeat; | ||
| 798 | height: 256px; | ||
| 799 | text-indent: -9000px; | ||
| 800 | overflow:hidden; | ||
| 801 | } | ||
| 802 | |||
| 803 | h2.subtitle { | ||
| 804 | background-color: transparent; | ||
| 805 | text-indent: -9000px; | ||
| 806 | overflow:hidden; | ||
| 807 | width: 0px; | ||
| 808 | display: none; | ||
| 809 | } | ||
| 810 | |||
| 811 | /*************************************** / | ||
| 812 | / pippin.gimp.org specific alterations / | ||
| 813 | / ***************************************/ | ||
| 814 | |||
| 815 | /* | ||
| 816 | div.heading, div.navheader { | ||
| 817 | color: #777; | ||
| 818 | font-size: 80%; | ||
| 819 | padding: 0; | ||
| 820 | margin: 0; | ||
| 821 | text-align: left; | ||
| 822 | position: absolute; | ||
| 823 | top: 0px; | ||
| 824 | left: 0px; | ||
| 825 | width: 100%; | ||
| 826 | height: 50px; | ||
| 827 | background: url('/gfx/heading_bg.png') transparent; | ||
| 828 | background-repeat: repeat-x; | ||
| 829 | background-attachment: fixed; | ||
| 830 | border: none; | ||
| 831 | } | ||
| 832 | |||
| 833 | div.heading a { | ||
| 834 | color: #444; | ||
| 835 | } | ||
| 836 | |||
| 837 | div.footing, div.navfooter { | ||
| 838 | border: none; | ||
| 839 | color: #ddd; | ||
| 840 | font-size: 80%; | ||
| 841 | text-align:right; | ||
| 842 | |||
| 843 | width: 100%; | ||
| 844 | padding-top: 10px; | ||
| 845 | position: absolute; | ||
| 846 | bottom: 0px; | ||
| 847 | left: 0px; | ||
| 848 | |||
| 849 | background: url('/gfx/footing_bg.png') transparent; | ||
| 850 | } | ||
| 851 | */ | ||
| 852 | |||
| 853 | |||
| 854 | |||
| 855 | /****************** / | ||
| 856 | / nasty ie tweaks / | ||
| 857 | / ******************/ | ||
| 858 | |||
| 859 | /* | ||
| 860 | div.heading, div.navheader { | ||
| 861 | width:expression(document.body.clientWidth + "px"); | ||
| 862 | } | ||
| 863 | |||
| 864 | div.footing, div.navfooter { | ||
| 865 | width:expression(document.body.clientWidth + "px"); | ||
| 866 | margin-left:expression("-5em"); | ||
| 867 | } | ||
| 868 | body { | ||
| 869 | padding:expression("4em 5em 0em 5em"); | ||
| 870 | } | ||
| 871 | */ | ||
| 872 | |||
| 873 | /**************************************** / | ||
| 874 | / mozilla vendor specific css extensions / | ||
| 875 | / ****************************************/ | ||
| 876 | /* | ||
| 877 | div.navfooter, div.footing{ | ||
| 878 | -moz-opacity: 0.8em; | ||
| 879 | } | ||
| 880 | |||
| 881 | div.figure, | ||
| 882 | div.table, | ||
| 883 | div.informalfigure, | ||
| 884 | div.informaltable, | ||
| 885 | div.informalexample, | ||
| 886 | div.example, | ||
| 887 | .tip, | ||
| 888 | .warning, | ||
| 889 | .caution, | ||
| 890 | .note { | ||
| 891 | -moz-border-radius: 0.5em; | ||
| 892 | } | ||
| 893 | |||
| 894 | b.keycap, | ||
| 895 | .keycap { | ||
| 896 | -moz-border-radius: 0.3em; | ||
| 897 | } | ||
| 898 | */ | ||
| 899 | |||
| 900 | table tr td table tr td { | ||
| 901 | display: none; | ||
| 902 | } | ||
| 903 | |||
| 904 | |||
| 905 | hr { | ||
| 906 | display: none; | ||
| 907 | } | ||
| 908 | |||
| 909 | table { | ||
| 910 | border: 0em; | ||
| 911 | } | ||
| 912 | |||
| 913 | .photo { | ||
| 914 | float: right; | ||
| 915 | margin-left: 1.5em; | ||
| 916 | margin-bottom: 1.5em; | ||
| 917 | margin-top: 0em; | ||
| 918 | max-width: 17em; | ||
| 919 | border: 1px solid gray; | ||
| 920 | padding: 3px; | ||
| 921 | background: white; | ||
| 922 | } | ||
| 923 | .seperator { | ||
| 924 | padding-top: 2em; | ||
| 925 | clear: both; | ||
| 926 | } | ||
| 927 | |||
| 928 | #validators { | ||
| 929 | margin-top: 5em; | ||
| 930 | text-align: right; | ||
| 931 | color: #777; | ||
| 932 | } | ||
| 933 | @media print { | ||
| 934 | body { | ||
| 935 | font-size: 8pt; | ||
| 936 | } | ||
| 937 | .noprint { | ||
| 938 | display: none; | ||
| 939 | } | ||
| 940 | } | ||
| 941 | |||
| 942 | |||
| 943 | .tip, | ||
| 944 | .note { | ||
| 945 | background: #f0f0f2; | ||
| 946 | color: #333; | ||
| 947 | padding: 20px; | ||
| 948 | margin: 20px; | ||
| 949 | } | ||
| 950 | |||
| 951 | .tip h3, | ||
| 952 | .note h3 { | ||
| 953 | padding: 0em; | ||
| 954 | margin: 0em; | ||
| 955 | font-size: 2em; | ||
| 956 | font-weight: bold; | ||
| 957 | color: #333; | ||
| 958 | } | ||
| 959 | |||
| 960 | .tip a, | ||
| 961 | .note a { | ||
| 962 | color: #333; | ||
| 963 | text-decoration: underline; | ||
| 964 | } | ||
| 965 | |||
| 966 | .footnote { | ||
| 967 | font-size: small; | ||
| 968 | color: #333; | ||
| 969 | } | ||
| 970 | |||
| 971 | /* Changes the announcement text */ | ||
| 972 | .tip h3, | ||
| 973 | .warning h3, | ||
| 974 | .caution h3, | ||
| 975 | .note h3 { | ||
| 976 | font-size:large; | ||
| 977 | color: #00557D; | ||
| 978 | } | ||
| 979 | |||
