2 % Copyright (c) 2010-2014 Dream Property 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 Property GmbH}.
59 OpenDreambox is based on the \href{http://www.openembedded.org/}{OpenEmbedded} build framework, which
60 uses BitBake to transform build instructions into
61 distributable firmare images and software packages.
63 The current version, OpenDreambox 2.2, is based on the \href{https://www.yoctoproject.org/}{Yocto Project}, release
64 1.5.1 "Dora", an umbrella project for OpenEmbedded and related tools.
67 \subsection{Target audience}
69 Developers familiar with previous versions of OpenDreambox or OpenEmbedded
73 \subsection{Supported products}
76 The current version includes support for the following products:
78 \begin{tabular}{ | l | l | }
80 \textbf{Product name} & \textbf{Environment variable} \\ \hline
82 DM 500 HD & \shell{MACHINE=dm500hd} \\
83 DM 500 HD V2 & \shell{MACHINE=dm500hdv2} \\
84 DM 800 HD SE & \shell{MACHINE=dm800se} \\
85 DM 800 HD SE V2 & \shell{MACHINE=dm800sev2} \\
86 DM 7020 HD & \shell{MACHINE=dm7020hd} \\
87 DM 7020 HD V2 & \shell{MACHINE=dm7020hdv2} \\
88 DM 7080 & \shell{MACHINE=dm7080} \\
89 DM 8000 HD PVR & \shell{MACHINE=dm8000} \\
94 Note, that not all of these platforms offer enough internal
95 storage to actually flash a generated firmware image. It might be possible
96 to boot from external storage or network, though.
102 Copyright (c) 2010-2014 Dream Property GmbH, Germany
103 http://www.dream-multimedia-tv.de/
105 Andreas Frisch <fraxinas@opendreambox.org>
106 Andreas Monzner <ghost@opendreambox.org>
107 Andreas Oberritter <obi@opendreambox.org>
108 Mladen Horvat <acid-burn@opendreambox.org>
109 Stefan Pluecken <thedoc@opendreambox.org>
110 Stephan Reichholf <reichi@opendreambox.org>
112 Permission is hereby granted, free of charge, to any person obtaining a copy
113 of this software and associated documentation files (the "Software"), to deal
114 in the Software without restriction, including without limitation the rights
115 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
116 copies of the Software, and to permit persons to whom the Software is
117 furnished to do so, subject to the following conditions:
119 The above copyright notice and this permission notice shall be included in
120 all copies or substantial portions of the Software.
122 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
123 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
124 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
125 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
126 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
127 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
131 \subsection{Obtaining the source code}
132 OpenDreambox uses the Git version control system. To obtain the source
133 code, it is required to install Git. See \url{http://git-scm.com/}.
135 To initially download the source into the current directory, issue the
138 \shell{git clone -b dora git://git.opendreambox.org/git/opendreambox.git}
140 The Git repository can be viewed online at:
142 \url{http://git.opendreambox.org/?p=opendreambox.git}
144 \subsection{Quick start}
147 \shell{make -C opendreambox image}
149 If this command fails, prerequisites my be missing. See section \ref{prerequisites}.
151 \subsection{Directory structure}
152 OpenDreambox consists of a set of layers containing build instructions.
153 This meta data is used by BitBake to download and compile source code
154 and to assemble installable software packages and firmware images.
156 Currently, these layers are used, ordered by priority from highest to
160 \item \shell{meta-dreambox}
161 \item \shell{meta-opendreambox}
162 \item \shell{meta-qt5}
163 \item \shell{meta-openembedded/meta-oe}
164 \item \shell{meta-openembedded/meta-filesystems}
165 \item \shell{meta-openembedded/meta-initramfs}
166 \item \shell{meta-openembedded/meta-multimedia}
167 \item \shell{meta-openembedded/meta-networking}
168 \item \shell{meta-openembedded/meta-ruby}
169 \item \shell{openembedded-core/meta}
172 If a recipe for the same package exists in multiple layers,
173 then the higher priority layer takes precedence over the lower priority
176 For example, if \shell{libmad\_0.15.1b.bb} existed in both
177 \shell{meta-openembedded} and \shell{openembedded-core}, the recipe in
178 \shell{meta-openembedded} would be used, because \shell{openembedded-core}
181 \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
182 \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
183 unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
184 There is currently no way to prefer a version of a lower priority layer, if the
185 same version is present in a higher priority layer.
187 \subsubsection{openembedded-core and meta-openembedded}
188 These directories contain copies of Git repositories from git.openembedded.org,
189 including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They
190 get created automatically when building the distribution for the first time.
192 Throughout this document, the combination of these directories will be
193 referred to as OpenEmbedded.
195 The latest changes to these Git repositories can be seen at:
197 \url{http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/dora}
199 \url{http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/dora}
201 \subsubsection{meta-opendreambox}
202 This directory contains:
205 \item Recipes for packages written specifically for the OpenDreambox distribution
206 \item Modifications to recipes from OpenEmbedded
207 \item Recipes for software versions older than those available from OpenEmbedded
208 \item Recipes for software versions newer than those available from OpenEmbedded
211 \subsubsection{meta-dreambox}
212 The directory \shell{meta-dreambox} contains Board Support Packages (BSP)
213 for the supported Dreambox models. This includes:
216 \item Hardware drivers
217 \item Machine specific overrides
218 \item The Linux kernel
219 \item The boot loader
223 \section{Further readings}
225 \item The Yocto Project Reference Manual:
226 \url{https://www.yoctoproject.org/docs/1.5.1/ref-manual/ref-manual.html}
229 \section{Prerequisites}
230 \label{prerequisites}
232 \subsection{Required software}
234 The OpenEmbedded project provides a general list of prerequisites for
235 many Linux distributions and also for some other operating systems.
238 \item \url{http://www.openembedded.org/wiki/Getting\_started#Required\_software}
241 It is highly recommended to use Linux to build OpenDreambox. In theory,
242 any recent distribution will do, but not many distributions have been
243 verified to build OpenDreambox without errors. Tested distributions
247 \item Debian 7.6 "Wheezy" [i386, amd64]
248 \item Ubuntu 14.04.1 LTS "Trusty Tahr" [amd64]
253 \section{Major changes since previous public releases}
255 \subsection{Changes since release 1.6}
257 \item Recipes were split across multiple layers and categorized.
258 \item \shell{env.source} has been replaced by two files,
259 \shell{bitbake.env} and \shell{cross-compile.env}. The former sets a minimal
260 environment that is needed to execute bitbake. The latter creates
261 machine-specific command aliases, in order to compile external software.
262 \item All machines share a common \shell{tmp} directory.
263 \item \shell{\$\{MACHINE\}/build} directories were renamed to \shell{build/\$\{MACHINE\}}.
264 \item Kernel packages were renamed from \shell{linux-\$\{MACHINE\}} to \shell{linux-dreambox}.
265 \item Support for machines based on ATI Xilleon or IBM STB was dropped.
268 \subsection{Changes since release 2.0}
270 \item Added support for DM7080.
271 \item If a recipe changes, the corresponding packages will be rebuilt automatically,
272 in contrast to required manual PR bumps in the past.
273 \item Each machine uses its own tmp directory again, like before 2.0. However,
274 there is a shared \shell{sstate-cache}, which allows to share already compiled
275 data between compatible machines. This impacts performance and size of the
276 build system, but improves reliability and consistency across builds.
277 \item Support for machines without FPU and kernel versions below 3.x was dropped (DM800).
278 \item Layers under meta-bsp were combined into meta-dreambox.
279 \item Default package format switched from ipk (opkg) to deb (dpkg + apt).
280 \item \shell{dreambox-image} was renamed to include the package format (\shell{dreambox-image-deb}).
283 \section{Known Issues}
289 \section{Building OpenDreambox}
291 In the top level directory, there is a \shell{Makefile}, which is used to
292 set up build directories and to fetch or update all used repositories.
293 The Makefile can be influenced by environment variables, either
294 by specifing them on the command-line or by storing them in a file called
295 \shell{conf/make.conf}. It is not recommended to edit the \shell{Makefile} directly
296 in order to avoid conflicts with future updates.
298 When the \shell{Makefile} is run for the first time, the following steps will
302 \item Creation of configuration files
304 \item \shell{bitbake.env}
305 \item \shell{conf/opendreambox.conf}
306 \item \shell{build/\$\{MACHINE\}/conf/bblayers.conf}
307 \item \shell{build/\$\{MACHINE\}/conf/local.conf}
309 \item Update or checkout of Git repositories
317 \subsection{Makefile targets}
318 Run \shell{make help} to get a list of targets of the top level Makefile, together with a brief description.
320 \subsection{Configuration variables}
321 \subsubsection{BB\_NUMBER\_THREADS}
322 Controls how many BitBake tasks may run at a time. Defaults to the
323 number of cores available on the build system.
325 \subsubsection{MACHINE}
326 Controls the target machine to build packages for. See section \ref{products}
327 for a list of supported products.
329 \subsubsection{PARALLEL\_MAKE}
330 Controls how many processes per recipe \shell{make} may use. Defaults to
331 the number of cores available on the build system.
333 \subsection{Adding custom layers}
334 \label{custom_layers}
335 It is possible to add custom layers to the build system. This can be done globally
336 and per machine. To add a layer globally, edit \shell{conf/bblayers-ext.conf}. To
337 add a machine-specific layer, edit \shell{conf/bblayers-\$\{MACHINE\}-ext.conf}.
338 Assuming that an additional layer is available at \shell{\$\{HOME\}/custom-layer},
339 the entry to add to the file will look like this:
341 \shell{BBLAYERS =+ "\$\{HOME\}/custom-layer"}
343 \subsection{Adding custom options}
344 It is possible to tweak a lot more options than those used by the
345 \shell{Makefile} by editing \shell{conf/local-ext.conf} or \shell{conf/local-\$\{MACHINE\}-ext.conf}.
347 For example, if the firmware shall use the package feed built on the develoment machine, which
348 happens to be 192.168.1.1 and has a webserver configured to point to \shell{tmp/deploy/ipk},
349 a line like the following may be added:
351 \shell{DISTRO\_FEED\_URI = "http://192.168.1.1/\$\{DISTRO\}/\$\{DISTRO\_VERSION\}"}
353 In general, any variable in OpenEmbedded that uses weak assignment (\shell{?=}) may be
354 overridden from these files.
356 The following sections list some commonly used options.
358 \subsubsection{DISTRO\_FEED\_PREFIX}
360 \shell{DISTRO\_FEED\_PREFIX} specifies the name of the package update feed.
361 This name may be chosen arbitarily.
363 Default: \shell{DISTRO\_FEED\_PREFIX = "remote"}
365 \subsubsection{DISTRO\_FEED\_URI}
367 \shell{DISTRO\_FEED\_URI} specifies the URI of the package update feed.
369 Default: \shell{DISTRO\_FEED\_URI = "http://my-distribution.example/remote-feed/"}
371 \subsubsection{INHERIT}
373 \shell{INHERIT} specifies bbclasses to include from a configuration file. Usually,
374 this variable gets appended to by using the \shell{+=} operator.
376 The OpenDreambox distribution automatically appends \shell{"buildhistory recipe\_sanity"} to \shell{INHERIT}.
378 Default: \shell{INHERIT = ""}
380 \textbf{Some examples:}
382 Always build the latest versions of OpenDreambox-related projects from Git:
384 \shell{INHERIT += "opendreambox-autorev"}
386 Remove temporary files of previous versions of a recipe before a newer version gets built:
388 \shell{INHERIT += "rm\_old\_work"}
390 \subsection{Setting up a build directory}
391 To set up a build directory for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080}. If
392 \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default), you can simply run \shell{make}
393 with no arguments instead. This will create and initialize the directory \shell{build/dm7080}.
395 \subsection{Building a firmware image}
396 To build a firmware image for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080 image}.
397 If \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default), you can simply run
398 \shell{make image} instead.
400 \subsection{Building a package}
401 To build a single package, BitBake has to be used directly. First, the environment
402 has to be set up, in order to make BitBake available to the shell. This can be done
403 with the following command:
405 \shell{source bitbake.env}
407 BitBake must be run from the machine's build directory. For \textbf{DM 7080} run:
409 \shell{cd build/dm7080}
411 In order to build enigma2, run:
413 \shell{bitbake enigma2}.
415 \section{Development hints}
417 \subsection{Cross-compilation of external software}
418 OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
419 the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
422 \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
423 \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
424 \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
425 \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
426 \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
429 The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
430 adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
432 \shell{source cross-compile.env dm7080}
434 The script may be called from any location, but must reside inside the OpenDreambox Git tree.
435 You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
437 \subsection{Coding style}
438 Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
440 \subsection {Package architecture}
441 Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
443 \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
444 \item The recipe uses \shell{COMPATIBLE\_MACHINE}.
445 \item The recipe is part of \shell{meta-dreambox}.
448 \section{Bug reports and patches}
450 Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
452 A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
453 local copy of the repository.