doc/opendreambox.txt

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