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