doc/opendreambox.tex

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