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