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