doc: add version, add gitwebs
[opendreambox.git] / doc / opendreambox.tex
1 %
2 % Copyright (c) 2010-2012 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{May 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
63     The current version, OpenDreambox 2.0, is based on OpenEmbedded "denzil".
64   \end{flushleft}
65
66   \subsection{Target audience}
67     \begin{flushleft}
68       Developers familiar with previous versions of OpenDreambox or OpenEmbedded
69       in general.
70     \end{flushleft}
71
72   \subsection{Supported products}
73     \label{products}
74     \begin{flushleft}
75       The current version includes support for the following machines:
76
77         \begin{tabular}{ | l | l | }
78           \hline
79           \textbf{Product name} & \textbf{Environment variable} \\ \hline
80           & \\
81           DM 500 HD & \shell{MACHINE=dm500hd} \\
82           DM 800 HD PVR & \shell{MACHINE=dm800} \\
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-2012 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 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 five layers, ordered by priority from lowest to
149     highest:
150
151     \begin{itemize}
152       \item \shell{openembedded-core}
153       \item \shell{meta-openembedded}
154       \item \shell{meta-opendreambox}
155       \item \shell{meta-bsp/common}
156       \item \shell{meta-bsp/\$\{MACHINE\}}
157     \end{itemize}
158
159     If a recipe for the same package exists in multiple layers,
160     then the higher priority layer takes precedence over the lower priority
161     layer.
162
163     For example, \shell{libmad\_0.15.1b.bb} exists in both
164     \shell{meta-openembedded} and \shell{openembedded-core}. The recipe in
165     \shell{meta-openembedded} will be used, because \shell{openembedded-core}
166     has lower priority.
167
168     \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
169     \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
170     unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
171     There is currently no way to prefer a version of a lower priority layer, if the
172     same version is present in a higher priority layer.
173
174     \subsubsection{openembedded-core and meta-openembedded}
175        These directories contain copies of Git repositories from git.openembedded.org, including
176        the OpenEmbedded-Core layer ("meta") and the OpenEmbedded layer ("meta-oe"). They get created
177        automatically when building the distribution for the first time.
178
179        Throughout this document, the combination of these directories will be
180        referred to as OpenEmbedded.
181
182        The latest changes to these Git repositories can be seen at:
183
184        \url{http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/current}
185
186        \url{http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/current}
187
188     \subsubsection{meta-opendreambox}
189       This directory contains:
190
191       \begin{itemize}
192         \item Recipes for packages written specifically for the OpenDreambox distribution
193         \item Modifications to recipes from OpenEmbedded
194         \item Recipes for software versions older than those available from OpenEmbedded
195         \item Recipes for software versions newer than those available from OpenEmbedded
196       \end{itemize}
197
198     \subsubsection{meta-bsp}
199       The directory \shell{meta-bsp} contains Board Support Packages (BSP)
200       for the supported Dreambox models. This includes:
201
202       \begin{itemize}
203         \item Hardware drivers
204         \item Machine specific overrides
205         \item The Linux kernel
206         \item The boot loader
207         \item Splash images
208       \end{itemize}
209
210 \section{Prerequisites}
211   \label{prerequisites}
212
213   \subsection{Required software}
214
215    The OpenEmbedded project provides a general list of prerequisites for
216    many Linux distributions and also for some other operating systems.
217
218    \begin{itemize}
219      \item \url{http://www.openembedded.org/index.php/OEandYourDistro}
220      \item \url{http://www.openembedded.org/index.php/Required\_software}
221    \end{itemize}
222
223    It is highly recommended to use Linux to build OpenDreambox. In theory,
224    any recent distribution will do, but not many distributions have been
225    verified to build OpenDreambox without errors. Tested distributions
226    include:
227
228    \begin{itemize}
229      \item Arch Linux 2011.08.19 [amd64]
230      \item Debian 6.0 (Squeeze) [i386]
231      \item Debian "Testing" (Wheezy) [i386]
232      \item Fedora 16 [i386, amd64]
233      \item Ubuntu 10.04 LTS (Lucid Lynx) [i386]
234      \item Ubuntu 11.10 (Oneiric Ocelot) [amd64]
235      \item Ubuntu 12.04 LTS (Precise Pangolin) [i386, amd64]
236    \end{itemize}
237
238    Distributions known not to work:
239
240    \begin{itemize}
241      \item Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.
242    \end{itemize}
243
244 \pagebreak
245
246 \section{Major changes since previous releases}
247
248   \subsection{Changes since release 1.6}
249     \begin{itemize}
250       \item Recipes were split across multiple layers and categorized.
251       \item \shell{env.source} has been replaced by two files,
252         \shell{bitbake.env} and \shell{cross-compile.env}. The former sets a minimal
253         environment that is needed to execute bitbake. The latter creates
254         machine-specific command aliases, in order to compile external software.
255       \item All machines share a common \shell{tmp} directory.
256       \item \shell{\$\{MACHINE\}/build} directories were renamed to \shell{build/\$\{MACHINE\}}.
257       \item Kernel packages were renamed from \shell{linux-\$\{MACHINE\}} to \shell{linux-dreambox}.
258       \item Support for machines based on ATI Xilleon or IBM STB was dropped.
259     \end{itemize}
260
261 \section{Known Issues}
262
263   \begin{itemize}
264     \item Building on eCryptfs fails, because it doesn't support sufficiently long filenames (\href{https://bugs.launchpad.net/ecryptfs/+bug/344878}{eCryptfs bug \#344878}).
265   \end{itemize}
266
267 \pagebreak
268
269 \section{Building OpenDreambox}
270
271   In the top level directory, there is a \shell{Makefile}, which is used to
272   set up build directories and to fetch or update all used repositories.
273   The Makefile can be influenced by environment variables, either
274   by specifing them on the command-line or by storing them in a file called
275   \shell{conf/make.conf}. It is not recommended to edit the \shell{Makefile} directly
276   in order to avoid conflicts with future updates.
277
278   When the \shell{Makefile} is run for the first time, the following steps will
279   be executed:
280
281   \begin{itemize}
282     \item Creation of configuration files
283       \begin{itemize}
284         \item \shell{bitbake.env}
285         \item \shell{conf/opendreambox.conf}
286         \item \shell{build/\$\{MACHINE\}/conf/bblayers.conf}
287         \item \shell{build/\$\{MACHINE\}/conf/local.conf}
288       \end{itemize}
289     \item Update or checkout of Git repositories
290       \begin{itemize}
291         \item OpenDreambox
292         \item BitBake
293         \item OpenEmbedded
294       \end{itemize}
295   \end{itemize}
296
297   \subsection{Makefile targets}
298     Run \shell{make help} to get a list of targets of the top level Makefile, together with a brief description.
299
300   \subsection{Configuration variables}
301     \subsubsection{BB\_NUMBER\_THREADS}
302       Controls how many BitBake tasks may run at a time. Defaults to the
303       number of cores available on the build system. The number of cores is
304       obtained from \shell{/proc/cpuinfo}. If this file is unavailable, the
305       default value is 1.
306
307     \subsubsection{MACHINE}
308       Controls the target machine to build packages for. See section \ref{products}
309       for a list of supported products.
310
311     \subsubsection{PARALLEL\_MAKE}
312       Controls how many processes per recipe \shell{make} may use. Defaults to
313       the number of cores available on the build system. The number of cores is
314       obtained from \shell{/proc/cpuinfo}. If this file is unavailable, the
315       default value is 1.
316
317       NOTE: If you see seemingly random build failures, try setting this variable to 1.
318
319   \subsection{Adding custom layers}
320   \label{custom_layers}
321      It is possible to add custom layers to the build system. This can be done globally
322      and per machine. To add a layer globally, edit \shell{conf/bblayers-ext.conf}. To
323      add a machine-specific layer, edit \shell{conf/bblayers-\$\{MACHINE\}-ext.conf}.
324      Assuming that an additional layer is available at \shell{\$\{HOME\}/custom-layer},
325      the entry to add to the file will look like this:
326
327      \shell{BBLAYERS =+ "\$\{HOME\}/custom-layer"}
328
329   \subsection{Adding custom options}
330      It is possible to tweak a lot more options than those used by the
331      \shell{Makefile} by editing \shell{conf/local-ext.conf} or \shell{conf/local-\$\{MACHINE\}-ext.conf}.
332
333      For example, if the firmware shall use the package feed built on the develoment machine, which
334      happens to be 192.168.1.1 and has a webserver configured to point to \shell{tmp/deploy/ipk},
335      a line like the following may be added:
336
337      \shell{DISTRO\_FEED\_URI = "http://192.168.1.1/\$\{DISTRO\}/\$\{DISTRO\_VERSION\}"}
338
339      In general, any variable in OpenEmbedded that uses weak assignment (\shell{?=}) may be
340      overridden from these files.
341
342      The following sections list some commonly used options.
343
344      \subsubsection{DISTRO\_FEED\_PREFIX}
345
346        \shell{DISTRO\_FEED\_PREFIX} specifies the name of the package update feed.
347        This name may be arbitarily chosen.
348
349        Default: \shell{DISTRO\_FEED\_PREFIX = "remote"}
350
351      \subsubsection{DISTRO\_FEED\_URI}
352
353        \shell{DISTRO\_FEED\_URI} specifies the URI of the package update feed.
354
355        Default: \shell{DISTRO\_FEED\_URI = "http://my-distribution.example/remote-feed/"}
356
357      \subsubsection{INHERIT}
358
359        \shell{INHERIT} specifies bbclasses to include from a configuration file. Usually,
360        this variable gets appended to by using the \shell{+=} operator.
361
362        The OpenDreambox distribution automatically appends \shell{"buildhistory recipe\_sanity testlab"} to \shell{INHERIT}.
363
364        Default: \shell{INHERIT = ""}
365
366        \textbf{Some examples:}
367
368        Always build the latest versions of OpenDreambox-related projects from Git:
369
370        \shell{INHERIT += "opendreambox-autorev"}
371
372        Remove temporary files of previous versions of a recipe before a newer version gets built:
373
374        \shell{INHERIT += "rm\_old\_work"}
375
376        Remove temporary files of a recipe after it has been built and packaged successfully.
377
378        \shell{INHERIT += "rm\_work"}
379
380   \subsection{Setting up a build directory}
381      To set up a build directory for e.g. \textbf{DM 500 HD} run \shell{make MACHINE=dm500hd}. If
382      \shell{MACHINE=dm500hd} has been set in \shell{conf/make.conf}, you can simply run \shell{make}
383      with no arguments instead. This will create and initialize the directory \shell{build/dm500hd}.
384
385   \subsection{Building a firmware image}
386      To build a firmware image for e.g. \textbf{DM 500 HD} run \shell{make MACHINE=dm500hd image}.
387      If \shell{MACHINE=dm500hd} has been set in \shell{conf/make.conf}, you can simply run
388      \shell{make image} instead.
389
390   \subsection{Building a package}
391      To build a single package, BitBake has to be used directly. First, the environment
392      has to be set up, in order to make BitBake available to the shell. This can be done
393      with the following command:
394
395      \shell{source bitbake.env}
396
397      BitBake must be run from the machine's build directory. For \textbf{DM 500 HD} run:
398
399      \shell{cd build/dm500hd}
400
401      In order to build enigma2, run:
402
403      \shell{bitbake enigma2}.
404
405 \section{Development hints}
406
407   \subsection{Cross-compilation of external software}
408     OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
409     the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
410
411     \begin{itemize}
412       \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
413       \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
414       \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
415       \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
416       \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
417     \end{itemize}
418
419     The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
420     adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
421
422     \shell{source cross-compile.env dm7020hd}
423
424     The script may be called from any location, but must reside inside the OpenDreambox Git tree.
425     You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
426
427   \subsection{Coding style}
428     Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
429
430   \subsection {Package architecture}
431     Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
432     \begin{itemize}
433       \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
434       \item The recipe is part of \shell{meta-bsp}.
435     \end{itemize}
436
437 \section{Bug reports and patches}
438
439   Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
440
441   A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
442   local copy of the repository.
443
444 \end{document}