installer/doc/modules.txt

Modules
-------

The new debian installer is highly modular. Modules are loaded at several
points in the install process to add capabilities to the installer. Modules
are essentially sets of files that get unpacked onto the installation
system, plus some metadata.

Because there is already so much infrastructure to build and manage debian
packages, and because it allows metadata to accompany the files in a module,
we have decided to use debian packages as the modules for the installer. To 
differentiate them from normal Debian packages, modules have filenames
ending in ".udeb". However, modules must not have the same package
name as any regular Debian package. The 'u' in udeb stands for Greek
mu, meaning micro (udebs take less space than regular debian packages).

Unlike regular debian packages, modules for the installer will not be
policy compliant. They will not contain documentation in /usr/share/doc.
They need not comply with the FHS. They may be statically linked. They may
conflict with essential "real" debian packages, and thus be non-installable
on a real debian system, although it is recommended that if possible, this
be avoided.

Here is a short rundown on differences between deb packages and udebs:

All udeb packages should be able to build debug versions if
DEB_BUILD_OPTIONS="debug".

Misc.Differences
================

* Udebs must not include .md5sum files.

New Control Scripts
===================

menutest
--------

Menutest scripts should return a true value (0) if they think it would be a
good idea if their menu item was default, and a false value if it doesn't
matter. For example in case of a udeb providing an ethernet driver, the
menutest script would run a hardware detection routine and return 0 if the
particular ethernet card was installed.

Menutest scripts are optional. If a module does not have one, a simpler
default test is used.

isinstallable
-------------

If this script exists, and when run returns a non-zero value, then
its menu item is not displayed.

New Headers
===========

Installer-Menu-Item
-------------------

A priority (a number). The priority number influences the ordering of
items in the menu; higher numbered items are closer to the end of the
menu.  See the file menu-item-number.txt for the currently used
numbers.  If this field does not appear, or has a value of 0, a module
will not appear on the main menu.

Subarchitecture
---------------

Whitespace seperated list of supported subarchitectures.


Modules will not be installed by a full-fledged dpkg implementation, so the
following features of regular debs will not be supported:

Disallowed Control Files
========================

preinst, postrm, prerm, md5sums, conffiles

Disallowed Headers
==================

* Pre-Depends
* Conflicts
* Essential
* Suggests

Disallowed Header Options
=========================

* `|' in dependencies.

Supported Control Files
========================

postinst

Supported Headers
=================

* Depends, Recommends
  only simple dependencies, no alternatives (versioned dependencies may be
  used, but the version part will be ignored by most of d-i)
* Enhances, Provides


A 2 minute primer on building udebs.
====================================

1. Add a Build-Dependency against debhelper (>= 4.2).
2. Add "XC-Package-Type: udeb" to the package's stanza in the control file.
3. Build the package!
1	Modules
2	-------
3
4	The new debian installer is highly modular. Modules are loaded at several
5	points in the install process to add capabilities to the installer. Modules
6	are essentially sets of files that get unpacked onto the installation
7	system, plus some metadata.
8
9	Because there is already so much infrastructure to build and manage debian
10	packages, and because it allows metadata to accompany the files in a module,
11	we have decided to use debian packages as the modules for the installer. To
12	differentiate them from normal Debian packages, modules have filenames
13	ending in ".udeb". However, modules must not have the same package
14	name as any regular Debian package. The 'u' in udeb stands for Greek
15	mu, meaning micro (udebs take less space than regular debian packages).
16
17	Unlike regular debian packages, modules for the installer will not be
18	policy compliant. They will not contain documentation in /usr/share/doc.
19	They need not comply with the FHS. They may be statically linked. They may
20	conflict with essential "real" debian packages, and thus be non-installable
21	on a real debian system, although it is recommended that if possible, this
22	be avoided.
23
24	Here is a short rundown on differences between deb packages and udebs:
25
26	All udeb packages should be able to build debug versions if
27	DEB_BUILD_OPTIONS="debug".
28
29	Misc.Differences
30	================
31
32	* Udebs must not include .md5sum files.
33
34	New Control Scripts
35	===================
36
37	menutest
38	--------
39
40	Menutest scripts should return a true value (0) if they think it would be a
41	good idea if their menu item was default, and a false value if it doesn't
42	matter. For example in case of a udeb providing an ethernet driver, the
43	menutest script would run a hardware detection routine and return 0 if the
44	particular ethernet card was installed.
45
46	Menutest scripts are optional. If a module does not have one, a simpler
47	default test is used.
48
49	isinstallable
50	-------------
51
52	If this script exists, and when run returns a non-zero value, then
53	its menu item is not displayed.
54
55	New Headers
56	===========
57
58	Installer-Menu-Item
59	-------------------
60
61	A priority (a number). The priority number influences the ordering of
62	items in the menu; higher numbered items are closer to the end of the
63	menu. See the file menu-item-number.txt for the currently used
64	numbers. If this field does not appear, or has a value of 0, a module
65	will not appear on the main menu.
66
67	Subarchitecture
68	---------------
69
70	Whitespace seperated list of supported subarchitectures.
71
72
73	Modules will not be installed by a full-fledged dpkg implementation, so the
74	following features of regular debs will not be supported:
75
76	Disallowed Control Files
77	========================
78
79	preinst, postrm, prerm, md5sums, conffiles
80
81	Disallowed Headers
82	==================
83
84	* Pre-Depends
85	* Conflicts
86	* Essential
87	* Suggests
88
89	Disallowed Header Options
90	=========================
91
92	* `\|' in dependencies.
93
94	Supported Control Files
95	========================
96
97	postinst
98
99	Supported Headers
100	=================
101
102	* Depends, Recommends
103	only simple dependencies, no alternatives (versioned dependencies may be
104	used, but the version part will be ignored by most of d-i)
105	* Enhances, Provides
106
107
108	A 2 minute primer on building udebs.
109	====================================
110
111	1. Add a Build-Dependency against debhelper (>= 4.2).
112	2. Add "XC-Package-Type: udeb" to the package's stanza in the control file.
113	3. Build the package!