2 % Copyright (c) 2010-2012 Dream Multimedia GmbH, Germany
3 % http://www.dream-multimedia-tv.de/
5 % Andreas Oberritter <obi@opendreambox.org>
7 % Permission is hereby granted, free of charge, to any person obtaining a copy
8 % of this software and associated documentation files (the "Software"), to deal
9 % in the Software without restriction, including without limitation the rights
10 % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 % copies of the Software, and to permit persons to whom the Software is
12 % furnished to do so, subject to the following conditions:
14 % The above copyright notice and this permission notice shall be included in
15 % all copies or substantial portions of the Software.
17 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 % IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 % FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 % AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 % LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
26 \documentclass[a4paper]{article}
39 %\setlength{\textwidth}{12cm}
41 \newcommand{\plaintext}[1]{\texttt{\small #1}}
42 \newcommand{\shell}[1]{\texttt{\small #1}}
46 \author{Andreas Oberritter \shell{<obi@opendreambox.org>}}
49 %\thispagestyle{empty}
54 \section{Introduction}
56 This document briefly describes the OpenDreambox distribution, an embedded Linux
57 distribution for Set-Top-Boxes manufactured by \href{http://www.dream-multimedia-tv.de/}{Dream Multimedia GmbH}.
59 OpenDreambox is based on the \href{http://www.openembedded.org/}{OpenEmbedded} build framework, which
60 uses \href{http://bitbake.berlios.de/}{BitBake} to transform build instructions into
61 distributable firmare images and software packages.
63 The current version, OpenDreambox 2.0, is based on OpenEmbedded "denzil".
66 \subsection{Target audience}
68 Developers familiar with previous versions of OpenDreambox or OpenEmbedded
72 \subsection{Supported products}
75 The current version includes support for the following machines:
77 \begin{tabular}{ | l | l | }
79 \textbf{Product name} & \textbf{Environment variable} \\ \hline
81 DM 500 HD & \shell{MACHINE=dm500hd} \\
82 DM 800 HD PVR & \shell{MACHINE=dm800} \\
83 DM 800 HD SE & \shell{MACHINE=dm800se} \\
84 DM 7020 HD & \shell{MACHINE=dm7020hd} \\
85 DM 8000 HD PVR & \shell{MACHINE=dm8000} \\
94 Copyright (c) 2010-2012 Dream Multimedia GmbH, Germany
95 http://www.dream-multimedia-tv.de/
97 Andreas Frisch <fraxinas@opendreambox.org>
98 Andreas Monzner <ghost@opendreambox.org>
99 Andreas Oberritter <obi@opendreambox.org>
100 Mladen Horvat <acid-burn@opendreambox.org>
101 Stefan Pluecken <thedoc@opendreambox.org>
102 Stephan Reichholf <reichi@opendreambox.org>
104 Permission is hereby granted, free of charge, to any person obtaining a copy
105 of this software and associated documentation files (the "Software"), to deal
106 in the Software without restriction, including without limitation the rights
107 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
108 copies of the Software, and to permit persons to whom the Software is
109 furnished to do so, subject to the following conditions:
111 The above copyright notice and this permission notice shall be included in
112 all copies or substantial portions of the Software.
114 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
115 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
116 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
117 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
118 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
119 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
123 \subsection{Obtaining the source code}
124 OpenDreambox uses the Git version control system. To obtain the source
125 code, it is required to install Git. See \url{http://git-scm.com/}.
127 To initially download the source into the current directory, issue the
130 \shell{git clone -b denzil git://git.opendreambox.org/git/opendreambox.git}
132 The Git repository can be viewed online at:
134 \url{http://cgit.opendreambox.org/opendreambox.git}
136 \subsection{Quick start}
139 \shell{make -C opendreambox image}
141 If this command fails, prerequisites my be missing. See section \ref{prerequisites}.
143 \subsection{Directory structure}
144 OpenDreambox consists of a set of layers containing build instructions.
145 This meta data is used by BitBake to download and compile source code
146 and to assemble installable software packages and firmware images.
148 Currently, there are five layers, ordered by priority from lowest to
152 \item \shell{openembedded-core}
153 \item \shell{meta-openembedded}
154 \item \shell{meta-opendreambox}
155 \item \shell{meta-bsp/common}
156 \item \shell{meta-bsp/\$\{MACHINE\}}
159 If a recipe for the same package exists in multiple layers,
160 then the higher priority layer takes precedence over the lower priority
163 For example, \shell{libmad\_0.15.1b.bb} exists in both
164 \shell{meta-openembedded} and \shell{openembedded-core}. The recipe in
165 \shell{meta-openembedded} will be used, because \shell{openembedded-core}
168 \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
169 \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
170 unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
171 There is currently no way to prefer a version of a lower priority layer, if the
172 same version is present in a higher priority layer.
174 \subsubsection{openembedded-core and meta-openembedded}
175 These directories contain copies of Git repositories from git.openembedded.org, including
176 the OpenEmbedded-Core layer ("meta") and the OpenEmbedded layer ("meta-oe"). They get created
177 automatically when building the distribution for the first time.
179 Throughout this document, the combination of these directories will be
180 referred to as OpenEmbedded.
182 The latest changes to these Git repositories can be seen at:
184 \url{http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/current}
186 \url{http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/current}
188 \subsubsection{meta-opendreambox}
189 This directory contains:
192 \item Recipes for packages written specifically for the OpenDreambox distribution
193 \item Modifications to recipes from OpenEmbedded
194 \item Recipes for software versions older than those available from OpenEmbedded
195 \item Recipes for software versions newer than those available from OpenEmbedded
198 \subsubsection{meta-bsp}
199 The directory \shell{meta-bsp} contains Board Support Packages (BSP)
200 for the supported Dreambox models. This includes:
203 \item Hardware drivers
204 \item Machine specific overrides
205 \item The Linux kernel
206 \item The boot loader
210 \section{Prerequisites}
211 \label{prerequisites}
213 \subsection{Required software}
215 The OpenEmbedded project provides a general list of prerequisites for
216 many Linux distributions and also for some other operating systems.
219 \item \url{http://www.openembedded.org/index.php/OEandYourDistro}
220 \item \url{http://www.openembedded.org/index.php/Required\_software}
223 It is highly recommended to use Linux to build OpenDreambox. In theory,
224 any recent distribution will do, but not many distributions have been
225 verified to build OpenDreambox without errors. Tested distributions
229 \item Arch Linux 2011.08.19 [amd64]
230 \item Debian 6.0 (Squeeze) [i386]
231 \item Debian "Testing" (Wheezy) [i386]
232 \item Fedora 16 [i386, amd64]
233 \item Ubuntu 10.04 LTS (Lucid Lynx) [i386]
234 \item Ubuntu 11.10 (Oneiric Ocelot) [amd64]
235 \item Ubuntu 12.04 LTS (Precise Pangolin) [i386, amd64]
238 Distributions known not to work:
241 \item Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.
246 \section{Major changes since previous releases}
248 \subsection{Changes since release 1.6}
250 \item Recipes were split across multiple layers and categorized.
251 \item \shell{env.source} has been replaced by two files,
252 \shell{bitbake.env} and \shell{cross-compile.env}. The former sets a minimal
253 environment that is needed to execute bitbake. The latter creates
254 machine-specific command aliases, in order to compile external software.
255 \item All machines share a common \shell{tmp} directory.
256 \item \shell{\$\{MACHINE\}/build} directories were renamed to \shell{build/\$\{MACHINE\}}.
257 \item Kernel packages were renamed from \shell{linux-\$\{MACHINE\}} to \shell{linux-dreambox}.
258 \item Support for machines based on ATI Xilleon or IBM STB was dropped.
261 \section{Known Issues}
265 \textbf{Problem:} Building on eCryptfs fails, because it doesn't support sufficiently long filenames (\href{https://bugs.launchpad.net/ecryptfs/+bug/344878}{eCryptfs bug \#344878}).
266 \textbf{Solution:} Choose a different filesystem.
267 \item \textbf{Problem:} When switching between machines after the gcc recipe was updated, gcc-cross-initial, gcc-cross-intermediate and gcc-cross may fail to build with the following error message:
269 \shell{configure: error: changes in the environment can compromise the build}
270 \shell{configure: error: run `make distclean' and/or `rm ./config.cache' and start over}
272 \textbf{Solution:} \shell{bitbake -ccleansstate gcc-cross-initial gcc-cross-intermediate gcc-cross}
278 \section{Building OpenDreambox}
280 In the top level directory, there is a \shell{Makefile}, which is used to
281 set up build directories and to fetch or update all used repositories.
282 The Makefile can be influenced by environment variables, either
283 by specifing them on the command-line or by storing them in a file called
284 \shell{conf/make.conf}. It is not recommended to edit the \shell{Makefile} directly
285 in order to avoid conflicts with future updates.
287 When the \shell{Makefile} is run for the first time, the following steps will
291 \item Creation of configuration files
293 \item \shell{bitbake.env}
294 \item \shell{conf/opendreambox.conf}
295 \item \shell{build/\$\{MACHINE\}/conf/bblayers.conf}
296 \item \shell{build/\$\{MACHINE\}/conf/local.conf}
298 \item Update or checkout of Git repositories
306 \subsection{Makefile targets}
307 Run \shell{make help} to get a list of targets of the top level Makefile, together with a brief description.
309 \subsection{Configuration variables}
310 \subsubsection{BB\_NUMBER\_THREADS}
311 Controls how many BitBake tasks may run at a time. Defaults to the
312 number of cores available on the build system. The number of cores is
313 obtained from \shell{/proc/cpuinfo}. If this file is unavailable, the
316 \subsubsection{MACHINE}
317 Controls the target machine to build packages for. See section \ref{products}
318 for a list of supported products.
320 \subsubsection{PARALLEL\_MAKE}
321 Controls how many processes per recipe \shell{make} may use. Defaults to
322 the number of cores available on the build system. The number of cores is
323 obtained from \shell{/proc/cpuinfo}. If this file is unavailable, the
326 NOTE: If you see seemingly random build failures, try setting this variable to 1.
328 \subsection{Adding custom layers}
329 \label{custom_layers}
330 It is possible to add custom layers to the build system. This can be done globally
331 and per machine. To add a layer globally, edit \shell{conf/bblayers-ext.conf}. To
332 add a machine-specific layer, edit \shell{conf/bblayers-\$\{MACHINE\}-ext.conf}.
333 Assuming that an additional layer is available at \shell{\$\{HOME\}/custom-layer},
334 the entry to add to the file will look like this:
336 \shell{BBLAYERS =+ "\$\{HOME\}/custom-layer"}
338 \subsection{Adding custom options}
339 It is possible to tweak a lot more options than those used by the
340 \shell{Makefile} by editing \shell{conf/local-ext.conf} or \shell{conf/local-\$\{MACHINE\}-ext.conf}.
342 For example, if the firmware shall use the package feed built on the develoment machine, which
343 happens to be 192.168.1.1 and has a webserver configured to point to \shell{tmp/deploy/ipk},
344 a line like the following may be added:
346 \shell{DISTRO\_FEED\_URI = "http://192.168.1.1/\$\{DISTRO\}/\$\{DISTRO\_VERSION\}"}
348 In general, any variable in OpenEmbedded that uses weak assignment (\shell{?=}) may be
349 overridden from these files.
351 The following sections list some commonly used options.
353 \subsubsection{DISTRO\_FEED\_PREFIX}
355 \shell{DISTRO\_FEED\_PREFIX} specifies the name of the package update feed.
356 This name may be arbitarily chosen.
358 Default: \shell{DISTRO\_FEED\_PREFIX = "remote"}
360 \subsubsection{DISTRO\_FEED\_URI}
362 \shell{DISTRO\_FEED\_URI} specifies the URI of the package update feed.
364 Default: \shell{DISTRO\_FEED\_URI = "http://my-distribution.example/remote-feed/"}
366 \subsubsection{INHERIT}
368 \shell{INHERIT} specifies bbclasses to include from a configuration file. Usually,
369 this variable gets appended to by using the \shell{+=} operator.
371 The OpenDreambox distribution automatically appends \shell{"buildhistory recipe\_sanity testlab"} to \shell{INHERIT}.
373 Default: \shell{INHERIT = ""}
375 \textbf{Some examples:}
377 Always build the latest versions of OpenDreambox-related projects from Git:
379 \shell{INHERIT += "opendreambox-autorev"}
381 Remove temporary files of previous versions of a recipe before a newer version gets built:
383 \shell{INHERIT += "rm\_old\_work"}
385 Remove temporary files of a recipe after it has been built and packaged successfully.
387 \shell{INHERIT += "rm\_work"}
389 \subsection{Setting up a build directory}
390 To set up a build directory for e.g. \textbf{DM 500 HD} run \shell{make MACHINE=dm500hd}. If
391 \shell{MACHINE=dm500hd} has been set in \shell{conf/make.conf}, you can simply run \shell{make}
392 with no arguments instead. This will create and initialize the directory \shell{build/dm500hd}.
394 \subsection{Building a firmware image}
395 To build a firmware image for e.g. \textbf{DM 500 HD} run \shell{make MACHINE=dm500hd image}.
396 If \shell{MACHINE=dm500hd} has been set in \shell{conf/make.conf}, you can simply run
397 \shell{make image} instead.
399 \subsection{Building a package}
400 To build a single package, BitBake has to be used directly. First, the environment
401 has to be set up, in order to make BitBake available to the shell. This can be done
402 with the following command:
404 \shell{source bitbake.env}
406 BitBake must be run from the machine's build directory. For \textbf{DM 500 HD} run:
408 \shell{cd build/dm500hd}
410 In order to build enigma2, run:
412 \shell{bitbake enigma2}.
414 \section{Development hints}
416 \subsection{Cross-compilation of external software}
417 OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
418 the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
421 \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
422 \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
423 \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
424 \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
425 \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
428 The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
429 adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
431 \shell{source cross-compile.env dm7020hd}
433 The script may be called from any location, but must reside inside the OpenDreambox Git tree.
434 You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
436 \subsection{Coding style}
437 Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
439 \subsection {Package architecture}
440 Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
442 \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
443 \item The recipe is part of \shell{meta-bsp}.
446 \section{Bug reports and patches}
448 Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
450 A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
451 local copy of the repository.