doc/opendreambox.tex

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