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 820 HD & \shell{MACHINE=dm820} \\
87 DM 7020 HD & \shell{MACHINE=dm7020hd} \\
88 DM 7020 HD V2 & \shell{MACHINE=dm7020hdv2} \\
89 DM 7080 HD & \shell{MACHINE=dm7080} \\
90 DM 8000 HD PVR & \shell{MACHINE=dm8000} \\
95 Note, that not all of these platforms offer enough internal
96 storage to actually flash a generated firmware image. It might be possible
97 to boot from external storage or network, though.
103 Copyright (c) 2010-2014 Dream Property GmbH, Germany
104 http://www.dream-multimedia-tv.de/
106 Andreas Frisch <fraxinas@opendreambox.org>
107 Andreas Monzner <ghost@opendreambox.org>
108 Andreas Oberritter <obi@opendreambox.org>
109 Mladen Horvat <acid-burn@opendreambox.org>
110 Stefan Pluecken <thedoc@opendreambox.org>
111 Stephan Reichholf <reichi@opendreambox.org>
113 Permission is hereby granted, free of charge, to any person obtaining a copy
114 of this software and associated documentation files (the "Software"), to deal
115 in the Software without restriction, including without limitation the rights
116 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
117 copies of the Software, and to permit persons to whom the Software is
118 furnished to do so, subject to the following conditions:
120 The above copyright notice and this permission notice shall be included in
121 all copies or substantial portions of the Software.
123 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
124 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
125 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
126 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
127 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
128 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
132 \subsection{Obtaining the source code}
133 OpenDreambox uses the Git version control system. To obtain the source
134 code, it is required to install Git. See \url{http://git-scm.com/}.
136 To initially download the source into the current directory, issue the
139 \shell{git clone -b dora git://git.opendreambox.org/git/opendreambox.git}
141 The Git repository can be viewed online at:
143 \url{http://git.opendreambox.org/?p=opendreambox.git}
145 \subsection{Quick start}
148 \shell{make -C opendreambox image}
150 If this command fails, prerequisites my be missing. See section \ref{prerequisites}.
152 \subsection{Directory structure}
153 OpenDreambox consists of a set of layers containing build instructions.
154 This meta data is used by BitBake to download and compile source code
155 and to assemble installable software packages and firmware images.
157 Currently, these layers are used, ordered by priority from highest to
161 \item \shell{meta-dreambox}
162 \item \shell{meta-opendreambox}
163 \item \shell{meta-qt5}
164 \item \shell{meta-openembedded/meta-oe}
165 \item \shell{meta-openembedded/meta-filesystems}
166 \item \shell{meta-openembedded/meta-initramfs}
167 \item \shell{meta-openembedded/meta-multimedia}
168 \item \shell{meta-openembedded/meta-networking}
169 \item \shell{meta-openembedded/meta-ruby}
170 \item \shell{openembedded-core/meta}
173 If a recipe for the same package exists in multiple layers,
174 then the higher priority layer takes precedence over the lower priority
177 For example, if \shell{libmad\_0.15.1b.bb} existed in both
178 \shell{meta-openembedded} and \shell{openembedded-core}, the recipe in
179 \shell{meta-openembedded} would be used, because \shell{openembedded-core}
182 \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
183 \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
184 unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
185 There is currently no way to prefer a version of a lower priority layer, if the
186 same version is present in a higher priority layer.
188 \subsubsection{openembedded-core and meta-openembedded}
189 These directories contain copies of Git repositories from git.openembedded.org,
190 including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They
191 get created automatically when building the distribution for the first time.
193 Throughout this document, the combination of these directories will be
194 referred to as OpenEmbedded.
196 The latest changes to these Git repositories can be seen at:
198 \url{http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/dora}
200 \url{http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/dora}
202 \subsubsection{meta-opendreambox}
203 This directory contains:
206 \item Recipes for packages written specifically for the OpenDreambox distribution
207 \item Modifications to recipes from OpenEmbedded
208 \item Recipes for software versions older than those available from OpenEmbedded
209 \item Recipes for software versions newer than those available from OpenEmbedded
212 \subsubsection{meta-dreambox}
213 The directory \shell{meta-dreambox} contains Board Support Packages (BSP)
214 for the supported Dreambox models. This includes:
217 \item Hardware drivers
218 \item Machine specific overrides
219 \item The Linux kernel
220 \item The boot loader
224 \section{Further readings}
226 \item The Yocto Project Reference Manual:
227 \url{https://www.yoctoproject.org/docs/1.5.1/ref-manual/ref-manual.html}
230 \section{Prerequisites}
231 \label{prerequisites}
233 \subsection{Required software}
235 The OpenEmbedded project provides a general list of prerequisites for
236 many Linux distributions and also for some other operating systems.
239 \item \url{http://www.openembedded.org/wiki/Getting\_started#Required\_software}
242 It is highly recommended to use Linux to build OpenDreambox. In theory,
243 any recent distribution will do, but not many distributions have been
244 verified to build OpenDreambox without errors. Tested distributions
248 \item Debian 7.6 "Wheezy" [i386, amd64]
249 \item Ubuntu 14.04.1 LTS "Trusty Tahr" [amd64]
254 \section{Major changes since previous public releases}
256 \subsection{Changes since release 1.6}
258 \item Recipes were split across multiple layers and categorized.
259 \item \shell{env.source} has been replaced by two files,
260 \shell{bitbake.env} and \shell{cross-compile.env}. The former sets a minimal
261 environment that is needed to execute bitbake. The latter creates
262 machine-specific command aliases, in order to compile external software.
263 \item All machines share a common \shell{tmp} directory.
264 \item \shell{\$\{MACHINE\}/build} directories were renamed to \shell{build/\$\{MACHINE\}}.
265 \item Kernel packages were renamed from \shell{linux-\$\{MACHINE\}} to \shell{linux-dreambox}.
266 \item Support for machines based on ATI Xilleon or IBM STB was dropped.
269 \subsection{Changes since release 2.0}
271 \item Added support for DM7080.
272 \item If a recipe changes, the corresponding packages will be rebuilt automatically,
273 in contrast to required manual PR bumps in the past.
274 \item Each machine uses its own tmp directory again, like before 2.0. However,
275 there is a shared \shell{sstate-cache}, which allows to share already compiled
276 data between compatible machines. This impacts performance and size of the
277 build system, but improves reliability and consistency across builds.
278 \item Support for machines without FPU and kernel versions below 3.x was dropped (DM800).
279 \item Layers under meta-bsp were combined into meta-dreambox.
280 \item Default package format switched from ipk (opkg) to deb (dpkg + apt).
281 \item \shell{dreambox-image} was renamed to include the package format (\shell{dreambox-image-deb}).
284 \section{Known Issues}
290 \section{Building OpenDreambox}
292 In the top level directory, there is a \shell{Makefile}, which is used to
293 set up build directories and to fetch or update all used repositories.
294 The Makefile can be influenced by environment variables, either
295 by specifing them on the command-line or by storing them in a file called
296 \shell{conf/make.conf}. It is not recommended to edit the \shell{Makefile} directly
297 in order to avoid conflicts with future updates.
299 When the \shell{Makefile} is run for the first time, the following steps will
303 \item Creation of configuration files
305 \item \shell{bitbake.env}
306 \item \shell{conf/opendreambox.conf}
307 \item \shell{build/\$\{MACHINE\}/conf/bblayers.conf}
308 \item \shell{build/\$\{MACHINE\}/conf/local.conf}
310 \item Update or checkout of Git repositories
318 \subsection{Makefile targets}
319 Run \shell{make help} to get a list of targets of the top level Makefile, together with a brief description.
321 \subsection{Configuration variables}
322 \subsubsection{BB\_NUMBER\_THREADS}
323 Controls how many BitBake tasks may run at a time. Defaults to the
324 number of cores available on the build system.
326 \subsubsection{MACHINE}
327 Controls the target machine to build packages for. See section \ref{products}
328 for a list of supported products.
330 \subsubsection{PARALLEL\_MAKE}
331 Controls how many processes per recipe \shell{make} may use. Defaults to
332 the number of cores available on the build system.
334 \subsection{Adding custom layers}
335 \label{custom_layers}
336 It is possible to add custom layers to the build system. This can be done globally
337 and per machine. To add a layer globally, edit \shell{conf/bblayers-ext.conf}. To
338 add a machine-specific layer, edit \shell{conf/bblayers-\$\{MACHINE\}-ext.conf}.
339 Assuming that an additional layer is available at \shell{\$\{HOME\}/custom-layer},
340 the entry to add to the file will look like this:
342 \shell{BBLAYERS =+ "\$\{HOME\}/custom-layer"}
344 \subsection{Adding custom options}
345 It is possible to tweak a lot more options than those used by the
346 \shell{Makefile} by editing \shell{conf/local-ext.conf} or \shell{conf/local-\$\{MACHINE\}-ext.conf}.
348 For example, if the firmware shall use the package feed built on the develoment machine, which
349 happens to be 192.168.1.1 and has a webserver configured to point to \shell{tmp/deploy/ipk},
350 a line like the following may be added:
352 \shell{DISTRO\_FEED\_URI = "http://192.168.1.1/\$\{DISTRO\}/\$\{DISTRO\_VERSION\}"}
354 In general, any variable in OpenEmbedded that uses weak assignment (\shell{?=}) may be
355 overridden from these files.
357 The following sections list some commonly used options.
359 \subsubsection{DISTRO\_FEED\_PREFIX}
361 \shell{DISTRO\_FEED\_PREFIX} specifies the name of the package update feed.
362 This name may be chosen arbitarily.
364 Default: \shell{DISTRO\_FEED\_PREFIX = "remote"}
366 \subsubsection{DISTRO\_FEED\_URI}
368 \shell{DISTRO\_FEED\_URI} specifies the URI of the package update feed.
370 Default: \shell{DISTRO\_FEED\_URI = "http://my-distribution.example/remote-feed/"}
372 \subsubsection{INHERIT}
374 \shell{INHERIT} specifies bbclasses to include from a configuration file. Usually,
375 this variable gets appended to by using the \shell{+=} operator.
377 The OpenDreambox distribution automatically appends \shell{"buildhistory recipe\_sanity"} to \shell{INHERIT}.
379 Default: \shell{INHERIT = ""}
381 \textbf{Some examples:}
383 Always build the latest versions of OpenDreambox-related projects from Git:
385 \shell{INHERIT += "opendreambox-autorev"}
387 Remove temporary files of previous versions of a recipe before a newer version gets built:
389 \shell{INHERIT += "rm\_old\_work"}
391 \subsection{Setting up a build directory}
392 To set up a build directory for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080}. If
393 \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default), you can simply run \shell{make}
394 with no arguments instead. This will create and initialize the directory \shell{build/dm7080}.
396 \subsection{Building a firmware image}
397 To build a firmware image for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080 image}.
398 If \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default), you can simply run
399 \shell{make image} instead.
401 \subsection{Building a package}
402 To build a single package, BitBake has to be used directly. First, the environment
403 has to be set up, in order to make BitBake available to the shell. This can be done
404 with the following command:
406 \shell{source bitbake.env}
408 BitBake must be run from the machine's build directory. For \textbf{DM 7080} run:
410 \shell{cd build/dm7080}
412 In order to build enigma2, run:
414 \shell{bitbake enigma2}.
416 \section{Development hints}
418 \subsection{Cross-compilation of external software}
419 OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
420 the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
423 \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
424 \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
425 \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
426 \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
427 \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
430 The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
431 adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
433 \shell{source cross-compile.env dm7080}
435 The script may be called from any location, but must reside inside the OpenDreambox Git tree.
436 You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
438 \subsection{Coding style}
439 Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
441 \subsection {Package architecture}
442 Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
444 \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
445 \item The recipe uses \shell{COMPATIBLE\_MACHINE}.
446 \item The recipe is part of \shell{meta-dreambox}.
449 \section{Bug reports and patches}
451 Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
453 A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
454 local copy of the repository.