python-twisted: remove version 12, meta-oe has 13.2.0
[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{August 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://cgit.opendreambox.org/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-bsp/\$\{MACHINE\}}
161       \item \shell{meta-bsp/common}
162       \item \shell{meta-opendreambox}
163       \item \shell{meta-qt5}
164       \item \shell{meta-openembedded/meta-oe}
165       \item \shell{meta-openembedded/meta-filesystems}
166       \item \shell{meta-openembedded/meta-initramfs}
167       \item \shell{meta-openembedded/meta-multimedia}
168       \item \shell{meta-openembedded/meta-networking}
169       \item \shell{meta-openembedded/meta-ruby}
170       \item \shell{openembedded-core/meta}
171     \end{itemize}
172
173     If a recipe for the same package exists in multiple layers,
174     then the higher priority layer takes precedence over the lower priority
175     layer.
176
177     For example, if \shell{libmad\_0.15.1b.bb} existed in both
178     \shell{meta-openembedded} and \shell{openembedded-core}, the recipe in
179     \shell{meta-openembedded} would be used, because \shell{openembedded-core}
180     has lower priority.
181
182     \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
183     \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
184     unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
185     There is currently no way to prefer a version of a lower priority layer, if the
186     same version is present in a higher priority layer.
187
188     \subsubsection{openembedded-core and meta-openembedded}
189        These directories contain copies of Git repositories from git.openembedded.org,
190        including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They
191        get created automatically when building the distribution for the first time.
192
193        Throughout this document, the combination of these directories will be
194        referred to as OpenEmbedded.
195
196        The latest changes to these Git repositories can be seen at:
197
198        \url{http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/dora}
199
200        \url{http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/dora}
201
202     \subsubsection{meta-opendreambox}
203       This directory contains:
204
205       \begin{itemize}
206         \item Recipes for packages written specifically for the OpenDreambox distribution
207         \item Modifications to recipes from OpenEmbedded
208         \item Recipes for software versions older than those available from OpenEmbedded
209         \item Recipes for software versions newer than those available from OpenEmbedded
210       \end{itemize}
211
212     \subsubsection{meta-bsp}
213       The directory \shell{meta-bsp} contains Board Support Packages (BSP)
214       for the supported Dreambox models. This includes:
215
216       \begin{itemize}
217         \item Hardware drivers
218         \item Machine specific overrides
219         \item The Linux kernel
220         \item The boot loader
221         \item Splash images
222       \end{itemize}
223
224 \section{Further readings}
225       \begin{itemize}
226         \item The Yocto Project Reference Manual:
227               \url{https://www.yoctoproject.org/docs/1.5.1/ref-manual/ref-manual.html}
228       \end{itemize}
229
230 \section{Prerequisites}
231   \label{prerequisites}
232
233   \subsection{Required software}
234
235    The OpenEmbedded project provides a general list of prerequisites for
236    many Linux distributions and also for some other operating systems.
237
238    \begin{itemize}
239      \item \url{http://www.openembedded.org/wiki/Getting\_started#Required\_software}
240    \end{itemize}
241
242    It is highly recommended to use Linux to build OpenDreambox. In theory,
243    any recent distribution will do, but not many distributions have been
244    verified to build OpenDreambox without errors. Tested distributions
245    include:
246
247    \begin{itemize}
248      \item Debian 7.6 "Wheezy" [amd64]
249      \item Ubuntu 14.04.1 LTS "Trusty Tahr" [amd64]
250    \end{itemize}
251
252 \pagebreak
253
254 \section{Major changes since previous public releases}
255
256   \subsection{Changes since release 1.6}
257     \begin{itemize}
258       \item Recipes were split across multiple layers and categorized.
259       \item \shell{env.source} has been replaced by two files,
260         \shell{bitbake.env} and \shell{cross-compile.env}. The former sets a minimal
261         environment that is needed to execute bitbake. The latter creates
262         machine-specific command aliases, in order to compile external software.
263       \item All machines share a common \shell{tmp} directory.
264       \item \shell{\$\{MACHINE\}/build} directories were renamed to \shell{build/\$\{MACHINE\}}.
265       \item Kernel packages were renamed from \shell{linux-\$\{MACHINE\}} to \shell{linux-dreambox}.
266       \item Support for machines based on ATI Xilleon or IBM STB was dropped.
267     \end{itemize}
268
269   \subsection{Changes since release 2.0}
270     \begin{itemize}
271       \item Added support for DM7080.
272       \item If a recipe changes, the corresponding packages will be rebuilt automatically,
273             in contrast to required manual PR bumps in the past.
274       \item Each machine uses its own tmp directory again, like before 2.0. However,
275             there is a shared \shell{sstate-cache}, which allows to share already compiled
276             data between compatible machines. This impacts performance and size of the
277             build system, but improves reliability and consistency across builds.
278       \item Support for machines without FPU and kernel versions below 3.x was dropped (DM800).
279     \end{itemize}
280
281 \section{Known Issues}
282
283   None.
284
285 \pagebreak
286
287 \section{Building OpenDreambox}
288
289   In the top level directory, there is a \shell{Makefile}, which is used to
290   set up build directories and to fetch or update all used repositories.
291   The Makefile can be influenced by environment variables, either
292   by specifing them on the command-line or by storing them in a file called
293   \shell{conf/make.conf}. It is not recommended to edit the \shell{Makefile} directly
294   in order to avoid conflicts with future updates.
295
296   When the \shell{Makefile} is run for the first time, the following steps will
297   be executed:
298
299   \begin{itemize}
300     \item Creation of configuration files
301       \begin{itemize}
302         \item \shell{bitbake.env}
303         \item \shell{conf/opendreambox.conf}
304         \item \shell{build/\$\{MACHINE\}/conf/bblayers.conf}
305         \item \shell{build/\$\{MACHINE\}/conf/local.conf}
306       \end{itemize}
307     \item Update or checkout of Git repositories
308       \begin{itemize}
309         \item OpenDreambox
310         \item BitBake
311         \item OpenEmbedded
312       \end{itemize}
313   \end{itemize}
314
315   \subsection{Makefile targets}
316     Run \shell{make help} to get a list of targets of the top level Makefile, together with a brief description.
317
318   \subsection{Configuration variables}
319     \subsubsection{BB\_NUMBER\_THREADS}
320       Controls how many BitBake tasks may run at a time. Defaults to the
321       number of cores available on the build system.
322
323     \subsubsection{MACHINE}
324       Controls the target machine to build packages for. See section \ref{products}
325       for a list of supported products.
326
327     \subsubsection{PARALLEL\_MAKE}
328       Controls how many processes per recipe \shell{make} may use. Defaults to
329       the number of cores available on the build system.
330
331   \subsection{Adding custom layers}
332   \label{custom_layers}
333      It is possible to add custom layers to the build system. This can be done globally
334      and per machine. To add a layer globally, edit \shell{conf/bblayers-ext.conf}. To
335      add a machine-specific layer, edit \shell{conf/bblayers-\$\{MACHINE\}-ext.conf}.
336      Assuming that an additional layer is available at \shell{\$\{HOME\}/custom-layer},
337      the entry to add to the file will look like this:
338
339      \shell{BBLAYERS =+ "\$\{HOME\}/custom-layer"}
340
341   \subsection{Adding custom options}
342      It is possible to tweak a lot more options than those used by the
343      \shell{Makefile} by editing \shell{conf/local-ext.conf} or \shell{conf/local-\$\{MACHINE\}-ext.conf}.
344
345      For example, if the firmware shall use the package feed built on the develoment machine, which
346      happens to be 192.168.1.1 and has a webserver configured to point to \shell{tmp/deploy/ipk},
347      a line like the following may be added:
348
349      \shell{DISTRO\_FEED\_URI = "http://192.168.1.1/\$\{DISTRO\}/\$\{DISTRO\_VERSION\}"}
350
351      In general, any variable in OpenEmbedded that uses weak assignment (\shell{?=}) may be
352      overridden from these files.
353
354      The following sections list some commonly used options.
355
356      \subsubsection{DISTRO\_FEED\_PREFIX}
357
358        \shell{DISTRO\_FEED\_PREFIX} specifies the name of the package update feed.
359        This name may be chosen arbitarily.
360
361        Default: \shell{DISTRO\_FEED\_PREFIX = "remote"}
362
363      \subsubsection{DISTRO\_FEED\_URI}
364
365        \shell{DISTRO\_FEED\_URI} specifies the URI of the package update feed.
366
367        Default: \shell{DISTRO\_FEED\_URI = "http://my-distribution.example/remote-feed/"}
368
369      \subsubsection{INHERIT}
370
371        \shell{INHERIT} specifies bbclasses to include from a configuration file. Usually,
372        this variable gets appended to by using the \shell{+=} operator.
373
374        The OpenDreambox distribution automatically appends \shell{"buildhistory recipe\_sanity"} to \shell{INHERIT}.
375
376        Default: \shell{INHERIT = ""}
377
378        \textbf{Some examples:}
379
380        Always build the latest versions of OpenDreambox-related projects from Git:
381
382        \shell{INHERIT += "opendreambox-autorev"}
383
384        Remove temporary files of previous versions of a recipe before a newer version gets built:
385
386        \shell{INHERIT += "rm\_old\_work"}
387
388   \subsection{Setting up a build directory}
389      To set up a build directory for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080}. If
390      \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default), you can simply run \shell{make}
391      with no arguments instead. This will create and initialize the directory \shell{build/dm7080}.
392
393   \subsection{Building a firmware image}
394      To build a firmware image for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080 image}.
395      If \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default), you can simply run
396      \shell{make image} instead.
397
398   \subsection{Building a package}
399      To build a single package, BitBake has to be used directly. First, the environment
400      has to be set up, in order to make BitBake available to the shell. This can be done
401      with the following command:
402
403      \shell{source bitbake.env}
404
405      BitBake must be run from the machine's build directory. For \textbf{DM 7080} run:
406
407      \shell{cd build/dm7080}
408
409      In order to build enigma2, run:
410
411      \shell{bitbake enigma2}.
412
413 \section{Development hints}
414
415   \subsection{Cross-compilation of external software}
416     OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
417     the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
418
419     \begin{itemize}
420       \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
421       \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
422       \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
423       \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
424       \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
425     \end{itemize}
426
427     The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
428     adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
429
430     \shell{source cross-compile.env dm7080}
431
432     The script may be called from any location, but must reside inside the OpenDreambox Git tree.
433     You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
434
435   \subsection{Coding style}
436     Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
437
438   \subsection {Package architecture}
439     Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
440     \begin{itemize}
441       \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
442       \item The recipe is part of \shell{meta-bsp}.
443     \end{itemize}
444
445 \section{Bug reports and patches}
446
447   Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
448
449   A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
450   local copy of the repository.
451
452 \end{document}