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="2016-12-07 10:48: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">December 2016</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-dreambox</a></span>
53 <br /><span class="sectionToc" >2 <a
54 href="#x1-120002" id="QQ2-1-12">Further readings</a></span>
55 <br /><span class="sectionToc" >3 <a
56 href="#x1-130003" id="QQ2-1-13">Prerequisites</a></span>
57 <br /> <span class="subsectionToc" >3.1 <a
58 href="#x1-140003.1" id="QQ2-1-14">Required software</a></span>
59 <br /><span class="sectionToc" >4 <a
60 href="#x1-150004" id="QQ2-1-15">Major changes since previous public releases</a></span>
61 <br /> <span class="subsectionToc" >4.1 <a
62 href="#x1-160004.1" id="QQ2-1-16">Changes since release 1.6</a></span>
63 <br /> <span class="subsectionToc" >4.2 <a
64 href="#x1-170004.2" id="QQ2-1-17">Changes since release 2.0</a></span>
65 <br /> <span class="subsectionToc" >4.3 <a
66 href="#x1-180004.3" id="QQ2-1-18">Changes since release 2.2</a></span>
70 <br /><span class="sectionToc" >5 <a
71 href="#x1-190005" id="QQ2-1-19">Known Issues</a></span>
72 <br /><span class="sectionToc" >6 <a
73 href="#x1-200006" id="QQ2-1-20">Building OpenDreambox</a></span>
74 <br /> <span class="subsectionToc" >6.1 <a
75 href="#x1-210006.1" id="QQ2-1-21">Makefile targets</a></span>
76 <br /> <span class="subsectionToc" >6.2 <a
77 href="#x1-220006.2" id="QQ2-1-22">Configuration variables</a></span>
78 <br />  <span class="subsubsectionToc" >6.2.1 <a
79 href="#x1-230006.2.1" id="QQ2-1-23">BB_NUMBER_THREADS</a></span>
80 <br />  <span class="subsubsectionToc" >6.2.2 <a
81 href="#x1-240006.2.2" id="QQ2-1-24">MACHINE</a></span>
82 <br />  <span class="subsubsectionToc" >6.2.3 <a
83 href="#x1-250006.2.3" id="QQ2-1-25">PARALLEL_MAKE</a></span>
84 <br /> <span class="subsectionToc" >6.3 <a
85 href="#x1-260006.3" id="QQ2-1-26">Adding custom layers</a></span>
86 <br /> <span class="subsectionToc" >6.4 <a
87 href="#x1-270006.4" id="QQ2-1-27">Adding custom options</a></span>
88 <br />  <span class="subsubsectionToc" >6.4.1 <a
89 href="#x1-280006.4.1" id="QQ2-1-28">DISTRO_FEED_PREFIX</a></span>
90 <br />  <span class="subsubsectionToc" >6.4.2 <a
91 href="#x1-290006.4.2" id="QQ2-1-29">DISTRO_FEED_URI</a></span>
92 <br />  <span class="subsubsectionToc" >6.4.3 <a
93 href="#x1-300006.4.3" id="QQ2-1-30">INHERIT</a></span>
94 <br /> <span class="subsectionToc" >6.5 <a
95 href="#x1-310006.5" id="QQ2-1-31">Setting up a build directory</a></span>
96 <br /> <span class="subsectionToc" >6.6 <a
97 href="#x1-320006.6" id="QQ2-1-32">Building a firmware image</a></span>
98 <br /> <span class="subsectionToc" >6.7 <a
99 href="#x1-330006.7" id="QQ2-1-33">Building a package</a></span>
100 <br /><span class="sectionToc" >7 <a
101 href="#x1-340007" id="QQ2-1-34">Development hints</a></span>
102 <br /> <span class="subsectionToc" >7.1 <a
103 href="#x1-350007.1" id="QQ2-1-35">Cross-compilation of external software</a></span>
104 <br /> <span class="subsectionToc" >7.2 <a
105 href="#x1-360007.2" id="QQ2-1-36">Coding style</a></span>
106 <br /> <span class="subsectionToc" >7.3 <a
107 href="#x1-370007.3" id="QQ2-1-37">Package architecture</a></span>
108 <br /><span class="sectionToc" >8 <a
109 href="#x1-380008" id="QQ2-1-38">Bug reports and patches</a></span>
114 <!--l. 54--><p class="noindent" >
115 <h3 class="sectionHead"><span class="titlemark">1 </span> <a
116 id="x1-20001"></a>Introduction</h3>
117 <div class="flushleft"
119 <!--l. 55--><p class="noindent" >
120 This document briefly describes the OpenDreambox distribution, an
121 embedded Linux distribution for Set-Top-Boxes manufactured by <a
122 href="https://dreambox.de/" >Dream
124 <!--l. 59--><p class="noindent" >OpenDreambox is based on the <a
125 href="http://www.openembedded.org/" >OpenEmbedded</a> build framework, which uses
126 BitBake to transform build instructions into distributable firmare images and
128 <!--l. 63--><p class="noindent" >The current version, OpenDreambox 2.5, is based on the <a
129 href="https://www.yoctoproject.org/" >Yocto Project</a>, release
130 2.1 ”Krogoth”, an umbrella project for OpenEmbedded and related tools.</div>
131 <!--l. 67--><p class="noindent" >
132 <h4 class="subsectionHead"><span class="titlemark">1.1 </span> <a
133 id="x1-30001.1"></a>Target audience</h4>
134 <div class="flushleft"
136 <!--l. 68--><p class="noindent" >
137 Developers familiar with previous versions of OpenDreambox or
138 OpenEmbedded in general.</div>
139 <!--l. 73--><p class="noindent" >
140 <h4 class="subsectionHead"><span class="titlemark">1.2 </span> <a
141 id="x1-40001.2"></a>Supported products</h4>
142 <div class="flushleft"
144 <!--l. 75--><p class="noindent" >
145 The current version includes support for the following products:
149 <div class="tabular"> <table id="TBL-2" class="tabular"
150 cellspacing="0" cellpadding="0" rules="groups"
151 ><colgroup id="TBL-2-1g"><col
152 id="TBL-2-1"></colgroup><colgroup id="TBL-2-2g"><col
153 id="TBL-2-2"></colgroup><tr
154 class="hline"><td><hr></td><td><hr></td></tr><tr
155 style="vertical-align:baseline;" id="TBL-2-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-1"
157 class="cmbx-10">Product name </span></td><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-2"
159 class="cmbx-10">Environment variable</span></td></tr><tr
160 class="hline"><td><hr></td><td><hr></td></tr><tr
161 style="vertical-align:baseline;" id="TBL-2-2-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-1"
162 class="td11"> </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-2"
165 style="vertical-align:baseline;" id="TBL-2-3-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-1"
166 class="td11">DM900 ultraHD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-2"
168 class="cmtt-9">MACHINE=dm900 </span></td>
170 style="vertical-align:baseline;" id="TBL-2-4-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-1"
171 class="td11">DM525 COMBO </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-2"
173 class="cmtt-9">MACHINE=dm520 </span></td>
175 style="vertical-align:baseline;" id="TBL-2-5-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-1"
176 class="td11">DM525 S2 CI slot </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-2"
178 class="cmtt-9">MACHINE=dm520 </span></td>
180 style="vertical-align:baseline;" id="TBL-2-6-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-6-1"
181 class="td11">DM525 C/T2 CI slot</td><td style="white-space:nowrap; text-align:left;" id="TBL-2-6-2"
183 class="cmtt-9">MACHINE=dm520 </span></td>
185 style="vertical-align:baseline;" id="TBL-2-7-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-7-1"
186 class="td11">DM520 S2 </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-7-2"
188 class="cmtt-9">MACHINE=dm520 </span></td>
190 style="vertical-align:baseline;" id="TBL-2-8-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-8-1"
191 class="td11">DM520 C/T2 </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-8-2"
193 class="cmtt-9">MACHINE=dm520 </span></td>
195 style="vertical-align:baseline;" id="TBL-2-9-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-9-1"
196 class="td11">DM7080 HD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-9-2"
198 class="cmtt-9">MACHINE=dm7080 </span></td>
200 style="vertical-align:baseline;" id="TBL-2-10-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-10-1"
201 class="td11">DM820 HD </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-10-2"
203 class="cmtt-9">MACHINE=dm820 </span></td>
205 style="vertical-align:baseline;" id="TBL-2-11-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-11-1"
206 class="td11"> </td><td style="white-space:nowrap; text-align:left;" id="TBL-2-11-2"
209 class="hline"><td><hr></td><td><hr></td></tr><tr
210 style="vertical-align:baseline;" id="TBL-2-12-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-12-1"
212 </tr></table></div></div>
213 <!--l. 95--><p class="noindent" >
214 <h4 class="subsectionHead"><span class="titlemark">1.3 </span> <a
215 id="x1-50001.3"></a>License</h4>
219 <div class="verbatim" id="verbatim-1">
220 Copyright (c) 2016 Dream Property GmbH, Germany
221  <br />                   https://dreambox.de/
223  <br />Permission is hereby granted, free of charge, to any person obtaining a copy
224  <br />of this software and associated documentation files (the "Software"), to deal
225  <br />in the Software without restriction, including without limitation the rights
226  <br />to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
227  <br />copies of the Software, and to permit persons to whom the Software is
228  <br />furnished to do so, subject to the following conditions:
230  <br />The above copyright notice and this permission notice shall be included in
231  <br />all copies or substantial portions of the Software.
233  <br />THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
234  <br />IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
235  <br />FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
236  <br />AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
237  <br />LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
238  <br />OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
239  <br />THE SOFTWARE.
240  <br />    </div>
241 <!--l. 118--><p class="nopar" >
242 <!--l. 120--><p class="noindent" >
243 <h4 class="subsectionHead"><span class="titlemark">1.4 </span> <a
244 id="x1-60001.4"></a>Obtaining the source code</h4>
245 <!--l. 121--><p class="noindent" >OpenDreambox uses the Git version control system. To obtain the source code, it is
246 required to install Git. See <a
247 href="http://git-scm.com/" class="url" ><span
248 class="cmtt-10">http://git-_scm.com/</span></a>.
249 <!--l. 124--><p class="noindent" >To initially download the source into the current directory, issue the following
251 <!--l. 127--><p class="noindent" ><span
252 class="cmtt-9">git clone -b krogoth git://git.opendreambox.org/git/opendreambox.git</span>
253 <!--l. 129--><p class="noindent" >The Git repository can be viewed online at:
254 <!--l. 131--><p class="noindent" ><a
255 href="http://git.opendreambox.org/?p=opendreambox.git" class="url" ><span
256 class="cmtt-10">http://git.opendreambox.org/?p=opendreambox.git</span></a>
257 <!--l. 133--><p class="noindent" >
258 <h4 class="subsectionHead"><span class="titlemark">1.5 </span> <a
259 id="x1-70001.5"></a>Quick start</h4>
260 <!--l. 134--><p class="noindent" >For the impatient:
264 <!--l. 136--><p class="noindent" ><span
265 class="cmtt-9">make -C opendreambox image</span>
266 <!--l. 138--><p class="noindent" >If this command fails, prerequisites may be missing. See section <a
267 href="#x1-130003">3<!--tex4ht:ref: prerequisites --></a>.
268 <!--l. 140--><p class="noindent" >
269 <h4 class="subsectionHead"><span class="titlemark">1.6 </span> <a
270 id="x1-80001.6"></a>Directory structure</h4>
271 <!--l. 141--><p class="noindent" >OpenDreambox consists of a set of layers containing build instructions. This meta
272 data is used by BitBake to download and compile source code and to assemble
273 installable software packages and firmware images.
274 <!--l. 145--><p class="noindent" >Currently, these layers are used:
275 <ul class="itemize1">
276 <li class="itemize"><span
277 class="cmtt-9">meta-dreambox</span>
279 <li class="itemize"><span
280 class="cmtt-9">meta-opendreambox</span>
282 <li class="itemize"><span
283 class="cmtt-9">meta-openembedded/meta-filesystems</span>
285 <li class="itemize"><span
286 class="cmtt-9">meta-openembedded/meta-multimedia</span>
288 <li class="itemize"><span
289 class="cmtt-9">meta-openembedded/meta-networking</span>
291 <li class="itemize"><span
292 class="cmtt-9">meta-openembedded/meta-oe</span>
294 <li class="itemize"><span
295 class="cmtt-9">meta-openembedded/meta-python</span>
297 <li class="itemize"><span
298 class="cmtt-9">meta-openembedded/meta-ruby</span>
300 <li class="itemize"><span
301 class="cmtt-9">meta-openembedded/meta-webserver</span>
303 <li class="itemize"><span
304 class="cmtt-9">meta-qt5</span>
306 <li class="itemize"><span
307 class="cmtt-9">openembedded-core/meta</span></li></ul>
308 <!--l. 161--><p class="noindent" >If a recipe for the same package exists in multiple layers, then the higher priority
309 layer takes precedence over the lower priority layer.
310 <!--l. 165--><p class="noindent" >For example, if <span
311 class="cmtt-9">libmad</span><span
312 class="cmtt-9">_0.15.1b.bb </span>existed in both <span
313 class="cmtt-9">meta-openembedded </span>and
315 class="cmtt-9">openembedded-core</span>, the recipe in <span
316 class="cmtt-9">meta-openembedded </span>would be used, because
318 class="cmtt-9">openembedded-core </span>has lower priority. Priority values are determined by the variable
320 class="cmtt-9">BBFILE</span><span
321 class="cmtt-9">_PRIORITY </span>in <span
322 class="cmtt-9">conf/layer.conf </span>of each layer.
326 <!--l. 171--><p class="noindent" ><span
327 class="cmbx-10">NOTE: </span>This would still be true even if the version of <span
328 class="cmtt-9">libmad </span>in <span
329 class="cmtt-9">openembeded-core</span>
330 was higher than the version in <span
331 class="cmtt-9">meta-openembedded</span>, unless <span
332 class="cmtt-9">PREFERRED</span><span
333 class="cmtt-9">_VERSION</span><span
334 class="cmtt-9">_libmad</span>
335 was set to the version in <span
336 class="cmtt-9">openembedded-core</span>. There is currently no way to prefer a
337 version of a lower priority layer, if the same version is present in a higher priority
339 <!--l. 177--><p class="noindent" >
340 <h5 class="subsubsectionHead"><span class="titlemark">1.6.1 </span> <a
341 id="x1-90001.6.1"></a>openembedded-core and meta-openembedded</h5>
342 <!--l. 178--><p class="noindent" >These directories contain copies of Git repositories from git.openembedded.org,
343 including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers.
344 They get created automatically when building the distribution for the first
346 <!--l. 182--><p class="noindent" >Throughout this document, the combination of these directories will be referred to as
348 <!--l. 185--><p class="noindent" >The latest changes to these Git repositories can be seen at:
349 <!--l. 187--><p class="noindent" ><a
350 href="http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/krogoth" class="url" ><span
351 class="cmtt-10">http://git.openembedded.org/openembedded-_core-_contrib/log/?h=obi/krogoth</span></a>
352 <!--l. 189--><p class="noindent" ><a
353 href="http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/krogoth" class="url" ><span
354 class="cmtt-10">http://git.openembedded.org/meta-_openembedded-_contrib/log/?h=obi/krogoth</span></a>
355 <!--l. 191--><p class="noindent" >
356 <h5 class="subsubsectionHead"><span class="titlemark">1.6.2 </span> <a
357 id="x1-100001.6.2"></a>meta-opendreambox</h5>
358 <!--l. 192--><p class="noindent" >This directory contains:
359 <ul class="itemize1">
360 <li class="itemize">Recipes for packages written specifically for the OpenDreambox
363 <li class="itemize">Modifications to recipes from OpenEmbedded
365 <li class="itemize">Recipes for software versions older than those available from
368 <li class="itemize">Recipes for software versions newer than those available from
369 OpenEmbedded</li></ul>
373 <!--l. 201--><p class="noindent" >
374 <h5 class="subsubsectionHead"><span class="titlemark">1.6.3 </span> <a
375 id="x1-110001.6.3"></a>meta-dreambox</h5>
376 <!--l. 202--><p class="noindent" >The directory <span
377 class="cmtt-9">meta-dreambox </span>contains Board Support Packages (BSP) for the
378 supported Dreambox models. This includes:
379 <ul class="itemize1">
380 <li class="itemize">Hardware drivers
382 <li class="itemize">Machine specific overrides
384 <li class="itemize">The Linux kernel
386 <li class="itemize">The boot loader
388 <li class="itemize">Splash images</li></ul>
389 <!--l. 213--><p class="noindent" >
390 <h3 class="sectionHead"><span class="titlemark">2 </span> <a
391 id="x1-120002"></a>Further readings</h3>
392 <ul class="itemize1">
393 <li class="itemize">The Yocto Project Reference Manual: <a
394 href="https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html" class="url" ><span
395 class="cmtt-10">https://www.yoctoproject.org/docs/2.1/ref-_manual/ref-_manual.html</span></a></li></ul>
396 <!--l. 219--><p class="noindent" >
397 <h3 class="sectionHead"><span class="titlemark">3 </span> <a
398 id="x1-130003"></a>Prerequisites</h3>
399 <!--l. 222--><p class="noindent" >
400 <h4 class="subsectionHead"><span class="titlemark">3.1 </span> <a
401 id="x1-140003.1"></a>Required software</h4>
402 <!--l. 224--><p class="noindent" >The OpenEmbedded project provides a general list of prerequisites for many Linux
403 distributions and also for some other operating systems.
404 <ul class="itemize1">
405 <li class="itemize"><a
406 href="http://www.openembedded.org/wiki/Getting\_started#Required\_software" class="url" ><span
407 class="cmtt-10">http://www.openembedded.org/wiki/Getting\_started#Required\_software</span></a></li></ul>
411 <!--l. 231--><p class="noindent" >It is highly recommended to use Linux to build OpenDreambox. In theory, any recent
412 distribution will do, but not many distributions have been verified to build
413 OpenDreambox without errors. Tested distributions include:
414 <ul class="itemize1">
415 <li class="itemize">Debian 8.6 ”Jessie” [amd64]
417 <li class="itemize">Ubuntu 16.04.1 LTS ”Xenial Xerus” [amd64]</li></ul>
421 <!--l. 243--><p class="noindent" >
422 <h3 class="sectionHead"><span class="titlemark">4 </span> <a
423 id="x1-150004"></a>Major changes since previous public releases</h3>
424 <!--l. 245--><p class="noindent" >
425 <h4 class="subsectionHead"><span class="titlemark">4.1 </span> <a
426 id="x1-160004.1"></a>Changes since release 1.6</h4>
427 <ul class="itemize1">
428 <li class="itemize">Recipes were split across multiple layers and categorized.
430 <li class="itemize"><span
431 class="cmtt-9">env.source </span>has been replaced by two files, <span
432 class="cmtt-9">bitbake.env </span>and
434 class="cmtt-9">cross-compile.env</span>. The former sets a minimal environment that is needed
435 to execute bitbake. The latter creates machine-specific command aliases,
436 in order to compile external software.
438 <li class="itemize">All machines share a common <span
439 class="cmtt-9">tmp </span>directory.
441 <li class="itemize"><span
442 class="cmtt-9">$</span><span
443 class="cmsy-9">{</span><span
444 class="cmtt-9">MACHINE</span><span
445 class="cmsy-9">}</span><span
446 class="cmtt-9">/build </span>directories were renamed to <span
447 class="cmtt-9">build/$</span><span
448 class="cmsy-9">{</span><span
449 class="cmtt-9">MACHINE</span><span
450 class="cmsy-9">}</span>.
452 <li class="itemize">Kernel packages were renamed from <span
453 class="cmtt-9">linux-$</span><span
454 class="cmsy-9">{</span><span
455 class="cmtt-9">MACHINE</span><span
456 class="cmsy-9">} </span>to <span
457 class="cmtt-9">linux-dreambox</span>.
459 <li class="itemize">Support for machines based on ATI Xilleon or IBM STB was dropped.</li></ul>
460 <!--l. 258--><p class="noindent" >
461 <h4 class="subsectionHead"><span class="titlemark">4.2 </span> <a
462 id="x1-170004.2"></a>Changes since release 2.0</h4>
463 <ul class="itemize1">
464 <li class="itemize">Added support for DM520, DM525, DM820 and DM7080.
466 <li class="itemize">If a recipe changes, the corresponding packages will be rebuilt
467 automatically, in contrast to required manual PR bumps in the past.
469 <li class="itemize">Each machine uses its own tmp directory again, like before 2.0. However,
470 there is a shared <span
471 class="cmtt-9">sstate-cache</span>, which allows to share already compiled
472 data between compatible machines. This impacts performance and size of
473 the build system, but improves reliability and consistency across builds.
478 <li class="itemize">Support for machines without FPU and kernel versions below 3.x was
481 <li class="itemize">Layers under meta-bsp were combined into meta-dreambox.
483 <li class="itemize">Default package format switched from ipk (opkg) to deb (dpkg + apt).
485 <li class="itemize"><span
486 class="cmtt-9">dreambox-image </span>was renamed to include the package format
488 class="cmtt-9">dreambox-image-deb</span>).</li></ul>
489 <!--l. 273--><p class="noindent" >
490 <h4 class="subsectionHead"><span class="titlemark">4.3 </span> <a
491 id="x1-180004.3"></a>Changes since release 2.2</h4>
492 <ul class="itemize1">
493 <li class="itemize">Added support for DM900.
495 <li class="itemize">Machines with low memory were dropped (DM500HD, DM800SE).
497 <li class="itemize">Switched from Qt4 to Qt5.</li></ul>
498 <!--l. 280--><p class="noindent" >
499 <h3 class="sectionHead"><span class="titlemark">5 </span> <a
500 id="x1-190005"></a>Known Issues</h3>
501 <ul class="itemize1">
502 <li class="itemize">Unsupported machines present in meta-dreambox (DM500HDv2,
503 DM800SEv2, DM7020HD, DM7020HDv2, DM8000) are known not to
504 work unless booted with a kernel of release 1.6, which however shows
505 incompatibilities with systemd. Additionally, there appear to be problems
506 rendering the user interface.</li></ul>
510 <!--l. 291--><p class="noindent" >
511 <h3 class="sectionHead"><span class="titlemark">6 </span> <a
512 id="x1-200006"></a>Building OpenDreambox</h3>
513 <!--l. 293--><p class="noindent" >In the top level directory, there is a <span
514 class="cmtt-9">Makefile</span>, which is used to set up build
515 directories and to fetch or update all used repositories. The Makefile can
516 be influenced by environment variables, either by specifing them on the
517 command-line or by storing them in a file called <span
518 class="cmtt-9">conf/make.conf</span>. It is not
519 recommended to edit the <span
520 class="cmtt-9">Makefile </span>directly in order to avoid conflicts with future
522 <!--l. 300--><p class="noindent" >When the <span
523 class="cmtt-9">Makefile </span>is run for the first time, the following steps will be executed:
524 <ul class="itemize1">
525 <li class="itemize">Creation of configuration files
526 <ul class="itemize2">
527 <li class="itemize"><span
528 class="cmtt-9">bitbake.env</span>
530 <li class="itemize"><span
531 class="cmtt-9">conf/opendreambox.conf</span>
533 <li class="itemize"><span
534 class="cmtt-9">build/$</span><span
535 class="cmsy-9">{</span><span
536 class="cmtt-9">MACHINE</span><span
537 class="cmsy-9">}</span><span
538 class="cmtt-9">/conf/bblayers.conf</span>
540 <li class="itemize"><span
541 class="cmtt-9">build/$</span><span
542 class="cmsy-9">{</span><span
543 class="cmtt-9">MACHINE</span><span
544 class="cmsy-9">}</span><span
545 class="cmtt-9">/conf/local.conf</span></li></ul>
547 <li class="itemize">Update or checkout of Git repositories
548 <ul class="itemize2">
549 <li class="itemize">OpenDreambox
551 <li class="itemize">BitBake
553 <li class="itemize">OpenEmbedded</li></ul>
555 <!--l. 319--><p class="noindent" >
556 <h4 class="subsectionHead"><span class="titlemark">6.1 </span> <a
557 id="x1-210006.1"></a>Makefile targets</h4>
558 <!--l. 320--><p class="noindent" >Run <span
559 class="cmtt-9">make help </span>to get a list of targets of the top level Makefile, together with a brief
564 <!--l. 322--><p class="noindent" >
565 <h4 class="subsectionHead"><span class="titlemark">6.2 </span> <a
566 id="x1-220006.2"></a>Configuration variables</h4>
567 <!--l. 323--><p class="noindent" >
568 <h5 class="subsubsectionHead"><span class="titlemark">6.2.1 </span> <a
569 id="x1-230006.2.1"></a>BB_NUMBER_THREADS</h5>
570 <!--l. 324--><p class="noindent" >Controls how many BitBake tasks may run at a time. Defaults to the number of cores
571 available on the build system.
572 <!--l. 327--><p class="noindent" >
573 <h5 class="subsubsectionHead"><span class="titlemark">6.2.2 </span> <a
574 id="x1-240006.2.2"></a>MACHINE</h5>
575 <!--l. 328--><p class="noindent" >Controls the target machine to build packages for. See section <a
576 href="#x1-40001.2">1.2<!--tex4ht:ref: products --></a> for a list of
578 <!--l. 331--><p class="noindent" >
579 <h5 class="subsubsectionHead"><span class="titlemark">6.2.3 </span> <a
580 id="x1-250006.2.3"></a>PARALLEL_MAKE</h5>
581 <!--l. 332--><p class="noindent" >Controls how many processes per recipe <span
582 class="cmtt-9">make </span>may use. Defaults to the number of
583 cores available on the build system.
584 <!--l. 335--><p class="noindent" >
585 <h4 class="subsectionHead"><span class="titlemark">6.3 </span> <a
586 id="x1-260006.3"></a>Adding custom layers</h4>
587 <!--l. 337--><p class="noindent" >It is possible to add custom layers to the build system. This can be done globally and
588 per machine. To add a layer globally, edit <span
589 class="cmtt-9">conf/bblayers-ext.conf</span>. To add a
590 machine-specific layer, edit <span
591 class="cmtt-9">conf/bblayers-$</span><span
592 class="cmsy-9">{</span><span
593 class="cmtt-9">MACHINE</span><span
594 class="cmsy-9">}</span><span
595 class="cmtt-9">-ext.conf</span>. Assuming that an
596 additional layer is available at <span
597 class="cmtt-9">$</span><span
598 class="cmsy-9">{</span><span
599 class="cmtt-9">HOME</span><span
600 class="cmsy-9">}</span><span
601 class="cmtt-9">/custom-layer</span>, the entry to add to the file will
603 <!--l. 343--><p class="noindent" ><span
604 class="cmtt-9">BBLAYERS =+ "$</span><span
605 class="cmsy-9">{</span><span
606 class="cmtt-9">HOME</span><span
607 class="cmsy-9">}</span><span
608 class="cmtt-9">/custom-layer"</span>
609 <!--l. 345--><p class="noindent" >
610 <h4 class="subsectionHead"><span class="titlemark">6.4 </span> <a
611 id="x1-270006.4"></a>Adding custom options</h4>
612 <!--l. 346--><p class="noindent" >It is possible to tweak a lot more options than those used by the <span
613 class="cmtt-9">Makefile </span>by editing
615 class="cmtt-9">conf/local-ext.conf </span>or <span
616 class="cmtt-9">conf/local-$</span><span
617 class="cmsy-9">{</span><span
618 class="cmtt-9">MACHINE</span><span
619 class="cmsy-9">}</span><span
620 class="cmtt-9">-ext.conf</span>.
624 <!--l. 349--><p class="noindent" >For example, if the firmware shall use the package feed built on the develoment
625 machine, which happens to be 192.168.1.1 and has a webserver configured to point to
627 class="cmtt-9">tmp/deploy/ipk</span>, a line like the following may be added:
628 <!--l. 353--><p class="noindent" ><span
629 class="cmtt-9">DISTRO</span><span
630 class="cmtt-9">_FEED</span><span
631 class="cmtt-9">_URI = "http://192.168.1.1/$</span><span
632 class="cmsy-9">{</span><span
633 class="cmtt-9">DISTRO</span><span
634 class="cmsy-9">}</span><span
635 class="cmtt-9">/$</span><span
636 class="cmsy-9">{</span><span
637 class="cmtt-9">DISTRO</span><span
638 class="cmtt-9">_VERSION</span><span
639 class="cmsy-9">}</span><span
640 class="cmtt-9">"</span>
641 <!--l. 355--><p class="noindent" >In general, any variable in OpenEmbedded that uses weak assignment (<span
642 class="cmtt-9">?=</span>) may be
643 overridden from these files.
644 <!--l. 358--><p class="noindent" >The following sections list some commonly used options.
645 <!--l. 360--><p class="noindent" >
646 <h5 class="subsubsectionHead"><span class="titlemark">6.4.1 </span> <a
647 id="x1-280006.4.1"></a>DISTRO_FEED_PREFIX</h5>
648 <!--l. 362--><p class="noindent" ><span
649 class="cmtt-9">DISTRO</span><span
650 class="cmtt-9">_FEED</span><span
651 class="cmtt-9">_PREFIX </span>specifies the name of the package update feed. This name may be
653 <!--l. 365--><p class="noindent" >Default: <span
654 class="cmtt-9">DISTRO</span><span
655 class="cmtt-9">_FEED</span><span
656 class="cmtt-9">_PREFIX = "remote"</span>
657 <!--l. 367--><p class="noindent" >
658 <h5 class="subsubsectionHead"><span class="titlemark">6.4.2 </span> <a
659 id="x1-290006.4.2"></a>DISTRO_FEED_URI</h5>
660 <!--l. 369--><p class="noindent" ><span
661 class="cmtt-9">DISTRO</span><span
662 class="cmtt-9">_FEED</span><span
663 class="cmtt-9">_URI </span>specifies the URI of the package update feed.
664 <!--l. 371--><p class="noindent" >Default: <span
665 class="cmtt-9">DISTRO</span><span
666 class="cmtt-9">_FEED</span><span
667 class="cmtt-9">_URI = "http://my-distribution.example/remote-feed/"</span>
668 <!--l. 373--><p class="noindent" >
669 <h5 class="subsubsectionHead"><span class="titlemark">6.4.3 </span> <a
670 id="x1-300006.4.3"></a>INHERIT</h5>
671 <!--l. 375--><p class="noindent" ><span
672 class="cmtt-9">INHERIT </span>specifies bbclasses to include from a configuration file. Usually, this variable
673 gets appended to by using the <span
674 class="cmtt-9">+= </span>operator.
675 <!--l. 378--><p class="noindent" >The OpenDreambox distribution automatically appends <span
676 class="cmtt-9">"buildhistory recipe</span><span
677 class="cmtt-9">_sanity"</span>
679 class="cmtt-9">INHERIT</span>.
680 <!--l. 380--><p class="noindent" >Default: <span
681 class="cmtt-9">INHERIT = ""</span>
682 <!--l. 382--><p class="noindent" ><span
683 class="cmbx-10">Some examples:</span>
684 <!--l. 384--><p class="noindent" >Always build the latest versions of OpenDreambox-related projects from
686 <!--l. 386--><p class="noindent" ><span
687 class="cmtt-9">INHERIT += "opendreambox-autorev"</span>
691 <!--l. 388--><p class="noindent" >
692 <h4 class="subsectionHead"><span class="titlemark">6.5 </span> <a
693 id="x1-310006.5"></a>Setting up a build directory</h4>
694 <!--l. 389--><p class="noindent" >To set up a build directory for e.g. <span
695 class="cmbx-10">DM 7080 </span>run <span
696 class="cmtt-9">make MACHINE=dm7080</span>. If
698 class="cmtt-9">MACHINE=dm7080 </span>has been set in <span
699 class="cmtt-9">conf/make.conf </span>(default: dm900), you can simply run
701 class="cmtt-9">make </span>with no arguments instead. This will create and initialize the directory
703 class="cmtt-9">build/dm7080</span>.
704 <!--l. 393--><p class="noindent" >
705 <h4 class="subsectionHead"><span class="titlemark">6.6 </span> <a
706 id="x1-320006.6"></a>Building a firmware image</h4>
707 <!--l. 394--><p class="noindent" >To build a firmware image for e.g. <span
708 class="cmbx-10">DM 7080 </span>run <span
709 class="cmtt-9">make MACHINE=dm7080 image</span>. If
711 class="cmtt-9">MACHINE=dm7080 </span>has been set in <span
712 class="cmtt-9">conf/make.conf </span>(default: dm900), you can simply run
714 class="cmtt-9">make image </span>instead.
715 <!--l. 398--><p class="noindent" >
716 <h4 class="subsectionHead"><span class="titlemark">6.7 </span> <a
717 id="x1-330006.7"></a>Building a package</h4>
718 <!--l. 399--><p class="noindent" >To build a single package, BitBake has to be used directly. First, the environment has
719 to be set up, in order to make BitBake available to the shell. This can be done with
720 the following command:
721 <!--l. 403--><p class="noindent" ><span
722 class="cmtt-9">source bitbake.env</span>
723 <!--l. 405--><p class="noindent" >BitBake must be run from the machine’s build directory. For <span
724 class="cmbx-10">DM 7080</span>
726 <!--l. 407--><p class="noindent" ><span
727 class="cmtt-9">cd build/dm7080</span>
728 <!--l. 409--><p class="noindent" >In order to build enigma2, run:
729 <!--l. 411--><p class="noindent" ><span
730 class="cmtt-9">bitbake enigma2</span>.
731 <!--l. 413--><p class="noindent" >
732 <h3 class="sectionHead"><span class="titlemark">7 </span> <a
733 id="x1-340007"></a>Development hints</h3>
734 <!--l. 415--><p class="noindent" >
735 <h4 class="subsectionHead"><span class="titlemark">7.1 </span> <a
736 id="x1-350007.1"></a>Cross-compilation of external software</h4>
737 <!--l. 416--><p class="noindent" >OpenDreambox provides a script called <span
738 class="cmtt-9">cross-compile.env</span>. Once run, the script will
739 create the following commands (shell aliases), aiming to ease cross-compilation of
740 external source trees:
744 <ul class="itemize1">
745 <li class="itemize"><span
746 class="cmtt-9">oe</span><span
747 class="cmtt-9">_autoreconf </span>- Calls OE’s version of <span
748 class="cmtt-9">autoreconf</span>. Useful for projects based
751 <li class="itemize"><span
752 class="cmtt-9">oe</span><span
753 class="cmtt-9">_runconf </span>- Calls <span
754 class="cmtt-9">./configure </span>with parameters suitable for OE. Useful
755 for projects based on GNU autotools.
757 <li class="itemize"><span
758 class="cmtt-9">oe</span><span
759 class="cmtt-9">_runmake </span>- Calls <span
760 class="cmtt-9">make </span>with parameters suitable for OE. Useful for
761 projects based on GNU autotools or GNU make.
763 <li class="itemize"><span
764 class="cmtt-9">oe</span><span
765 class="cmtt-9">_env </span>- Useful to execute arbitrary commands in the OE environment
767 class="cmtt-9">oe</span><span
768 class="cmtt-9">_env env</span>).
770 <li class="itemize"><span
771 class="cmtt-9">oe</span><span
772 class="cmtt-9">_setenv </span>- Exports the OE environment to the currently running shell
774 <!--l. 427--><p class="noindent" >The script needs to know the target machine, which can be one of the supported
776 href="#x1-40001.2">1.2<!--tex4ht:ref: products --></a>). Because the script adds aliases to your currently running shell
777 session, it has to be invoked using <span
778 class="cmtt-9">source </span>or <span
779 class="cmtt-9">. </span>(the dot operator), e.g.:
780 <!--l. 430--><p class="noindent" ><span
781 class="cmtt-9">source cross-compile.env dm7080</span>
782 <!--l. 432--><p class="noindent" >The script may be called from any location, but must reside inside the OpenDreambox
783 Git tree. You may want to create a symlink to <span
784 class="cmtt-9">cross-compile.env </span>somewhere in your
786 class="cmtt-9">PATH</span>.
787 <!--l. 435--><p class="noindent" >
788 <h4 class="subsectionHead"><span class="titlemark">7.2 </span> <a
789 id="x1-360007.2"></a>Coding style</h4>
790 <!--l. 436--><p class="noindent" >Run <span
791 class="cmtt-9">scripts/do</span><span
792 class="cmtt-9">_stylize.sh </span>on new recipes to ensure proper coding style.
793 <!--l. 438--><p class="noindent" >
794 <h4 class="subsectionHead"><span class="titlemark">7.3 </span> <a
795 id="x1-370007.3"></a>Package architecture</h4>
796 <!--l. 439--><p class="noindent" >Set <span
797 class="cmtt-9">PACKAGE</span><span
798 class="cmtt-9">_ARCH = "$</span><span
799 class="cmsy-9">{</span><span
800 class="cmtt-9">MACHINE</span><span
801 class="cmtt-9">_ARCH</span><span
802 class="cmsy-9">}</span><span
803 class="cmtt-9">" </span>if either condition is met:
804 <ul class="itemize1">
805 <li class="itemize">The recipe uses <span
806 class="cmtt-9">COMBINED</span><span
807 class="cmtt-9">_FEATURES</span>, <span
808 class="cmtt-9">MACHINE</span><span
809 class="cmtt-9">_FEATURES </span>or
811 class="cmtt-9">DREAMBOX</span><span
812 class="cmtt-9">_FEATURES</span>.
814 <li class="itemize">The recipe uses <span
815 class="cmtt-9">COMPATIBLE</span><span
816 class="cmtt-9">_MACHINE</span>.
821 <li class="itemize">The recipe is part of <span
822 class="cmtt-9">meta-dreambox</span>.</li></ul>
823 <!--l. 446--><p class="noindent" >
824 <h3 class="sectionHead"><span class="titlemark">8 </span> <a
825 id="x1-380008"></a>Bug reports and patches</h3>
826 <!--l. 448--><p class="noindent" >Please send bug reports to <a
827 href="mailto:bugs@opendreambox.org" ><span
828 class="cmbx-10">bugs@opendreambox.org</span></a> and patches to
830 href="mailto:patches@opendreambox.org" ><span
831 class="cmbx-10">patches@opendreambox.org</span></a>.
832 <!--l. 450--><p class="noindent" >A comfortable way to create patches is to use <span
833 class="cmtt-9">git format-patch</span>, after all changes
834 have been committed to your local copy of the repository.