python 2.6.7: added missing dependency for bzip2 (without this python-compression...
[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 $ <command>mkdir</command> -p $OEBASE/build/conf
26 $ <command>cd</command> $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 of the
34         <literal>bitbake/</literal> and <literal>openembedded/</literal> directories.
35         These will be discussed in <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 <varname>PATH</varname> variable so that the BitBake tools are
51     accessible (see <xref linkend="gettingoe_configuring_oe"/>).</para>
52
53         <section><title>Downloading a <application>BitBake</application> release</title>
54           <para>Releases are available from the berlios project website. The current
55           release series is <application>BitBake</application> <emphasis>1.8</emphasis>
56           and the current release is <emphasis>1.8.18</emphasis>. To download execute
57           the following commands:
58                 <screen>
59 $ <command>cd</command> $OEBASE
60 $ <command>wget</command> http://download.berlios.de/bitbake/bitbake-1.8.18.tar.gz
61 $ <command>tar</command> -xvzf bitbake-1.8.18.tar.gz
62 $ <command>mv</command> bitbake-1.8.18 bitbake
63 </screen>
64           </para>
65
66           <para><application>BitBake</application> is now downloaded and
67                 the <varname>$OEBASE</varname> directory will contain
68                 a <literal>bitbake/</literal> subdirectory.</para>
69         </section>
70   </section>
71
72
73   <section id="gettingoe_getting_oe">
74     <title>Getting OpenEmbedded</title>
75
76     <para><emphasis>Note:</emphasis> Once upon a time OpenEmbedded used
77       Monotone for version control. If you have an OE Monotone repository on
78       your computer, you should replace it with the Git repository.</para>
79
80     <para>The OpenEmbedded metadata has a high rate of development, so it's a
81       good idea to stay up to date. You'll need Git to get the metadata and
82       stay up to date. Git is available in most distributions and has binaries
83       at <ulink url="http://git-scm.com/">Git homepage</ulink>.</para>
84
85     <section><title>Checking Out OpenEmbedded With Git</title>
86       <para>Once you have installed Git, checkout the OpenEmbedded repository:
87         <screen>
88 $ <command>cd</command> $OEBASE
89 $ <command>git</command> clone git://git.openembedded.org/openembedded</screen>
90         The <literal>$OEBASE/openembedded/</literal> directory should now
91         exist.</para>
92     </section>
93
94     <section><title>Updating OpenEmbedded</title>
95       <para>The <literal>org.openembedded.dev</literal> branch of OpenEmbedded
96         is updated very frequently (as much as several times an hour). The
97         distro branches are not updated as much but still fairly often. It
98         seems good practice to update your OpenEmbedded tree at least
99         daily. To do this, run:
100         <screen>
101 $ <command>cd</command> $OEBASE
102 $ <command>git</command> pull</screen>
103       </para>
104     </section>
105     <section><title>Changing Branches</title>
106       <para>Working with multiple branches is very easy to do with Git. The
107         OpenEmbedded repository holds many branches. To list all branches, use this command:
108         <screen>$ <command>git</command> branch -a</screen>
109         Branch names that begin with <literal>origin/</literal> denote
110         branches that exist on the remote server. The name with a * in front
111         of it is the branch currently checked out. If you want to work with a
112         remote branch, you must first create a local copy of it. The following
113         command will create a local copy of a remote branch:
114         <screen>$ <command>git</command> branch &lt;local_name&gt; &lt;remote_name&gt;</screen>
115         To change branches, use this command:
116         <screen>$ <command>git</command> checkout &lt;branch_name&gt;</screen>
117         There are more complicated branch operations that can be done with git,
118         but those are beyond the scope of this document.</para>
119     </section>
120   </section>
121
122   <section id="gettingoe_configuring_oe">
123     <title>Configuring OpenEmbedded</title>
124
125     <para>At this point, your <literal>$OEBASE/</literal> directory should
126       contain at least the following subdirectories:
127       <itemizedlist>
128         <listitem><simpara><literal>build/</literal></simpara></listitem>
129         <listitem><simpara><literal>bitbake/</literal></simpara></listitem>
130         <listitem><simpara><literal>openembedded/</literal></simpara></listitem>
131       </itemizedlist>
132     </para>
133
134     <section><title>Environment Setup</title>
135       <para>There are a few environment variables that you will need to set
136         before you can build software for OpenEmbedded using BitBake. You will
137         need to set these variables every time you open a terminal for
138         development. You can automate this in
139         <filename>~/.profile</filename>, <filename>/etc/profile</filename>, or
140         perhaps use a script to set the necessary variables for using BitBake.
141       </para>
142
143       <para>Since the path to your OpenEmbedded installation will be used in
144         many places, setting it in your environment will allow you to use
145         the <varname>$OEBASE</varname> variable in all pathes and make it
146         easier to change in the future should the need arise. To
147         set <varname>$OEBASE</varname> if you use a Bourne like shell
148         <footnote>
149           <para>If you use a CSH like shell (e.g. on a FreeBSD system), you
150             will set environment variables like this:
151             <screen>
152 $ <command>setenv</command> VAR_NAME "VAR_VALUE"</screen>
153           </para>
154         </footnote>, do this:
155
156         <screen>
157 $ <command>export</command> OEBASE=/path/to/your/oe/installation</screen>
158
159       </para>
160
161       <para>If you followed the recommendation to use BitBake from svn, you
162         will need to add the path to the BitBake executable to
163         your <varname>PATH</varname> environment variable like this:
164
165         <screen>
166 $ <command>export</command> PATH=$OEBASE/bitbake/bin:$PATH</screen>
167       </para>
168
169       <para>In order for bitbake to find the configuration files for
170         OpenEmbedded, you will need to set the <varname>BBPATH</varname>
171         variable.
172
173         <screen>
174 $ <command>export</command> BBPATH=$OEBASE/build:$OEBASE/openembedded</screen>
175       </para>
176
177       <para>Finally, if you wish to allow BitBake to inherit
178         the <varname>$OEBASE</varname> variable from the environment, you will
179         need to set the <varname>BB_ENV_EXTRAWHITE</varname> variable:
180
181         <screen>
182 $ <command>export</command> BB_ENV_EXTRAWHITE="OEBASE"</screen>
183
184         Note the absence of the "$" character which implies that you are
185         setting <varname>BB_ENV_EXTRAWHITE</varname> to the variable name, not
186         the variable value.
187       </para>
188     </section>
189
190     <section><title>Local Configuration</title>
191       <para>It is now time to create your local configuration. While you could
192         copy the default <filename>local.conf.sample</filename> like this:
193
194         <screen>
195 $ <command>cd</command> $OEBASE
196 $ <command>cp</command> openembedded/conf/local.conf.sample build/conf/local.conf
197 $ <command>vi</command> build/conf/local.conf</screen>
198
199         It is actually recommended to start smaller and
200         keep <filename>local.conf.sample</filename> in the background. Add
201         entries from there step-by-step as you understand and need
202         them. Please, do not just edit
203         <filename>build/conf/local.conf.sample</filename> but
204         actually <emphasis>READ</emphasis> it (read it and then edit it).
205       </para>
206
207       <para>For building an <literal>org.openembedded.dev</literal> branch, in
208         your <filename>local.conf</filename> file, you should have at least
209         the following three
210         entries: <varname>BBFILES</varname>, <varname>DISTRO</varname>
211         and <varname>MACHINE</varname>. For example, consider the following
212         minimal <literal>local.conf</literal> file for the &Aring;ngstr&ouml;m
213         distribution and the Openmoko gta01 machine:
214
215         <screen>
216 BBFILES = "${OEBASE}/openembedded/recipes/*/*.bb"
217 DISTRO = "angstrom-2008.1"
218 MACHINE = "om-gta01"</screen>
219       </para>
220     </section>
221   </section>
222
223   <section id="gettingoe_building_software">
224     <title>Building Software</title>
225
226     <para>The primary interface to the build system is
227       the <command>bitbake</command> command (see
228       the <ulink url="http://bitbake.berlios.de/manual/">BitBake
229       users manual</ulink>). BitBake will download and patch files from the
230       internet, so it helps if you are on a well connected machine.
231     </para>
232
233     <para>Note that you should issue all BitBake commands from inside of the
234       <filename>build/</filename> directory, or you should
235       override <varname>TMPDIR</varname> in
236       your <filename>$OEBASE/build/conf/local.conf</filename> to point
237       elsewhere (by default it goes to <filename>tmp/</filename> relative to
238       the directory you run <command>bitbake</command> commands in).
239     </para>
240
241     <note>
242       <para>BitBake might complain that there is a problem with the setting in
243         <filename>/proc/sys/vm/mmap_min_addr</filename>, which needs to be set
244         to zero. You can set it by doing the following as root:
245
246         <screen># echo 0 > /proc/sys/vm/mmap_min_addr</screen>
247
248         Note that you can not use a text editor to do this since files
249         in <filename>/proc</filename> are not real files. Also note that this
250         above change will be lost when you reboot your system. To have the
251         change made automatically when the system boots, some systems provide
252         a <filename>/etc/sysctl.conf</filename> file. Add the following line
253         to that file:
254
255         <screen>vm.mmap_min_addr=0</screen>
256
257         If your system does not provide
258         the <filename>/etc/sysctl.conf</filename> mechanism, you can try adding
259         the above <command>echo</command> command line to
260         your <filename>/etc/rc.local</filename>.  But that's not all.
261
262         On some systems (such as Fedora 11), changing that kernel setting
263         will cause an SELinux violation if you're running SELinux in enforcing
264         mode. If that's the case, you can either disable SELinux or run:
265
266         <screen>$ setsebool -P allow_unconfirmed_mmap_low 1</screen>
267       </para>
268     </note>
269
270     <para>Once BitBake and OpenEmbedded are set up and configured, you can build
271       software and images like this:
272
273       <screen>$ bitbake &lt;recipe_name&gt;</screen>
274
275       A recipe name corresponds to a BitBake <filename>.bb</filename> file.  A
276       BitBake file is a logical unit of tasks to be executed. Normally this is
277       a package to be built. Inter-recipe dependencies are obeyed. The recipes
278       are located by BitBake via the <varname>BBFILES</varname> variable (set
279       in your <filename>$OEBASE/build/conf/local.conf</filename>), which is a
280       space separated list of <filename>.bb</filename> files, and does handle
281       wildcards.
282     </para>
283
284     <para>To build a single package, bypassing the long parse step (and
285       therefore its dependencies -- use with care):
286
287       <screen>$ bitbake -b $OEBASE/openembedded/recipes/blah/blah.bb</screen>
288     </para>
289
290     <para>There are a few groups of special recipes located in subdirectories
291       of the <filename>$OEBASE/openembedded/recipes/</filename>
292       directory. These groups are:
293
294       <variablelist>
295         <varlistentry>
296           <term><filename>tasks/</filename></term>
297           <listitem><para>A collection of meta-packages that depend on real
298               packages to make managing package sets easier.</para></listitem>
299         </varlistentry>
300
301         <varlistentry>
302           <term><filename>meta/</filename></term>
303           <listitem><para>A collection of useful meta tasks and recipes that
304               don't fit in a general category.</para></listitem>
305         </varlistentry>
306
307         <varlistentry>
308           <term><filename>images/</filename></term>
309           <listitem><para>A collection of image targets that depend on
310               packages that will be installed into an image which can be put
311               on the target system.</para></listitem>
312         </varlistentry>
313       </variablelist>
314     </para>
315
316     <section><title>Useful Target Recipes</title>
317       <para>Although BitBake can build individual packages, it is often more
318         useful to build a set of packages and combine them into an image. The
319         following recipe names are commonly used to that effect.
320       </para>
321
322       <section><title>Images</title>
323         <para>
324           <variablelist>
325             <varlistentry>
326               <term><literal>helloworld-image</literal></term>
327               <listitem>
328                 <para>Builds an image, that if used as a root filesystem, will
329                   start a static executable that prints hello world then
330                   loops infinitely. Can be used to test the Linux boot
331                   procedure into user space (init).
332                 </para>
333               </listitem>
334             </varlistentry>
335
336             <varlistentry>
337               <term><literal>bootstrap-image</literal></term>
338               <listitem>
339                 <para>Build image contains task-base packages.
340                 </para>
341               </listitem>
342             </varlistentry>
343
344             <varlistentry>
345               <term><literal>console-image</literal></term>
346               <listitem>
347                 <para>Build an image without the X11, gtk+, or qt windowing
348                   libraries.
349                 </para>
350               </listitem>
351             </varlistentry>
352
353             <varlistentry>
354               <term><literal>x11-image</literal></term>
355               <listitem>
356                 <para>Builds an image with X11.
357                 </para>
358               </listitem>
359             </varlistentry>
360
361             <varlistentry>
362               <term><literal>beagleboard-demo-image</literal></term>
363               <listitem>
364                 <para>Builds the &Aring;ngstr&ouml;m distribution like Koen
365                 proposed.
366                 </para>
367               </listitem>
368             </varlistentry>
369
370             <varlistentry>
371               <term><literal>opie-image</literal></term>
372               <listitem>
373                 <para>Build image based on the
374                   <ulink url="http://opie.handhelds.org/">Open Palmtop
375                   Integrated Environment</ulink> (OPIE). OPIE is a completely
376                   Open Source based graphical user environment and suite of
377                   applications for small form-factor devices, such as PDAs,
378                   running Linux.
379                 </para>
380               </listitem>
381             </varlistentry>
382
383             <varlistentry>
384               <term><literal>opie-kdepim-image</literal></term>
385               <listitem>
386                 <para>Build image based on the OPIE and full featured
387                   KDE-based PIM (pi-sync, ko/pi, ka/pi, etc).
388                 </para>
389               </listitem>
390             </varlistentry>
391
392             <varlistentry>
393               <term><literal>pivotboot-image</literal></term>
394               <listitem>
395                 <para>Build image that is necessary to flash a Sharp SL C3000,
396                   Zaurus. It pivots after booting from the NAND and finalizes
397                   the install to the HD during the first boot.
398                 </para>
399               </listitem>
400             </varlistentry>
401
402             <varlistentry>
403               <term><literal>twin-image</literal></term>
404               <listitem>
405                 <para>A image with task-base plus a couple of editors, nano and
406                   vim (why two?), and a mail reader, mutt.
407                 </para>
408               </listitem>
409             </varlistentry>
410
411             <varlistentry>
412               <term><literal>uml-image</literal></term>
413               <listitem>
414                 <para>A root image for user-mode-linux. Includes task-base,
415                   and parts of opie.
416                 </para>
417               </listitem>
418             </varlistentry>
419
420             <varlistentry>
421               <term><literal>gpe-image</literal></term>
422               <listitem>
423                 <para>Build a <ulink url="http://opie.handhelds.org/">GPE
424                   Palmtop Environment</ulink> based kernel and rootfs. The GPE
425                   provides a user interface environment for palmtop/handheld
426                   computers running the GNU/Linux or any other UNIX-like
427                   operating system.
428                 </para>
429               </listitem>
430             </varlistentry>
431           </variablelist>
432         </para>
433       </section>
434
435       <section><title>Tasks</title>
436         <para>
437           <variablelist>
438             <varlistentry>
439               <term><literal>task-base</literal></term>
440               <listitem>
441                 <para>Build a kernel and core packages for a basic
442                   installation. You won't be able to do much more than ssh to
443                   the machine if this is all that is installed.
444                 </para>
445               </listitem>
446             </varlistentry>
447
448             <varlistentry>
449               <term><literal>task-dvb</literal></term>
450               <listitem>
451                 <para>Meta-package for DVB application (DVB = Digital Video
452                 Broadcasting).
453                 </para>
454               </listitem>
455             </varlistentry>
456
457             <varlistentry>
458               <term><literal>task-python-everything</literal></term>
459               <listitem>
460                 <para>All of python.
461                 </para>
462               </listitem>
463             </varlistentry>
464
465             <varlistentry>
466               <term><literal>task-native-sdk</literal></term>
467               <listitem>
468                 <para>Mata-package for native (on-device) SDK.
469                 </para>
470               </listitem>
471             </varlistentry>
472           </variablelist>
473         </para>
474       </section>
475
476       <section><title>Meta</title>
477         <para>
478           <variablelist>
479             <varlistentry>
480               <term><literal>meta-opie</literal></term>
481               <listitem>
482                 <para>Build all OPIE related packages and some more for OPIE
483                   based usage.
484                 </para>
485               </listitem>
486             </varlistentry>
487
488             <varlistentry>
489               <term><literal>meta-gpe</literal></term>
490               <listitem>
491                 <para>Basic packages to go with gpe-image.
492                 </para>
493               </listitem>
494             </varlistentry>
495           </variablelist>
496         </para>
497       </section>
498
499       <section><title>Other</title>
500         <para>
501           <variablelist>
502             <varlistentry>
503               <term><literal>helloworld</literal></term>
504               <listitem>
505                 <para>Builds a static executable that prints hello
506                   world then loops infinitely.
507                 </para>
508               </listitem>
509             </varlistentry>
510
511             <varlistentry>
512               <term><literal>world</literal></term>
513               <listitem>
514                 <para>Build everything. This takes a long time, a lot
515                   of network bandwidth, and a lot of disc space. Can also
516                   break your toolchain.
517                 </para>
518               </listitem>
519             </varlistentry>
520
521             <varlistentry>
522               <term><literal>package-index</literal></term>
523               <listitem>
524                 <para>Target to update the "feed" files to reflect the current
525                   set of .ipk's that exist in the deploy directory. Commonly
526                   used after building some packages individually to update the
527                   feed and allow them to be installed via a package manager or
528                   the ipkg command line tools.
529                 </para>
530               </listitem>
531             </varlistentry>
532
533             <varlistentry>
534               <term><literal>virtual/kernel</literal></term>
535               <listitem>
536                 <para>Builds the appropriate kernel for your device.</para>
537               </listitem>
538             </varlistentry>
539           </variablelist>
540         </para>
541       </section>
542     </section>
543   </section>
544 </chapter>