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