Merge branch 'org.openembedded.dev' of git://git.openembedded.org/openembedded into...
[openembedded.git] / docs / usermanual / chapters / common_use_cases.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="chapter_common_use_cases">
3   <title>Common Use-cases/tasks</title>
4
5   <section id="commonuse_new_distro">
6     <title>Creating a new Distribution</title>
7
8     <para>Creating a new distribution is not complicated, however we urge you
9     to try existing distributions first, because it's also very easy to do
10     wrong. The config need to be created in /conf/distro directory. So what
11     has to be inside? <itemizedlist>
12         <listitem>
13           <para><command>DISTRO_VERSION</command> so users will know which
14           version of distribution they use.</para>
15         </listitem>
16
17         <listitem>
18           <para><command>DISTRO_TYPE</command> (release/debug) variable is
19           used in some recipes to enable/disable some features - for example
20           kernel output on screen for "debug" builds.</para>
21         </listitem>
22
23         <listitem>
24           <para>Type of libc used: will it be glibc
25           (<command>TARGET_OS</command> = "linux") or uclibc
26           (<command>TARGET_OS</command> = "linux-uclibc")?</para>
27         </listitem>
28
29         <listitem>
30           <para>Toolchain versions - for example gcc 3.4.4 based distro will
31           have: <screen>
32 PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc-initial:gcc-cross-initial"
33 PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc:gcc-cross"
34 PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}g++:gcc-cross"
35
36 PREFERRED_VERSION_binutils = "2.16"
37 PREFERRED_VERSION_binutils-cross = "2.16"
38
39 PREFERRED_VERSION_gcc = "3.4.4"
40 PREFERRED_VERSION_gcc-cross = "3.4.4"
41 PREFERRED_VERSION_gcc-initial-cross = "3.4.4"
42             </screen></para>
43         </listitem>
44
45         <listitem>
46           <para><command>DISTRO_FEATURES</command> which describe which
47           features distro has. More about it in <link
48           linkend="task-base">task-base</link> section.</para>
49         </listitem>
50
51         <listitem>
52           <para>Versions of kernels used for supported devices: <screen>
53 PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
54 PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
55             </screen></para>
56         </listitem>
57
58         <listitem>
59           <para>To get more stable build it is good to make use of
60           sane-srcdates.inc file which contain working SRCDATE for many of
61           floating recipes. <screen>
62 require conf/distro/include/sane-srcdates.inc
63             </screen> It also should have global <command>SRCDATE</command>
64           value set (format is ISO date: YYYYMMDD): <screen>
65 SRCDATE = "20061014"
66             </screen></para>
67         </listitem>
68       </itemizedlist></para>
69   </section>
70
71   <section id="commonuse_new_machine">
72     <title>Adding a new Machine</title>
73
74     <para>To be able to build for device OpenEmbedded have to know it, so
75     machine config file need to be written. All those configs are stored in
76     /conf/machine/ directory.</para>
77
78     <para>As usual some variables are required: <itemizedlist>
79         <listitem>
80           <para><command>TARGET_ARCH</command> which describe which CPU
81           architecture does machine use.</para>
82         </listitem>
83
84         <listitem>
85           <para><command>MACHINE_FEATURES</command> which describe which
86           features device has. More about it in <link
87           linkend="task-base">task-base</link> section.</para>
88         </listitem>
89
90         <listitem>
91           <para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to
92           point into proper kernel recipe for this machine.</para>
93         </listitem>
94       </itemizedlist></para>
95
96     <para>Next kernel recipe needs to be added.</para>
97   </section>
98
99   <section id="commonuse_new_package">
100     <title>Adding a new Package</title>
101
102     <para>This section is a stub, help us by expanding it.  Learn by example, go through the
103     recipes that are already there and mimic them to do what you want.</para>
104
105     <section>
106         <title>building from unstable source code</title>
107         <para>Building against the latest, bleeding-edge source has some intricacies of its own.
108         For one, it is desirable to pin down a souce code revision that is known to build to 
109         prevent random breakage in OE at the most inopportune time for all OE users.  Here is
110         how to do that properly.
111           <itemizedlist>
112             <listitem><para>for svn: add 'PV = "1.1+svnr${SRCREV}"' to your bb file.</para></listitem>
113             <listitem><para>for cvs: add 'PV = "1.1+cvs${SRCREV}"' to your bb file.</para></listitem>
114           </itemizedlist>
115         Accompany either with an entry to conf/distro/include/sane-srcrevs.inc for a revision that you know
116         builds successfully.
117         </para>
118         <para>
119         If you really absolutely have to follow the latest commits, you can do that by adding
120         'SRCREV_pn-linux-davinci ?= ${AUTOREV}' to your local.conf, for example.  In this case,
121         you'd build against the most recent and unstable source for the pn-linux-davinci package.
122         </para>
123     </section>
124   </section>
125
126   <section id="commonuse_new_image">
127     <title>Creating your own image</title>
128
129     <para>Creating own image is easy - only few variables needs to be set:
130     <itemizedlist>
131         <listitem>
132           <para><command>IMAGE_BASENAME</command> to give a name for your own
133           image</para>
134         </listitem>
135
136         <listitem>
137           <para><command>PACKAGE_INSTALL</command> to give a list of packages
138           to install into the image</para>
139         </listitem>
140
141         <listitem>
142           <para><command>RDEPENDS</command> to give a list of recipes which
143           are needed to be built to create this image</para>
144         </listitem>
145
146         <listitem>
147           <para><command>IMAGE_LINGUAS</command> is an optional list of
148           languages which has to be installed into the image</para>
149         </listitem>
150       </itemizedlist> Then adding of the <emphasis>image</emphasis> class use:
151     <screen>
152 inherit image
153 </screen> And the image recipe is ready for usage.</para>
154   </section>
155
156   <section id="commonuse_prebuilt_toolchain">
157     <title>Using a prebuilt toolchain to create your packages</title>
158
159     <para>It might be necessary to integrate a prebuilt toolchain and other
160     libraries but still be use OpenEmbedded to build packages. One of many
161     approaches is shown and discussed here.</para>
162
163     <section>
164       <title>The toolchain</title>
165
166       <para>We assume the toolchain provides a C and C++ compiler, an
167       assembler and other tools to build packages. The list below shows a gcc
168       3.4.4 toolchain for ARM architectures using glibc. We assume that the
169       toolchain is in your <command>PATH</command>.</para>
170
171       <screen>
172 <command>ls</command> pre-built/cross/bin
173
174 arm-linux-g++
175 arm-linux-ld
176 arm-linux-ranlib
177 arm-linux-ar
178 arm-linux-g77
179 arm-linux-readelf
180 arm-linux-as
181 arm-linux-gcc
182 arm-linux-gcc-3.4.4
183 arm-linux-c++
184 arm-linux-size
185 arm-linux-c++filt
186 arm-linux-nm
187 arm-linux-strings
188 arm-linux-cpp
189 arm-linux-objcopy
190 arm-linux-strip
191 arm-linux-objdump
192 </screen>
193     </section>
194
195     <section>
196       <title>The prebuilt libraries</title>
197
198       <para>We need the header files and the libraries itself. The following
199       directory layout is assume. <command>PRE_BUILT</command> has two
200       subdirectories one is called <emphasis>include</emphasis> and holds the
201       header files and the other directory is called <emphasis>lib</emphasis>
202       and holds the shared and static libraries. Additionally a Qt2 directory
203       is present having a <emphasis>include</emphasis> and
204       <emphasis>lib</emphasis> sub-directory.</para>
205
206       <screen>
207 <command>ls</command> $PRE_BUILT
208 include
209 lib
210 qt2
211 </screen>
212     </section>
213
214     <section>
215       <title>Setting up OpenEmbedded</title>
216
217       <para>OpenEmbedded will be setup here. We assume that your machine and
218       distribution is not part of OpenEmbedded and they will be created ad-hoc
219       in the <emphasis>local.conf</emphasis> file. You will need to have
220       <application>BitBake</application> and a current OpenEmbedded version
221       available.</para>
222
223       <section>
224         <title>Sourcable script</title>
225
226         <para>To ease the usage of OpenEmbedded we start by creating a
227         source-able script. This is actually a small variation from the
228         already seen script. We will name it <emphasis>build_source</emphasis>
229         and you will need to source it.</para>
230
231         <screen>
232 BITBAKE_PATH=/where/is/bitbake/bin
233 TOOLCHAIN=/where/is/toolchain/bin
234 HOST_TOOLS=/where/is/hosttools/bin
235 export PRE_BUILT=/where/is/pre-built
236
237 export PATH=$BITBAKE_PATH:$TOOLCHAIN:$HOST_TOOLS:$PATH
238 export OEDIR=$PWD
239 export LOCALDIR=$PWD/secret-isv
240                     </screen>
241
242         <para>Use <command>source build_source</command> to source the script,
243         use <command>env</command> to check that the variable where
244         exported.</para>
245       </section>
246
247       <section>
248         <title>Creating the local.conf</title>
249
250         <para>We will configure OpenEmbedded now, it is very similar to what
251         we have done above.</para>
252
253         <screen>
254 DL_DIR = "${OEDIR}/sources"
255 BBFILES := "${OEDIR}/openembedded/recipes/*/*.bb ${LOCALDIR}/recipes/*/*.bb"
256 BBFILE_COLLECTIONS = "upstream local"
257 BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/recipes/"
258 BBFILE_PATTERN_local = "^${LOCALDIR}/recipes/"
259 BBFILE_PRIORITY_upstream = "5"
260 BBFILE_PRIORITY_local = "10"
261 BBMASK = ""
262                     </screen>
263
264         <para>${OEDIR}/openembedded will be a upstream release of
265         OpenEmbedded. Above we have assumed it is in the current working
266         directory. Additionally we have a ${LOCALDIR}, we combine these two
267         directories as a special <link linkend="collections">BitBake
268         Collection</link>.</para>
269
270         <screen>
271 #
272 # machine stuff
273 #
274 MACHINE = "secret-killer"
275 PACKAGE_EXTRA_ARCHS = "armv4 armv4t armv5te iwmmxt xscale""
276 TARGET_CC_ARCH = "-mcpu=xscale -mtune=iwmmxt"
277 TARGET_ARCH = "arm"
278 PACKAGE_ARCH="xscale"
279                 </screen>
280
281         <para>We tell OpenEmbedded that we build for the ARM platform and
282         optimize for xscale and iwmmxt.</para>
283
284         <screen>
285 INHERIT += " package_ipk debian"
286 TARGET_OS  = "linux"
287 TARGET_FPU = "soft"
288 DISTRO = "secret-disro"
289 DISTRO_NAME = "secret-distro"
290 DISTRO_VERSION = "x.y.z"
291 DISTRO_TYPE = "release"
292                 </screen>
293
294         <para>Create a distribution ad-hoc as well. We tell OpenEmbedded that
295         we build for linux and glibc using soft float as fpu. If your
296         toolchain is a uclibc toolchain you will need to set
297         <command>TARGET_OS</command> to linux-uclibc.</para>
298
299         <screen>
300 export CC="${CCACHE}arm-linux-gcc-3.4.4 ${HOST_CC_ARCH}"
301 export CXX="${CCACHE}arm-linux-g++ ${HOST_CC_ARCH}"
302 export CPP="arm-linux-gcc-3.4.4 -E"
303 export LD="arm-linux-ld"
304 export AR="arm-linux-ar"
305 export AS="arm-linux-as"
306 export RANLIB="arm-linux-ranlib"
307 export STRIP="arm-linux-strip"
308                 </screen>
309
310         <para>The above variables replace the ones from
311         <emphasis>bitbake.conf</emphasis>. This will make OpenEmbedded use the
312         prebuilt toolchain.</para>
313
314         <screen>
315 #
316 # point OE to the lib and include directory
317 #
318 TARGET_CPPFLAGS_append = " -I${PRE_BUILT}/include "
319 TARGET_LDFLAGS_prepend = " -L${PRE_BUILT}/qt2/lib -L${PRE_BUILT}/lib \
320 -Wl,-rpath-link,${PRE_BUILT}/lib -Wl,-rpath-link,${PRE_BUILT}/qt2/lib "
321
322 # special to Qt/Qtopia
323 QTDIR  = "${PRE_BUILT}/qt2"
324 QPEDIR = "${PRE_BUILT}"
325 palmtopdir = "/opt/Qtopia"
326 palmqtdir  = "/opt/Qtopia"
327                 </screen>
328
329         <para>We will add the <command>PRE_BUILT</command> libraries to the
330         include and library paths. And the same is done for the special
331         version of Qt we have in your <command>PRE_BUILT</command>
332         directory.</para>
333
334         <screen>
335 ASSUME_PROVIDED += " virtual/${TARGET_PREFIX}gcc "
336 ASSUME_PROVIDED += " virtual/libc "
337 ASSUME_PROVIDED += " virtual/qte "
338 ASSUME_PROVIDED += " virtual/libqpe "
339 ASSUME_PROVIDED += " libqpe-opie "
340                 </screen>
341
342         <para>Now we have told <application>BitBake</application> that the C
343         library, compiler and Qtopia is already provided. These lines will
344         avoid building binutils, gcc initial, glibc, gcc.</para>
345
346         <screen>
347 <command>source</command> build_source
348 <command>bitbake</command> your-killer-app
349                 </screen>
350
351         <para>You should be able to create the packages you want to using the
352         prebuilt toolchain now.</para>
353       </section>
354     </section>
355
356     <section>
357       <title>Useful hints</title>
358
359       <para>If you have more prebuilt libraries you need to add additional
360       <command>ASSUME_PROVIDED</command> lines to your
361       <emphasis>local.conf</emphasis>. Using <command>bitbake -vvv
362       PACKAGE</command> you can easily see the package names you could
363       <command>ASSUME_PROVIDED</command> if you have some prebuilt.</para>
364     </section>
365
366     <section>
367       <title>Issues with this approach</title>
368
369       <screen>
370 NOTE: Couldn't find shared library provider for libqtopia.so.1
371 NOTE: Couldn't find shared library provider for libqtopia2.so.2
372 NOTE: Couldn't find shared library provider for libqpe.so.1
373 NOTE: Couldn't find shared library provider for libpthread.so.0
374 NOTE: Couldn't find shared library provider for libstdc++.so.6
375 NOTE: Couldn't find shared library provider for libqte.so.2
376 NOTE: Couldn't find shared library provider for libgcc_s.so.1
377 NOTE: Couldn't find shared library provider for libc.so.6
378 NOTE: Couldn't find shared library provider for libm.so.6
379 </screen>
380
381       <para>OpenEmbedded tries to automatically add run-time dependencies
382       (RDEPENDS) to the package. It uses the <emphasis><link
383       linkend="shlibs">shlibs</link></emphasis> system to do add them, in this
384       case it was not able to find packages providing these libraries as they
385       are prebuilt. This means they will not be added to the RDEPENDS of the
386       just created package. The result can be fatal. If you use OpenEmbedded
387       to create images you will end up with a image without a libc being
388       installed. This will lead to a fatal failure. To workaround this issue
389       you could create a package for the metadata to install every needed
390       library and use ${BOOTSTRAP_EXTRA_RDEPENDS} to make sure this package is
391       installed when creating images.</para>
392       
393       <para>However, the correct way to resolve this is to provide explicit 
394       mapping using ASSUME_SHLIBS variable. For example, for the libraries 
395       above (partial):
396       <screen>
397 ASSUME_SHLIBS = "libqtopia2.so.2:qtopia2_2.4 libc.so.6:libc"
398 </screen>
399       The format is shlib_file_name:package[_version]. If a version is specified it will be
400       used as the minimal (>=) version for the dependency.</para>
401     </section>
402   </section>
403
404   <section id="commonuse_new_package_format">
405     <title>Using a new package format</title>
406
407     <para>This section is a stub, help us by expanding it</para>
408   </section>
409 </chapter>