small introdution to the defaults handlers (could still be subject to
[enigma2.git] / doc / DEFAULTS
1 Contents:
2 1) What is a default?
3 2) Where are defaults used?
4 3) How do you build a default?
5 4) What are the contents of an .info file?
6 5) What about .dmpkg files?
7 6) Details about the default types
8
9 1) What is a default?
10
11 A default can consist of one or many of the following:
12 - skins
13 - lamedbs
14 - config files
15 - favourite files
16 - ipk packages
17
18 2) Where are defaults used?
19 There are several places, where defaults are used. Some require user interaction and some don't.
20 - First of all an "image default" is installed, when you start e2 for the first time. No user interaction is needed for that.
21 - After that e2 tries to mount a "preset partion" (also called "dealer partition"). If this partition contains defaults,
22   the user is presented with a list of these defaults and can choose to install/not install each of these defaults.
23 - You can create ".dmpkg files" and put them on a SD card (or something, that will be given to the FileScanner.
24 - The default satlists feature uses defaults.
25
26 3) How do you build a default?
27 A default contains at least an .info file (see next section for details). The .info file contains meta information about data,
28 that this default consists of. Furthermore the default can contain the data, you wish to install (skin, lamedbs etc.). The data
29 can also lie on some http server.
30
31 4) What are the contents of an .info file?
32 The .info file is an XMl file containing meta information about what this default contains. The basic structure
33 is as follows:
34 <default>
35         <prerequisites>
36                 ...
37         </prerequisites>
38         <info>
39                 ...
40         </info>
41         <files type="directories">
42                 ...
43         </files>
44 </default>
45
46 Prerequisites can be used globally for this default (as seen in the sketch above) or in the <files> area for specific files
47 (see below for details). Prerequisites can have the following tags:
48 <hardware type="<boxtype>"> (e.g. boxtype "dm8000")
49 <bcastsystem type="<system>"> (e.g. DVB-S, DVB-T, DVB-C)
50 <satellite type="<orbitalposition>"> (e.g. 192 for Astra 19.2E)
51
52 Used in the global section of the .info file, the default can ONLY be installed if ALL prerequisites are fulfilled. Something
53 similar applies to the use of prerequisites in the <files> section. But in contrary to not being able to install the whole
54 default, the prerequisites in the <files> section can only exclude distinct <file> entries. For example, you have a lamedb
55 containing only services and transponders for Astra 19.2E and this is the only stuff in your default. Then you would define
56 a <bcastsystem type="DVB-S"> in the global section, so that cable or terrestrial boxes don't get the possibility for the
57 useless default and use a <satellite type="192"> whith the <file> tag for the lamedb with the 19.2 transponders/services.
58
59 The <info> tag must contain a <name> tag and can (but should!) contain an <author> tag:
60 <info>
61         <author>Dream Multimedia GmbH</author>
62         <name>Dream Multimedia Default</name>
63 </info>
64 The <name> tag is presented to the user as the name for the default to install.
65
66 The <files> tag can contain several <file> tags. Each <file> tag must have "type" and a "name" attribute and can have a directory
67 attribute which is the directory relative to the .info file, where the file in the "name" attribute is stored (exception:
68 type="skin" => "name" is the description of the skin, since skins are always stored in whole directories, not single files).
69 The "type" attribute can be "skin", "config", "services", "favourites" or "package".
70 A short example for every type:
71 <file type="skin" directory="test_skin/" flag="default" name="Default Skin" />
72 <file type="config" name="settings.8000" />
73 <file type="services" name="lamedb.192" />
74 <file type="favourites" directory="" name="bouquets.tv" />              
75 <file type="favourites" directory="" name="userbouquet.favourites.tv" />
76 <file type="package" directory="packages/" name="small-test_1.0_mipsel.ipk" />
77
78 As mentioned above, each <file> tag can have it's own prerequisites. An example for a lamedb, containing only transponders for Astra
79 19.2 would be:
80 <file type="services" name="lamedb.192">
81         <prerequisites>
82                 <bcastsystem type="DVB-S" />
83                 <satellite type="192" />
84         </prerequisites>
85 </file>
86 So this would only install the lamedb.192 file, if you have a DVB-S NIM in your box AND some of the tuners is configured to 19.2.
87
88 5) What about .dmpkg files?
89 .dmpkg files are nothing else than tar'ed defaults. You can also use gzipped tars.
90
91 6) Details about the default types
92 - "image default"
93   An image default is stored in /usr/share/enigma2/defaults. You can have several defaults at the same time, but you should keep
94   in mind, that these defaults are all installed without user interaction. So defaults with contrary contents should be avoided
95   (e.g. setting a default parameter in one settings file an setting another setting for the same parameter in another could lead
96   to unexpected behaviour, since the installation order is undetermined and completely random. so use prerequisites insted)
97   The "image default" is also used to set box specific config elements (for example show the new RC on a dm8000) and install the
98   default bouquets.
99 - The "preset partition" defaults are stored in /usr/share/enigma2/dealer or in an mtd partition which must be calles "preset partition".
100   The user is presented a list of the names of the installable
101   (installable means, that all prerequisites in the global section are met) defaults and can choose the defaults to install.
102   This can be used for customizing a users box. For example, a dealer can put in a skin, the settings for the user's sat dish etc.
103   into the preset partition. This partition will not be overwritten by an original Dream image. So if the user installs a new image
104   from the Dream website, the default settings are presented to the user in the start wizard of the new image.
105 - .dmpkg Packages are already explained in detail. This could be used to easily distribute update for packages (e.g. the e2 core package)
106   for quick hotfixes on boxes without internet connection. The advantage over normal .ipk packages is, that one .dmpkg package
107   can contain more than one .ipk package.
108 - Default satlists are stored either in the "image default"-directory or in the "preset partition" directory. The satlists must contain a
109   <tag> tag in the global <prerequisites> tag:
110   <prerequisites>
111     <tag type="services" />
112         <bcastsystem type="DVB-S" />
113     <satellite type="192" />
114   </prerequisites>
115   Only if this tag is present, the user get's this default presented in the default satlist selection (and nowhere else!).
116