doc/opendreambox.tex

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