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