doc: known issues: eCryptfs
[opendreambox.git] / doc / opendreambox.txt
1 opendreambox
2
3    Andreas Oberritter <obi@opendreambox.org>
4    March 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     1.1 Target audience
53
54    Developers familiar with previous versions of OpenDreambox or OpenEmbedded in
55    general.
56
57     1.2 Supported products
58
59    The current version includes support for the following machines:
60
61    +-----------------------------------+
62    |  ----------  |  ----------------  |
63    |Product name  |Environment variable|
64    |  ----------  |  ----------------  |
65    |DM 500 HD     |MACHINE=dm500hd     |
66    |DM 800 HD PVR |MACHINE=dm800       |
67    |DM 800 HD SE  |MACHINE=dm800se     |
68    |DM 7020 HD    |MACHINE=dm7020hd    |
69    |DM 8000 HD PVR|MACHINE=dm8000      |
70    |  ----------  |  ----------------  |
71    +-----------------------------------+
72
73     1.3 License
74
75    Copyright (c) 2010-2012 Dream Multimedia GmbH, Germany
76                            http://www.dream-multimedia-tv.de/
77    Authors:
78      Andreas Frisch <fraxinas@opendreambox.org>
79      Andreas Monzner <ghost@opendreambox.org>
80      Andreas Oberritter <obi@opendreambox.org>
81      Mladen Horvat <acid-burn@opendreambox.org>
82      Stefan Pluecken <thedoc@opendreambox.org>
83      Stephan Reichholf <reichi@opendreambox.org>
84
85    Permission is hereby granted, free of charge, to any person obtaining a copy
86    of this software and associated documentation files (the "Software"), to deal
87    in the Software without restriction, including without limitation the rights
88    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
89    copies of the Software, and to permit persons to whom the Software is
90    furnished to do so, subject to the following conditions:
91
92    The above copyright notice and this permission notice shall be included in
93    all copies or substantial portions of the Software.
94
95    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
96    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
97    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
98    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
99    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
100    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
101    THE SOFTWARE.
102
103
104     1.4 Obtaining the source code
105
106    OpenDreambox uses the Git version control system. To obtain the source code, it
107    is required to install Git. See http://git-scm.com/.
108
109    To initially download the source into the current directory, issue the
110    following command:
111
112    git clone git://git.opendreambox.org/git/opendreambox.git
113
114     1.5 Quick start
115
116    For the impatient:
117
118    make -C opendreambox image
119
120    If this command fails, prerequisites my be missing. See section 2.
121
122     1.6 Directory structure
123
124    OpenDreambox consists of a set of layers containing build instructions. This
125    meta data is used by BitBake to download and compile source code and to
126    assemble installable software packages and firmware images.
127
128    Currently, there are five layers, ordered by priority from lowest to highest:
129      * openembedded-core
130      * meta-openembedded
131      * meta-opendreambox
132      * meta-bsp/common
133      * meta-bsp/${MACHINE}
134
135    If a recipe for the same package exists in multiple layers, then the higher
136    priority layer takes precedence over the lower priority layer.
137
138    For example, libmad_0.15.1b.bb exists in both meta-openembedded and
139    openembedded-core. The recipe in meta-openembedded will be used, because
140    openembedded-core has lower priority.
141
142    NOTE: This would still be true even if the version of libmad in
143    openembeded-core was higher than the version in meta-openembedded, unless
144    PREFERRED_VERSION_libmad was set to the version in openembedded-core. There is
145    currently no way to prefer a version of a lower priority layer, if the same
146    version is present in a higher priority layer.
147
148       1.6.1 openembedded-core and meta-openembedded
149
150    These directories contain copies of Git repositories from git.openembedded.org,
151    including the OpenEmbedded-Core layer ("meta") and the OpenEmbedded layer
152    ("meta-oe"). They get created automatically when building the distribution for
153    the first time.
154
155    Throughout this document, the combination of these directories will be referred
156    to as OpenEmbedded.
157
158       1.6.2 meta-opendreambox
159
160    This directory contains:
161      * Recipes for packages written specifically for the OpenDreambox distribution
162      * Modifications to recipes from OpenEmbedded
163      * Recipes for software versions older than those available from OpenEmbedded
164      * Recipes for software versions newer than those available from OpenEmbedded
165
166       1.6.3 meta-bsp
167
168    The directory meta-bsp contains Board Support Packages (BSP) for the supported
169    Dreambox models. This includes:
170      * Hardware drivers
171      * Machine specific overrides
172      * The Linux kernel
173      * The boot loader
174      * Splash images
175
176   2 Prerequisites
177
178     2.1 Required software
179
180    The OpenEmbedded project provides a general list of prerequisites for many
181    Linux distributions and also for some other operating systems.
182      * http://www.openembedded.org/index.php/OEandYourDistro
183      * http://www.openembedded.org/index.php/Required\_software
184
185    It is highly recommended to use Linux to build OpenDreambox. In theory, any
186    recent distribution will do, but not many distributions have been verified to
187    build OpenDreambox without errors. Tested distributions include:
188      * Arch Linux 2011.08.19 [amd64]
189      * Debian 6.0 (Squeeze) [i386]
190      * Debian "Testing" (Wheezy) [i386]
191      * Fedora 16 [i386, amd64]
192      * Ubuntu 10.04 LTS (Lucid Lynx) [i386]
193      * Ubuntu 10.10 (Maverick Meerkat) [i386]
194      * Ubuntu 11.10 (Oneiric Ocelot) [amd64]
195      * Ubuntu 12.04 LTS (Precise Pangolin) [i386, amd64]
196
197    Distributions known not to work:
198      * Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.
199
200   3 Major changes since previous releases
201
202     3.1 Changes since release 1.6
203
204      * Recipes were split across multiple layers and categorized.
205      * env.source has been replaced by two files, bitbake.env and
206        cross-compile.env. The former sets a minimal environment that is needed to
207        execute bitbake. The latter creates machine-specific command aliases, in
208        order to compile external software.
209      * All machines share a common tmp directory.
210      * ${MACHINE}/build directories were renamed to build/${MACHINE}.
211      * Kernel packages were renamed from linux-${MACHINE} to linux-dreambox.
212      * Support for machines based on ATI Xilleon or IBM STB was dropped.
213
214   4 Known Issues
215
216      * Building on eCryptfs fails, because it doesn't support sufficiently long
217        filenames (eCryptfs bug #344878).
218
219   5 Building OpenDreambox
220
221    In the top level directory, there is a Makefile, which is used to set up build
222    directories and to fetch or update all used repositories. The Makefile can be
223    influenced by environment variables, either by specifing them on the
224    command-line or by storing them in a file called conf/make.conf. It is not
225    recommended to edit the Makefile directly in order to avoid conflicts with
226    future updates.
227
228    When the Makefile is run for the first time, the following steps will be
229    executed:
230      * Creation of configuration files
231           * bitbake.env
232           * conf/opendreambox.conf
233           * build/${MACHINE}/conf/bblayers.conf
234           * build/${MACHINE}/conf/local.conf
235      * Update or checkout of Git repositories
236           * OpenDreambox
237           * BitBake
238           * OpenEmbedded
239
240     5.1 Makefile targets
241
242    Run make help to get a list of targets of the top level Makefile, together with
243    a brief description.
244
245     5.2 Configuration variables
246
247       5.2.1 BB_NUMBER_THREADS
248
249    Controls how many BitBake tasks may run at a time. Defaults to the number of
250    cores available on the build system. The number of cores is obtained from
251    /proc/cpuinfo. If this file is unavailable, the default value is 1.
252
253       5.2.2 MACHINE
254
255    Controls the target machine to build packages for. See section 1.2 for a list
256    of supported products.
257
258       5.2.3 PARALLEL_MAKE
259
260    Controls how many processes per recipe make may use. Defaults to the number of
261    cores available on the build system. The number of cores is obtained from
262    /proc/cpuinfo. If this file is unavailable, the default value is 1.
263
264    NOTE: If you see seemingly random build failures, try setting this variable to
265    1.
266
267     5.3 Adding custom layers
268
269    It is possible to add custom layers to the build system. This can be done
270    globally and per machine. To add a layer globally, edit conf/bblayers-ext.conf.
271    To add a machine-specific layer, edit conf/bblayers-${MACHINE}-ext.conf.
272    Assuming that an additional layer is available at ${HOME}/custom-layer, the
273    entry to add to the file will look like this:
274
275    BBLAYERS =+ "${HOME}/custom-layer"
276
277     5.4 Adding custom options
278
279    It is possible to tweak a lot more options than those used by the Makefile by
280    editing conf/local-ext.conf or conf/local-${MACHINE}-ext.conf.
281
282    For example, if the firmware shall use the package feed built on the develoment
283    machine, which happens to be 192.168.1.1 and has a webserver configured to
284    point to tmp/deploy/ipk, a line like the following may be added:
285
286    DISTRO_FEED_URI = "http://192.168.1.1/${DISTRO}/${DISTRO_VERSION}"
287
288    In general, any variable in OpenEmbedded that uses weak assignment (?=) may be
289    overridden from these files.
290
291    The following sections list some commonly used options.
292
293       5.4.1 DISTRO_FEED_PREFIX
294
295    DISTRO_FEED_PREFIX specifies the name of the package update feed. This name may
296    be arbitarily chosen.
297
298    Default: DISTRO_FEED_PREFIX = "remote"
299
300       5.4.2 DISTRO_FEED_URI
301
302    DISTRO_FEED_URI specifies the URI of the package update feed.
303
304    Default: DISTRO_FEED_URI = "http://my-distribution.example/remote-feed/"
305
306       5.4.3 INHERIT
307
308    INHERIT specifies bbclasses to include from a configuration file. Usually, this
309    variable gets appended to by using the += operator.
310
311    The OpenDreambox distribution automatically appends "buildhistory recipe_sanity
312    testlab" to INHERIT.
313
314    Default: INHERIT = ""
315
316    Some examples:
317
318    Always build the latest versions of OpenDreambox-related projects from Git:
319
320    INHERIT += "opendreambox-autorev"
321
322    Remove temporary files of previous versions of a recipe before a newer version
323    gets built:
324
325    INHERIT += "rm_old_work"
326
327    Remove temporary files of a recipe after it has been built and packaged
328    successfully.
329
330    INHERIT += "rm_work"
331
332     5.5 Setting up a build directory
333
334    To set up a build directory for e.g. DM 500 HD run make MACHINE=dm500hd. If
335    MACHINE=dm500hd has been set in conf/make.conf, you can simply run make with no
336    arguments instead. This will create and initialize the directory build/dm500hd.
337
338     5.6 Building a firmware image
339
340    To build a firmware image for e.g. DM 500 HD run make MACHINE=dm500hd image. If
341    MACHINE=dm500hd has been set in conf/make.conf, you can simply run make image
342    instead.
343
344     5.7 Building a package
345
346    To build a single package, BitBake has to be used directly. First, the
347    environment has to be set up, in order to make BitBake available to the shell.
348    This can be done with the following command:
349
350    source bitbake.env
351
352    BitBake must be run from the machine's build directory. For DM 500 HD run:
353
354    cd build/dm500hd
355
356    In order to build enigma2, run:
357
358    bitbake enigma2.
359
360   6 Development hints
361
362     6.1 Cross-compilation of external software
363
364    OpenDreambox provides a script called cross-compile.env. Once run, the script
365    will create the following commands (shell aliases), aiming to ease
366    cross-compilation of external source trees:
367      * oe_autoreconf - Calls OE's version of autoreconf. Useful for projects based
368        on GNU autotools.
369      * oe_runconf - Calls ./configure with parameters suitable for OE. Useful for
370        projects based on GNU autotools.
371      * oe_runmake - Calls make with parameters suitable for OE. Useful for
372        projects based on GNU autotools or GNU make.
373      * oe_env - Useful to execute arbitrary commands in the OE environment (e.g.
374        oe_env env).
375      * oe_setenv - Exports the OE environment to the currently running shell
376        session.
377
378    The script needs to know the target machine, which can be one of the supported
379    products (see 1.2). Because the script adds aliases to your currently running
380    shell session, it has to be invoked using source or . (the dot operator), e.g.:
381
382    source cross-compile.env dm7020hd
383
384    The script may be called from any location, but must reside inside the
385    OpenDreambox Git tree. You may want to create a symlink to cross-compile.env
386    somewhere in your PATH.
387
388     6.2 Coding style
389
390    Run scripts/do_stylize.sh on new recipes to ensure proper coding style.
391
392     6.3 Package architecture
393
394    Set PACKAGE_ARCH = "${MACHINE_ARCH}" if either condition is met:
395      * The recipe uses COMBINED_FEATURES, MACHINE_FEATURES or DREAMBOX_FEATURES.
396      * The recipe is part of meta-bsp.
397
398   7 Bug reports and patches
399
400    Please send bug reports and patches to the Enigma2 development mailing list
401    <enigma2-devel@lists.elitedvb.net>.
402
403    A comfortable way to create patches is to use git format-patch, after all
404    changes have been committed to your local copy of the repository.