1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
4 <head><title>opendreambox</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6 <meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)">
7 <meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)">
9 <meta name="src" content="opendreambox.tex">
10 <meta name="date" content="2013-11-05 00:52:00">
11 <link rel="stylesheet" type="text/css" href="opendreambox.css">
14 <div class="maketitle">
22 <h2 class="titleHead">opendreambox</h2>
23 <div class="author" ><span
24 class="cmr-12">Andreas Oberritter </span><span
25 class="cmtt-9"><obi@opendreambox.org></span></div>
27 <div class="date" ><span
28 class="cmr-12">October 2013</span></div>
30 <h3 class="likesectionHead"><a
31 id="x1-1000"></a>Contents</h3>
32 <div class="tableofcontents">
33 <span class="sectionToc" >1 <a
34 href="#x1-20001" id="QQ2-1-2">Introduction</a></span>
35 <br /> <span class="subsectionToc" >1.1 <a
36 href="#x1-30001.1" id="QQ2-1-3">Target audience</a></span>
37 <br /> <span class="subsectionToc" >1.2 <a
38 href="#x1-40001.2" id="QQ2-1-4">Supported products</a></span>
39 <br /> <span class="subsectionToc" >1.3 <a
40 href="#x1-50001.3" id="QQ2-1-5">License</a></span>
41 <br /> <span class="subsectionToc" >1.4 <a
42 href="#x1-60001.4" id="QQ2-1-6">Obtaining the source code</a></span>
43 <br /> <span class="subsectionToc" >1.5 <a
44 href="#x1-70001.5" id="QQ2-1-7">Quick start</a></span>
45 <br /> <span class="subsectionToc" >1.6 <a
46 href="#x1-80001.6" id="QQ2-1-8">Directory structure</a></span>
47 <br />  <span class="subsubsectionToc" >1.6.1 <a
48 href="#x1-90001.6.1" id="QQ2-1-9">openembedded-core and meta-openembedded</a></span>
49 <br />  <span class="subsubsectionToc" >1.6.2 <a
50 href="#x1-100001.6.2" id="QQ2-1-10">meta-opendreambox</a></span>
51 <br />  <span class="subsubsectionToc" >1.6.3 <a
52 href="#x1-110001.6.3" id="QQ2-1-11">meta-bsp</a></span>
53 <br /><span class="sectionToc" >2 <a
54 href="#x1-120002" id="QQ2-1-12">Prerequisites</a></span>
55 <br /> <span class="subsectionToc" >2.1 <a
56 href="#x1-130002.1" id="QQ2-1-13">Required software</a></span>
57 <br /><span class="sectionToc" >3 <a
58 href="#x1-140003" id="QQ2-1-14">Major changes since previous public releases</a></span>
59 <br /> <span class="subsectionToc" >3.1 <a
60 href="#x1-150003.1" id="QQ2-1-15">Changes since release 1.6</a></span>
61 <br /> <span class="subsectionToc" >3.2 <a
62 href="#x1-160003.2" id="QQ2-1-16">Changes since release 2.0</a></span>
63 <br /><span class="sectionToc" >4 <a
64 href="#x1-170004" id="QQ2-1-17">Known Issues</a></span>
65 <br /><span class="sectionToc" >5 <a
66 href="#x1-180005" id="QQ2-1-18">Building OpenDreambox</a></span>
70 <br /> <span class="subsectionToc" >5.1 <a
71 href="#x1-190005.1" id="QQ2-1-19">Makefile targets</a></span>
72 <br /> <span class="subsectionToc" >5.2 <a
73 href="#x1-200005.2" id="QQ2-1-20">Configuration variables</a></span>
74 <br />  <span class="subsubsectionToc" >5.2.1 <a
75 href="#x1-210005.2.1" id="QQ2-1-21">BB_NUMBER_THREADS</a></span>
76 <br />  <span class="subsubsectionToc" >5.2.2 <a
77 href="#x1-220005.2.2" id="QQ2-1-22">MACHINE</a></span>
78 <br />  <span class="subsubsectionToc" >5.2.3 <a
79 href="#x1-230005.2.3" id="QQ2-1-23">PARALLEL_MAKE</a></span>
80 <br /> <span class="subsectionToc" >5.3 <a
81 href="#x1-240005.3" id="QQ2-1-24">Adding custom layers</a></span>
82 <br /> <span class="subsectionToc" >5.4 <a
83 href="#x1-250005.4" id="QQ2-1-25">Adding custom options</a></span>
84 <br />  <span class="subsubsectionToc" >5.4.1 <a
85 href="#x1-260005.4.1" id="QQ2-1-26">DISTRO_FEED_PREFIX</a></span>
86 <br />  <span class="subsubsectionToc" >5.4.2 <a
87 href="#x1-270005.4.2" id="QQ2-1-27">DISTRO_FEED_URI</a></span>
88 <br />  <span class="subsubsectionToc" >5.4.3 <a
89 href="#x1-280005.4.3" id="QQ2-1-28">INHERIT</a></span>
90 <br /> <span class="subsectionToc" >5.5 <a
91 href="#x1-290005.5" id="QQ2-1-29">Setting up a build directory</a></span>
92 <br /> <span class="subsectionToc" >5.6 <a
93 href="#x1-300005.6" id="QQ2-1-30">Building a firmware image</a></span>
94 <br /> <span class="subsectionToc" >5.7 <a
95 href="#x1-310005.7" id="QQ2-1-31">Building a package</a></span>
96 <br /><span class="sectionToc" >6 <a
97 href="#x1-320006" id="QQ2-1-32">Development hints</a></span>
98 <br /> <span class="subsectionToc" >6.1 <a
99 href="#x1-330006.1" id="QQ2-1-33">Cross-compilation of external software</a></span>
100 <br /> <span class="subsectionToc" >6.2 <a
101 href="#x1-340006.2" id="QQ2-1-34">Coding style</a></span>
102 <br /> <span class="subsectionToc" >6.3 <a
103 href="#x1-350006.3" id="QQ2-1-35">Package architecture</a></span>
104 <br /><span class="sectionToc" >7 <a
105 href="#x1-360007" id="QQ2-1-36">Bug reports and patches</a></span>
110 <!--l. 54--><p class="noindent" >
111 <h3 class="sectionHead"><span class="titlemark">1 </span> <a
112 id="x1-20001"></a>Introduction</h3>
113 <div class="flushleft"
115 <!--l. 55--><p class="noindent" >
116 This document briefly describes the OpenDreambox distribution, an
117 embedded Linux distribution for Set-Top-Boxes manufactured by <a
118 href="http://www.dream-multimedia-tv.de/" >Dream
120 <!--l. 59--><p class="noindent" >OpenDreambox is based on the <a
121 href="http://www.openembedded.org/" >OpenEmbedded</a> build framework, which uses
123 href="http://bitbake.berlios.de/" >BitBake</a> to transform build instructions into distributable firmare images and
125 <!--l. 63--><p class="noindent" >The current version, OpenDreambox 2.2, is based on the <a
126 href="http://www.yoctoproject.org" >Yocto Project</a>,
127 release 1.5 ”Dora”, an umbrella project for OpenEmbedded and related tools.</div>
128 <!--l. 67--><p class="noindent" >
129 <h4 class="subsectionHead"><span class="titlemark">1.1 </span> <a
130 id="x1-30001.1"></a>Target audience</h4>
131 <div class="flushleft"
133 <!--l. 68--><p class="noindent" >
134 Developers familiar with previous versions of OpenDreambox or
135 OpenEmbedded in general.</div>
136 <!--l. 73--><p class="noindent" >
137 <h4 class="subsectionHead"><span class="titlemark">1.2 </span> <a
138 id="x1-40001.2"></a>Supported products</h4>
139 <div class="flushleft"
141 <!--l. 75--><p class="noindent" >
142 The current version includes support for the following machines:
143 <div class="tabular"> <table id="TBL-2" class="tabular"
144 cellspacing="0" cellpadding="0" rules="groups"
145 ><colgroup id="TBL-2-1g"><col
146 id="TBL-2-1"></colgroup><colgroup id="TBL-2-2g"><col
147 id="TBL-2-2"></colgroup><tr
148 class="hline"><td><hr></td><td><hr></td></tr><tr
149 style="vertical-align:baseline;" id="TBL-2-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-1"
151 class="cmbx-10">Product name </span></td><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-2"
153 class="cmbx-10">Environment variable</span></td></tr><tr
154 class="hline"><td><hr></td><td><hr></td></tr><tr
155 style="vertical-align:baseline;" id="TBL-2-2-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-1"
156 class="td11"> </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-2"
159 style="vertical-align:baseline;" id="TBL-2-3-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-1"
160 class="td11">DM 500 HD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-2"
162 class="cmtt-9">MACHINE=dm500hd </span></td>
164 style="vertical-align:baseline;" id="TBL-2-4-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-1"
165 class="td11">DM 800 HD SE </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-2"
167 class="cmtt-9">MACHINE=dm800se </span></td>
169 style="vertical-align:baseline;" id="TBL-2-5-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-1"
170 class="td11">DM 7020 HD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-2"
172 class="cmtt-9">MACHINE=dm7020hd </span></td>
174 style="vertical-align:baseline;" id="TBL-2-6-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-6-1"
175 class="td11">DM 8000 HD PVR</td><td style="white-space:nowrap; text-align:left;" id="TBL-2-6-2"
177 class="cmtt-9">MACHINE=dm8000 </span></td>
179 style="vertical-align:baseline;" id="TBL-2-7-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-7-1"
180 class="td11"> </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-7-2"
183 class="hline"><td><hr></td><td><hr></td></tr><tr
184 style="vertical-align:baseline;" id="TBL-2-8-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-8-1"
186 </tr></table></div></div>
190 <!--l. 91--><p class="noindent" >
191 <h4 class="subsectionHead"><span class="titlemark">1.3 </span> <a
192 id="x1-50001.3"></a>License</h4>
196 <div class="verbatim" id="verbatim-1">
197 Copyright (c) 2010-2013 Dream Multimedia GmbH, Germany
198  <br />                        http://www.dream-multimedia-tv.de/
199  <br />Authors:
200  <br />  Andreas Frisch <fraxinas@opendreambox.org>
201  <br />  Andreas Monzner <ghost@opendreambox.org>
202  <br />  Andreas Oberritter <obi@opendreambox.org>
203  <br />  Mladen Horvat <acid-burn@opendreambox.org>
204  <br />  Stefan Pluecken <thedoc@opendreambox.org>
205  <br />  Stephan Reichholf <reichi@opendreambox.org>
207  <br />Permission is hereby granted, free of charge, to any person obtaining a copy
208  <br />of this software and associated documentation files (the "Software"), to deal
209  <br />in the Software without restriction, including without limitation the rights
210  <br />to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
211  <br />copies of the Software, and to permit persons to whom the Software is
212  <br />furnished to do so, subject to the following conditions:
214  <br />The above copyright notice and this permission notice shall be included in
215  <br />all copies or substantial portions of the Software.
217  <br />THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
218  <br />IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
219  <br />FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
220  <br />AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
221  <br />LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
222  <br />OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
223  <br />THE SOFTWARE.
224  <br />    </div>
225 <!--l. 121--><p class="nopar" >
226 <!--l. 123--><p class="noindent" >
227 <h4 class="subsectionHead"><span class="titlemark">1.4 </span> <a
228 id="x1-60001.4"></a>Obtaining the source code</h4>
229 <!--l. 124--><p class="noindent" >OpenDreambox uses the Git version control system. To obtain the source code, it is
230 required to install Git. See <a
231 href="http://git-scm.com/" class="url" ><span
232 class="cmtt-10">http://git-scm.com/</span></a>.
233 <!--l. 127--><p class="noindent" >To initially download the source into the current directory, issue the following
235 <!--l. 130--><p class="noindent" ><span
236 class="cmtt-9">git clone -b dora git://git.opendreambox.org/git/opendreambox.git</span>
237 <!--l. 132--><p class="noindent" >The Git repository can be viewed online at:
238 <!--l. 134--><p class="noindent" ><a
239 href="http://cgit.opendreambox.org/opendreambox.git" class="url" ><span
240 class="cmtt-10">http://cgit.opendreambox.org/opendreambox.git</span></a>
244 <!--l. 136--><p class="noindent" >
245 <h4 class="subsectionHead"><span class="titlemark">1.5 </span> <a
246 id="x1-70001.5"></a>Quick start</h4>
247 <!--l. 137--><p class="noindent" >For the impatient:
248 <!--l. 139--><p class="noindent" ><span
249 class="cmtt-9">make -C opendreambox image</span>
250 <!--l. 141--><p class="noindent" >If this command fails, prerequisites my be missing. See section <a
251 href="#x1-120002">2<!--tex4ht:ref: prerequisites --></a>.
252 <!--l. 143--><p class="noindent" >
253 <h4 class="subsectionHead"><span class="titlemark">1.6 </span> <a
254 id="x1-80001.6"></a>Directory structure</h4>
255 <!--l. 144--><p class="noindent" >OpenDreambox consists of a set of layers containing build instructions. This meta
256 data is used by BitBake to download and compile source code and to assemble
257 installable software packages and firmware images.
258 <!--l. 148--><p class="noindent" >Currently, there are eight layers, ordered by priority from highest to lowest:
259 <ul class="itemize1">
260 <li class="itemize"><span
261 class="cmtt-9">meta-bsp/$</span><span
262 class="cmsy-9">{</span><span
263 class="cmtt-9">MACHINE</span><span
264 class="cmsy-9">}</span>
266 <li class="itemize"><span
267 class="cmtt-9">meta-bsp/common</span>
269 <li class="itemize"><span
270 class="cmtt-9">meta-opendreambox</span>
272 <li class="itemize"><span
273 class="cmtt-9">meta-openembedded/meta-oe</span>
275 <li class="itemize"><span
276 class="cmtt-9">meta-openembedded/meta-filesystems</span>
278 <li class="itemize"><span
279 class="cmtt-9">meta-openembedded/meta-multimedia</span>
281 <li class="itemize"><span
282 class="cmtt-9">meta-openembedded/meta-networking</span>
284 <li class="itemize"><span
285 class="cmtt-9">openembedded-core/meta</span></li></ul>
286 <!--l. 162--><p class="noindent" >If a recipe for the same package exists in multiple layers, then the higher priority
287 layer takes precedence over the lower priority layer.
288 <!--l. 166--><p class="noindent" >For example, if <span
289 class="cmtt-9">libmad</span><span
290 class="cmtt-9">_0.15.1b.bb </span>existed in both <span
291 class="cmtt-9">meta-openembedded </span>and
293 class="cmtt-9">openembedded-core</span>, the recipe in <span
294 class="cmtt-9">meta-openembedded </span>would be used, because
296 class="cmtt-9">openembedded-core </span>has lower priority.
300 <!--l. 171--><p class="noindent" ><span
301 class="cmbx-10">NOTE: </span>This would still be true even if the version of <span
302 class="cmtt-9">libmad </span>in <span
303 class="cmtt-9">openembeded-core</span>
304 was higher than the version in <span
305 class="cmtt-9">meta-openembedded</span>, unless <span
306 class="cmtt-9">PREFERRED</span><span
307 class="cmtt-9">_VERSION</span><span
308 class="cmtt-9">_libmad</span>
309 was set to the version in <span
310 class="cmtt-9">openembedded-core</span>. There is currently no way to prefer a
311 version of a lower priority layer, if the same version is present in a higher priority
313 <!--l. 177--><p class="noindent" >
314 <h5 class="subsubsectionHead"><span class="titlemark">1.6.1 </span> <a
315 id="x1-90001.6.1"></a>openembedded-core and meta-openembedded</h5>
316 <!--l. 178--><p class="noindent" >These directories contain copies of Git repositories from git.openembedded.org,
317 including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers.
318 They get created automatically when building the distribution for the first
320 <!--l. 182--><p class="noindent" >Throughout this document, the combination of these directories will be referred to as
322 <!--l. 185--><p class="noindent" >The latest changes to these Git repositories can be seen at:
323 <!--l. 187--><p class="noindent" ><a
324 href="http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/dora" class="url" ><span
325 class="cmtt-10">http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/dora</span></a>
326 <!--l. 189--><p class="noindent" ><a
327 href="http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/dora" class="url" ><span
328 class="cmtt-10">http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/dora</span></a>
329 <!--l. 191--><p class="noindent" >
330 <h5 class="subsubsectionHead"><span class="titlemark">1.6.2 </span> <a
331 id="x1-100001.6.2"></a>meta-opendreambox</h5>
332 <!--l. 192--><p class="noindent" >This directory contains:
333 <ul class="itemize1">
334 <li class="itemize">Recipes for packages written specifically for the OpenDreambox
337 <li class="itemize">Modifications to recipes from OpenEmbedded
339 <li class="itemize">Recipes for software versions older than those available from
342 <li class="itemize">Recipes for software versions newer than those available from
343 OpenEmbedded</li></ul>
347 <!--l. 201--><p class="noindent" >
348 <h5 class="subsubsectionHead"><span class="titlemark">1.6.3 </span> <a
349 id="x1-110001.6.3"></a>meta-bsp</h5>
350 <!--l. 202--><p class="noindent" >The directory <span
351 class="cmtt-9">meta-bsp </span>contains Board Support Packages (BSP) for the supported
352 Dreambox models. This includes:
353 <ul class="itemize1">
354 <li class="itemize">Hardware drivers
356 <li class="itemize">Machine specific overrides
358 <li class="itemize">The Linux kernel
360 <li class="itemize">The boot loader
362 <li class="itemize">Splash images</li></ul>
363 <!--l. 213--><p class="noindent" >
364 <h3 class="sectionHead"><span class="titlemark">2 </span> <a
365 id="x1-120002"></a>Prerequisites</h3>
366 <!--l. 216--><p class="noindent" >
367 <h4 class="subsectionHead"><span class="titlemark">2.1 </span> <a
368 id="x1-130002.1"></a>Required software</h4>
369 <!--l. 218--><p class="noindent" >The OpenEmbedded project provides a general list of prerequisites for many Linux
370 distributions and also for some other operating systems.
371 <ul class="itemize1">
372 <li class="itemize"><a
373 href="http://www.openembedded.org/wiki/Getting\_started#Required\_software" class="url" ><span
374 class="cmtt-10">http://www.openembedded.org/wiki/Getting\_started#Required\_software</span></a></li></ul>
375 <!--l. 225--><p class="noindent" >It is highly recommended to use Linux to build OpenDreambox. In theory, any recent
376 distribution will do, but not many distributions have been verified to build
377 OpenDreambox without errors. Tested distributions include:
378 <ul class="itemize1">
379 <li class="itemize">Debian 7.2 ”Wheezy” [amd64]
381 <li class="itemize">Ubuntu 13.04 ”Raring Ringtail” [amd64]</li></ul>
385 <!--l. 235--><p class="noindent" >Distributions known not to work:
386 <ul class="itemize1">
387 <li class="itemize">Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.</li></ul>
391 <!--l. 243--><p class="noindent" >
392 <h3 class="sectionHead"><span class="titlemark">3 </span> <a
393 id="x1-140003"></a>Major changes since previous public releases</h3>
394 <!--l. 245--><p class="noindent" >
395 <h4 class="subsectionHead"><span class="titlemark">3.1 </span> <a
396 id="x1-150003.1"></a>Changes since release 1.6</h4>
397 <ul class="itemize1">
398 <li class="itemize">Recipes were split across multiple layers and categorized.
400 <li class="itemize"><span
401 class="cmtt-9">env.source </span>has been replaced by two files, <span
402 class="cmtt-9">bitbake.env </span>and
404 class="cmtt-9">cross-compile.env</span>. The former sets a minimal environment that is needed
405 to execute bitbake. The latter creates machine-specific command aliases,
406 in order to compile external software.
408 <li class="itemize">All machines share a common <span
409 class="cmtt-9">tmp </span>directory.
411 <li class="itemize"><span
412 class="cmtt-9">$</span><span
413 class="cmsy-9">{</span><span
414 class="cmtt-9">MACHINE</span><span
415 class="cmsy-9">}</span><span
416 class="cmtt-9">/build </span>directories were renamed to <span
417 class="cmtt-9">build/$</span><span
418 class="cmsy-9">{</span><span
419 class="cmtt-9">MACHINE</span><span
420 class="cmsy-9">}</span>.
422 <li class="itemize">Kernel packages were renamed from <span
423 class="cmtt-9">linux-$</span><span
424 class="cmsy-9">{</span><span
425 class="cmtt-9">MACHINE</span><span
426 class="cmsy-9">} </span>to <span
427 class="cmtt-9">linux-dreambox</span>.
429 <li class="itemize">Support for machines based on ATI Xilleon or IBM STB was dropped.</li></ul>
430 <!--l. 258--><p class="noindent" >
431 <h4 class="subsectionHead"><span class="titlemark">3.2 </span> <a
432 id="x1-160003.2"></a>Changes since release 2.0</h4>
433 <ul class="itemize1">
434 <li class="itemize">If a recipe changes, the corresponding packages will be rebuilt
435 automatically, in contrast to required manual PR bumps in the past.
437 <li class="itemize">Each machine uses its own tmp directory again, like before 2.0. However,
438 there is a shared <span
439 class="cmtt-9">sstate-cache</span>, which allows to share already compiled
440 data between compatible machines. This impacts performance and size of
441 the build system, but improves reliability and consistency across builds.
446 <li class="itemize">Support for machines without FPU and kernel versions below 3.x was
447 dropped (DM800).</li></ul>
448 <!--l. 269--><p class="noindent" >
449 <h3 class="sectionHead"><span class="titlemark">4 </span> <a
450 id="x1-170004"></a>Known Issues</h3>
451 <ul class="itemize1">
452 <li class="itemize"><span
453 class="cmbx-10">Problem: </span>qt4-native may fail to build with
454 <!--l. 274--><p class="noindent" ><span
455 class="cmtt-9">error: one or more PCH files were found, but they were invalid</span>
456 <!--l. 276--><p class="noindent" ><span
457 class="cmbx-10">Solution: </span><span
458 class="cmtt-9">bitbake -ccleansstate qt4-native</span></li></ul>
462 <!--l. 281--><p class="noindent" >
463 <h3 class="sectionHead"><span class="titlemark">5 </span> <a
464 id="x1-180005"></a>Building OpenDreambox</h3>
465 <!--l. 283--><p class="noindent" >In the top level directory, there is a <span
466 class="cmtt-9">Makefile</span>, which is used to set up build
467 directories and to fetch or update all used repositories. The Makefile can
468 be influenced by environment variables, either by specifing them on the
469 command-line or by storing them in a file called <span
470 class="cmtt-9">conf/make.conf</span>. It is not
471 recommended to edit the <span
472 class="cmtt-9">Makefile </span>directly in order to avoid conflicts with future
474 <!--l. 290--><p class="noindent" >When the <span
475 class="cmtt-9">Makefile </span>is run for the first time, the following steps will be executed:
476 <ul class="itemize1">
477 <li class="itemize">Creation of configuration files
478 <ul class="itemize2">
479 <li class="itemize"><span
480 class="cmtt-9">bitbake.env</span>
482 <li class="itemize"><span
483 class="cmtt-9">conf/opendreambox.conf</span>
485 <li class="itemize"><span
486 class="cmtt-9">build/$</span><span
487 class="cmsy-9">{</span><span
488 class="cmtt-9">MACHINE</span><span
489 class="cmsy-9">}</span><span
490 class="cmtt-9">/conf/bblayers.conf</span>
492 <li class="itemize"><span
493 class="cmtt-9">build/$</span><span
494 class="cmsy-9">{</span><span
495 class="cmtt-9">MACHINE</span><span
496 class="cmsy-9">}</span><span
497 class="cmtt-9">/conf/local.conf</span></li></ul>
499 <li class="itemize">Update or checkout of Git repositories
500 <ul class="itemize2">
501 <li class="itemize">OpenDreambox
503 <li class="itemize">BitBake
505 <li class="itemize">OpenEmbedded</li></ul>
507 <!--l. 309--><p class="noindent" >
508 <h4 class="subsectionHead"><span class="titlemark">5.1 </span> <a
509 id="x1-190005.1"></a>Makefile targets</h4>
510 <!--l. 310--><p class="noindent" >Run <span
511 class="cmtt-9">make help </span>to get a list of targets of the top level Makefile, together with a brief
516 <!--l. 312--><p class="noindent" >
517 <h4 class="subsectionHead"><span class="titlemark">5.2 </span> <a
518 id="x1-200005.2"></a>Configuration variables</h4>
519 <!--l. 313--><p class="noindent" >
520 <h5 class="subsubsectionHead"><span class="titlemark">5.2.1 </span> <a
521 id="x1-210005.2.1"></a>BB_NUMBER_THREADS</h5>
522 <!--l. 314--><p class="noindent" >Controls how many BitBake tasks may run at a time. Defaults to the number of cores
523 available on the build system. The number of cores is obtained from <span
524 class="cmtt-9">/proc/cpuinfo</span>. If
525 this file is unavailable, the default value is 1.
526 <!--l. 319--><p class="noindent" >
527 <h5 class="subsubsectionHead"><span class="titlemark">5.2.2 </span> <a
528 id="x1-220005.2.2"></a>MACHINE</h5>
529 <!--l. 320--><p class="noindent" >Controls the target machine to build packages for. See section <a
530 href="#x1-40001.2">1.2<!--tex4ht:ref: products --></a> for a list of
532 <!--l. 323--><p class="noindent" >
533 <h5 class="subsubsectionHead"><span class="titlemark">5.2.3 </span> <a
534 id="x1-230005.2.3"></a>PARALLEL_MAKE</h5>
535 <!--l. 324--><p class="noindent" >Controls how many processes per recipe <span
536 class="cmtt-9">make </span>may use. Defaults to the number of
537 cores available on the build system. The number of cores is obtained from
539 class="cmtt-9">/proc/cpuinfo</span>. If this file is unavailable, the default value is 1.
540 <!--l. 329--><p class="noindent" >NOTE: If you see seemingly random build failures, try setting this variable to
542 <!--l. 331--><p class="noindent" >
543 <h4 class="subsectionHead"><span class="titlemark">5.3 </span> <a
544 id="x1-240005.3"></a>Adding custom layers</h4>
545 <!--l. 333--><p class="noindent" >It is possible to add custom layers to the build system. This can be done globally and
546 per machine. To add a layer globally, edit <span
547 class="cmtt-9">conf/bblayers-ext.conf</span>. To add a
548 machine-specific layer, edit <span
549 class="cmtt-9">conf/bblayers-$</span><span
550 class="cmsy-9">{</span><span
551 class="cmtt-9">MACHINE</span><span
552 class="cmsy-9">}</span><span
553 class="cmtt-9">-ext.conf</span>. Assuming that an
554 additional layer is available at <span
555 class="cmtt-9">$</span><span
556 class="cmsy-9">{</span><span
557 class="cmtt-9">HOME</span><span
558 class="cmsy-9">}</span><span
559 class="cmtt-9">/custom-layer</span>, the entry to add to the file will
561 <!--l. 339--><p class="noindent" ><span
562 class="cmtt-9">BBLAYERS =+ "$</span><span
563 class="cmsy-9">{</span><span
564 class="cmtt-9">HOME</span><span
565 class="cmsy-9">}</span><span
566 class="cmtt-9">/custom-layer"</span>
570 <!--l. 341--><p class="noindent" >
571 <h4 class="subsectionHead"><span class="titlemark">5.4 </span> <a
572 id="x1-250005.4"></a>Adding custom options</h4>
573 <!--l. 342--><p class="noindent" >It is possible to tweak a lot more options than those used by the <span
574 class="cmtt-9">Makefile </span>by editing
576 class="cmtt-9">conf/local-ext.conf </span>or <span
577 class="cmtt-9">conf/local-$</span><span
578 class="cmsy-9">{</span><span
579 class="cmtt-9">MACHINE</span><span
580 class="cmsy-9">}</span><span
581 class="cmtt-9">-ext.conf</span>.
582 <!--l. 345--><p class="noindent" >For example, if the firmware shall use the package feed built on the develoment
583 machine, which happens to be 192.168.1.1 and has a webserver configured to point to
585 class="cmtt-9">tmp/deploy/ipk</span>, a line like the following may be added:
586 <!--l. 349--><p class="noindent" ><span
587 class="cmtt-9">DISTRO</span><span
588 class="cmtt-9">_FEED</span><span
589 class="cmtt-9">_URI = "http://192.168.1.1/$</span><span
590 class="cmsy-9">{</span><span
591 class="cmtt-9">DISTRO</span><span
592 class="cmsy-9">}</span><span
593 class="cmtt-9">/$</span><span
594 class="cmsy-9">{</span><span
595 class="cmtt-9">DISTRO</span><span
596 class="cmtt-9">_VERSION</span><span
597 class="cmsy-9">}</span><span
598 class="cmtt-9">"</span>
599 <!--l. 351--><p class="noindent" >In general, any variable in OpenEmbedded that uses weak assignment (<span
600 class="cmtt-9">?=</span>) may be
601 overridden from these files.
602 <!--l. 354--><p class="noindent" >The following sections list some commonly used options.
603 <!--l. 356--><p class="noindent" >
604 <h5 class="subsubsectionHead"><span class="titlemark">5.4.1 </span> <a
605 id="x1-260005.4.1"></a>DISTRO_FEED_PREFIX</h5>
606 <!--l. 358--><p class="noindent" ><span
607 class="cmtt-9">DISTRO</span><span
608 class="cmtt-9">_FEED</span><span
609 class="cmtt-9">_PREFIX </span>specifies the name of the package update feed. This name may be
611 <!--l. 361--><p class="noindent" >Default: <span
612 class="cmtt-9">DISTRO</span><span
613 class="cmtt-9">_FEED</span><span
614 class="cmtt-9">_PREFIX = "remote"</span>
615 <!--l. 363--><p class="noindent" >
616 <h5 class="subsubsectionHead"><span class="titlemark">5.4.2 </span> <a
617 id="x1-270005.4.2"></a>DISTRO_FEED_URI</h5>
618 <!--l. 365--><p class="noindent" ><span
619 class="cmtt-9">DISTRO</span><span
620 class="cmtt-9">_FEED</span><span
621 class="cmtt-9">_URI </span>specifies the URI of the package update feed.
622 <!--l. 367--><p class="noindent" >Default: <span
623 class="cmtt-9">DISTRO</span><span
624 class="cmtt-9">_FEED</span><span
625 class="cmtt-9">_URI = "http://my-distribution.example/remote-feed/"</span>
626 <!--l. 369--><p class="noindent" >
627 <h5 class="subsubsectionHead"><span class="titlemark">5.4.3 </span> <a
628 id="x1-280005.4.3"></a>INHERIT</h5>
629 <!--l. 371--><p class="noindent" ><span
630 class="cmtt-9">INHERIT </span>specifies bbclasses to include from a configuration file. Usually, this variable
631 gets appended to by using the <span
632 class="cmtt-9">+= </span>operator.
633 <!--l. 374--><p class="noindent" >The OpenDreambox distribution automatically appends <span
634 class="cmtt-9">"buildhistory recipe</span><span
635 class="cmtt-9">_sanity"</span>
637 class="cmtt-9">INHERIT</span>.
638 <!--l. 376--><p class="noindent" >Default: <span
639 class="cmtt-9">INHERIT = ""</span>
640 <!--l. 378--><p class="noindent" ><span
641 class="cmbx-10">Some examples:</span>
642 <!--l. 380--><p class="noindent" >Always build the latest versions of OpenDreambox-related projects from
644 <!--l. 382--><p class="noindent" ><span
645 class="cmtt-9">INHERIT += "opendreambox-autorev"</span>
649 <!--l. 384--><p class="noindent" >Remove temporary files of previous versions of a recipe before a newer version gets
651 <!--l. 386--><p class="noindent" ><span
652 class="cmtt-9">INHERIT += "rm</span><span
653 class="cmtt-9">_old</span><span
654 class="cmtt-9">_work"</span>
655 <!--l. 388--><p class="noindent" >
656 <h4 class="subsectionHead"><span class="titlemark">5.5 </span> <a
657 id="x1-290005.5"></a>Setting up a build directory</h4>
658 <!--l. 389--><p class="noindent" >To set up a build directory for e.g. <span
659 class="cmbx-10">DM 7020 HD </span>run <span
660 class="cmtt-9">make MACHINE=dm7020hd</span>. If
662 class="cmtt-9">MACHINE=dm7020hd </span>has been set in <span
663 class="cmtt-9">conf/make.conf </span>(default), you can simply run
665 class="cmtt-9">make </span>with no arguments instead. This will create and initialize the directory
667 class="cmtt-9">build/dm7020hd</span>.
668 <!--l. 393--><p class="noindent" >
669 <h4 class="subsectionHead"><span class="titlemark">5.6 </span> <a
670 id="x1-300005.6"></a>Building a firmware image</h4>
671 <!--l. 394--><p class="noindent" >To build a firmware image for e.g. <span
672 class="cmbx-10">DM 7020 HD </span>run <span
673 class="cmtt-9">make MACHINE=dm7020hd image</span>.
675 class="cmtt-9">MACHINE=dm7020hd </span>has been set in <span
676 class="cmtt-9">conf/make.conf </span>(default), you can simply run
678 class="cmtt-9">make image </span>instead.
679 <!--l. 398--><p class="noindent" >
680 <h4 class="subsectionHead"><span class="titlemark">5.7 </span> <a
681 id="x1-310005.7"></a>Building a package</h4>
682 <!--l. 399--><p class="noindent" >To build a single package, BitBake has to be used directly. First, the environment has
683 to be set up, in order to make BitBake available to the shell. This can be done with
684 the following command:
685 <!--l. 403--><p class="noindent" ><span
686 class="cmtt-9">source bitbake.env</span>
687 <!--l. 405--><p class="noindent" >BitBake must be run from the machine’s build directory. For <span
688 class="cmbx-10">DM 7020 HD</span>
690 <!--l. 407--><p class="noindent" ><span
691 class="cmtt-9">cd build/dm7020hd</span>
692 <!--l. 409--><p class="noindent" >In order to build enigma2, run:
693 <!--l. 411--><p class="noindent" ><span
694 class="cmtt-9">bitbake enigma2</span>.
695 <!--l. 413--><p class="noindent" >
696 <h3 class="sectionHead"><span class="titlemark">6 </span> <a
697 id="x1-320006"></a>Development hints</h3>
701 <!--l. 415--><p class="noindent" >
702 <h4 class="subsectionHead"><span class="titlemark">6.1 </span> <a
703 id="x1-330006.1"></a>Cross-compilation of external software</h4>
704 <!--l. 416--><p class="noindent" >OpenDreambox provides a script called <span
705 class="cmtt-9">cross-compile.env</span>. Once run, the script will
706 create the following commands (shell aliases), aiming to ease cross-compilation of
707 external source trees:
708 <ul class="itemize1">
709 <li class="itemize"><span
710 class="cmtt-9">oe</span><span
711 class="cmtt-9">_autoreconf </span>- Calls OE’s version of <span
712 class="cmtt-9">autoreconf</span>. Useful for projects based
715 <li class="itemize"><span
716 class="cmtt-9">oe</span><span
717 class="cmtt-9">_runconf </span>- Calls <span
718 class="cmtt-9">./configure </span>with parameters suitable for OE. Useful
719 for projects based on GNU autotools.
721 <li class="itemize"><span
722 class="cmtt-9">oe</span><span
723 class="cmtt-9">_runmake </span>- Calls <span
724 class="cmtt-9">make </span>with parameters suitable for OE. Useful for
725 projects based on GNU autotools or GNU make.
727 <li class="itemize"><span
728 class="cmtt-9">oe</span><span
729 class="cmtt-9">_env </span>- Useful to execute arbitrary commands in the OE environment
731 class="cmtt-9">oe</span><span
732 class="cmtt-9">_env env</span>).
734 <li class="itemize"><span
735 class="cmtt-9">oe</span><span
736 class="cmtt-9">_setenv </span>- Exports the OE environment to the currently running shell
738 <!--l. 427--><p class="noindent" >The script needs to know the target machine, which can be one of the supported
740 href="#x1-40001.2">1.2<!--tex4ht:ref: products --></a>). Because the script adds aliases to your currently running shell
741 session, it has to be invoked using <span
742 class="cmtt-9">source </span>or <span
743 class="cmtt-9">. </span>(the dot operator), e.g.:
744 <!--l. 430--><p class="noindent" ><span
745 class="cmtt-9">source cross-compile.env dm7020hd</span>
746 <!--l. 432--><p class="noindent" >The script may be called from any location, but must reside inside the OpenDreambox
747 Git tree. You may want to create a symlink to <span
748 class="cmtt-9">cross-compile.env </span>somewhere in your
750 class="cmtt-9">PATH</span>.
751 <!--l. 435--><p class="noindent" >
752 <h4 class="subsectionHead"><span class="titlemark">6.2 </span> <a
753 id="x1-340006.2"></a>Coding style</h4>
754 <!--l. 436--><p class="noindent" >Run <span
755 class="cmtt-9">scripts/do</span><span
756 class="cmtt-9">_stylize.sh </span>on new recipes to ensure proper coding style.
757 <!--l. 438--><p class="noindent" >
758 <h4 class="subsectionHead"><span class="titlemark">6.3 </span> <a
759 id="x1-350006.3"></a>Package architecture</h4>
760 <!--l. 439--><p class="noindent" >Set <span
761 class="cmtt-9">PACKAGE</span><span
762 class="cmtt-9">_ARCH = "$</span><span
763 class="cmsy-9">{</span><span
764 class="cmtt-9">MACHINE</span><span
765 class="cmtt-9">_ARCH</span><span
766 class="cmsy-9">}</span><span
767 class="cmtt-9">" </span>if either condition is met:
771 <ul class="itemize1">
772 <li class="itemize">The recipe uses <span
773 class="cmtt-9">COMBINED</span><span
774 class="cmtt-9">_FEATURES</span>, <span
775 class="cmtt-9">MACHINE</span><span
776 class="cmtt-9">_FEATURES </span>or
778 class="cmtt-9">DREAMBOX</span><span
779 class="cmtt-9">_FEATURES</span>.
781 <li class="itemize">The recipe is part of <span
782 class="cmtt-9">meta-bsp</span>.</li></ul>
783 <!--l. 445--><p class="noindent" >
784 <h3 class="sectionHead"><span class="titlemark">7 </span> <a
785 id="x1-360007"></a>Bug reports and patches</h3>
786 <!--l. 447--><p class="noindent" >Please send bug reports and patches to the Enigma2 development mailing list
788 class="cmtt-9"><enigma2-devel@lists.elitedvb.net></span>.
789 <!--l. 449--><p class="noindent" >A comfortable way to create patches is to use <span
790 class="cmtt-9">git format-patch</span>, after all changes
791 have been committed to your local copy of the repository.