doc/opendreambox.txt

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