getting_oe.xml: Update getting openembedded 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>This section is a stub, help us by expanding it</para>
145   </section>
146
147   <section id="gettingoe_building_software">
148     <title>Building Software</title>
149
150     <para>Once BitBake and OpenEmbedded are set up and configured, one can build 
151     software and images like this:
152 <screen>
153 bitbake &lt;recipe_name&gt;
154 </screen>
155             </para>
156
157     <para>This section is a stub, help us by expanding it</para>
158   </section>
159 </chapter>