code.vuplus.com Git - vuplus_openembedded/blob - 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>