doc/opendreambox.txt

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