doc: known issues: eCryptfs
[opendreambox.git] / doc / opendreambox.tex
1 %
2 % Copyright (c) 2010-2011 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{March 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   \end{flushleft}
63
64   \subsection{Target audience}
65     \begin{flushleft}
66       Developers familiar with previous versions of OpenDreambox or OpenEmbedded
67       in general.
68     \end{flushleft}
69
70   \subsection{Supported products}
71     \label{products}
72     \begin{flushleft}
73       The current version includes support for the following machines:
74
75         \begin{tabular}{ | l | l | }
76           \hline
77           \textbf{Product name} & \textbf{Environment variable} \\ \hline
78           & \\
79           DM 500 HD & \shell{MACHINE=dm500hd} \\
80           DM 800 HD PVR & \shell{MACHINE=dm800} \\
81           DM 800 HD SE & \shell{MACHINE=dm800se} \\
82           DM 7020 HD & \shell{MACHINE=dm7020hd} \\
83           DM 8000 HD PVR & \shell{MACHINE=dm8000} \\
84           & \\
85           \hline
86         \end{tabular}
87     \end{flushleft}
88
89   \subsection{License}
90
91     \begin{verbatim}
92 Copyright (c) 2010-2012 Dream Multimedia GmbH, Germany
93                         http://www.dream-multimedia-tv.de/
94 Authors:
95   Andreas Frisch <fraxinas@opendreambox.org>
96   Andreas Monzner <ghost@opendreambox.org>
97   Andreas Oberritter <obi@opendreambox.org>
98   Mladen Horvat <acid-burn@opendreambox.org>
99   Stefan Pluecken <thedoc@opendreambox.org>
100   Stephan Reichholf <reichi@opendreambox.org>
101
102 Permission is hereby granted, free of charge, to any person obtaining a copy
103 of this software and associated documentation files (the "Software"), to deal
104 in the Software without restriction, including without limitation the rights
105 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
106 copies of the Software, and to permit persons to whom the Software is
107 furnished to do so, subject to the following conditions:
108
109 The above copyright notice and this permission notice shall be included in
110 all copies or substantial portions of the Software.
111
112 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
113 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
114 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
115 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
116 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
117 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
118 THE SOFTWARE.
119     \end{verbatim}
120
121   \subsection{Obtaining the source code}
122     OpenDreambox uses the Git version control system. To obtain the source
123     code, it is required to install Git. See \url{http://git-scm.com/}.
124
125     To initially download the source into the current directory, issue the
126     following command:
127
128     \shell{git clone git://git.opendreambox.org/git/opendreambox.git}
129
130   \subsection{Quick start}
131     For the impatient:
132
133     \shell{make -C opendreambox image}
134
135     If this command fails, prerequisites my be missing. See section \ref{prerequisites}.
136
137   \subsection{Directory structure}
138     OpenDreambox consists of a set of layers containing build instructions.
139     This meta data is used by BitBake to download and compile source code
140     and to assemble installable software packages and firmware images.
141
142     Currently, there are five layers, ordered by priority from lowest to
143     highest:
144
145     \begin{itemize}
146       \item \shell{openembedded-core}
147       \item \shell{meta-openembedded}
148       \item \shell{meta-opendreambox}
149       \item \shell{meta-bsp/common}
150       \item \shell{meta-bsp/\$\{MACHINE\}}
151     \end{itemize}
152
153     If a recipe for the same package exists in multiple layers,
154     then the higher priority layer takes precedence over the lower priority
155     layer.
156
157     For example, \shell{libmad\_0.15.1b.bb} exists in both
158     \shell{meta-openembedded} and \shell{openembedded-core}. The recipe in
159     \shell{meta-openembedded} will be used, because \shell{openembedded-core}
160     has lower priority.
161
162     \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
163     \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
164     unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
165     There is currently no way to prefer a version of a lower priority layer, if the
166     same version is present in a higher priority layer.
167
168     \subsubsection{openembedded-core and meta-openembedded}
169        These directories contain copies of Git repositories from git.openembedded.org, including
170        the OpenEmbedded-Core layer ("meta") and the OpenEmbedded layer ("meta-oe"). They get created
171        automatically when building the distribution for the first time.
172
173        Throughout this document, the combination of these directories will be
174        referred to as OpenEmbedded.
175
176     \subsubsection{meta-opendreambox}
177       This directory contains:
178
179       \begin{itemize}
180         \item Recipes for packages written specifically for the OpenDreambox distribution
181         \item Modifications to recipes from OpenEmbedded
182         \item Recipes for software versions older than those available from OpenEmbedded
183         \item Recipes for software versions newer than those available from OpenEmbedded
184       \end{itemize}
185
186     \subsubsection{meta-bsp}
187       The directory \shell{meta-bsp} contains Board Support Packages (BSP)
188       for the supported Dreambox models. This includes:
189
190       \begin{itemize}
191         \item Hardware drivers
192         \item Machine specific overrides
193         \item The Linux kernel
194         \item The boot loader
195         \item Splash images
196       \end{itemize}
197
198 \section{Prerequisites}
199   \label{prerequisites}
200
201   \subsection{Required software}
202
203    The OpenEmbedded project provides a general list of prerequisites for
204    many Linux distributions and also for some other operating systems.
205
206    \begin{itemize}
207      \item \url{http://www.openembedded.org/index.php/OEandYourDistro}
208      \item \url{http://www.openembedded.org/index.php/Required\_software}
209    \end{itemize}
210
211    It is highly recommended to use Linux to build OpenDreambox. In theory,
212    any recent distribution will do, but not many distributions have been
213    verified to build OpenDreambox without errors. Tested distributions
214    include:
215
216    \begin{itemize}
217      \item Arch Linux 2011.08.19 [amd64]
218      \item Debian 6.0 (Squeeze) [i386]
219      \item Debian "Testing" (Wheezy) [i386]
220      \item Fedora 16 [i386, amd64]
221      \item Ubuntu 10.04 LTS (Lucid Lynx) [i386]
222      \item Ubuntu 10.10 (Maverick Meerkat) [i386]
223      \item Ubuntu 11.10 (Oneiric Ocelot) [amd64]
224      \item Ubuntu 12.04 LTS (Precise Pangolin) [i386, amd64]
225    \end{itemize}
226
227    Distributions known not to work:
228
229    \begin{itemize}
230      \item Debian 5.0 (Lenny): Comes with Python 2.5, which is too old.
231    \end{itemize}
232
233 \pagebreak
234
235 \section{Major changes since previous releases}
236
237   \subsection{Changes since release 1.6}
238     \begin{itemize}
239       \item Recipes were split across multiple layers and categorized.
240       \item \shell{env.source} has been replaced by two files,
241         \shell{bitbake.env} and \shell{cross-compile.env}. The former sets a minimal
242         environment that is needed to execute bitbake. The latter creates
243         machine-specific command aliases, in order to compile external software.
244       \item All machines share a common \shell{tmp} directory.
245       \item \shell{\$\{MACHINE\}/build} directories were renamed to \shell{build/\$\{MACHINE\}}.
246       \item Kernel packages were renamed from \shell{linux-\$\{MACHINE\}} to \shell{linux-dreambox}.
247       \item Support for machines based on ATI Xilleon or IBM STB was dropped.
248     \end{itemize}
249
250 \section{Known Issues}
251
252   \begin{itemize}
253     \item Building on eCryptfs fails, because it doesn't support sufficiently long filenames (\href{https://bugs.launchpad.net/ecryptfs/+bug/344878}{eCryptfs bug \#344878}).
254   \end{itemize}
255
256 \pagebreak
257
258 \section{Building OpenDreambox}
259
260   In the top level directory, there is a \shell{Makefile}, which is used to
261   set up build directories and to fetch or update all used repositories.
262   The Makefile can be influenced by environment variables, either
263   by specifing them on the command-line or by storing them in a file called
264   \shell{conf/make.conf}. It is not recommended to edit the \shell{Makefile} directly
265   in order to avoid conflicts with future updates.
266
267   When the \shell{Makefile} is run for the first time, the following steps will
268   be executed:
269
270   \begin{itemize}
271     \item Creation of configuration files
272       \begin{itemize}
273         \item \shell{bitbake.env}
274         \item \shell{conf/opendreambox.conf}
275         \item \shell{build/\$\{MACHINE\}/conf/bblayers.conf}
276         \item \shell{build/\$\{MACHINE\}/conf/local.conf}
277       \end{itemize}
278     \item Update or checkout of Git repositories
279       \begin{itemize}
280         \item OpenDreambox
281         \item BitBake
282         \item OpenEmbedded
283       \end{itemize}
284   \end{itemize}
285
286   \subsection{Makefile targets}
287     Run \shell{make help} to get a list of targets of the top level Makefile, together with a brief description.
288
289   \subsection{Configuration variables}
290     \subsubsection{BB\_NUMBER\_THREADS}
291       Controls how many BitBake tasks may run at a time. Defaults to the
292       number of cores available on the build system. The number of cores is
293       obtained from \shell{/proc/cpuinfo}. If this file is unavailable, the
294       default value is 1.
295
296     \subsubsection{MACHINE}
297       Controls the target machine to build packages for. See section \ref{products}
298       for a list of supported products.
299
300     \subsubsection{PARALLEL\_MAKE}
301       Controls how many processes per recipe \shell{make} may use. Defaults to
302       the number of cores available on the build system. The number of cores is
303       obtained from \shell{/proc/cpuinfo}. If this file is unavailable, the
304       default value is 1.
305
306       NOTE: If you see seemingly random build failures, try setting this variable to 1.
307
308   \subsection{Adding custom layers}
309   \label{custom_layers}
310      It is possible to add custom layers to the build system. This can be done globally
311      and per machine. To add a layer globally, edit \shell{conf/bblayers-ext.conf}. To
312      add a machine-specific layer, edit \shell{conf/bblayers-\$\{MACHINE\}-ext.conf}.
313      Assuming that an additional layer is available at \shell{\$\{HOME\}/custom-layer},
314      the entry to add to the file will look like this:
315
316      \shell{BBLAYERS =+ "\$\{HOME\}/custom-layer"}
317
318   \subsection{Adding custom options}
319      It is possible to tweak a lot more options than those used by the
320      \shell{Makefile} by editing \shell{conf/local-ext.conf} or \shell{conf/local-\$\{MACHINE\}-ext.conf}.
321
322      For example, if the firmware shall use the package feed built on the develoment machine, which
323      happens to be 192.168.1.1 and has a webserver configured to point to \shell{tmp/deploy/ipk},
324      a line like the following may be added:
325
326      \shell{DISTRO\_FEED\_URI = "http://192.168.1.1/\$\{DISTRO\}/\$\{DISTRO\_VERSION\}"}
327
328      In general, any variable in OpenEmbedded that uses weak assignment (\shell{?=}) may be
329      overridden from these files.
330
331      The following sections list some commonly used options.
332
333      \subsubsection{DISTRO\_FEED\_PREFIX}
334
335        \shell{DISTRO\_FEED\_PREFIX} specifies the name of the package update feed.
336        This name may be arbitarily chosen.
337
338        Default: \shell{DISTRO\_FEED\_PREFIX = "remote"}
339
340      \subsubsection{DISTRO\_FEED\_URI}
341
342        \shell{DISTRO\_FEED\_URI} specifies the URI of the package update feed.
343
344        Default: \shell{DISTRO\_FEED\_URI = "http://my-distribution.example/remote-feed/"}
345
346      \subsubsection{INHERIT}
347
348        \shell{INHERIT} specifies bbclasses to include from a configuration file. Usually,
349        this variable gets appended to by using the \shell{+=} operator.
350
351        The OpenDreambox distribution automatically appends \shell{"buildhistory recipe\_sanity testlab"} to \shell{INHERIT}.
352
353        Default: \shell{INHERIT = ""}
354
355        \textbf{Some examples:}
356
357        Always build the latest versions of OpenDreambox-related projects from Git:
358
359        \shell{INHERIT += "opendreambox-autorev"}
360
361        Remove temporary files of previous versions of a recipe before a newer version gets built:
362
363        \shell{INHERIT += "rm\_old\_work"}
364
365        Remove temporary files of a recipe after it has been built and packaged successfully.
366
367        \shell{INHERIT += "rm\_work"}
368
369   \subsection{Setting up a build directory}
370      To set up a build directory for e.g. \textbf{DM 500 HD} run \shell{make MACHINE=dm500hd}. If
371      \shell{MACHINE=dm500hd} has been set in \shell{conf/make.conf}, you can simply run \shell{make}
372      with no arguments instead. This will create and initialize the directory \shell{build/dm500hd}.
373
374   \subsection{Building a firmware image}
375      To build a firmware image for e.g. \textbf{DM 500 HD} run \shell{make MACHINE=dm500hd image}.
376      If \shell{MACHINE=dm500hd} has been set in \shell{conf/make.conf}, you can simply run
377      \shell{make image} instead.
378
379   \subsection{Building a package}
380      To build a single package, BitBake has to be used directly. First, the environment
381      has to be set up, in order to make BitBake available to the shell. This can be done
382      with the following command:
383
384      \shell{source bitbake.env}
385
386      BitBake must be run from the machine's build directory. For \textbf{DM 500 HD} run:
387
388      \shell{cd build/dm500hd}
389
390      In order to build enigma2, run:
391
392      \shell{bitbake enigma2}.
393
394 \section{Development hints}
395
396   \subsection{Cross-compilation of external software}
397     OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
398     the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
399
400     \begin{itemize}
401       \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
402       \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
403       \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
404       \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
405       \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
406     \end{itemize}
407
408     The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
409     adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
410
411     \shell{source cross-compile.env dm7020hd}
412
413     The script may be called from any location, but must reside inside the OpenDreambox Git tree.
414     You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
415
416   \subsection{Coding style}
417     Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
418
419   \subsection {Package architecture}
420     Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
421     \begin{itemize}
422       \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
423       \item The recipe is part of \shell{meta-bsp}.
424     \end{itemize}
425
426 \section{Bug reports and patches}
427
428   Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
429
430   A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
431   local copy of the repository.
432
433 \end{document}