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