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
20 3 Major changes since previous releases
21 3.1 Changes since release 1.6
23 5 Building OpenDreambox
25 5.2 Configuration variables
26 5.2.1 BB_NUMBER_THREADS
29 5.3 Adding custom layers
30 5.4 Adding custom options
31 5.4.1 DISTRO_FEED_PREFIX
34 5.5 Setting up a build directory
35 5.6 Building a firmware image
36 5.7 Building a package
38 6.1 Cross-compilation of external software
40 6.3 Package architecture
41 7 Bug reports and patches
45 This document briefly describes the OpenDreambox distribution, an embedded
46 Linux distribution for Set-Top-Boxes manufactured by Dream Multimedia GmbH.
48 OpenDreambox is based on the OpenEmbedded build framework, which uses BitBake
49 to transform build instructions into distributable firmare images and software
52 The current version, OpenDreambox 2.0, is based on OpenEmbedded "denzil".
56 Developers familiar with previous versions of OpenDreambox or OpenEmbedded in
59 1.2 Supported products
61 The current version includes support for the following machines:
63 +-----------------------------------+
64 | ---------- | ---------------- |
65 |Product name |Environment variable|
66 | ---------- | ---------------- |
67 |DM 500 HD |MACHINE=dm500hd |
68 |DM 800 HD PVR |MACHINE=dm800 |
69 |DM 800 HD SE |MACHINE=dm800se |
70 |DM 7020 HD |MACHINE=dm7020hd |
71 |DM 8000 HD PVR|MACHINE=dm8000 |
72 | ---------- | ---------------- |
73 +-----------------------------------+
77 Copyright (c) 2010-2012 Dream Multimedia GmbH, Germany
78 http://www.dream-multimedia-tv.de/
80 Andreas Frisch <fraxinas@opendreambox.org>
81 Andreas Monzner <ghost@opendreambox.org>
82 Andreas Oberritter <obi@opendreambox.org>
83 Mladen Horvat <acid-burn@opendreambox.org>
84 Stefan Pluecken <thedoc@opendreambox.org>
85 Stephan Reichholf <reichi@opendreambox.org>
87 Permission is hereby granted, free of charge, to any person obtaining a copy
88 of this software and associated documentation files (the "Software"), to deal
89 in the Software without restriction, including without limitation the rights
90 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
91 copies of the Software, and to permit persons to whom the Software is
92 furnished to do so, subject to the following conditions:
94 The above copyright notice and this permission notice shall be included in
95 all copies or substantial portions of the Software.
97 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
98 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
99 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
100 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
101 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
102 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
106 1.4 Obtaining the source code
108 OpenDreambox uses the Git version control system. To obtain the source code, it
109 is required to install Git. See http://git-scm.com/.
111 To initially download the source into the current directory, issue the
114 git clone git://git.opendreambox.org/git/opendreambox.git
116 The Git repository can be viewed online at:
118 http://cgit.opendreambox.org/opendreambox.git
124 make -C opendreambox image
126 If this command fails, prerequisites my be missing. See section 2.
128 1.6 Directory structure
130 OpenDreambox consists of a set of layers containing build instructions. This
131 meta data is used by BitBake to download and compile source code and to
132 assemble installable software packages and firmware images.
134 Currently, there are five layers, ordered by priority from lowest to highest:
139 * meta-bsp/${MACHINE}
141 If a recipe for the same package exists in multiple layers, then the higher
142 priority layer takes precedence over the lower priority layer.
144 For example, libmad_0.15.1b.bb exists in both meta-openembedded and
145 openembedded-core. The recipe in meta-openembedded will be used, because
146 openembedded-core has lower priority.
148 NOTE: This would still be true even if the version of libmad in
149 openembeded-core was higher than the version in meta-openembedded, unless
150 PREFERRED_VERSION_libmad was set to the version in openembedded-core. There is
151 currently no way to prefer a version of a lower priority layer, if the same
152 version is present in a higher priority layer.
154 1.6.1 openembedded-core and meta-openembedded
156 These directories contain copies of Git repositories from git.openembedded.org,
157 including the OpenEmbedded-Core layer ("meta") and the OpenEmbedded layer
158 ("meta-oe"). They get created automatically when building the distribution for
161 Throughout this document, the combination of these directories will be referred
164 The latest changes to these Git repositories can be seen at:
166 http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/current
168 http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/current
170 1.6.2 meta-opendreambox
172 This directory contains:
173 * Recipes for packages written specifically for the OpenDreambox distribution
174 * Modifications to recipes from OpenEmbedded
175 * Recipes for software versions older than those available from OpenEmbedded
176 * Recipes for software versions newer than those available from OpenEmbedded
180 The directory meta-bsp contains Board Support Packages (BSP) for the supported
181 Dreambox models. This includes:
183 * Machine specific overrides
190 2.1 Required software
192 The OpenEmbedded project provides a general list of prerequisites for many
193 Linux distributions and also for some other operating systems.
194 * http://www.openembedded.org/index.php/OEandYourDistro
195 * http://www.openembedded.org/index.php/Required\_software
197 It is highly recommended to use Linux to build OpenDreambox. In theory, any
198 recent distribution will do, but not many distributions have been verified to
199 build OpenDreambox without errors. Tested distributions include:
200 * Arch Linux 2011.08.19 [amd64]
201 * Debian 6.0 (Squeeze) [i386]
202 * Debian "Testing" (Wheezy) [i386]
203 * Fedora 16 [i386, amd64]
204 * Ubuntu 10.04 LTS (Lucid Lynx) [i386]
205 * Ubuntu 11.10 (Oneiric Ocelot) [amd64]
206 * Ubuntu 12.04 LTS (Precise Pangolin) [i386, amd64]
208 Distributions known not to work:
209 * Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.
211 3 Major changes since previous releases
213 3.1 Changes since release 1.6
215 * Recipes were split across multiple layers and categorized.
216 * env.source has been replaced by two files, bitbake.env and
217 cross-compile.env. The former sets a minimal environment that is needed to
218 execute bitbake. The latter creates machine-specific command aliases, in
219 order to compile external software.
220 * All machines share a common tmp directory.
221 * ${MACHINE}/build directories were renamed to build/${MACHINE}.
222 * Kernel packages were renamed from linux-${MACHINE} to linux-dreambox.
223 * Support for machines based on ATI Xilleon or IBM STB was dropped.
227 * Problem: Building on eCryptfs fails, because it doesn't support
228 sufficiently long filenames (eCryptfs bug #344878). Solution: Choose a
229 different filesystem.
230 * Problem: When switching between machines after the gcc recipe was updated,
231 gcc-cross-initial, gcc-cross-intermediate and gcc-cross may fail to build
232 with the following error message:
234 configure: error: changes in the environment can compromise the build
235 configure: error: run `make distclean' and/or `rm ./config.cache' and start
238 Solution: bitbake -ccleansstate gcc-cross-initial gcc-cross-intermediate
241 5 Building OpenDreambox
243 In the top level directory, there is a Makefile, which is used to set up build
244 directories and to fetch or update all used repositories. The Makefile can be
245 influenced by environment variables, either by specifing them on the
246 command-line or by storing them in a file called conf/make.conf. It is not
247 recommended to edit the Makefile directly in order to avoid conflicts with
250 When the Makefile is run for the first time, the following steps will be
252 * Creation of configuration files
254 * conf/opendreambox.conf
255 * build/${MACHINE}/conf/bblayers.conf
256 * build/${MACHINE}/conf/local.conf
257 * Update or checkout of Git repositories
264 Run make help to get a list of targets of the top level Makefile, together with
267 5.2 Configuration variables
269 5.2.1 BB_NUMBER_THREADS
271 Controls how many BitBake tasks may run at a time. Defaults to the number of
272 cores available on the build system. The number of cores is obtained from
273 /proc/cpuinfo. If this file is unavailable, the default value is 1.
277 Controls the target machine to build packages for. See section 1.2 for a list
278 of supported products.
282 Controls how many processes per recipe make may use. Defaults to the number of
283 cores available on the build system. The number of cores is obtained from
284 /proc/cpuinfo. If this file is unavailable, the default value is 1.
286 NOTE: If you see seemingly random build failures, try setting this variable to
289 5.3 Adding custom layers
291 It is possible to add custom layers to the build system. This can be done
292 globally and per machine. To add a layer globally, edit conf/bblayers-ext.conf.
293 To add a machine-specific layer, edit conf/bblayers-${MACHINE}-ext.conf.
294 Assuming that an additional layer is available at ${HOME}/custom-layer, the
295 entry to add to the file will look like this:
297 BBLAYERS =+ "${HOME}/custom-layer"
299 5.4 Adding custom options
301 It is possible to tweak a lot more options than those used by the Makefile by
302 editing conf/local-ext.conf or conf/local-${MACHINE}-ext.conf.
304 For example, if the firmware shall use the package feed built on the develoment
305 machine, which happens to be 192.168.1.1 and has a webserver configured to
306 point to tmp/deploy/ipk, a line like the following may be added:
308 DISTRO_FEED_URI = "http://192.168.1.1/${DISTRO}/${DISTRO_VERSION}"
310 In general, any variable in OpenEmbedded that uses weak assignment (?=) may be
311 overridden from these files.
313 The following sections list some commonly used options.
315 5.4.1 DISTRO_FEED_PREFIX
317 DISTRO_FEED_PREFIX specifies the name of the package update feed. This name may
318 be arbitarily chosen.
320 Default: DISTRO_FEED_PREFIX = "remote"
322 5.4.2 DISTRO_FEED_URI
324 DISTRO_FEED_URI specifies the URI of the package update feed.
326 Default: DISTRO_FEED_URI = "http://my-distribution.example/remote-feed/"
330 INHERIT specifies bbclasses to include from a configuration file. Usually, this
331 variable gets appended to by using the += operator.
333 The OpenDreambox distribution automatically appends "buildhistory recipe_sanity
336 Default: INHERIT = ""
340 Always build the latest versions of OpenDreambox-related projects from Git:
342 INHERIT += "opendreambox-autorev"
344 Remove temporary files of previous versions of a recipe before a newer version
347 INHERIT += "rm_old_work"
349 Remove temporary files of a recipe after it has been built and packaged
354 5.5 Setting up a build directory
356 To set up a build directory for e.g. DM 500 HD run make MACHINE=dm500hd. If
357 MACHINE=dm500hd has been set in conf/make.conf, you can simply run make with no
358 arguments instead. This will create and initialize the directory build/dm500hd.
360 5.6 Building a firmware image
362 To build a firmware image for e.g. DM 500 HD run make MACHINE=dm500hd image. If
363 MACHINE=dm500hd has been set in conf/make.conf, you can simply run make image
366 5.7 Building a package
368 To build a single package, BitBake has to be used directly. First, the
369 environment has to be set up, in order to make BitBake available to the shell.
370 This can be done with the following command:
374 BitBake must be run from the machine's build directory. For DM 500 HD run:
378 In order to build enigma2, run:
384 6.1 Cross-compilation of external software
386 OpenDreambox provides a script called cross-compile.env. Once run, the script
387 will create the following commands (shell aliases), aiming to ease
388 cross-compilation of external source trees:
389 * oe_autoreconf - Calls OE's version of autoreconf. Useful for projects based
391 * oe_runconf - Calls ./configure with parameters suitable for OE. Useful for
392 projects based on GNU autotools.
393 * oe_runmake - Calls make with parameters suitable for OE. Useful for
394 projects based on GNU autotools or GNU make.
395 * oe_env - Useful to execute arbitrary commands in the OE environment (e.g.
397 * oe_setenv - Exports the OE environment to the currently running shell
400 The script needs to know the target machine, which can be one of the supported
401 products (see 1.2). Because the script adds aliases to your currently running
402 shell session, it has to be invoked using source or . (the dot operator), e.g.:
404 source cross-compile.env dm7020hd
406 The script may be called from any location, but must reside inside the
407 OpenDreambox Git tree. You may want to create a symlink to cross-compile.env
408 somewhere in your PATH.
412 Run scripts/do_stylize.sh on new recipes to ensure proper coding style.
414 6.3 Package architecture
416 Set PACKAGE_ARCH = "${MACHINE_ARCH}" if either condition is met:
417 * The recipe uses COMBINED_FEATURES, MACHINE_FEATURES or DREAMBOX_FEATURES.
418 * The recipe is part of meta-bsp.
420 7 Bug reports and patches
422 Please send bug reports and patches to the Enigma2 development mailing list
423 <enigma2-devel@lists.elitedvb.net>.
425 A comfortable way to create patches is to use git format-patch, after all
426 changes have been committed to your local copy of the repository.