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