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