doc/opendreambox.tex: add DM820HD, add HD suffix to DM7080(HD)
[opendreambox.git] / 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}