opendreambox Andreas Oberritter September 2014 Contents 1 Introduction 1.1 Target audience 1.2 Supported products 1.3 License 1.4 Obtaining the source code 1.5 Quick start 1.6 Directory structure 1.6.1 openembedded-core and meta-openembedded 1.6.2 meta-opendreambox 1.6.3 meta-dreambox 2 Further readings 3 Prerequisites 3.1 Required software 4 Major changes since previous public releases 4.1 Changes since release 1.6 4.2 Changes since release 2.0 5 Known Issues 6 Building OpenDreambox 6.1 Makefile targets 6.2 Configuration variables 6.2.1 BB_NUMBER_THREADS 6.2.2 MACHINE 6.2.3 PARALLEL_MAKE 6.3 Adding custom layers 6.4 Adding custom options 6.4.1 DISTRO_FEED_PREFIX 6.4.2 DISTRO_FEED_URI 6.4.3 INHERIT 6.5 Setting up a build directory 6.6 Building a firmware image 6.7 Building a package 7 Development hints 7.1 Cross-compilation of external software 7.2 Coding style 7.3 Package architecture 8 Bug reports and patches 1 Introduction This document briefly describes the OpenDreambox distribution, an embedded Linux distribution for Set-Top-Boxes manufactured by Dream Property GmbH. OpenDreambox is based on the OpenEmbedded build framework, which uses BitBake to transform build instructions into distributable firmare images and software packages. The current version, OpenDreambox 2.2, is based on the Yocto Project, release 1.5.1 "Dora", an umbrella project for OpenEmbedded and related tools. 1.1 Target audience Developers familiar with previous versions of OpenDreambox or OpenEmbedded in general. 1.2 Supported products The current version includes support for the following products: +-----------------------------------------------------------------------------+ | ---------------------- | ---------------------------------------------- | |Product name |Environment variable | | ---------------------- | ---------------------------------------------- | |DM 500 HD |MACHINE=dm500hd | |DM 500 HD V2 |MACHINE=dm500hdv2 | |DM 800 HD SE |MACHINE=dm800se | |DM 800 HD SE V2 |MACHINE=dm800sev2 | |DM 7020 HD |MACHINE=dm7020hd | |DM 7020 HD V2 |MACHINE=dm7020hdv2 | |DM 7080 |MACHINE=dm7080 | |DM 8000 HD PVR |MACHINE=dm8000 | | ---------------------- | ---------------------------------------------- | +-----------------------------------------------------------------------------+ Note, that not all of these platforms offer enough internal storage to actually flash a generated firmware image. It might be possible to boot from external storage or network, though. 1.3 License Copyright (c) 2010-2014 Dream Property GmbH, Germany http://www.dream-multimedia-tv.de/ Authors: Andreas Frisch Andreas Monzner Andreas Oberritter Mladen Horvat Stefan Pluecken Stephan Reichholf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 1.4 Obtaining the source code OpenDreambox uses the Git version control system. To obtain the source code, it is required to install Git. See http://git-_scm.com/. To initially download the source into the current directory, issue the following command: git clone -b dora git://git.opendreambox.org/git/opendreambox.git The Git repository can be viewed online at: http://git.opendreambox.org/?p=opendreambox.git 1.5 Quick start For the impatient: make -C opendreambox image If this command fails, prerequisites my be missing. See section 3. 1.6 Directory structure OpenDreambox consists of a set of layers containing build instructions. This meta data is used by BitBake to download and compile source code and to assemble installable software packages and firmware images. Currently, these layers are used, ordered by priority from highest to lowest: * meta-dreambox * meta-opendreambox * meta-qt5 * meta-openembedded/meta-oe * meta-openembedded/meta-filesystems * meta-openembedded/meta-initramfs * meta-openembedded/meta-multimedia * meta-openembedded/meta-networking * meta-openembedded/meta-ruby * openembedded-core/meta If a recipe for the same package exists in multiple layers, then the higher priority layer takes precedence over the lower priority layer. For example, if libmad_0.15.1b.bb existed in both meta-openembedded and openembedded-core, the recipe in meta-openembedded would be used, because openembedded-core has lower priority. NOTE: This would still be true even if the version of libmad in openembeded-core was higher than the version in meta-openembedded, unless PREFERRED_VERSION_libmad was set to the version in openembedded-core. There is currently no way to prefer a version of a lower priority layer, if the same version is present in a higher priority layer. 1.6.1 openembedded-core and meta-openembedded These directories contain copies of Git repositories from git.openembedded.org, including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They get created automatically when building the distribution for the first time. Throughout this document, the combination of these directories will be referred to as OpenEmbedded. The latest changes to these Git repositories can be seen at: http://git.openembedded.org/openembedded-_core-_contrib/log/?h=obi/dora http://git.openembedded.org/meta-_openembedded-_contrib/log/?h=obi/dora 1.6.2 meta-opendreambox This directory contains: * Recipes for packages written specifically for the OpenDreambox distribution * Modifications to recipes from OpenEmbedded * Recipes for software versions older than those available from OpenEmbedded * Recipes for software versions newer than those available from OpenEmbedded 1.6.3 meta-dreambox The directory meta-dreambox contains Board Support Packages (BSP) for the supported Dreambox models. This includes: * Hardware drivers * Machine specific overrides * The Linux kernel * The boot loader * Splash images 2 Further readings * The Yocto Project Reference Manual: https://www.yoctoproject.org/docs/1.5.1/ref-_manual/ref-_manual.html 3 Prerequisites 3.1 Required software The OpenEmbedded project provides a general list of prerequisites for many Linux distributions and also for some other operating systems. * http://www.openembedded.org/wiki/Getting\_started#Required\_software It is highly recommended to use Linux to build OpenDreambox. In theory, any recent distribution will do, but not many distributions have been verified to build OpenDreambox without errors. Tested distributions include: * Debian 7.6 "Wheezy" [i386, amd64] * Ubuntu 14.04.1 LTS "Trusty Tahr" [amd64] 4 Major changes since previous public releases 4.1 Changes since release 1.6 * Recipes were split across multiple layers and categorized. * env.source has been replaced by two files, bitbake.env and cross-compile.env. The former sets a minimal environment that is needed to execute bitbake. The latter creates machine-specific command aliases, in order to compile external software. * All machines share a common tmp directory. * ${MACHINE}/build directories were renamed to build/${MACHINE}. * Kernel packages were renamed from linux-${MACHINE} to linux-dreambox. * Support for machines based on ATI Xilleon or IBM STB was dropped. 4.2 Changes since release 2.0 * Added support for DM7080. * If a recipe changes, the corresponding packages will be rebuilt automatically, in contrast to required manual PR bumps in the past. * Each machine uses its own tmp directory again, like before 2.0. However, there is a shared sstate-cache, which allows to share already compiled data between compatible machines. This impacts performance and size of the build system, but improves reliability and consistency across builds. * Support for machines without FPU and kernel versions below 3.x was dropped (DM800). * Layers under meta-bsp were combined into meta-dreambox. * Default package format switched from ipk (opkg) to deb (dpkg + apt). * dreambox-image was renamed to include the package format (dreambox-image-deb). 5 Known Issues None. 6 Building OpenDreambox In the top level directory, there is a Makefile, which is used to set up build directories and to fetch or update all used repositories. The Makefile can be influenced by environment variables, either by specifing them on the command-line or by storing them in a file called conf/make.conf. It is not recommended to edit the Makefile directly in order to avoid conflicts with future updates. When the Makefile is run for the first time, the following steps will be executed: * Creation of configuration files * bitbake.env * conf/opendreambox.conf * build/${MACHINE}/conf/bblayers.conf * build/${MACHINE}/conf/local.conf * Update or checkout of Git repositories * OpenDreambox * BitBake * OpenEmbedded 6.1 Makefile targets Run make help to get a list of targets of the top level Makefile, together with a brief description. 6.2 Configuration variables 6.2.1 BB_NUMBER_THREADS Controls how many BitBake tasks may run at a time. Defaults to the number of cores available on the build system. 6.2.2 MACHINE Controls the target machine to build packages for. See section 1.2 for a list of supported products. 6.2.3 PARALLEL_MAKE Controls how many processes per recipe make may use. Defaults to the number of cores available on the build system. 6.3 Adding custom layers It is possible to add custom layers to the build system. This can be done globally and per machine. To add a layer globally, edit conf/bblayers-ext.conf. To add a machine-specific layer, edit conf/bblayers-${MACHINE}-ext.conf. Assuming that an additional layer is available at ${HOME}/custom-layer, the entry to add to the file will look like this: BBLAYERS =+ "${HOME}/custom-layer" 6.4 Adding custom options It is possible to tweak a lot more options than those used by the Makefile by editing conf/local-ext.conf or conf/local-${MACHINE}-ext.conf. For example, if the firmware shall use the package feed built on the develoment machine, which happens to be 192.168.1.1 and has a webserver configured to point to tmp/deploy/ipk, a line like the following may be added: DISTRO_FEED_URI = "http://192.168.1.1/${DISTRO}/${DISTRO_VERSION}" In general, any variable in OpenEmbedded that uses weak assignment (?=) may be overridden from these files. The following sections list some commonly used options. 6.4.1 DISTRO_FEED_PREFIX DISTRO_FEED_PREFIX specifies the name of the package update feed. This name may be chosen arbitarily. Default: DISTRO_FEED_PREFIX = "remote" 6.4.2 DISTRO_FEED_URI DISTRO_FEED_URI specifies the URI of the package update feed. Default: DISTRO_FEED_URI = "http://my-distribution.example/remote-feed/" 6.4.3 INHERIT INHERIT specifies bbclasses to include from a configuration file. Usually, this variable gets appended to by using the += operator. The OpenDreambox distribution automatically appends "buildhistory recipe_sanity" to INHERIT. Default: INHERIT = "" Some examples: Always build the latest versions of OpenDreambox-related projects from Git: INHERIT += "opendreambox-autorev" Remove temporary files of previous versions of a recipe before a newer version gets built: INHERIT += "rm_old_work" 6.5 Setting up a build directory To set up a build directory for e.g. DM 7080 run make MACHINE=dm7080. If MACHINE=dm7080 has been set in conf/make.conf (default), you can simply run make with no arguments instead. This will create and initialize the directory build/dm7080. 6.6 Building a firmware image To build a firmware image for e.g. DM 7080 run make MACHINE=dm7080 image. If MACHINE=dm7080 has been set in conf/make.conf (default), you can simply run make image instead. 6.7 Building a package To build a single package, BitBake has to be used directly. First, the environment has to be set up, in order to make BitBake available to the shell. This can be done with the following command: source bitbake.env BitBake must be run from the machine's build directory. For DM 7080 run: cd build/dm7080 In order to build enigma2, run: bitbake enigma2. 7 Development hints 7.1 Cross-compilation of external software OpenDreambox provides a script called cross-compile.env. Once run, the script will create the following commands (shell aliases), aiming to ease cross-compilation of external source trees: * oe_autoreconf - Calls OE's version of autoreconf. Useful for projects based on GNU autotools. * oe_runconf - Calls ./configure with parameters suitable for OE. Useful for projects based on GNU autotools. * oe_runmake - Calls make with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make. * oe_env - Useful to execute arbitrary commands in the OE environment (e.g. oe_env env). * oe_setenv - Exports the OE environment to the currently running shell session. The script needs to know the target machine, which can be one of the supported products (see 1.2). Because the script adds aliases to your currently running shell session, it has to be invoked using source or . (the dot operator), e.g.: source cross-compile.env dm7080 The script may be called from any location, but must reside inside the OpenDreambox Git tree. You may want to create a symlink to cross-compile.env somewhere in your PATH. 7.2 Coding style Run scripts/do_stylize.sh on new recipes to ensure proper coding style. 7.3 Package architecture Set PACKAGE_ARCH = "${MACHINE_ARCH}" if either condition is met: * The recipe uses COMBINED_FEATURES, MACHINE_FEATURES or DREAMBOX_FEATURES. * The recipe uses COMPATIBLE_MACHINE. * The recipe is part of meta-dreambox. 8 Bug reports and patches Please send bug reports and patches to the Enigma2 development mailing list . A comfortable way to create patches is to use git format-patch, after all changes have been committed to your local copy of the repository.