1
<appendix id="DevelDescription">
2
<heading>Description of development tools</heading>
4
<heading>Package <package>blends-dev</package></heading>
7
If metapackages are builded using the tools inside the
8
<package>blends-dev</package> package it can be ensured that the
9
resulting metapackages will work nicely with the same version of
10
<package>blends-common</package> package. The goal is to keep
11
necessary changes for the source of the metapackages of a Debian Pure
12
Blend as low as possible when the version of the
13
<package>blends</package> source package changes. Thus it is
14
strongly recommended to use the tools described below.
17
The usage of the tools in the <package>blends-dev</package> package might
18
introduce a versioned dependency in the
19
<package><var><blend></var>-config</package> package from which
20
all other metapackages of the <var>Blend</var> in question will
21
depend. This <package><var><blend></var>-config</package> package
22
instantiates the <var>Blend</var> in the common registry for all Blends in
23
<file>/etc/blends</file>.
26
The best idea to use the tools provided by the
27
<package>blends-dev</package> is to put a <file>Makefile</file> into the
28
build directory containig one single line
31
include /usr/share/blends-dev/Makefile
34
(see <file>/usr/share/doc/blends-dev/examples/Makefile</file>). Using
35
this <file>Makefile</file> all tools that were contained in
36
<package>blends-dev</package> package versions before 0.4. These tools
37
are moved to <file>/usr/share/blends-dev/</file> because there is no need
38
to call them directly. Here is a list of the <file>make</file> targets.
41
<sect1 id="blends-tasks.desc">
42
<heading>Blend<tt>-tasks.desk</tt></heading>
45
This target is the description file that is used in
46
<prgn>tasksel</prgn> to enable selecting the tasks belonging to the
47
Blend. The file will be moved to the
48
<var>blend</var><package>-tasks</package>. All information is obtained
49
from the single task files in the <file>tasks</file> directory of the
54
<sect1 id="debian_control">
55
<heading><tt>debian/control</tt></heading>
58
The <file>debian/control</file> file of a Blend metapackage source
59
archive is auto generated out of dependencies that are specified in so
60
called <file>tasks</file> files. The rationale behind this is to
61
enhance flexibility about changes inside the Debian package pool where
62
new packages might appear and others might be renamed.
63
The <file>tasks</file> just define which dependencies the Blend
64
maintainer group wants to be fulfilled and the
65
script <prgn>blend-gen-control</prgn> verifies whether these
66
dependencies exist in the specified package pool and create
67
the <file>debian/control</file> file according to the available
68
packages. This does not only work for the Debian package pool
69
containing the distributions stable, testing and unstable. You can
70
even build your metapackages against a different package pool of a
71
Debian based distribution. This is for instance used to create the
72
SkoleLinux metapackages.
75
The syntax of the <file>tasks</file> files which serve as the central
76
database for the information in the <file>debian/control</file> file
77
is defined by RFC822. Some of the tags were mentioned formerly in
78
<ref id="packageslist"> to explain how the <file>tasks</file> files
79
can be used to create the web sentinel pages. Now the tags that
80
influence the creation of the <file>debian/control</file> file are given.
85
<item>Will be turned to "Recommends" in the
86
resulting <file>debian/control</file> file. The
87
rationale behind this is to enable installing the
88
metapackage even if a package belonging to this task is
89
missing for whatever reason. It also allows finally to
90
remove the metapackage. This makes even more
91
sense since <prgn>apt-get</prgn> considers "Recommends"
92
as default installation targets.
95
<item>The packages that are listed as "Recommends" in the
96
tasks file should be installed on the machine where the
97
metapackage is installed and which are needed to work
101
<!-- [BA] Why would we suggest non-free? Doesn't policy allow a non-free
102
package to specify "Enhances" to avoid this problem?
103
[AT] I have to admit that "Enhances" is new to me. When
104
reading policy I think this field is out of control of
105
the metapackage developer because it has to be included
106
by the package maintainer. I'm not really convinced that
107
this is a good solution - but I would follow the suggestions
108
of others in this issue.
110
<item><p>Use "Suggests" for packages of lesser importance that
111
might be possibly useful, or non-free packages.</p>
113
If a package is not available in the package pool of the
114
target distribution when creating
115
the <file>debian/control</file> file inside the meta
116
package source archive any "Depends" or "Recommends" are
117
turned into "Suggests" to enable a flawless installation
118
of the metapackage. Packages that are specified with
119
"Suggests" will not be taken over to
120
the <prgn>tasksel</prgn> control file
121
(Blend<file>-tasks.desk</file>,
122
see <ref id="blends-tasks.desc">) but only to the list of
123
suggested packages of the according metapackage.
126
<item>The "Ignore" key can be used as kind of "Soft-Suggests"
127
to put a package on the radar of the Blend. Packages that
128
are tagged with Ignore will not be taken over into the
129
list of dependencies inside
130
the <file>debian/control</file> file of the resulting
131
metapackage neither to the Blend<file>-tasks.desk</file>
132
control file for <prgn>tasksel</prgn> but will be taken
133
over onto the installation medium of a Blend in case there
134
is some space left. This key becomes especially
135
important for specifying not yet packaged software that
136
might be packaged in the future (prospective packages).
137
This is explained in detail in the paragraph about the
138
web sentinel (see <ref id="packageslist">).
141
<item>The "Avoids" key specifies existing packages that will
142
be listed in the the <file>debian/control</file> file as
143
"Recommends" or "Suggests" but, should not go to a
144
installation medium (CD, DVD, etc.) that might be
145
produced by the Blend. A reason to avoid a package might
146
be that it belongs to the non-free section.
153
<heading>Apt <file>sources.list</file> files in <file>/etc/blends/</file></heading>
155
These files are used by <manref name="blend-gen-control" section="1"> to
156
build valid <file>debian/control</file> files that contain only
157
available packages in their dependencies. This enables building meta
158
packages for <tt>stable</tt>, <tt>testing</tt>, <tt>unstable</tt> or
159
even a completely different distribution that has valid
160
<file>sources.list</file> entries. The file
161
<file>/etc/blends/control.list</file> is used as default for <manref
162
name="blend-gen-control" section="1"> and usually is a symbolic link
163
(see <manref name="ln" section="1">) to
164
<file>sources.list.</file><var>distribution</var>. It might be
165
changed using the <tt>-s </tt><var>dist</var> option of <manref
166
name="blend-gen-control" section="1">.
169
<strong>TODO:</strong> <em>Either parse the available
170
<file>/etc/apt/sources.list</file> or use a sane <prgn>debconf</prgn>
171
question to use the "nearest" mirror.</em>
176
<heading>Templates in <file>/usr/share/blends/templates</file></heading>
178
The directory <file>/usr/share/blends/templates</file> contains templates
179
that can be used to build a <var><blend></var><package>-config</package>,
180
which uses the tools that are contained in the
181
<package>blends-common</package> package, and are useful to manage
182
<var><blend></var> user groups (see <ref id="userroles">).
187
<sect id="blends-common">
188
<heading>Package <package>blends-common</package></heading>
191
This package creates a common registry for all Blends in
192
<file>/etc/blends</file>. Each Blend should put the files that are used
193
into a subdirectory named like the Blend of <file>/etc/blends</file>. The
194
<package>blends-common</package> package installs a common configuration
195
file <file>/etc/blends/blends.conf</file>, which can be used to influence the
196
behaviour of the tools described below.
200
<heading><!-- document type does not allow element "MANREF" here--><tt>blend-role(8)</tt></heading>
205
<prgn>blend-role</prgn> - add/remove roles in registered Debian Pure Blend
210
<prgn>blend-role</prgn> <var>add|del</var> <var>Blend</var> [<var>Role</var>]
212
<tag>DESCRIPTION</tag>
213
<item>Add/remove (register/unregister) <var>Role</var> for the
214
specified <var>Blend</var>. If <var>Role</var> is not specified, it's
215
assumed to be named like <var>Blend</var>.
222
<tag><var>Blend</var></tag>
223
<item>A registered Blend in /etc/blends, for example
224
one of <tt>med</tt>, <tt>junior</tt>,
225
<tt>edu</tt> or <tt>science</tt>
230
<item>Andreas Tille <email>tille@debian.org</email>,
231
Cosimo Alfarano <email>kalfa@debian.org</email>.</item>
236
<sect1 id="blend-update-menus">
237
<heading><!-- document type does not allow element "MANREF"
238
here--><tt>blend-update-menus(8)</tt></heading>
243
<prgn>blend-update-menus</prgn> - add menu of metapackage to all Blend users
247
<prgn>blend-update-menus</prgn> [<var>--blend Blend</var> | <var>--user
250
<tag>DESCRIPTION</tag>
253
blend-update-menus behaves differently depending on who run the
258
If it is called by a user, it adds, and keeps updated, menu
259
entries for the user who runs it.
263
If it is called by root, it adds and keeps updated user's menu
264
entries (see menu package for users' menus) for all users who
265
belong to the group of the specified Blend, or only for a specified
266
user, depending on which parameter is passed to the script.
273
<tag><var>Blend</var></tag>
274
<item>one of the installed Blends, listed in /etc/blends/, for example
275
(if installed: <tt>med</tt>, <tt>junior</tt>,
276
<tt>edu</tt> or <tt>science</tt>.
278
<tag><var>user</var></tag>
279
<item>system user</item>
283
<item>Andreas Tille <email>tille@debian.org</email>,
284
Cosimo Alfarano <email>kalfa@debian.org</email>.</item>
290
<heading><!-- document type does not allow element "MANREF" here--><tt>blend-user(8)</tt></heading>
295
<prgn>blend-user</prgn> - add/remove user to Role of a registered Blend
300
<prgn>blend-user</prgn> <var>add|del</var> <var>Blend</var> <var>user</var> [<var>Role</var>]
302
<tag>DESCRIPTION</tag>
303
<item>Add/remove user to a <var>Role</var> of the specified <var>Blend</var>.
305
If <var>Role</var> is not specified, it's assumed to be named like
313
<tag><var>Blend</var></tag>
314
<item>A registered Blend in /etc/blends, for example
315
one of <tt>med</tt>, <tt>junior</tt>,
316
<tt>edu</tt> or <tt>science</tt>.
318
<tag><var>user</var></tag>
319
<item>user to add</item>
320
<tag><var>Role</var></tag>
321
<item>the role in the <var>Blend</var> that <var>user</var> will
326
<item>Andreas Tille <email>tille@debian.org</email>,
327
Cosimo Alfarano <email>kalfa@debian.org</email>.</item>
333
<heading><tt>blends.conf(5)</tt></heading>
338
<file>blends.conf</file> - configuration for Debian Pure Blends registry
340
<tag>DESCRIPTION</tag>
341
<item>This file is sourced from shell scripts inside the Debian
342
Pure Blends package <package>blends-common</package> and thus
343
it has to follow shell syntax. The variables that are set
344
inside this configuration file can be overriden by special
345
Blend configration files
346
<file>/etc/blends/<var><>Blend></var>/<var><>Blend></var>.conf</file>
347
for each single Blend.
349
<item>The following variables can be set:
351
<tag><tt>DBBACKEND</tt></tag>
352
<item>Set the backend for the user role management system.
353
Currently the only implemented role management system is
354
<tt>unixgroups</tt> but others might be implemented
355
later. Unsetting this variable leads to use no roles at all.
357
<tag><tt>UPDATEUSERMENU</tt></tag>
358
<item>If this is set to <tt>yes</tt>, the user menus of meta
359
packages can be created automatically at install time of
360
the package if the postinst script of the package allows
361
this. It is suggested to use this option in the specific
362
configuration files of a special Debian Pure Blend that
363
override the settings of the general configuration file.
365
<tag><tt>SHAREDIR</tt></tag>
366
<item>Set the base directory for the user role management
367
system. While this is more or less a feature for
368
debugging this might be also used otherwise.
370
<tag><tt>DRYRUN</tt></tag>
371
<item>This variable can be set for debugging. Normally it
372
should be left unset (<em>NOT</em> set to <tt>false</tt>
373
or anything else!). If set to <tt>true</tt> a dry run of
374
the tools is performed or <tt>echo DRYRUN:</tt> would
375
print debugging information.
377
<tag><tt>DEBUG</tt></tag>
378
<item>If set to <tt>1</tt> debugging mode is switched on.
383
<file>blend-role (8)</file>, <file>blend-update-menus (8)</file>,
384
<file>blend-user (8)</file>
387
<item>Andreas Tille <email>tille@debian.org</email>,
388
Cosimo Alfarano <email>kalfa@debian.org</email>.</item>
397
<heading>Working with <file>svn</file></heading>
399
Sometimes it might be interesting for developers to check out the
400
latest code of the Blend tools or a special Blend code for the meta
401
packages. In <ref id="communication"> the directory layout of the
402
<file>svn</file>-directory was described. How to derive the
403
Debian packages from this layout?
409
svn checkout svn+ssh://<var>username</var>@svn.debian.org/svn/blends/blends/trunk/blends blends
411
or for the Debian Pure Blend <var>BLEND-name</var>
413
svn checkout svn+ssh://<var>username</var>@svn.debian.org/svn/blends/projects/<var>BLEND-name</var>/trunk
416
<tag>Build source package</tag>
418
Change into the created directory and type
420
make -f debian/rules get-orig-source
422
This creates a <file>tar.gz</file> source archive of the packages
423
you want to build. For your personal comfort you can create a
424
file <file>Makefile</file> in your package source directory containing
427
include /usr/share/blends-dev/Makefile
429
Which enables you to simply say
433
to create the source tarball.
435
<tag>Build Debian packages</tag>
437
Unpack the created source tarball and proceed like you build
438
Debian packages normally.
443
The current Debian Med packages provide a working example how to use
444
the tools described below.
449
<!-- Keep this comment at the end of the file
454
sgml-namecase-general:t
455
sgml-general-insert-case:lower
456
sgml-minimize-attributes:nil
457
sgml-always-quote-attributes:t
460
sgml-parent-document:("../debian-blends.en.sgml" "book" "chapt")
461
sgml-exposed-tags:nil
462
sgml-local-catalogs:nil
463
sgml-local-ecat-files:nil
added
removed
doc/en/A_devel.sgml
