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-10-17 17:24: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 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="sectionToc" >4 <a
62 href="#x1-160004" id="QQ2-1-16">Known Issues</a></span>
63 <br /><span class="sectionToc" >5 <a
64 href="#x1-170005" id="QQ2-1-17">Building OpenDreambox</a></span>
65 <br /> <span class="subsectionToc" >5.1 <a
66 href="#x1-180005.1" id="QQ2-1-18">Makefile targets</a></span>
70 <br /> <span class="subsectionToc" >5.2 <a
71 href="#x1-190005.2" id="QQ2-1-19">Configuration variables</a></span>
72 <br />  <span class="subsubsectionToc" >5.2.1 <a
73 href="#x1-200005.2.1" id="QQ2-1-20">BB_NUMBER_THREADS</a></span>
74 <br />  <span class="subsubsectionToc" >5.2.2 <a
75 href="#x1-210005.2.2" id="QQ2-1-21">MACHINE</a></span>
76 <br />  <span class="subsubsectionToc" >5.2.3 <a
77 href="#x1-220005.2.3" id="QQ2-1-22">PARALLEL_MAKE</a></span>
78 <br /> <span class="subsectionToc" >5.3 <a
79 href="#x1-230005.3" id="QQ2-1-23">Adding custom layers</a></span>
80 <br /> <span class="subsectionToc" >5.4 <a
81 href="#x1-240005.4" id="QQ2-1-24">Adding custom options</a></span>
82 <br />  <span class="subsubsectionToc" >5.4.1 <a
83 href="#x1-250005.4.1" id="QQ2-1-25">DISTRO_FEED_PREFIX</a></span>
84 <br />  <span class="subsubsectionToc" >5.4.2 <a
85 href="#x1-260005.4.2" id="QQ2-1-26">DISTRO_FEED_URI</a></span>
86 <br />  <span class="subsubsectionToc" >5.4.3 <a
87 href="#x1-270005.4.3" id="QQ2-1-27">INHERIT</a></span>
88 <br /> <span class="subsectionToc" >5.5 <a
89 href="#x1-280005.5" id="QQ2-1-28">Setting up a build directory</a></span>
90 <br /> <span class="subsectionToc" >5.6 <a
91 href="#x1-290005.6" id="QQ2-1-29">Building a firmware image</a></span>
92 <br /> <span class="subsectionToc" >5.7 <a
93 href="#x1-300005.7" id="QQ2-1-30">Building a package</a></span>
94 <br /><span class="sectionToc" >6 <a
95 href="#x1-310006" id="QQ2-1-31">Development hints</a></span>
96 <br /> <span class="subsectionToc" >6.1 <a
97 href="#x1-320006.1" id="QQ2-1-32">Cross-compilation of external software</a></span>
98 <br /> <span class="subsectionToc" >6.2 <a
99 href="#x1-330006.2" id="QQ2-1-33">Coding style</a></span>
100 <br /> <span class="subsectionToc" >6.3 <a
101 href="#x1-340006.3" id="QQ2-1-34">Package architecture</a></span>
102 <br /><span class="sectionToc" >7 <a
103 href="#x1-350007" id="QQ2-1-35">Bug reports and patches</a></span>
108 <!--l. 54--><p class="noindent" >
109 <h3 class="sectionHead"><span class="titlemark">1 </span> <a
110 id="x1-20001"></a>Introduction</h3>
111 <div class="flushleft"
113 <!--l. 55--><p class="noindent" >
114 This document briefly describes the OpenDreambox distribution, an
115 embedded Linux distribution for Set-Top-Boxes manufactured by <a
116 href="http://www.dream-multimedia-tv.de/" >Dream
118 <!--l. 59--><p class="noindent" >OpenDreambox is based on the <a
119 href="http://www.openembedded.org/" >OpenEmbedded</a> build framework, which uses
121 href="http://bitbake.berlios.de/" >BitBake</a> to transform build instructions into distributable firmare images and
123 <!--l. 63--><p class="noindent" >The current version, OpenDreambox 2.0, is based on OpenEmbedded ”denzil”.</div>
124 <!--l. 66--><p class="noindent" >
125 <h4 class="subsectionHead"><span class="titlemark">1.1 </span> <a
126 id="x1-30001.1"></a>Target audience</h4>
127 <div class="flushleft"
129 <!--l. 67--><p class="noindent" >
130 Developers familiar with previous versions of OpenDreambox or
131 OpenEmbedded in general.</div>
132 <!--l. 72--><p class="noindent" >
133 <h4 class="subsectionHead"><span class="titlemark">1.2 </span> <a
134 id="x1-40001.2"></a>Supported products</h4>
135 <div class="flushleft"
137 <!--l. 74--><p class="noindent" >
138 The current version includes support for the following machines:
139 <div class="tabular"> <table id="TBL-2" class="tabular"
140 cellspacing="0" cellpadding="0" rules="groups"
141 ><colgroup id="TBL-2-1g"><col
142 id="TBL-2-1"></colgroup><colgroup id="TBL-2-2g"><col
143 id="TBL-2-2"></colgroup><tr
144 class="hline"><td><hr></td><td><hr></td></tr><tr
145 style="vertical-align:baseline;" id="TBL-2-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-1"
147 class="cmbx-10">Product name </span></td><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-2"
149 class="cmbx-10">Environment variable</span></td></tr><tr
150 class="hline"><td><hr></td><td><hr></td></tr><tr
151 style="vertical-align:baseline;" id="TBL-2-2-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-1"
152 class="td11"> </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-2"
155 style="vertical-align:baseline;" id="TBL-2-3-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-1"
156 class="td11">DM 500 HD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-2"
158 class="cmtt-9">MACHINE=dm500hd </span></td>
160 style="vertical-align:baseline;" id="TBL-2-4-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-1"
161 class="td11">DM 800 HD PVR </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-2"
163 class="cmtt-9">MACHINE=dm800 </span></td>
165 style="vertical-align:baseline;" id="TBL-2-5-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-1"
166 class="td11">DM 800 HD SE </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-2"
168 class="cmtt-9">MACHINE=dm800se </span></td>
170 style="vertical-align:baseline;" id="TBL-2-6-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-6-1"
171 class="td11">DM 7020 HD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-6-2"
173 class="cmtt-9">MACHINE=dm7020hd </span></td>
175 style="vertical-align:baseline;" id="TBL-2-7-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-7-1"
176 class="td11">DM 8000 HD PVR</td><td style="white-space:nowrap; text-align:left;" id="TBL-2-7-2"
178 class="cmtt-9">MACHINE=dm8000 </span></td>
180 style="vertical-align:baseline;" id="TBL-2-8-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-8-1"
181 class="td11"> </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-8-2"
184 class="hline"><td><hr></td><td><hr></td></tr><tr
185 style="vertical-align:baseline;" id="TBL-2-9-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-9-1"
187 </tr></table></div></div>
191 <!--l. 91--><p class="noindent" >
192 <h4 class="subsectionHead"><span class="titlemark">1.3 </span> <a
193 id="x1-50001.3"></a>License</h4>
197 <div class="verbatim" id="verbatim-1">
198 Copyright (c) 2010-2013 Dream Multimedia GmbH, Germany
199  <br />                        http://www.dream-multimedia-tv.de/
200  <br />Authors:
201  <br />  Andreas Frisch <fraxinas@opendreambox.org>
202  <br />  Andreas Monzner <ghost@opendreambox.org>
203  <br />  Andreas Oberritter <obi@opendreambox.org>
204  <br />  Mladen Horvat <acid-burn@opendreambox.org>
205  <br />  Stefan Pluecken <thedoc@opendreambox.org>
206  <br />  Stephan Reichholf <reichi@opendreambox.org>
208  <br />Permission is hereby granted, free of charge, to any person obtaining a copy
209  <br />of this software and associated documentation files (the "Software"), to deal
210  <br />in the Software without restriction, including without limitation the rights
211  <br />to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
212  <br />copies of the Software, and to permit persons to whom the Software is
213  <br />furnished to do so, subject to the following conditions:
215  <br />The above copyright notice and this permission notice shall be included in
216  <br />all copies or substantial portions of the Software.
218  <br />THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
219  <br />IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
220  <br />FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
221  <br />AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
222  <br />LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
223  <br />OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
224  <br />THE SOFTWARE.
225  <br />    </div>
226 <!--l. 121--><p class="nopar" >
227 <!--l. 123--><p class="noindent" >
228 <h4 class="subsectionHead"><span class="titlemark">1.4 </span> <a
229 id="x1-60001.4"></a>Obtaining the source code</h4>
230 <!--l. 124--><p class="noindent" >OpenDreambox uses the Git version control system. To obtain the source code, it is
231 required to install Git. See <a
232 href="http://git-scm.com/" class="url" ><span
233 class="cmtt-10">http://git-scm.com/</span></a>.
234 <!--l. 127--><p class="noindent" >To initially download the source into the current directory, issue the following
236 <!--l. 130--><p class="noindent" ><span
237 class="cmtt-9">git clone -b denzil git://git.opendreambox.org/git/opendreambox.git</span>
238 <!--l. 132--><p class="noindent" >The Git repository can be viewed online at:
239 <!--l. 134--><p class="noindent" ><a
240 href="http://cgit.opendreambox.org/opendreambox.git" class="url" ><span
241 class="cmtt-10">http://cgit.opendreambox.org/opendreambox.git</span></a>
245 <!--l. 136--><p class="noindent" >
246 <h4 class="subsectionHead"><span class="titlemark">1.5 </span> <a
247 id="x1-70001.5"></a>Quick start</h4>
248 <!--l. 137--><p class="noindent" >For the impatient:
249 <!--l. 139--><p class="noindent" ><span
250 class="cmtt-9">make -C opendreambox image</span>
251 <!--l. 141--><p class="noindent" >If this command fails, prerequisites my be missing. See section <a
252 href="#x1-120002">2<!--tex4ht:ref: prerequisites --></a>.
253 <!--l. 143--><p class="noindent" >
254 <h4 class="subsectionHead"><span class="titlemark">1.6 </span> <a
255 id="x1-80001.6"></a>Directory structure</h4>
256 <!--l. 144--><p class="noindent" >OpenDreambox consists of a set of layers containing build instructions. This meta
257 data is used by BitBake to download and compile source code and to assemble
258 installable software packages and firmware images.
259 <!--l. 148--><p class="noindent" >Currently, there are five layers, ordered by priority from lowest to highest:
260 <ul class="itemize1">
261 <li class="itemize"><span
262 class="cmtt-9">openembedded-core</span>
264 <li class="itemize"><span
265 class="cmtt-9">meta-openembedded</span>
267 <li class="itemize"><span
268 class="cmtt-9">meta-opendreambox</span>
270 <li class="itemize"><span
271 class="cmtt-9">meta-bsp/common</span>
273 <li class="itemize"><span
274 class="cmtt-9">meta-bsp/$</span><span
275 class="cmsy-9">{</span><span
276 class="cmtt-9">MACHINE</span><span
277 class="cmsy-9">}</span></li></ul>
278 <!--l. 159--><p class="noindent" >If a recipe for the same package exists in multiple layers, then the higher priority
279 layer takes precedence over the lower priority layer.
280 <!--l. 163--><p class="noindent" >For example, <span
281 class="cmtt-9">libmad</span><span
282 class="cmtt-9">_0.15.1b.bb </span>exists in both <span
283 class="cmtt-9">meta-openembedded </span>and
285 class="cmtt-9">openembedded-core</span>. The recipe in <span
286 class="cmtt-9">meta-openembedded </span>will be used, because
288 class="cmtt-9">openembedded-core </span>has lower priority.
289 <!--l. 168--><p class="noindent" ><span
290 class="cmbx-10">NOTE: </span>This would still be true even if the version of <span
291 class="cmtt-9">libmad </span>in <span
292 class="cmtt-9">openembeded-core</span>
293 was higher than the version in <span
294 class="cmtt-9">meta-openembedded</span>, unless <span
295 class="cmtt-9">PREFERRED</span><span
296 class="cmtt-9">_VERSION</span><span
297 class="cmtt-9">_libmad</span>
298 was set to the version in <span
299 class="cmtt-9">openembedded-core</span>. There is currently no way to prefer a
300 version of a lower priority layer, if the same version is present in a higher priority
305 <!--l. 174--><p class="noindent" >
306 <h5 class="subsubsectionHead"><span class="titlemark">1.6.1 </span> <a
307 id="x1-90001.6.1"></a>openembedded-core and meta-openembedded</h5>
308 <!--l. 175--><p class="noindent" >These directories contain copies of Git repositories from git.openembedded.org,
309 including the OpenEmbedded-Core layer (”meta”) and the OpenEmbedded layer
310 (”meta-oe”). They get created automatically when building the distribution for the
312 <!--l. 179--><p class="noindent" >Throughout this document, the combination of these directories will be referred to as
314 <!--l. 182--><p class="noindent" >The latest changes to these Git repositories can be seen at:
315 <!--l. 184--><p class="noindent" ><a
316 href="http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/current" class="url" ><span
317 class="cmtt-10">http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/current</span></a>
318 <!--l. 186--><p class="noindent" ><a
319 href="http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/current" class="url" ><span
320 class="cmtt-10">http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/current</span></a>
321 <!--l. 188--><p class="noindent" >
322 <h5 class="subsubsectionHead"><span class="titlemark">1.6.2 </span> <a
323 id="x1-100001.6.2"></a>meta-opendreambox</h5>
324 <!--l. 189--><p class="noindent" >This directory contains:
325 <ul class="itemize1">
326 <li class="itemize">Recipes for packages written specifically for the OpenDreambox
329 <li class="itemize">Modifications to recipes from OpenEmbedded
331 <li class="itemize">Recipes for software versions older than those available from
334 <li class="itemize">Recipes for software versions newer than those available from
335 OpenEmbedded</li></ul>
336 <!--l. 198--><p class="noindent" >
337 <h5 class="subsubsectionHead"><span class="titlemark">1.6.3 </span> <a
338 id="x1-110001.6.3"></a>meta-bsp</h5>
339 <!--l. 199--><p class="noindent" >The directory <span
340 class="cmtt-9">meta-bsp </span>contains Board Support Packages (BSP) for the supported
341 Dreambox models. This includes:
342 <ul class="itemize1">
343 <li class="itemize">Hardware drivers
348 <li class="itemize">Machine specific overrides
350 <li class="itemize">The Linux kernel
352 <li class="itemize">The boot loader
354 <li class="itemize">Splash images</li></ul>
355 <!--l. 210--><p class="noindent" >
356 <h3 class="sectionHead"><span class="titlemark">2 </span> <a
357 id="x1-120002"></a>Prerequisites</h3>
358 <!--l. 213--><p class="noindent" >
359 <h4 class="subsectionHead"><span class="titlemark">2.1 </span> <a
360 id="x1-130002.1"></a>Required software</h4>
361 <!--l. 215--><p class="noindent" >The OpenEmbedded project provides a general list of prerequisites for many Linux
362 distributions and also for some other operating systems.
363 <ul class="itemize1">
364 <li class="itemize"><a
365 href="http://www.openembedded.org/index.php/OEandYourDistro" class="url" ><span
366 class="cmtt-10">http://www.openembedded.org/index.php/OEandYourDistro</span></a>
368 <li class="itemize"><a
369 href="http://www.openembedded.org/index.php/Required\_software" class="url" ><span
370 class="cmtt-10">http://www.openembedded.org/index.php/Required\_software</span></a></li></ul>
371 <!--l. 223--><p class="noindent" >It is highly recommended to use Linux to build OpenDreambox. In theory, any recent
372 distribution will do, but not many distributions have been verified to build
373 OpenDreambox without errors. Tested distributions include:
374 <ul class="itemize1">
375 <li class="itemize">Arch Linux 2011.08.19 [amd64]
377 <li class="itemize">Debian 6.0 (Squeeze) [i386]
379 <li class="itemize">Debian ”Testing” (Wheezy) [i386]
381 <li class="itemize">Fedora 16 [i386, amd64]
383 <li class="itemize">Ubuntu 10.04 LTS (Lucid Lynx) [i386]
388 <li class="itemize">Ubuntu 11.10 (Oneiric Ocelot) [amd64]
390 <li class="itemize">Ubuntu 12.04 LTS (Precise Pangolin) [i386, amd64]</li></ul>
391 <!--l. 238--><p class="noindent" >Distributions known not to work:
392 <ul class="itemize1">
393 <li class="itemize">Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.</li></ul>
397 <!--l. 246--><p class="noindent" >
398 <h3 class="sectionHead"><span class="titlemark">3 </span> <a
399 id="x1-140003"></a>Major changes since previous releases</h3>
400 <!--l. 248--><p class="noindent" >
401 <h4 class="subsectionHead"><span class="titlemark">3.1 </span> <a
402 id="x1-150003.1"></a>Changes since release 1.6</h4>
403 <ul class="itemize1">
404 <li class="itemize">Recipes were split across multiple layers and categorized.
406 <li class="itemize"><span
407 class="cmtt-9">env.source </span>has been replaced by two files, <span
408 class="cmtt-9">bitbake.env </span>and
410 class="cmtt-9">cross-compile.env</span>. The former sets a minimal environment that is needed
411 to execute bitbake. The latter creates machine-specific command aliases,
412 in order to compile external software.
414 <li class="itemize">All machines share a common <span
415 class="cmtt-9">tmp </span>directory.
417 <li class="itemize"><span
418 class="cmtt-9">$</span><span
419 class="cmsy-9">{</span><span
420 class="cmtt-9">MACHINE</span><span
421 class="cmsy-9">}</span><span
422 class="cmtt-9">/build </span>directories were renamed to <span
423 class="cmtt-9">build/$</span><span
424 class="cmsy-9">{</span><span
425 class="cmtt-9">MACHINE</span><span
426 class="cmsy-9">}</span>.
428 <li class="itemize">Kernel packages were renamed from <span
429 class="cmtt-9">linux-$</span><span
430 class="cmsy-9">{</span><span
431 class="cmtt-9">MACHINE</span><span
432 class="cmsy-9">} </span>to <span
433 class="cmtt-9">linux-dreambox</span>.
435 <li class="itemize">Support for machines based on ATI Xilleon or IBM STB was dropped.</li></ul>
436 <!--l. 261--><p class="noindent" >
437 <h3 class="sectionHead"><span class="titlemark">4 </span> <a
438 id="x1-160004"></a>Known Issues</h3>
439 <ul class="itemize1">
440 <li class="itemize"><span
441 class="cmbx-10">Problem: </span>Building on eCryptfs fails, because it doesn’t support
442 sufficiently long filenames (<a
443 href="https://bugs.launchpad.net/ecryptfs/+bug/344878" >eCryptfs bug #344878</a>). <span
444 class="cmbx-10">Solution: </span>Choose a
445 different filesystem.
447 <li class="itemize"><span
448 class="cmbx-10">Problem: </span>When switching between machines after the gcc recipe was
449 updated, gcc-cross-initial, gcc-cross-intermediate and gcc-cross may fail to
450 build with the following error message:
454 <!--l. 269--><p class="noindent" ><span
455 class="cmtt-9">configure: error: changes in</span>
457 class="cmtt-9">the environment can compromise the build configure: error: run ‘make</span>
459 class="cmtt-9">distclean’ and/or ‘rm ./config.cache’ and start over</span>
460 <!--l. 272--><p class="noindent" ><span
461 class="cmbx-10">Solution: </span><span
462 class="cmtt-9">bitbake -ccleansstate gcc-cross-initial</span>
464 class="cmtt-9">gcc-cross-intermediate gcc-cross</span>
469 <!--l. 278--><p class="noindent" >
470 <h3 class="sectionHead"><span class="titlemark">5 </span> <a
471 id="x1-170005"></a>Building OpenDreambox</h3>
472 <!--l. 280--><p class="noindent" >In the top level directory, there is a <span
473 class="cmtt-9">Makefile</span>, which is used to set up build
474 directories and to fetch or update all used repositories. The Makefile can
475 be influenced by environment variables, either by specifing them on the
476 command-line or by storing them in a file called <span
477 class="cmtt-9">conf/make.conf</span>. It is not
478 recommended to edit the <span
479 class="cmtt-9">Makefile </span>directly in order to avoid conflicts with future
481 <!--l. 287--><p class="noindent" >When the <span
482 class="cmtt-9">Makefile </span>is run for the first time, the following steps will be executed:
483 <ul class="itemize1">
484 <li class="itemize">Creation of configuration files
485 <ul class="itemize2">
486 <li class="itemize"><span
487 class="cmtt-9">bitbake.env</span>
489 <li class="itemize"><span
490 class="cmtt-9">conf/opendreambox.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/bblayers.conf</span>
499 <li class="itemize"><span
500 class="cmtt-9">build/$</span><span
501 class="cmsy-9">{</span><span
502 class="cmtt-9">MACHINE</span><span
503 class="cmsy-9">}</span><span
504 class="cmtt-9">/conf/local.conf</span></li></ul>
506 <li class="itemize">Update or checkout of Git repositories
507 <ul class="itemize2">
508 <li class="itemize">OpenDreambox
510 <li class="itemize">BitBake
512 <li class="itemize">OpenEmbedded</li></ul>
514 <!--l. 306--><p class="noindent" >
515 <h4 class="subsectionHead"><span class="titlemark">5.1 </span> <a
516 id="x1-180005.1"></a>Makefile targets</h4>
517 <!--l. 307--><p class="noindent" >Run <span
518 class="cmtt-9">make help </span>to get a list of targets of the top level Makefile, together with a brief
523 <!--l. 309--><p class="noindent" >
524 <h4 class="subsectionHead"><span class="titlemark">5.2 </span> <a
525 id="x1-190005.2"></a>Configuration variables</h4>
526 <!--l. 310--><p class="noindent" >
527 <h5 class="subsubsectionHead"><span class="titlemark">5.2.1 </span> <a
528 id="x1-200005.2.1"></a>BB_NUMBER_THREADS</h5>
529 <!--l. 311--><p class="noindent" >Controls how many BitBake tasks may run at a time. Defaults to the number of cores
530 available on the build system. The number of cores is obtained from <span
531 class="cmtt-9">/proc/cpuinfo</span>. If
532 this file is unavailable, the default value is 1.
533 <!--l. 316--><p class="noindent" >
534 <h5 class="subsubsectionHead"><span class="titlemark">5.2.2 </span> <a
535 id="x1-210005.2.2"></a>MACHINE</h5>
536 <!--l. 317--><p class="noindent" >Controls the target machine to build packages for. See section <a
537 href="#x1-40001.2">1.2<!--tex4ht:ref: products --></a> for a list of
539 <!--l. 320--><p class="noindent" >
540 <h5 class="subsubsectionHead"><span class="titlemark">5.2.3 </span> <a
541 id="x1-220005.2.3"></a>PARALLEL_MAKE</h5>
542 <!--l. 321--><p class="noindent" >Controls how many processes per recipe <span
543 class="cmtt-9">make </span>may use. Defaults to the number of
544 cores available on the build system. The number of cores is obtained from
546 class="cmtt-9">/proc/cpuinfo</span>. If this file is unavailable, the default value is 1.
547 <!--l. 326--><p class="noindent" >NOTE: If you see seemingly random build failures, try setting this variable to
549 <!--l. 328--><p class="noindent" >
550 <h4 class="subsectionHead"><span class="titlemark">5.3 </span> <a
551 id="x1-230005.3"></a>Adding custom layers</h4>
552 <!--l. 330--><p class="noindent" >It is possible to add custom layers to the build system. This can be done globally and
553 per machine. To add a layer globally, edit <span
554 class="cmtt-9">conf/bblayers-ext.conf</span>. To add a
555 machine-specific layer, edit <span
556 class="cmtt-9">conf/bblayers-$</span><span
557 class="cmsy-9">{</span><span
558 class="cmtt-9">MACHINE</span><span
559 class="cmsy-9">}</span><span
560 class="cmtt-9">-ext.conf</span>. Assuming that an
561 additional layer is available at <span
562 class="cmtt-9">$</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>, the entry to add to the file will
568 <!--l. 336--><p class="noindent" ><span
569 class="cmtt-9">BBLAYERS =+ "$</span><span
570 class="cmsy-9">{</span><span
571 class="cmtt-9">HOME</span><span
572 class="cmsy-9">}</span><span
573 class="cmtt-9">/custom-layer"</span>
577 <!--l. 338--><p class="noindent" >
578 <h4 class="subsectionHead"><span class="titlemark">5.4 </span> <a
579 id="x1-240005.4"></a>Adding custom options</h4>
580 <!--l. 339--><p class="noindent" >It is possible to tweak a lot more options than those used by the <span
581 class="cmtt-9">Makefile </span>by editing
583 class="cmtt-9">conf/local-ext.conf </span>or <span
584 class="cmtt-9">conf/local-$</span><span
585 class="cmsy-9">{</span><span
586 class="cmtt-9">MACHINE</span><span
587 class="cmsy-9">}</span><span
588 class="cmtt-9">-ext.conf</span>.
589 <!--l. 342--><p class="noindent" >For example, if the firmware shall use the package feed built on the develoment
590 machine, which happens to be 192.168.1.1 and has a webserver configured to point to
592 class="cmtt-9">tmp/deploy/ipk</span>, a line like the following may be added:
593 <!--l. 346--><p class="noindent" ><span
594 class="cmtt-9">DISTRO</span><span
595 class="cmtt-9">_FEED</span><span
596 class="cmtt-9">_URI = "http://192.168.1.1/$</span><span
597 class="cmsy-9">{</span><span
598 class="cmtt-9">DISTRO</span><span
599 class="cmsy-9">}</span><span
600 class="cmtt-9">/$</span><span
601 class="cmsy-9">{</span><span
602 class="cmtt-9">DISTRO</span><span
603 class="cmtt-9">_VERSION</span><span
604 class="cmsy-9">}</span><span
605 class="cmtt-9">"</span>
606 <!--l. 348--><p class="noindent" >In general, any variable in OpenEmbedded that uses weak assignment (<span
607 class="cmtt-9">?=</span>) may be
608 overridden from these files.
609 <!--l. 351--><p class="noindent" >The following sections list some commonly used options.
610 <!--l. 353--><p class="noindent" >
611 <h5 class="subsubsectionHead"><span class="titlemark">5.4.1 </span> <a
612 id="x1-250005.4.1"></a>DISTRO_FEED_PREFIX</h5>
613 <!--l. 355--><p class="noindent" ><span
614 class="cmtt-9">DISTRO</span><span
615 class="cmtt-9">_FEED</span><span
616 class="cmtt-9">_PREFIX </span>specifies the name of the package update feed. This name may be
618 <!--l. 358--><p class="noindent" >Default: <span
619 class="cmtt-9">DISTRO</span><span
620 class="cmtt-9">_FEED</span><span
621 class="cmtt-9">_PREFIX = "remote"</span>
622 <!--l. 360--><p class="noindent" >
623 <h5 class="subsubsectionHead"><span class="titlemark">5.4.2 </span> <a
624 id="x1-260005.4.2"></a>DISTRO_FEED_URI</h5>
625 <!--l. 362--><p class="noindent" ><span
626 class="cmtt-9">DISTRO</span><span
627 class="cmtt-9">_FEED</span><span
628 class="cmtt-9">_URI </span>specifies the URI of the package update feed.
629 <!--l. 364--><p class="noindent" >Default: <span
630 class="cmtt-9">DISTRO</span><span
631 class="cmtt-9">_FEED</span><span
632 class="cmtt-9">_URI = "http://my-distribution.example/remote-feed/"</span>
633 <!--l. 366--><p class="noindent" >
634 <h5 class="subsubsectionHead"><span class="titlemark">5.4.3 </span> <a
635 id="x1-270005.4.3"></a>INHERIT</h5>
636 <!--l. 368--><p class="noindent" ><span
637 class="cmtt-9">INHERIT </span>specifies bbclasses to include from a configuration file. Usually, this variable
638 gets appended to by using the <span
639 class="cmtt-9">+= </span>operator.
640 <!--l. 371--><p class="noindent" >The OpenDreambox distribution automatically appends <span
641 class="cmtt-9">"buildhistory recipe</span><span
642 class="cmtt-9">_sanity</span>
644 class="cmtt-9">testlab" </span>to <span
645 class="cmtt-9">INHERIT</span>.
646 <!--l. 373--><p class="noindent" >Default: <span
647 class="cmtt-9">INHERIT = ""</span>
648 <!--l. 375--><p class="noindent" ><span
649 class="cmbx-10">Some examples:</span>
650 <!--l. 377--><p class="noindent" >Always build the latest versions of OpenDreambox-related projects from
652 <!--l. 379--><p class="noindent" ><span
653 class="cmtt-9">INHERIT += "opendreambox-autorev"</span>
657 <!--l. 381--><p class="noindent" >Remove temporary files of previous versions of a recipe before a newer version gets
659 <!--l. 383--><p class="noindent" ><span
660 class="cmtt-9">INHERIT += "rm</span><span
661 class="cmtt-9">_old</span><span
662 class="cmtt-9">_work"</span>
663 <!--l. 385--><p class="noindent" >Remove temporary files of a recipe after it has been built and packaged
665 <!--l. 387--><p class="noindent" ><span
666 class="cmtt-9">INHERIT += "rm</span><span
667 class="cmtt-9">_work"</span>
668 <!--l. 389--><p class="noindent" >
669 <h4 class="subsectionHead"><span class="titlemark">5.5 </span> <a
670 id="x1-280005.5"></a>Setting up a build directory</h4>
671 <!--l. 390--><p class="noindent" >To set up a build directory for e.g. <span
672 class="cmbx-10">DM 500 HD </span>run <span
673 class="cmtt-9">make MACHINE=dm500hd</span>. If
675 class="cmtt-9">MACHINE=dm500hd </span>has been set in <span
676 class="cmtt-9">conf/make.conf</span>, you can simply run <span
677 class="cmtt-9">make </span>with no
678 arguments instead. This will create and initialize the directory <span
679 class="cmtt-9">build/dm500hd</span>.
680 <!--l. 394--><p class="noindent" >
681 <h4 class="subsectionHead"><span class="titlemark">5.6 </span> <a
682 id="x1-290005.6"></a>Building a firmware image</h4>
683 <!--l. 395--><p class="noindent" >To build a firmware image for e.g. <span
684 class="cmbx-10">DM 500 HD </span>run <span
685 class="cmtt-9">make MACHINE=dm500hd image</span>. If
687 class="cmtt-9">MACHINE=dm500hd </span>has been set in <span
688 class="cmtt-9">conf/make.conf</span>, you can simply run <span
689 class="cmtt-9">make image</span>
691 <!--l. 399--><p class="noindent" >
692 <h4 class="subsectionHead"><span class="titlemark">5.7 </span> <a
693 id="x1-300005.7"></a>Building a package</h4>
694 <!--l. 400--><p class="noindent" >To build a single package, BitBake has to be used directly. First, the environment has
695 to be set up, in order to make BitBake available to the shell. This can be done with
696 the following command:
697 <!--l. 404--><p class="noindent" ><span
698 class="cmtt-9">source bitbake.env</span>
699 <!--l. 406--><p class="noindent" >BitBake must be run from the machine’s build directory. For <span
700 class="cmbx-10">DM 500 HD</span>
702 <!--l. 408--><p class="noindent" ><span
703 class="cmtt-9">cd build/dm500hd</span>
704 <!--l. 410--><p class="noindent" >In order to build enigma2, run:
705 <!--l. 412--><p class="noindent" ><span
706 class="cmtt-9">bitbake enigma2</span>.
710 <!--l. 414--><p class="noindent" >
711 <h3 class="sectionHead"><span class="titlemark">6 </span> <a
712 id="x1-310006"></a>Development hints</h3>
713 <!--l. 416--><p class="noindent" >
714 <h4 class="subsectionHead"><span class="titlemark">6.1 </span> <a
715 id="x1-320006.1"></a>Cross-compilation of external software</h4>
716 <!--l. 417--><p class="noindent" >OpenDreambox provides a script called <span
717 class="cmtt-9">cross-compile.env</span>. Once run, the script will
718 create the following commands (shell aliases), aiming to ease cross-compilation of
719 external source trees:
720 <ul class="itemize1">
721 <li class="itemize"><span
722 class="cmtt-9">oe</span><span
723 class="cmtt-9">_autoreconf </span>- Calls OE’s version of <span
724 class="cmtt-9">autoreconf</span>. Useful for projects based
727 <li class="itemize"><span
728 class="cmtt-9">oe</span><span
729 class="cmtt-9">_runconf </span>- Calls <span
730 class="cmtt-9">./configure </span>with parameters suitable for OE. Useful
731 for projects based on GNU autotools.
733 <li class="itemize"><span
734 class="cmtt-9">oe</span><span
735 class="cmtt-9">_runmake </span>- Calls <span
736 class="cmtt-9">make </span>with parameters suitable for OE. Useful for
737 projects based on GNU autotools or GNU make.
739 <li class="itemize"><span
740 class="cmtt-9">oe</span><span
741 class="cmtt-9">_env </span>- Useful to execute arbitrary commands in the OE environment
743 class="cmtt-9">oe</span><span
744 class="cmtt-9">_env env</span>).
746 <li class="itemize"><span
747 class="cmtt-9">oe</span><span
748 class="cmtt-9">_setenv </span>- Exports the OE environment to the currently running shell
750 <!--l. 428--><p class="noindent" >The script needs to know the target machine, which can be one of the supported
752 href="#x1-40001.2">1.2<!--tex4ht:ref: products --></a>). Because the script adds aliases to your currently running shell
753 session, it has to be invoked using <span
754 class="cmtt-9">source </span>or <span
755 class="cmtt-9">. </span>(the dot operator), e.g.:
756 <!--l. 431--><p class="noindent" ><span
757 class="cmtt-9">source cross-compile.env dm7020hd</span>
758 <!--l. 433--><p class="noindent" >The script may be called from any location, but must reside inside the OpenDreambox
759 Git tree. You may want to create a symlink to <span
760 class="cmtt-9">cross-compile.env </span>somewhere in your
762 class="cmtt-9">PATH</span>.
763 <!--l. 436--><p class="noindent" >
764 <h4 class="subsectionHead"><span class="titlemark">6.2 </span> <a
765 id="x1-330006.2"></a>Coding style</h4>
766 <!--l. 437--><p class="noindent" >Run <span
767 class="cmtt-9">scripts/do</span><span
768 class="cmtt-9">_stylize.sh </span>on new recipes to ensure proper coding style.
772 <!--l. 439--><p class="noindent" >
773 <h4 class="subsectionHead"><span class="titlemark">6.3 </span> <a
774 id="x1-340006.3"></a>Package architecture</h4>
775 <!--l. 440--><p class="noindent" >Set <span
776 class="cmtt-9">PACKAGE</span><span
777 class="cmtt-9">_ARCH = "$</span><span
778 class="cmsy-9">{</span><span
779 class="cmtt-9">MACHINE</span><span
780 class="cmtt-9">_ARCH</span><span
781 class="cmsy-9">}</span><span
782 class="cmtt-9">" </span>if either condition is met:
783 <ul class="itemize1">
784 <li class="itemize">The recipe uses <span
785 class="cmtt-9">COMBINED</span><span
786 class="cmtt-9">_FEATURES</span>, <span
787 class="cmtt-9">MACHINE</span><span
788 class="cmtt-9">_FEATURES </span>or
790 class="cmtt-9">DREAMBOX</span><span
791 class="cmtt-9">_FEATURES</span>.
793 <li class="itemize">The recipe is part of <span
794 class="cmtt-9">meta-bsp</span>.</li></ul>
795 <!--l. 446--><p class="noindent" >
796 <h3 class="sectionHead"><span class="titlemark">7 </span> <a
797 id="x1-350007"></a>Bug reports and patches</h3>
798 <!--l. 448--><p class="noindent" >Please send bug reports and patches to the Enigma2 development mailing list
800 class="cmtt-9"><enigma2-devel@lists.elitedvb.net></span>.
801 <!--l. 450--><p class="noindent" >A comfortable way to create patches is to use <span
802 class="cmtt-9">git format-patch</span>, after all changes
803 have been committed to your local copy of the repository.