doc: from now on, please use "git clone -b denzil git://git.opendreambox.org/git...
[opendreambox.git] / doc / opendreambox.txt
1 opendreambox
2
3    Andreas Oberritter <obi@opendreambox.org>
4    May 2012
5
6   Contents
7
8    1 Introduction
9     1.1 Target audience
10     1.2 Supported products
11     1.3 License
12     1.4 Obtaining the source code
13     1.5 Quick start
14     1.6 Directory structure
15      1.6.1 openembedded-core and meta-openembedded
16      1.6.2 meta-opendreambox
17      1.6.3 meta-bsp
18    2 Prerequisites
19     2.1 Required software
20    3 Major changes since previous releases
21     3.1 Changes since release 1.6
22    4 Known Issues
23    5 Building OpenDreambox
24     5.1 Makefile targets
25     5.2 Configuration variables
26      5.2.1 BB_NUMBER_THREADS
27      5.2.2 MACHINE
28      5.2.3 PARALLEL_MAKE
29     5.3 Adding custom layers
30     5.4 Adding custom options
31      5.4.1 DISTRO_FEED_PREFIX
32      5.4.2 DISTRO_FEED_URI
33      5.4.3 INHERIT
34     5.5 Setting up a build directory
35     5.6 Building a firmware image
36     5.7 Building a package
37    6 Development hints
38     6.1 Cross-compilation of external software
39     6.2 Coding style
40     6.3 Package architecture
41    7 Bug reports and patches
42
43   1 Introduction
44
45    This document briefly describes the OpenDreambox distribution, an embedded
46    Linux distribution for Set-Top-Boxes manufactured by Dream Multimedia GmbH.
47
48    OpenDreambox is based on the OpenEmbedded build framework, which uses BitBake
49    to transform build instructions into distributable firmare images and software
50    packages.
51
52    The current version, OpenDreambox 2.0, is based on OpenEmbedded "denzil".
53
54     1.1 Target audience
55
56    Developers familiar with previous versions of OpenDreambox or OpenEmbedded in
57    general.
58
59     1.2 Supported products
60
61    The current version includes support for the following machines:
62
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    +-----------------------------------+
74
75     1.3 License
76
77    Copyright (c) 2010-2012 Dream Multimedia GmbH, Germany
78                            http://www.dream-multimedia-tv.de/
79    Authors:
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>
86
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:
93
94    The above copyright notice and this permission notice shall be included in
95    all copies or substantial portions of the Software.
96
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
103    THE SOFTWARE.
104
105
106     1.4 Obtaining the source code
107
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/.
110
111    To initially download the source into the current directory, issue the
112    following command:
113
114    git clone -b denzil git://git.opendreambox.org/git/opendreambox.git
115
116    The Git repository can be viewed online at:
117
118    http://cgit.opendreambox.org/opendreambox.git
119
120     1.5 Quick start
121
122    For the impatient:
123
124    make -C opendreambox image
125
126    If this command fails, prerequisites my be missing. See section 2.
127
128     1.6 Directory structure
129
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.
133
134    Currently, there are five layers, ordered by priority from lowest to highest:
135      * openembedded-core
136      * meta-openembedded
137      * meta-opendreambox
138      * meta-bsp/common
139      * meta-bsp/${MACHINE}
140
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.
143
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.
147
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.
153
154       1.6.1 openembedded-core and meta-openembedded
155
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
159    the first time.
160
161    Throughout this document, the combination of these directories will be referred
162    to as OpenEmbedded.
163
164    The latest changes to these Git repositories can be seen at:
165
166    http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/current
167
168    http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/current
169
170       1.6.2 meta-opendreambox
171
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
177
178       1.6.3 meta-bsp
179
180    The directory meta-bsp contains Board Support Packages (BSP) for the supported
181    Dreambox models. This includes:
182      * Hardware drivers
183      * Machine specific overrides
184      * The Linux kernel
185      * The boot loader
186      * Splash images
187
188   2 Prerequisites
189
190     2.1 Required software
191
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
196
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]
207
208    Distributions known not to work:
209      * Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.
210
211   3 Major changes since previous releases
212
213     3.1 Changes since release 1.6
214
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.
224
225   4 Known Issues
226
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:
233
234        configure: error: changes in the environment can compromise the build
235        configure: error: run `make distclean' and/or `rm ./config.cache' and start
236        over
237
238        Solution: bitbake -ccleansstate gcc-cross-initial gcc-cross-intermediate
239        gcc-cross
240
241   5 Building OpenDreambox
242
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
248    future updates.
249
250    When the Makefile is run for the first time, the following steps will be
251    executed:
252      * Creation of configuration files
253           * bitbake.env
254           * conf/opendreambox.conf
255           * build/${MACHINE}/conf/bblayers.conf
256           * build/${MACHINE}/conf/local.conf
257      * Update or checkout of Git repositories
258           * OpenDreambox
259           * BitBake
260           * OpenEmbedded
261
262     5.1 Makefile targets
263
264    Run make help to get a list of targets of the top level Makefile, together with
265    a brief description.
266
267     5.2 Configuration variables
268
269       5.2.1 BB_NUMBER_THREADS
270
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.
274
275       5.2.2 MACHINE
276
277    Controls the target machine to build packages for. See section 1.2 for a list
278    of supported products.
279
280       5.2.3 PARALLEL_MAKE
281
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.
285
286    NOTE: If you see seemingly random build failures, try setting this variable to
287    1.
288
289     5.3 Adding custom layers
290
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:
296
297    BBLAYERS =+ "${HOME}/custom-layer"
298
299     5.4 Adding custom options
300
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.
303
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:
307
308    DISTRO_FEED_URI = "http://192.168.1.1/${DISTRO}/${DISTRO_VERSION}"
309
310    In general, any variable in OpenEmbedded that uses weak assignment (?=) may be
311    overridden from these files.
312
313    The following sections list some commonly used options.
314
315       5.4.1 DISTRO_FEED_PREFIX
316
317    DISTRO_FEED_PREFIX specifies the name of the package update feed. This name may
318    be arbitarily chosen.
319
320    Default: DISTRO_FEED_PREFIX = "remote"
321
322       5.4.2 DISTRO_FEED_URI
323
324    DISTRO_FEED_URI specifies the URI of the package update feed.
325
326    Default: DISTRO_FEED_URI = "http://my-distribution.example/remote-feed/"
327
328       5.4.3 INHERIT
329
330    INHERIT specifies bbclasses to include from a configuration file. Usually, this
331    variable gets appended to by using the += operator.
332
333    The OpenDreambox distribution automatically appends "buildhistory recipe_sanity
334    testlab" to INHERIT.
335
336    Default: INHERIT = ""
337
338    Some examples:
339
340    Always build the latest versions of OpenDreambox-related projects from Git:
341
342    INHERIT += "opendreambox-autorev"
343
344    Remove temporary files of previous versions of a recipe before a newer version
345    gets built:
346
347    INHERIT += "rm_old_work"
348
349    Remove temporary files of a recipe after it has been built and packaged
350    successfully.
351
352    INHERIT += "rm_work"
353
354     5.5 Setting up a build directory
355
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.
359
360     5.6 Building a firmware image
361
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
364    instead.
365
366     5.7 Building a package
367
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:
371
372    source bitbake.env
373
374    BitBake must be run from the machine's build directory. For DM 500 HD run:
375
376    cd build/dm500hd
377
378    In order to build enigma2, run:
379
380    bitbake enigma2.
381
382   6 Development hints
383
384     6.1 Cross-compilation of external software
385
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
390        on GNU autotools.
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.
396        oe_env env).
397      * oe_setenv - Exports the OE environment to the currently running shell
398        session.
399
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.:
403
404    source cross-compile.env dm7020hd
405
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.
409
410     6.2 Coding style
411
412    Run scripts/do_stylize.sh on new recipes to ensure proper coding style.
413
414     6.3 Package architecture
415
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.
419
420   7 Bug reports and patches
421
422    Please send bug reports and patches to the Enigma2 development mailing list
423    <enigma2-devel@lists.elitedvb.net>.
424
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.