1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="chapter_getting_oe">
3 <title>Getting Started</title>
5 <section id="gettingoe_directory_setup">
6 <title>OpenEmbedded Directory Structure</title>
8 <para>Before you begin downloading OpenEmbedded, you need to setup your
9 working environment.</para>
11 <para>The first step is to decide where on your system you wish to
12 work. This document will use the <varname>$OEBASE</varname> variable to
13 denote the base directory of the OpenEmbedded environment. For
14 example, <varname>$OEBASE</varname> could
15 be <literal>/home/joe/work/oe</literal>.</para>
17 <para>The base directory of your OpenEmbedded environment
18 (<varname>$OEBASE</varname>) is the location where sources will be checked
19 out (or unpacked). You must choose a location with <emphasis>no symlinks
20 above it</emphasis>.</para>
22 <para>To create the directory structure:
25 $ mkdir -p $OEBASE/build/conf
28 The <literal>$OEBASE/build</literal> directory will contain your
29 local configurations and extensions to the OpenEmbedded system which allow
30 you to build your applications and images.
33 <para>The <varname>$OEBASE</varname> will also contain both bitbake/ and
34 openembedded/ directories. These will be discussed in
35 <xref linkend="gettingoe_getting_bitbake"/> and
36 <xref linkend="gettingoe_getting_oe"/>.
40 <section id="gettingoe_getting_bitbake">
41 <title>Getting <application>BitBake</application></title>
43 <para>Before using OE, you must first obtain the build tool it needs:
46 <para>It is recommended to run bitbake without installing it, as a sibling
47 directory of <literal>openembedded/</literal>
48 and <literal>build/</literal> directories. Indeed, as bitbake is written
49 in python it does not need compilation for being used. You'll just have to
50 set the PATH variable so that the BitBake tools are accessible (see
51 <xref linkend="gettingoe_configuring_oe"/>).</para>
53 <section><title>Getting <application>BitBake</application> Using Subversion</title>
54 <para>To checkout the latest version of the BitBake 1.8 branch, use the
58 $ <command>svn</command> co svn://svn.berlios.de/bitbake/branches/bitbake-1.8/ bitbake
62 <para><application>BitBake</application> is checked out now and
63 the <varname>$OEBASE</varname> directory will contain
64 a <literal>bitbake/</literal> subdirectory.</para>
66 <para>If you need to access a Subversion server through a proxy, see the
67 <ulink url="http://subversion.tigris.org/faq.html#proxy">SVN FAQ</ulink>
71 <section><title>Updating <application>BitBake</application></title>
72 <para>Bitbake is being revised fairly often. Periodically it's a good
73 idea to check the repository of bitbake stable branches to see if a
74 new stable branch is available or if the current branch has been
75 revised. Compare your existing bitbake directory with the latest
76 bitbake branch in the repository. Your existing bitbake branch and
77 its 'last changed revision' number can be found as follows:
79 <screen>$ cd $OEBASE/bitbake; svn info</screen>
81 If there is a new stable branch, you will want to move or delete
82 your existing bitbake directory and repeat the process listed above
83 under "To obtain bitbake". If there is no new branch, it is easy to
86 <screen>$ cd $OEBASE/bitbake; svn update</screen>
92 <section id="gettingoe_getting_oe">
93 <title>Getting OpenEmbedded</title>
95 <para><emphasis>Note:</emphasis> Once upon a time OpenEmbedded used
96 Monotone for version control. If you have an OE Monotone repository on
97 your computer, you should replace it with the Git repository.</para>
99 <para>The OpenEmbedded metadata has a high rate of development, so it's a
100 good idea to stay up to date. You'll need Git to get the metadata and
101 stay up to date. Git is available in most distributions and has binaries
102 at <ulink url="http://git-scm.com/">Git homepage</ulink>.</para>
104 <section><title>Checking Out OpenEmbedded With Git</title>
105 <para>Once you have installed Git, checkout the OpenEmbedded repository:
108 $ git clone git://git.openembedded.org/openembedded</screen>
109 The <literal>$OEBASE/openembedded/</literal> directory should now
113 <section><title>Updating OpenEmbedded</title>
114 <para>The <literal>org.openembedded.dev</literal> branch of OpenEmbedded
115 is updated very frequently (as much as several times an hour). The
116 distro branches are not updated as much but still fairly often. It
117 seems good practice to update your OpenEmbedded tree at least
118 daily. To do this, run:
124 <section><title>Changing Branches</title>
125 <para>Working with multiple branches is very easy to do with Git. The
126 OpenEmbedded repository holds many branches. To list all branches, use this command:
127 <screen>$ git branch -a</screen>
128 Branch names that begin with <literal>origin/</literal> denote
129 branches that exist on the remote server. The name with a * in front
130 of it is the branch currently checked out. If you want to work with a
131 remote branch, you must first create a local copy of it. The following
132 command will create a local copy of a remote branch:
133 <screen>$ git branch <local_name> <remote_name></screen>
134 To change branches, use this command:
135 <screen>$ git checkout <branch_name></screen>
136 There are more complicated branch operations that can be done with git,
137 but those are beyond the scope of this document.</para>
141 <section id="gettingoe_configuring_oe">
142 <title>Configuring OpenEmbedded</title>
144 <para>At this point, your <literal>$OEBASE/</literal> directory should
145 contain at least the following subdirectories:
147 <listitem><simpara><literal>build/</literal></simpara></listitem>
148 <listitem><simpara><literal>bitbake/</literal></simpara></listitem>
149 <listitem><simpara><literal>openembedded/</literal></simpara></listitem>
153 <section><title>Environment Setup</title>
154 <para>There are a few environment variables that you will need to set
155 before you can build software for OpenEmbedded using BitBake. You will
156 need to set these variables every time you open a terminal for
157 development. You can automate this in
158 <filename>~/.profile</filename>, <filename>/etc/profile</filename>, or
159 perhaps use a script to set the necessary variables for using BitBake.
162 <para>Since the path to your OpenEmbedded installation will be used in
163 many places, setting it in your environment will allow you to use
164 the <varname>$OEBASE</varname> variable in all pathes and make it
165 easier to change in the future should the need arise. To
166 set <varname>$OEBASE</varname> if you use a Bourne like shell
168 <para>If you use a CSH like shell (e.g. on a FreeBSD system), you
169 will set environment variables like this:
171 $ setenv VAR_NAME "VAR_VALUE"</screen>
173 </footnote>, do this:
176 $ export OEBASE=/path/to/your/oe/installation</screen>
180 <para>If you followed the recommendation to use BitBake from svn, you
181 will need to add the path to the BitBake executable to
182 your <varname>PATH</varname> environment variable like this:
185 $ export PATH=$OEBASE/bitbake/bin:$PATH</screen>
188 <para>In order for bitbake to find the configuration files for
189 OpenEmbedded, you will need to set the <varname>BBPATH</varname>
193 $ export BBPATH=$OEBASE/build:$OEBASE/openembedded</screen>
196 <para>Finally, if you wish to allow BitBake to inherit
197 the <varname>$OEBASE</varname> variable from the environment, you will
198 need to set the <varname>BB_ENV_EXTRAWHITE</varname> variable:
201 $ export BB_ENV_EXTRAWHITE="OEBASE"</screen>
203 Note the absence of the "$" character which implies that you are
204 setting <varname>BB_ENV_EXTRAWHITE</varname> to the variable name, not
209 <section><title>Local Configuration</title>
210 <para>It is now time to create your local configuration. While you could
211 copy the default <filename>local.conf.sample</filename> like this:
215 $ cp openembedded/conf/local.conf.sample build/conf/local.conf
216 $ vi build/conf/local.conf</screen>
218 It is actually recommended to start smaller and
219 keep <filename>local.conf.sample</filename> in the background. Add
220 entries from there step-by-step as you understand and need
221 them. Please, do not just edit
222 <filename>build/conf/local.conf.sample</filename> but
223 actually <emphasis>READ</emphasis> it (read it and then edit it).
226 <para>For building an <literal>org.openembedded.dev</literal> branch, in
227 your <filename>local.conf</filename> file, you should have at least
229 entries: <varname>BBFILES</varname>, <varname>DISTRO</varname>
230 and <varname>MACHINE</varname>. For example, consider the following
231 mininal <literal>local.conf</literal> file for the Ångström
232 distribution and the Openmoko gta01 machine:
235 BBFILES = "${OEBASE}/openembedded/recipes/*/*.bb"
236 DISTRO = "angstrom-2008.1"
237 MACHINE = "om-gta01"</screen>
242 <section id="gettingoe_building_software">
243 <title>Building Software</title>
245 <para>The primary interface to the build system is
246 the <command>bitbake</command> command (see
247 the <ulink url="http://bitbake.berlios.de/manual/">BitBake
248 users manual</ulink>). BitBake will download and patch files from the
249 internet, so it helps if you are on a well connected machine.
252 <para>Note that you should issue all BitBake commands from inside of the
253 <filename>build/</filename> directory, or you should
254 override <varname>TMPDIR</varname> in
255 your <filename>$OEBASE/build/conf/local.conf</filename> to point
256 elsewhere (by default it goes to <filename>tmp/</filename> relative to
257 the directory you run <command>bitbake</command> commands in).
261 <para>BitBake might complain that there is a problem with the setting in
262 <filename>/proc/sys/vm/mmap_min_addr</filename>, which needs to be set
263 to zero. You can set it by doing the following as root:
265 <screen># echo 0 > /proc/sys/vm/mmap_min_addr</screen>
267 Note that you can not use a text editor to do this since files
268 in <filename>/proc</filename> are not real files. Also note that this
269 above change will be lost when you reboot your system. To have the
270 change made automatically when the system boots, some systems provide
271 a <filename>/etc/sysctl.conf</filename> file. Add the following line
274 <screen>vm.mmap_min_addr=0</screen>
276 If your system does not provide
277 the <filename>/etc/sysctl.conf</filename> mechanism, you can try adding
278 the above <command>echo</command> command line to
279 your <filename>/etc/rc.local</filename>.
283 <para>Once BitBake and OpenEmbedded are set up and configured, you can build
284 software and images like this:
286 <screen>$ bitbake <recipe_name></screen>
288 A recipe name corresponds to a BitBake <filename>.bb</filename> file. A
289 BitBake file is a logical unit of tasks to be executed. Normally this is
290 a package to be built. Inter-recipe dependencies are obeyed. The recipes
291 are located by BitBake via the <varname>BBFILES</varname> variable (set
292 in your <filename>$OEBASE/build/conf/local/conf</filename>), which is a
293 space separated list of <filename>.bb</filename> files, and does handle
297 <para>To build a single package, bypassing the long parse step (and
298 therefore its dependencies -- use with care):
300 <screen>$ bitbake -b $OEBASE/openembedded/recipes/blah/blah.bb</screen>
303 <para>There are a few groups of special recipes located in subdirectories
304 of the <filename>$OEBASE/openembedded/recipes/</filename>
305 directory. These groups are:
309 <term><filename>tasks/</filename></term>
310 <listitem><para>A collection of meta-packages that depend on real
311 packages to make managing package sets easier.</para></listitem>
315 <term><filename>meta/</filename></term>
316 <listitem><para>A collection of usefull meta tasks and recipes that
317 don't fit in a general category.</para></listitem>
321 <term><filename>images/</filename></term>
322 <listitem><para>A collection of image targets that depend on
323 packages that will be installed into an image which can be put
324 on the target system.</para></listitem>
329 <section><title>Useful Target Recipes</title>
330 <para>Although BitBake can build individual packages, it is often more
331 useful to build a set of packages and combine them into an image. The
332 following recipe names are commonly used to that effect.
335 <section><title>Images</title>
339 <term><literal>helloworld-image</literal></term>
341 <para>Builds an image, that if used as a root filesystem, will
342 start a static executable that prints hello world then
343 loops infinitely. Can be used to test the Linux boot
344 procedure into user space (init).
350 <term><literal>bootstrap-image</literal></term>
352 <para>Build image contains task-base packages.
358 <term><literal>console-image</literal></term>
360 <para>Build an image without the X11, gtk+, or qt windowing
367 <term><literal>x11-image</literal></term>
369 <para>Builds an image with X11.
375 <term><literal>beagleboard-demo-image</literal></term>
377 <para>Builds the Ångström distribution like Koen
384 <term><literal>opie-image</literal></term>
386 <para>Build image based on the
387 <ulink url="http://opie.handhelds.org/">Open Palmtop
388 Integrated Environment</ulink> (OPIE). OPIE is a completely
389 Open Source based graphical user environment and suite of
390 applications for small form-factor devices, such as PDAs,
397 <term><literal>opie-kdepim-image</literal></term>
399 <para>Build image based on the OPIE and full featured
400 KDE-based PIM (pi-sync, ko/pi, ka/pi, etc).
406 <term><literal>pivotboot-image</literal></term>
408 <para>Build image that is necessary to flash a Sharp SL C3000,
409 Zaurus. It pivots after booting from the NAND and finalizes
410 the install to the HD during the first boot.
416 <term><literal>twin-image</literal></term>
418 <para>A image with task-base plus a couple of editors, nano and
419 vim (why two?), and a mail reader, mutt.
425 <term><literal>uml-image</literal></term>
427 <para>A root image for user-mode-linux. Includes task-base,
434 <term><literal>gpe-image</literal></term>
436 <para>Build a <ulink url="http://opie.handhelds.org/">GPE
437 Palmtop Environment</ulink> based kernel and rootfs. The GPE
438 provides a user interface environment for palmtop/handheld
439 computers running the GNU/Linux or any other UNIX-like
448 <section><title>Tasks</title>
452 <term><literal>task-base</literal></term>
454 <para>Build a kernel and core packages for a basic
455 installation. You won't be able to do much more than ssh to
456 the machine if this is all that is installed.
462 <term><literal>task-dvb</literal></term>
464 <para>Meta-package for DVB application (DVB = Digital Video
471 <term><literal>task-python-everything</literal></term>
479 <term><literal>task-native-sdk</literal></term>
481 <para>Mata-package for native (on-device) SDK.
489 <section><title>Meta</title>
493 <term><literal>meta-opie</literal></term>
495 <para>Build all OPIE related packages and some more for OPIE
502 <term><literal>meta-gpe</literal></term>
504 <para>Basic packages to go with gpe-image.
512 <section><title>Other</title>
516 <term><literal>helloworld</literal></term>
518 <para>Builds a static executable that prints hello
519 world then loops infinitely.
525 <term><literal>world</literal></term>
527 <para>Build everything. This takes a long time, a lot
528 of network bandwidth, and a lot of disc space. Can also
529 break your toolchain.
535 <term><literal>package-index</literal></term>
537 <para>Target to update the "feed" files to reflect the current
538 set of .ipk's that exist in the deploy directory. Commonly
539 used after building some packages individually to update the
540 feed and allow them to be installed via a package manager or
541 the ipkg command line tools.
547 <term><literal>virtual/kernel</literal></term>
549 <para>Builds the appropriate kernel for your device.</para>