dreambox-console-image: open image file in binary mode
[opendreambox.git] / doc / opendreambox.tex
1 %
2 % Copyright (c) 2016 Dream Property GmbH, Germany
3 %                    https://dreambox.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 2016}
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{https://dreambox.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.5, is based on the \href{https://www.yoctoproject.org/}{Yocto Project}, release 
64     2.1 "Krogoth", 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           DM900 UHD & \shell{MACHINE=dm900} \\
83           DM525 S2 CI-Slot & \shell{MACHINE=dm520} \\
84           DM525 C/T2 CI-Slot & \shell{MACHINE=dm520} \\
85           DM520 S2 & \shell{MACHINE=dm520} \\
86           DM520 C/T2 & \shell{MACHINE=dm520} \\
87           DM7080 HD & \shell{MACHINE=dm7080} \\
88           DM820 HD & \shell{MACHINE=dm820} \\
89           & \\
90           \hline
91         \end{tabular}
92
93       Note, that not all of these platforms offer enough internal
94       storage to actually flash a generated firmware image. It might be possible
95       to boot from external storage or network, though.
96     \end{flushleft}
97
98   \subsection{License}
99
100     \begin{verbatim}
101 Copyright (c) 2016 Dream Property GmbH, Germany
102                    https://dreambox.de/
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 krogoth git://git.opendreambox.org/git/opendreambox.git}
131
132     The Git repository can be viewed online at:
133
134     \url{http://git.opendreambox.org/?p=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, these layers are used:
149
150     \begin{itemize}
151       \item \shell{meta-dreambox}
152       \item \shell{meta-opendreambox}
153       \item \shell{meta-openembedded/meta-filesystems}
154       \item \shell{meta-openembedded/meta-multimedia}
155       \item \shell{meta-openembedded/meta-networking}
156       \item \shell{meta-openembedded/meta-oe}
157       \item \shell{meta-openembedded/meta-python}
158       \item \shell{meta-openembedded/meta-ruby}
159       \item \shell{meta-openembedded/meta-webserver}
160       \item \shell{meta-qt5}
161       \item \shell{openembedded-core/meta}
162     \end{itemize}
163
164     If a recipe for the same package exists in multiple layers,
165     then the higher priority layer takes precedence over the lower priority
166     layer.
167
168     For example, if \shell{libmad\_0.15.1b.bb} existed in both
169     \shell{meta-openembedded} and \shell{openembedded-core}, the recipe in
170     \shell{meta-openembedded} would be used, because \shell{openembedded-core}
171     has lower priority. Priority values are determined by the variable \shell{BBFILE\_PRIORITY}
172     in \shell{conf/layer.conf} of each layer.
173
174     \textbf{NOTE:} This would still be true even if the version of \shell{libmad} in
175     \shell{openembeded-core} was higher than the version in \shell{meta-openembedded},
176     unless \shell{PREFERRED\_VERSION\_libmad} was set to the version in \shell{openembedded-core}.
177     There is currently no way to prefer a version of a lower priority layer, if the
178     same version is present in a higher priority layer.
179
180     \subsubsection{openembedded-core and meta-openembedded}
181        These directories contain copies of Git repositories from git.openembedded.org,
182        including the OpenEmbedded-Core layer and the (Meta-)OpenEmbedded layers. They
183        get created automatically when building the distribution for the first time.
184
185        Throughout this document, the combination of these directories will be
186        referred to as OpenEmbedded.
187
188        The latest changes to these Git repositories can be seen at:
189
190        \url{http://git.openembedded.org/openembedded-core-contrib/log/?h=obi/krogoth}
191
192        \url{http://git.openembedded.org/meta-openembedded-contrib/log/?h=obi/krogoth}
193
194     \subsubsection{meta-opendreambox}
195       This directory contains:
196
197       \begin{itemize}
198         \item Recipes for packages written specifically for the OpenDreambox distribution
199         \item Modifications to recipes from OpenEmbedded
200         \item Recipes for software versions older than those available from OpenEmbedded
201         \item Recipes for software versions newer than those available from OpenEmbedded
202       \end{itemize}
203
204     \subsubsection{meta-dreambox}
205       The directory \shell{meta-dreambox} contains Board Support Packages (BSP)
206       for the supported Dreambox models. This includes:
207
208       \begin{itemize}
209         \item Hardware drivers
210         \item Machine specific overrides
211         \item The Linux kernel
212         \item The boot loader
213         \item Splash images
214       \end{itemize}
215
216 \section{Further readings}
217       \begin{itemize}
218         \item The Yocto Project Reference Manual:
219               \url{https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html}
220       \end{itemize}
221
222 \section{Prerequisites}
223   \label{prerequisites}
224
225   \subsection{Required software}
226
227    The OpenEmbedded project provides a general list of prerequisites for
228    many Linux distributions and also for some other operating systems.
229
230    \begin{itemize}
231      \item \url{http://www.openembedded.org/wiki/Getting\_started#Required\_software}
232    \end{itemize}
233
234    It is highly recommended to use Linux to build OpenDreambox. In theory,
235    any recent distribution will do, but not many distributions have been
236    verified to build OpenDreambox without errors. Tested distributions
237    include:
238
239    \begin{itemize}
240      \item Debian 8.6 "Jessie" [amd64]
241      \item Ubuntu 16.04.1 LTS "Xenial Xerus" [amd64]
242    \end{itemize}
243
244 \pagebreak
245
246 \section{Major changes since previous public 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   \subsection{Changes since release 2.0}
262     \begin{itemize}
263       \item Added support for DM520, DM525, DM820 and DM7080.
264       \item If a recipe changes, the corresponding packages will be rebuilt automatically,
265             in contrast to required manual PR bumps in the past.
266       \item Each machine uses its own tmp directory again, like before 2.0. However,
267             there is a shared \shell{sstate-cache}, which allows to share already compiled
268             data between compatible machines. This impacts performance and size of the
269             build system, but improves reliability and consistency across builds.
270       \item Support for machines without FPU and kernel versions below 3.x was dropped (DM800).
271       \item Layers under meta-bsp were combined into meta-dreambox.
272       \item Default package format switched from ipk (opkg) to deb (dpkg + apt).
273       \item \shell{dreambox-image} was renamed to include the package format (\shell{dreambox-image-deb}).
274     \end{itemize}
275
276    \subsection{Changes since release 2.2}
277      \begin{itemize}
278        \item Added support for DM900.
279        \item Support for machines with low memory was dropped (DM500HD, DM800SE).
280        \item Switched from Qt4 to Qt5.
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   \subsection{Setting up a build directory}
387      To set up a build directory for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080}. If
388      \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default: dm900), you can simply run \shell{make}
389      with no arguments instead. This will create and initialize the directory \shell{build/dm7080}.
390
391   \subsection{Building a firmware image}
392      To build a firmware image for e.g. \textbf{DM 7080} run \shell{make MACHINE=dm7080 image}.
393      If \shell{MACHINE=dm7080} has been set in \shell{conf/make.conf} (default: dm900), you can simply run
394      \shell{make image} instead.
395
396   \subsection{Building a package}
397      To build a single package, BitBake has to be used directly. First, the environment
398      has to be set up, in order to make BitBake available to the shell. This can be done
399      with the following command:
400
401      \shell{source bitbake.env}
402
403      BitBake must be run from the machine's build directory. For \textbf{DM 7080} run:
404
405      \shell{cd build/dm7080}
406
407      In order to build enigma2, run:
408
409      \shell{bitbake enigma2}.
410
411 \section{Development hints}
412
413   \subsection{Cross-compilation of external software}
414     OpenDreambox provides a script called \shell{cross-compile.env}. Once run, the script will create
415     the following commands (shell aliases), aiming to ease cross-compilation of external source trees:
416
417     \begin{itemize}
418       \item \shell{oe\_autoreconf} - Calls OE's version of \shell{autoreconf}. Useful for projects based on GNU autotools.
419       \item \shell{oe\_runconf} - Calls \shell{./configure} with parameters suitable for OE. Useful for projects based on GNU autotools.
420       \item \shell{oe\_runmake} - Calls \shell{make} with parameters suitable for OE. Useful for projects based on GNU autotools or GNU make.
421       \item \shell{oe\_env} - Useful to execute arbitrary commands in the OE environment (e.g. \shell{oe\_env env}).
422       \item \shell{oe\_setenv} - Exports the OE environment to the currently running shell session.
423     \end{itemize}
424
425     The script needs to know the target machine, which can be one of the supported products (see \ref{products}). Because the script
426     adds aliases to your currently running shell session, it has to be invoked using \shell{source} or \shell{.} (the dot operator), e.g.:
427
428     \shell{source cross-compile.env dm7080}
429
430     The script may be called from any location, but must reside inside the OpenDreambox Git tree.
431     You may want to create a symlink to \shell{cross-compile.env} somewhere in your \shell{PATH}.
432
433   \subsection{Coding style}
434     Run \shell{scripts/do\_stylize.sh} on new recipes to ensure proper coding style.
435
436   \subsection {Package architecture}
437     Set \shell{PACKAGE\_ARCH = "\$\{MACHINE\_ARCH\}"} if either condition is met:
438     \begin{itemize}
439       \item The recipe uses \shell{COMBINED\_FEATURES}, \shell{MACHINE\_FEATURES} or \shell{DREAMBOX\_FEATURES}.
440       \item The recipe uses \shell{COMPATIBLE\_MACHINE}.
441       \item The recipe is part of \shell{meta-dreambox}.
442     \end{itemize}
443
444 \section{Bug reports and patches}
445
446   Please send bug reports and patches to the Enigma2 development mailing list \shell{<enigma2-devel@lists.elitedvb.net>}.
447
448   A comfortable way to create patches is to use \shell{git format-patch}, after all changes have been committed to your
449   local copy of the repository.
450
451 \end{document}