getting_oe.xml: Update documentation.
[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>The OpenEmbedded metadata has a high rate of development, so it's a
96     good idea to stay up to date. You'll need monotone 0.28 to get the
97     metadata and stay up to date. Monotone is available in most distributions
98     and has binaries at <ulink url="http://venge.net/monotone/">Monotone
99     homepage</ulink>.</para>
100
101     <para>Next step is getting snapshot of database. <screen>
102 wget http://openembedded.org/snapshots/OE.mtn.bz2 http://openembedded.org/snapshots/OE.mtn.bz2.md5
103 </screen> Or if you have monotone 0.30 or later: <screen>
104 wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2 
105 wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2.md5
106 </screen> Then verify integrity of snapshot by checking md5sum. <screen>
107 md5sum -c OE.mtn.bz2.md5sum
108 </screen> Then unpack database. <screen>
109 bunzip OE.mtn.bz2
110 </screen> Finally checkout the development branch. <screen>
111 mtn --db=OE.mtn co -b org.openembedded.dev
112 </screen></para>
113   </section>
114
115   <section id="gettingoe_configuring_oe">
116     <title>Configuring OpenEmbedded</title>
117
118     <para>This section is a stub, help us by expanding it</para>
119   </section>
120
121   <section id="gettingoe_building_software">
122     <title>Building Software</title>
123
124     <para>Once BitBake and OpenEmbedded are set up and configured, one can build 
125     software and images like this:
126 <screen>
127 bitbake &lt;recipe_name&gt;
128 </screen>
129             </para>
130
131     <para>This section is a stub, help us by expanding it</para>
132   </section>
133 </chapter>