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