3 Andreas Oberritter <obi@opendreambox.org>
10 1.2 Supported products
12 1.4 Obtaining the source code
14 1.6 Directory structure
15 1.6.1 openembedded-core and meta-openembedded
16 1.6.2 meta-opendreambox
21 4 Major changes since previous public releases
22 4.1 Changes since release 1.6
23 4.2 Changes since release 2.0
25 6 Building OpenDreambox
27 6.2 Configuration variables
28 6.2.1 BB_NUMBER_THREADS
31 6.3 Adding custom layers
32 6.4 Adding custom options
33 6.4.1 DISTRO_FEED_PREFIX
36 6.5 Setting up a build directory
37 6.6 Building a firmware image
38 6.7 Building a package
40 7.1 Cross-compilation of external software
42 7.3 Package architecture
43 8 Bug reports and patches
47 This document briefly describes the OpenDreambox distribution, an embedded
48 Linux distribution for Set-Top-Boxes manufactured by Dream Property GmbH.
50 OpenDreambox is based on the OpenEmbedded build framework, which uses BitBake
51 to transform build instructions into distributable firmare images and software
54 The current version, OpenDreambox 2.2, is based on the Yocto Project, release
55 1.5.1 "Dora", an umbrella project for OpenEmbedded and related tools.
59 Developers familiar with previous versions of OpenDreambox or OpenEmbedded in
62 1.2 Supported products
64 The current version includes support for the following products:
66 +-----------------------------------------------------------------------------+
67 | ---------------------- | ---------------------------------------------- |
68 |Product name |Environment variable |
69 | ---------------------- | ---------------------------------------------- |
70 |DM 500 HD |MACHINE=dm500hd |
71 |DM 500 HD V2 |MACHINE=dm500hdv2 |
72 |DM 800 HD SE |MACHINE=dm800se |
73 |DM 800 HD SE V2 |MACHINE=dm800sev2 |
74 |DM 7020 HD |MACHINE=dm7020hd |
75 |DM 7020 HD V2 |MACHINE=dm7020hdv2 |
76 |DM 7080 |MACHINE=dm7080 |
77 |DM 8000 HD PVR |MACHINE=dm8000 |
78 | ---------------------- | ---------------------------------------------- |
79 +-----------------------------------------------------------------------------+
81 Note, that not all of these platforms offer enough internal storage to actually
82 flash a generated firmware image. It might be possible to boot from external
83 storage or network, though.
87 Copyright (c) 2010-2014 Dream Property GmbH, Germany
88 http://www.dream-multimedia-tv.de/
90 Andreas Frisch <fraxinas@opendreambox.org>
91 Andreas Monzner <ghost@opendreambox.org>
92 Andreas Oberritter <obi@opendreambox.org>
93 Mladen Horvat <acid-burn@opendreambox.org>
94 Stefan Pluecken <thedoc@opendreambox.org>
95 Stephan Reichholf <reichi@opendreambox.org>
97 Permission is hereby granted, free of charge, to any person obtaining a copy
98 of this software and associated documentation files (the "Software"), to deal
99 in the Software without restriction, including without limitation the rights
100 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
101 copies of the Software, and to permit persons to whom the Software is
102 furnished to do so, subject to the following conditions:
104 The above copyright notice and this permission notice shall be included in
105 all copies or substantial portions of the Software.
107 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
108 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
109 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
110 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
111 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
112 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
116 1.4 Obtaining the source code
118 OpenDreambox uses the Git version control system. To obtain the source code, it
119 is required to install Git. See http://git-scm.com/.
121 To initially download the source into the current directory, issue the
124 git clone -b dora git://git.opendreambox.org/git/opendreambox.git
126 The Git repository can be viewed online at:
128 http://git.opendreambox.org/?p=opendreambox.git
134 make -C opendreambox image
136 If this command fails, prerequisites my be missing. See section 3.
138 1.6 Directory structure
140 OpenDreambox consists of a set of layers containing build instructions. This
141 meta data is used by BitBake to download and compile source code and to
142 assemble installable software packages and firmware images.
144 Currently, these layers are used, ordered by priority from highest to lowest:
148 * meta-openembedded/meta-oe
149 * meta-openembedded/meta-filesystems
150 * meta-openembedded/meta-initramfs
151 * meta-openembedded/meta-multimedia
152 * meta-openembedded/meta-networking
153 * meta-openembedded/meta-ruby
154 * openembedded-core/meta
156 If a recipe for the same package exists in multiple layers, then the higher
157 priority layer takes precedence over the lower priority layer.
159 For example, if libmad_0.15.1b.bb existed in both meta-openembedded and
160 openembedded-core, the recipe in meta-openembedded would be used, because
161 openembedded-core has lower priority.
163 NOTE: This would still be true even if the version of libmad in
164 openembeded-core was higher than the version in meta-openembedded, unless
165 PREFERRED_VERSION_libmad was set to the version in openembedded-core. There is
166 currently no way to prefer a version of a lower priority layer, if the same
167 version is present in a higher priority layer.
169 1.6.1 openembedded-core and meta-openembedded
171 These directories contain copies of Git repositories from git.openembedded.org,
172 including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They
173 get created automatically when building the distribution for the first time.
175 Throughout this document, the combination of these directories will be referred
178 The latest changes to these Git repositories can be seen at:
180 http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/dora
182 http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/dora
184 1.6.2 meta-opendreambox
186 This directory contains:
187 * Recipes for packages written specifically for the OpenDreambox distribution
188 * Modifications to recipes from OpenEmbedded
189 * Recipes for software versions older than those available from OpenEmbedded
190 * Recipes for software versions newer than those available from OpenEmbedded
194 The directory meta-dreambox contains Board Support Packages (BSP) for the
195 supported Dreambox models. This includes:
197 * Machine specific overrides
204 * The Yocto Project Reference Manual:
205 https://www.yoctoproject.org/docs/1.5.1/ref-manual/ref-manual.html
209 3.1 Required software
211 The OpenEmbedded project provides a general list of prerequisites for many
212 Linux distributions and also for some other operating systems.
213 * http://www.openembedded.org/wiki/Getting\_started#Required\_software
215 It is highly recommended to use Linux to build OpenDreambox. In theory, any
216 recent distribution will do, but not many distributions have been verified to
217 build OpenDreambox without errors. Tested distributions include:
218 * Debian 7.6 "Wheezy" [i386, amd64]
219 * Ubuntu 14.04.1 LTS "Trusty Tahr" [amd64]
221 4 Major changes since previous public releases
223 4.1 Changes since release 1.6
225 * Recipes were split across multiple layers and categorized.
226 * env.source has been replaced by two files, bitbake.env and
227 cross-compile.env. The former sets a minimal environment that is needed to
228 execute bitbake. The latter creates machine-specific command aliases, in
229 order to compile external software.
230 * All machines share a common tmp directory.
231 * ${MACHINE}/build directories were renamed to build/${MACHINE}.
232 * Kernel packages were renamed from linux-${MACHINE} to linux-dreambox.
233 * Support for machines based on ATI Xilleon or IBM STB was dropped.
235 4.2 Changes since release 2.0
237 * Added support for DM7080.
238 * If a recipe changes, the corresponding packages will be rebuilt
239 automatically, in contrast to required manual PR bumps in the past.
240 * Each machine uses its own tmp directory again, like before 2.0. However,
241 there is a shared sstate-cache, which allows to share already compiled data
242 between compatible machines. This impacts performance and size of the build
243 system, but improves reliability and consistency across builds.
244 * Support for machines without FPU and kernel versions below 3.x was dropped
246 * Layers under meta-bsp were combined into meta-dreambox.
247 * Default package format switched from ipk (opkg) to deb (dpkg + apt).
248 * dreambox-image was renamed to include the package format
249 (dreambox-image-deb).
255 6 Building OpenDreambox
257 In the top level directory, there is a Makefile, which is used to set up build
258 directories and to fetch or update all used repositories. The Makefile can be
259 influenced by environment variables, either by specifing them on the
260 command-line or by storing them in a file called conf/make.conf. It is not
261 recommended to edit the Makefile directly in order to avoid conflicts with
264 When the Makefile is run for the first time, the following steps will be
266 * Creation of configuration files
268 * conf/opendreambox.conf
269 * build/${MACHINE}/conf/bblayers.conf
270 * build/${MACHINE}/conf/local.conf
271 * Update or checkout of Git repositories
278 Run make help to get a list of targets of the top level Makefile, together with
281 6.2 Configuration variables
283 6.2.1 BB_NUMBER_THREADS
285 Controls how many BitBake tasks may run at a time. Defaults to the number of
286 cores available on the build system.
290 Controls the target machine to build packages for. See section 1.2 for a list
291 of supported products.
295 Controls how many processes per recipe make may use. Defaults to the number of
296 cores available on the build system.
298 6.3 Adding custom layers
300 It is possible to add custom layers to the build system. This can be done
301 globally and per machine. To add a layer globally, edit conf/bblayers-ext.conf.
302 To add a machine-specific layer, edit conf/bblayers-${MACHINE}-ext.conf.
303 Assuming that an additional layer is available at ${HOME}/custom-layer, the
304 entry to add to the file will look like this:
306 BBLAYERS =+ "${HOME}/custom-layer"
308 6.4 Adding custom options
310 It is possible to tweak a lot more options than those used by the Makefile by
311 editing conf/local-ext.conf or conf/local-${MACHINE}-ext.conf.
313 For example, if the firmware shall use the package feed built on the develoment
314 machine, which happens to be 192.168.1.1 and has a webserver configured to
315 point to tmp/deploy/ipk, a line like the following may be added:
317 DISTRO_FEED_URI = "http://192.168.1.1/${DISTRO}/${DISTRO_VERSION}"
319 In general, any variable in OpenEmbedded that uses weak assignment (?=) may be
320 overridden from these files.
322 The following sections list some commonly used options.
324 6.4.1 DISTRO_FEED_PREFIX
326 DISTRO_FEED_PREFIX specifies the name of the package update feed. This name may
327 be chosen arbitarily.
329 Default: DISTRO_FEED_PREFIX = "remote"
331 6.4.2 DISTRO_FEED_URI
333 DISTRO_FEED_URI specifies the URI of the package update feed.
335 Default: DISTRO_FEED_URI = "http://my-distribution.example/remote-feed/"
339 INHERIT specifies bbclasses to include from a configuration file. Usually, this
340 variable gets appended to by using the += operator.
342 The OpenDreambox distribution automatically appends "buildhistory
343 recipe_sanity" to INHERIT.
345 Default: INHERIT = ""
349 Always build the latest versions of OpenDreambox-related projects from Git:
351 INHERIT += "opendreambox-autorev"
353 Remove temporary files of previous versions of a recipe before a newer version
356 INHERIT += "rm_old_work"
358 6.5 Setting up a build directory
360 To set up a build directory for e.g. DM 7080 run make MACHINE=dm7080. If
361 MACHINE=dm7080 has been set in conf/make.conf (default), you can simply run
362 make with no arguments instead. This will create and initialize the directory
365 6.6 Building a firmware image
367 To build a firmware image for e.g. DM 7080 run make MACHINE=dm7080 image. If
368 MACHINE=dm7080 has been set in conf/make.conf (default), you can simply run
371 6.7 Building a package
373 To build a single package, BitBake has to be used directly. First, the
374 environment has to be set up, in order to make BitBake available to the shell.
375 This can be done with the following command:
379 BitBake must be run from the machine's build directory. For DM 7080 run:
383 In order to build enigma2, run:
389 7.1 Cross-compilation of external software
391 OpenDreambox provides a script called cross-compile.env. Once run, the script
392 will create the following commands (shell aliases), aiming to ease
393 cross-compilation of external source trees:
394 * oe_autoreconf - Calls OE's version of autoreconf. Useful for projects based
396 * oe_runconf - Calls ./configure with parameters suitable for OE. Useful for
397 projects based on GNU autotools.
398 * oe_runmake - Calls make with parameters suitable for OE. Useful for
399 projects based on GNU autotools or GNU make.
400 * oe_env - Useful to execute arbitrary commands in the OE environment (e.g.
402 * oe_setenv - Exports the OE environment to the currently running shell
405 The script needs to know the target machine, which can be one of the supported
406 products (see 1.2). Because the script adds aliases to your currently running
407 shell session, it has to be invoked using source or . (the dot operator), e.g.:
409 source cross-compile.env dm7080
411 The script may be called from any location, but must reside inside the
412 OpenDreambox Git tree. You may want to create a symlink to cross-compile.env
413 somewhere in your PATH.
417 Run scripts/do_stylize.sh on new recipes to ensure proper coding style.
419 7.3 Package architecture
421 Set PACKAGE_ARCH = "${MACHINE_ARCH}" if either condition is met:
422 * The recipe uses COMBINED_FEATURES, MACHINE_FEATURES or DREAMBOX_FEATURES.
423 * The recipe uses COMPATIBLE_MACHINE.
424 * The recipe is part of meta-dreambox.
426 8 Bug reports and patches
428 Please send bug reports and patches to the Enigma2 development mailing list
429 <enigma2-devel@lists.elitedvb.net>.
431 A comfortable way to create patches is to use git format-patch, after all
432 changes have been committed to your local copy of the repository.