python-twisted: remove version 12, meta-oe has 13.2.0
[opendreambox.git] / doc / opendreambox.txt
1 opendreambox
2
3    Andreas Oberritter <obi@opendreambox.org>
4    August 2014
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 Further readings
19    3 Prerequisites
20     3.1 Required software
21    4 Major changes since previous public releases
22     4.1 Changes since release 1.6
23     4.2 Changes since release 2.0
24    5 Known Issues
25    6 Building OpenDreambox
26     6.1 Makefile targets
27     6.2 Configuration variables
28      6.2.1 BB_NUMBER_THREADS
29      6.2.2 MACHINE
30      6.2.3 PARALLEL_MAKE
31     6.3 Adding custom layers
32     6.4 Adding custom options
33      6.4.1 DISTRO_FEED_PREFIX
34      6.4.2 DISTRO_FEED_URI
35      6.4.3 INHERIT
36     6.5 Setting up a build directory
37     6.6 Building a firmware image
38     6.7 Building a package
39    7 Development hints
40     7.1 Cross-compilation of external software
41     7.2 Coding style
42     7.3 Package architecture
43    8 Bug reports and patches
44
45   1 Introduction
46
47    This document briefly describes the OpenDreambox distribution, an embedded
48    Linux distribution for Set-Top-Boxes manufactured by Dream Property GmbH.
49
50    OpenDreambox is based on the OpenEmbedded build framework, which uses BitBake
51    to transform build instructions into distributable firmare images and software
52    packages.
53
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.
56
57     1.1 Target audience
58
59    Developers familiar with previous versions of OpenDreambox or OpenEmbedded in
60    general.
61
62     1.2 Supported products
63
64    The current version includes support for the following products:
65
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    +-----------------------------------------------------------------------------+
80
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.
84
85     1.3 License
86
87    Copyright (c) 2010-2014 Dream Property GmbH, Germany
88                            http://www.dream-multimedia-tv.de/
89    Authors:
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>
96
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:
103
104    The above copyright notice and this permission notice shall be included in
105    all copies or substantial portions of the Software.
106
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
113    THE SOFTWARE.
114
115
116     1.4 Obtaining the source code
117
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/.
120
121    To initially download the source into the current directory, issue the
122    following command:
123
124    git clone -b dora git://git.opendreambox.org/git/opendreambox.git
125
126    The Git repository can be viewed online at:
127
128    http://cgit.opendreambox.org/opendreambox.git
129
130     1.5 Quick start
131
132    For the impatient:
133
134    make -C opendreambox image
135
136    If this command fails, prerequisites my be missing. See section 3.
137
138     1.6 Directory structure
139
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.
143
144    Currently, these layers are used, ordered by priority from highest to lowest:
145      * meta-bsp/${MACHINE}
146      * meta-bsp/common
147      * meta-opendreambox
148      * meta-qt5
149      * meta-openembedded/meta-oe
150      * meta-openembedded/meta-filesystems
151      * meta-openembedded/meta-initramfs
152      * meta-openembedded/meta-multimedia
153      * meta-openembedded/meta-networking
154      * meta-openembedded/meta-ruby
155      * openembedded-core/meta
156
157    If a recipe for the same package exists in multiple layers, then the higher
158    priority layer takes precedence over the lower priority layer.
159
160    For example, if libmad_0.15.1b.bb existed in both meta-openembedded and
161    openembedded-core, the recipe in meta-openembedded would be used, because
162    openembedded-core has lower priority.
163
164    NOTE: This would still be true even if the version of libmad in
165    openembeded-core was higher than the version in meta-openembedded, unless
166    PREFERRED_VERSION_libmad was set to the version in openembedded-core. There is
167    currently no way to prefer a version of a lower priority layer, if the same
168    version is present in a higher priority layer.
169
170       1.6.1 openembedded-core and meta-openembedded
171
172    These directories contain copies of Git repositories from git.openembedded.org,
173    including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They
174    get created automatically when building the distribution for the first time.
175
176    Throughout this document, the combination of these directories will be referred
177    to as OpenEmbedded.
178
179    The latest changes to these Git repositories can be seen at:
180
181    http://git.openembedded.org/openembedded-_core-_contrib/log/?h=obi/dora
182
183    http://git.openembedded.org/meta-_openembedded-_contrib/log/?h=obi/dora
184
185       1.6.2 meta-opendreambox
186
187    This directory contains:
188      * Recipes for packages written specifically for the OpenDreambox distribution
189      * Modifications to recipes from OpenEmbedded
190      * Recipes for software versions older than those available from OpenEmbedded
191      * Recipes for software versions newer than those available from OpenEmbedded
192
193       1.6.3 meta-bsp
194
195    The directory meta-bsp contains Board Support Packages (BSP) for the supported
196    Dreambox models. This includes:
197      * Hardware drivers
198      * Machine specific overrides
199      * The Linux kernel
200      * The boot loader
201      * Splash images
202
203   2 Further readings
204
205      * The Yocto Project Reference Manual:
206        https://www.yoctoproject.org/docs/1.5.1/ref-_manual/ref-_manual.html
207
208   3 Prerequisites
209
210     3.1 Required software
211
212    The OpenEmbedded project provides a general list of prerequisites for many
213    Linux distributions and also for some other operating systems.
214      * http://www.openembedded.org/wiki/Getting\_started#Required\_software
215
216    It is highly recommended to use Linux to build OpenDreambox. In theory, any
217    recent distribution will do, but not many distributions have been verified to
218    build OpenDreambox without errors. Tested distributions include:
219      * Debian 7.6 "Wheezy" [amd64]
220      * Ubuntu 14.04.1 LTS "Trusty Tahr" [amd64]
221
222   4 Major changes since previous public releases
223
224     4.1 Changes since release 1.6
225
226      * Recipes were split across multiple layers and categorized.
227      * env.source has been replaced by two files, bitbake.env and
228        cross-compile.env. The former sets a minimal environment that is needed to
229        execute bitbake. The latter creates machine-specific command aliases, in
230        order to compile external software.
231      * All machines share a common tmp directory.
232      * ${MACHINE}/build directories were renamed to build/${MACHINE}.
233      * Kernel packages were renamed from linux-${MACHINE} to linux-dreambox.
234      * Support for machines based on ATI Xilleon or IBM STB was dropped.
235
236     4.2 Changes since release 2.0
237
238      * Added support for DM7080.
239      * If a recipe changes, the corresponding packages will be rebuilt
240        automatically, in contrast to required manual PR bumps in the past.
241      * Each machine uses its own tmp directory again, like before 2.0. However,
242        there is a shared sstate-cache, which allows to share already compiled data
243        between compatible machines. This impacts performance and size of the build
244        system, but improves reliability and consistency across builds.
245      * Support for machines without FPU and kernel versions below 3.x was dropped
246        (DM800).
247
248   5 Known Issues
249
250    None.
251
252   6 Building OpenDreambox
253
254    In the top level directory, there is a Makefile, which is used to set up build
255    directories and to fetch or update all used repositories. The Makefile can be
256    influenced by environment variables, either by specifing them on the
257    command-line or by storing them in a file called conf/make.conf. It is not
258    recommended to edit the Makefile directly in order to avoid conflicts with
259    future updates.
260
261    When the Makefile is run for the first time, the following steps will be
262    executed:
263      * Creation of configuration files
264           * bitbake.env
265           * conf/opendreambox.conf
266           * build/${MACHINE}/conf/bblayers.conf
267           * build/${MACHINE}/conf/local.conf
268      * Update or checkout of Git repositories
269           * OpenDreambox
270           * BitBake
271           * OpenEmbedded
272
273     6.1 Makefile targets
274
275    Run make help to get a list of targets of the top level Makefile, together with
276    a brief description.
277
278     6.2 Configuration variables
279
280       6.2.1 BB_NUMBER_THREADS
281
282    Controls how many BitBake tasks may run at a time. Defaults to the number of
283    cores available on the build system.
284
285       6.2.2 MACHINE
286
287    Controls the target machine to build packages for. See section 1.2 for a list
288    of supported products.
289
290       6.2.3 PARALLEL_MAKE
291
292    Controls how many processes per recipe make may use. Defaults to the number of
293    cores available on the build system.
294
295     6.3 Adding custom layers
296
297    It is possible to add custom layers to the build system. This can be done
298    globally and per machine. To add a layer globally, edit conf/bblayers-ext.conf.
299    To add a machine-specific layer, edit conf/bblayers-${MACHINE}-ext.conf.
300    Assuming that an additional layer is available at ${HOME}/custom-layer, the
301    entry to add to the file will look like this:
302
303    BBLAYERS =+ "${HOME}/custom-layer"
304
305     6.4 Adding custom options
306
307    It is possible to tweak a lot more options than those used by the Makefile by
308    editing conf/local-ext.conf or conf/local-${MACHINE}-ext.conf.
309
310    For example, if the firmware shall use the package feed built on the develoment
311    machine, which happens to be 192.168.1.1 and has a webserver configured to
312    point to tmp/deploy/ipk, a line like the following may be added:
313
314    DISTRO_FEED_URI = "http://192.168.1.1/${DISTRO}/${DISTRO_VERSION}"
315
316    In general, any variable in OpenEmbedded that uses weak assignment (?=) may be
317    overridden from these files.
318
319    The following sections list some commonly used options.
320
321       6.4.1 DISTRO_FEED_PREFIX
322
323    DISTRO_FEED_PREFIX specifies the name of the package update feed. This name may
324    be chosen arbitarily.
325
326    Default: DISTRO_FEED_PREFIX = "remote"
327
328       6.4.2 DISTRO_FEED_URI
329
330    DISTRO_FEED_URI specifies the URI of the package update feed.
331
332    Default: DISTRO_FEED_URI = "http://my-distribution.example/remote-feed/"
333
334       6.4.3 INHERIT
335
336    INHERIT specifies bbclasses to include from a configuration file. Usually, this
337    variable gets appended to by using the += operator.
338
339    The OpenDreambox distribution automatically appends "buildhistory
340    recipe_sanity" to INHERIT.
341
342    Default: INHERIT = ""
343
344    Some examples:
345
346    Always build the latest versions of OpenDreambox-related projects from Git:
347
348    INHERIT += "opendreambox-autorev"
349
350    Remove temporary files of previous versions of a recipe before a newer version
351    gets built:
352
353    INHERIT += "rm_old_work"
354
355     6.5 Setting up a build directory
356
357    To set up a build directory for e.g. DM 7080 run make MACHINE=dm7080. If
358    MACHINE=dm7080 has been set in conf/make.conf (default), you can simply run
359    make with no arguments instead. This will create and initialize the directory
360    build/dm7080.
361
362     6.6 Building a firmware image
363
364    To build a firmware image for e.g. DM 7080 run make MACHINE=dm7080 image. If
365    MACHINE=dm7080 has been set in conf/make.conf (default), you can simply run
366    make image instead.
367
368     6.7 Building a package
369
370    To build a single package, BitBake has to be used directly. First, the
371    environment has to be set up, in order to make BitBake available to the shell.
372    This can be done with the following command:
373
374    source bitbake.env
375
376    BitBake must be run from the machine's build directory. For DM 7080 run:
377
378    cd build/dm7080
379
380    In order to build enigma2, run:
381
382    bitbake enigma2.
383
384   7 Development hints
385
386     7.1 Cross-compilation of external software
387
388    OpenDreambox provides a script called cross-compile.env. Once run, the script
389    will create the following commands (shell aliases), aiming to ease
390    cross-compilation of external source trees:
391      * oe_autoreconf - Calls OE's version of autoreconf. Useful for projects based
392        on GNU autotools.
393      * oe_runconf - Calls ./configure with parameters suitable for OE. Useful for
394        projects based on GNU autotools.
395      * oe_runmake - Calls make with parameters suitable for OE. Useful for
396        projects based on GNU autotools or GNU make.
397      * oe_env - Useful to execute arbitrary commands in the OE environment (e.g.
398        oe_env env).
399      * oe_setenv - Exports the OE environment to the currently running shell
400        session.
401
402    The script needs to know the target machine, which can be one of the supported
403    products (see 1.2). Because the script adds aliases to your currently running
404    shell session, it has to be invoked using source or . (the dot operator), e.g.:
405
406    source cross-compile.env dm7080
407
408    The script may be called from any location, but must reside inside the
409    OpenDreambox Git tree. You may want to create a symlink to cross-compile.env
410    somewhere in your PATH.
411
412     7.2 Coding style
413
414    Run scripts/do_stylize.sh on new recipes to ensure proper coding style.
415
416     7.3 Package architecture
417
418    Set PACKAGE_ARCH = "${MACHINE_ARCH}" if either condition is met:
419      * The recipe uses COMBINED_FEATURES, MACHINE_FEATURES or DREAMBOX_FEATURES.
420      * The recipe is part of meta-bsp.
421
422   8 Bug reports and patches
423
424    Please send bug reports and patches to the Enigma2 development mailing list
425    <enigma2-devel@lists.elitedvb.net>.
426
427    A comfortable way to create patches is to use git format-patch, after all
428    changes have been committed to your local copy of the repository.