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