getting_oe.xml: Update "Building Software" section.
[openembedded.git] / docs / usermanual / chapters / getting_oe.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="chapter_getting_oe">
3   <title>Getting Started</title>
4
5   <section id="gettingoe_directory_setup">
6     <title>OpenEmbedded Directory Structure</title>
7
8     <para>Before you begin downloading OpenEmbedded, you need to setup your
9     working environment.</para>
10
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>
16
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>
21
22         <para>To create the directory structure:
23
24     <screen>
25 $ mkdir -p $OEBASE/build/conf
26 $ cd $OEBASE</screen>
27
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.
31     </para>
32
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"/>.
37         </para>
38   </section>
39
40   <section id="gettingoe_getting_bitbake">
41     <title>Getting <application>BitBake</application></title>
42
43     <para>Before using OE, you must first obtain the build tool it needs:
44     bitbake.</para>
45
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>
52
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
55                 following command:
56                 <screen>
57 $ cd $OEBASE
58 $ <command>svn</command> co svn://svn.berlios.de/bitbake/branches/bitbake-1.8/ bitbake
59 </screen>
60           </para>
61
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>
65
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>
68           </para>
69         </section>
70
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:
78
79                 <screen>$ cd $OEBASE/bitbake; svn info</screen>
80
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
84                 update bitbake:
85
86                 <screen>$ cd $OEBASE/bitbake; svn update</screen>
87           </para>
88         </section>
89   </section>
90
91
92   <section id="gettingoe_getting_oe">
93     <title>Getting OpenEmbedded</title>
94
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>
98
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>
103
104     <section><title>Checking Out OpenEmbedded With Git</title>
105       <para>Once you have installed Git, checkout the OpenEmbedded repository:
106         <screen>
107 $ cd $OEBASE
108 $ git clone git://git.openembedded.net/openembedded</screen>
109         The <literal>$OEBASE/openembedded/</literal> directory should now
110         exist.</para>
111     </section>
112
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:
119         <screen>
120 $ cd $OEBASE
121 $ git pull</screen>
122       </para>
123     </section>
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 &lt;local_name&gt; &lt;remote_name&gt;</screen>
134         To change branches, use this command:
135         <screen>$ git checkout &lt;branch_name&gt;</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>
138     </section>
139   </section>
140
141   <section id="gettingoe_configuring_oe">
142     <title>Configuring OpenEmbedded</title>
143
144     <para>At this point, your <literal>$OEBASE/</literal> directory should
145       contain at least the following subdirectories:
146       <itemizedlist>
147         <listitem><simpara><literal>build/</literal></simpara></listitem>
148         <listitem><simpara><literal>bitbake/</literal></simpara></listitem>
149         <listitem><simpara><literal>openembedded/</literal></simpara></listitem>
150       </itemizedlist>
151     </para>
152
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.
160       </para>
161
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
167         <footnote>
168           <para>If you use a CSH like shell (e.g. on a FreeBSD system), you
169             will set environment variables like this:
170             <screen>
171 $ setenv VAR_NAME "VAR_VALUE"</screen>
172           </para>
173         </footnote>, do this:
174
175         <screen>
176 $ export OEBASE=/path/to/your/oe/installation</screen>
177
178       </para>
179
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:
183
184         <screen>
185 $ export PATH=$OEBASE/bitbake/bin:$PATH</screen>
186       </para>
187
188       <para>In order for bitbake to find the configuration files for
189         OpenEmbedded, you will need to set the <varname>BBPATH</varname>
190         variable.
191
192         <screen>
193 $ export BBPATH=$OEBASE/build:$OEBASE/openembedded</screen>
194       </para>
195
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:
199
200         <screen>
201 $ export BB_ENV_EXTRAWHITE="OEBASE"</screen>
202
203         Note the absence of the "$" character which implies that you are
204         setting <varname>BB_ENV_EXTRAWHITE</varname> to the variable name, not
205         the variable value.
206       </para>
207     </section>
208
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:
212
213         <screen>
214 $ cd $OEBASE
215 $ cp openembedded/conf/local.conf.sample build/conf/local.conf
216 $ vi build/conf/local.conf</screen>
217
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).
224       </para>
225
226       <para>For building an <literal>org.openembedded.dev</literal> branch, in
227         your <filename>local.conf</filename> file, you should have at least
228         the following three
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 &Aring;ngstr&ouml;m
232         distribution and the Openmoko gta01 machine:
233
234         <screen>
235 BBFILES = "${OEBASE}/openembedded/packages/*/*.bb"
236 DISTRO = "angstrom-2008.1"
237 MACHINE = "om-gta01"</screen>
238       </para>
239     </section>
240   </section>
241
242   <section id="gettingoe_building_software">
243     <title>Building Software</title>
244
245     <para>The primary interface to the build system is
246       the <command>bitbake</command> command (see
247       the <ulink url="http://subversion.tigris.org/faq.html#proxy">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.
250     </para>
251
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).
258     </para>
259
260     <note>
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:
264
265         <screen># echo 0 > /proc/sys/vm/mmap_min_addr</screen>
266
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
272         to that file:
273
274         <screen>vm.mmap_min_addr=0</screen>
275
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>.
280       </para>
281     </note>
282
283     <para>Once BitBake and OpenEmbedded are set up and configured, you can build
284       software and images like this:
285
286       <screen>$ bitbake &lt;recipe_name&gt;</screen>
287
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
294       wildcards.
295     </para>
296
297     <para>To build a single package, bypassing the long parse step (and
298       therefore its dependencies -- use with care):
299
300       <screen>$ bitbake -b $OEBASE/openembedded/packages/blah/blah.bb</screen>
301     </para>
302
303     <para>There are a few groups of special recipes located in subdirectories
304       of the <filename>$OEBASE/openembedded/packages/</filename>
305       directory. These groups are:
306
307       <variablelist>
308         <varlistentry>
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>
312         </varlistentry>
313
314         <varlistentry>
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>
318         </varlistentry>
319
320         <varlistentry>
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>
325         </varlistentry>
326       </variablelist>
327     </para>
328
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.
333       </para>
334
335       <section><title>Images</title>
336         <para>
337           <variablelist>
338             <varlistentry>
339               <term><literal>helloworld-image</literal></term>
340               <listitem>
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).
345                 </para>
346               </listitem>
347             </varlistentry>
348
349             <varlistentry>
350               <term><literal>bootstrap-image</literal></term>
351               <listitem>
352                 <para>Build image contains task-base packages.
353                 </para>
354               </listitem>
355             </varlistentry>
356
357             <varlistentry>
358               <term><literal>console-image</literal></term>
359               <listitem>
360                 <para>Build an image without the X11, gtk+, or qt windowing
361                   libraries.
362                 </para>
363               </listitem>
364             </varlistentry>
365
366             <varlistentry>
367               <term><literal>x11-image</literal></term>
368               <listitem>
369                 <para>Builds an image with X11.
370                 </para>
371               </listitem>
372             </varlistentry>
373
374             <varlistentry>
375               <term><literal>beagleboard-demo-image</literal></term>
376               <listitem>
377                 <para>Builds the &Aring;ngstr&ouml;m distribution like Koen
378                 proposed.
379                 </para>
380               </listitem>
381             </varlistentry>
382
383             <varlistentry>
384               <term><literal>opie-image</literal></term>
385               <listitem>
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,
391                   running Linux.
392                 </para>
393               </listitem>
394             </varlistentry>
395
396             <varlistentry>
397               <term><literal>opie-kdepim-image</literal></term>
398               <listitem>
399                 <para>Build image based on the OPIE and full featured
400                   KDE-based PIM (pi-sync, ko/pi, ka/pi, etc).
401                 </para>
402               </listitem>
403             </varlistentry>
404
405             <varlistentry>
406               <term><literal>pivotboot-image</literal></term>
407               <listitem>
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.
411                 </para>
412               </listitem>
413             </varlistentry>
414
415             <varlistentry>
416               <term><literal>twin-image</literal></term>
417               <listitem>
418                 <para>A image with task-base plus a couple of editors, nano and
419                   vim (why two?), and a mail reader, mutt.
420                 </para>
421               </listitem>
422             </varlistentry>
423
424             <varlistentry>
425               <term><literal>uml-image</literal></term>
426               <listitem>
427                 <para>A root image for user-mode-linux. Includes task-base,
428                   and parts of opie.
429                 </para>
430               </listitem>
431             </varlistentry>
432
433             <varlistentry>
434               <term><literal>gpe-image</literal></term>
435               <listitem>
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
440                   operating system.
441                 </para>
442               </listitem>
443             </varlistentry>
444           </variablelist>
445         </para>
446       </section>
447
448       <section><title>Tasks</title>
449         <para>
450           <variablelist>
451             <varlistentry>
452               <term><literal>task-base</literal></term>
453               <listitem>
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.
457                 </para>
458               </listitem>
459             </varlistentry>
460
461             <varlistentry>
462               <term><literal>task-dvb</literal></term>
463               <listitem>
464                 <para>Meta-package for DVB application (DVB = Digital Video
465                 Broadcasting).
466                 </para>
467               </listitem>
468             </varlistentry>
469
470             <varlistentry>
471               <term><literal>task-python-everything</literal></term>
472               <listitem>
473                 <para>All of python.
474                 </para>
475               </listitem>
476             </varlistentry>
477
478             <varlistentry>
479               <term><literal>task-native-sdk</literal></term>
480               <listitem>
481                 <para>Mata-package for native (on-device) SDK.
482                 </para>
483               </listitem>
484             </varlistentry>
485           </variablelist>
486         </para>
487       </section>
488
489       <section><title>Meta</title>
490         <para>
491           <variablelist>
492             <varlistentry>
493               <term><literal>meta-opie</literal></term>
494               <listitem>
495                 <para>Build all OPIE related packages and some more for OPIE
496                   based usage.
497                 </para>
498               </listitem>
499             </varlistentry>
500
501             <varlistentry>
502               <term><literal>meta-gpe</literal></term>
503               <listitem>
504                 <para>Basic packages to go with gpe-image.
505                 </para>
506               </listitem>
507             </varlistentry>
508           </variablelist>
509         </para>
510       </section>
511
512       <section><title>Other</title>
513         <para>
514           <variablelist>
515             <varlistentry>
516               <term><literal>helloworld</literal></term>
517               <listitem>
518                 <para>Builds a static executable that prints hello
519                   world then loops infinitely.
520                 </para>
521               </listitem>
522             </varlistentry>
523
524             <varlistentry>
525               <term><literal>world</literal></term>
526               <listitem>
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.
530                 </para>
531               </listitem>
532             </varlistentry>
533
534             <varlistentry>
535               <term><literal>package-index</literal></term>
536               <listitem>
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.
542                 </para>
543               </listitem>
544             </varlistentry>
545
546             <varlistentry>
547               <term><literal>virtual/kernel</literal></term>
548               <listitem>
549                 <para>Builds the appropriate kernel for your device.</para>
550               </listitem>
551             </varlistentry>
552           </variablelist>
553         </para>
554       </section>
555     </section>
556   </section>
557 </chapter>