/usr/share/doc/blends-doc/html/apa.html is in blends-doc 0.6.100ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Appendix A. Description of development tools</title><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Debian Pure Blends"><link rel="up" href="index.html" title="Debian Pure Blends"><link rel="prev" href="ch09.html" title="Chapter 9. To do"><link rel="next" href="apb.html" title="Appendix B. Quick intro into building metapackages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix A. Description of development tools</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch09.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apb.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a name="DevelDescription"></a>Appendix A. Description of development tools</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="apa.html#blends-dev">A.1. Package <span class="package">blends-dev</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="apa.html#blends-tasks.desc">A.1.1. Blend<span class="package">-tasks.desk</span></a></span></dt><dt><span class="sect2"><a href="apa.html#debian_control">A.1.2. <code class="filename">debian/control</code></a></span></dt><dt><span class="sect2"><a href="apa.html#statusdump">A.1.3. <span class="package">statusdump</span></a></span></dt><dt><span class="sect2"><a href="apa.html#changelogentry">A.1.4. changelogentry</a></span></dt><dt><span class="sect2"><a href="apa.html#idm2013">A.1.5. Apt <code class="filename">sources.list</code> files in <code class="filename">/etc/blends/</code></a></span></dt><dt><span class="sect2"><a href="apa.html#idm2045">A.1.6. Templates in <code class="filename">/usr/share/blends/templates</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="apa.html#blends-common">A.2. Package <span class="package">blends-common</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="apa.html#idm2063">A.2.1. <span class="citerefentry"><span class="refentrytitle">blend-role</span>(8)</span></a></span></dt><dt><span class="sect2"><a href="apa.html#blend-update-menus">A.2.2. <span class="citerefentry"><span class="refentrytitle">blend-update-menus</span>(8)</span></a></span></dt><dt><span class="sect2"><a href="apa.html#idm2159">A.2.3. <span class="citerefentry"><span class="refentrytitle">blend-user</span>(8)</span></a></span></dt><dt><span class="sect2"><a href="apa.html#idm2219">A.2.4. <span class="citerefentry"><span class="refentrytitle">blends.conf</span>(5)</span></a></span></dt></dl></dd><dt><span class="sect1"><a href="apa.html#developing_normal_packages">A.3. How to develop new normal packages in Pure Blends</a></span></dt><dt><span class="sect1"><a href="apa.html#svn">A.4. Working with the source repository (<code class="filename">svn</code> in process of moving to <code class="filename">git</code>)</a></span></dt><dt><span class="sect1"><a href="apa.html#webpagecreation">A.5. How to create tasks and bugs pages of web sentinel</a></span></dt><dt><span class="sect1"><a href="apa.html#staticwebpages">A.6. Editing static web pages of Blends on blends.debian.org</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="blends-dev"></a>A.1. Package <span class="package">blends-dev</span></h2></div></div></div><p>
If metapackages are builded using the tools inside the
<span class="package">blends-dev</span> package it can be ensured that the
resulting metapackages will work nicely with the same version of
<span class="package">blends-common</span> package. The goal is to keep
necessary changes for the source of the metapackages of a Debian Pure
Blend as low as possible when the version of the
<span class="package">blends</span> source package changes. Thus it is
strongly recommended to use the tools described below.
</p><p>
The usage of the tools in the <span class="package">blends-dev</span> package might
introduce a versioned dependency in the
<code class="varname"><blend></code>-<span class="package">config</span> package from which
all other metapackages of the <code class="varname">Blend</code> in question will
depend. This <code class="varname"><blend></code>-<span class="package">config</span> package
instantiates the <code class="varname">Blend</code> in the common registry for all Blends in
<code class="filename">/etc/blends</code>.
</p><p>
The version <span class="package">0.7.0</span> of <span class="package">blends-dev</span> uses
<a class="ulink" href="https://wiki.debian.org/UltimateDebianDatabase" target="_top">UDD</a>
to generate Blends' metapackages. Currently all Blends' info is stored into UDD.
Information such as VCs, description, homepage etc for a Blend can be found into the
<a class="ulink" href="http://udd.debian.org/schema/udd.html#public.table.blends-metadata" target="_top">blends_metadata</a>
UDD table. All the info about Blends' tasks and their package dependencies are also stored
into the <a class="ulink" href="http://udd.debian.org/schema/udd.html#public.table.blends-tasks" target="_top">blends_tasks</a> and
<a class="ulink" href="http://udd.debian.org/schema/udd.html#public.table.blends-dependencies-alternatives" target="_top">
blends_dependencies_alternatives</a>
tables. Having the latter in combination with other UDD tables
(such as a table with info about all Debian available packages)
provides the ability to check whether a package exists for an architecture or not thus
<span class="package">blends-dev</span> can generate architecture dependent metapackages.
</p><p>
The best idea to use the tools provided by the
<span class="package">blends-dev</span> is to put a <code class="filename">Makefile</code> into the
build directory containing one single line
</p><div class="informalexample"><pre class="programlisting">
include /usr/share/blends-dev/Makefile
</pre></div><p>
(see <code class="filename">/usr/share/doc/blends-dev/examples/Makefile</code>).
Users using <span class="package">blends-dev 0.7.0</span> on existing Blends
which have more than one releases might encouter some <code class="filename">Makefile</code>
errors for more info see <a class="xref" href="apa.html#statusdump" title="A.1.3. statusdump">Section A.1.3, “<span class="package">statusdump</span>”</a> and <a class="xref" href="apa.html#changelogentry" title="A.1.4. changelogentry">Section A.1.4, “changelogentry”</a>.
Using this <code class="filename">Makefile</code> all tools that were contained in
<span class="package">blends-dev</span> package versions before 0.4. These tools
are moved to <code class="filename">/usr/share/blends-dev/</code> because there is no need
to call them directly. Here is a list of the <code class="filename">make</code> targets.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="blends-tasks.desc"></a>A.1.1. Blend<span class="package">-tasks.desk</span></h3></div></div></div><p>
This target generates a <span class="package">task-description.template</span> file.
The template can be converted to a proper description file that is used in
<span class="package">tasksel</span> to enable selecting the tasks belonging to the Blend.
The initial template contains all the needed package dependencies
for a Blend. But because some packages might not be available for a(or multiple)
architectures the template uses the following syntax when specifying packages:
</p><div class="informalexample"><pre class="programlisting"> package1 [!arch1 arch2]</pre></div><p>
That says do not include the package1 in the
taskdescription file when arch1 or arch2 is used.
When a Blends' <span class="package">orig.tar.gz</span> is generated,
the initial template gets converted
from the <span class="package">blends-dev rules</span> file to a proper taskdescription file.
The convertion is filtering out the packages which are not available for the
host's (where the <span class="package">orig.tar.gz</span> is generated) architecture.
This make sure that the taskdescription file will not include package which are
not available for the target architecture.
Finally the file will be moved to the
<code class="varname">blend</code><span class="package">-tasks</span>. All information
about Blends package dependencies is obtained from the UDD.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="debian_control"></a>A.1.2. <code class="filename">debian/control</code></h3></div></div></div><p>
The <code class="filename">debian/control</code> file of a Blend metapackage source
archive is auto generated out of dependencies that are specified in so
called <code class="filename">tasks</code> files. The rationale behind this is to
enhance flexibility about changes inside the Debian package pool where
new packages might appear and others might be renamed.
The <code class="filename">tasks</code> just define which dependencies the Blend
maintainer group wants to be fulfilled and the
script <span class="package">blend-gen-control</span> using UDD verifies whether these
dependencies exist in a specified package pool. A
package pool can be considered as the packages available for a
combination of distribution, component and release values. By default when
creating metapackages debian,main,testing values are used to "create" a package pool from UDD.
Once a Blends' dependencies are verified the <code class="filename">debian/control</code> file is generated
according to the available packages. This does not only work for the Debian package pool
containing the distributions stable, testing and unstable. You can
even build your metapackages against a different package pool of a
Debian based distribution. This is for instance used to create the
SkoleLinux metapackages.
</p><p>
As mentioned in the previous section, using UDD in Blends' tools provides the ability to generate
architecture dependent metapackages. Thus the generated
<span class="package">debian/control</span> specifies for every task source target as architecture value:
</p><div class="informalexample"><pre class="programlisting">Architecture: any</pre></div><p>
Specifying <span class="package">any</span> indicates that the source package isn't dependent
on any particular architecture and should compile fine on any one. To fulfil this
in case of missing packages <span class="package">control</span> file uses the following syntax:
</p><div class="informalexample"><pre class="programlisting">Depends: package1 [!arch1 !arch2]</pre></div><p>
If a package is not available for a specific arch, exclude it from it. So the above example says:
depend on package1 but not when architecture arch1 or arch2 is used. More info about
<span class="package">debian/control</span> syntax can be found in
<a class="ulink" href="http://www.debian.org/doc/debian-policy/" target="_top">Debian Policy Manual</a>
</p><p>
The syntax of the <code class="filename">tasks</code> files which serve as the central
database for the information in the <code class="filename">debian/control</code> file
is defined by RFC822. Some of the tags were mentioned formerly in
<a class="xref" href="ch08.html#packageslist" title="8.1. Existing and prospective packages">Section 8.1, “Existing and prospective packages”</a> to explain how the <code class="filename">tasks</code> files
can be used to create the web sentinel pages. In order to write valid task
files it is mandatory to separate a task file paragraph by an empty line.
Otherwise the task pages of the web sentinel will not be built correctly. Now the tags that
influence the creation of the <code class="filename">debian/control</code> file are given.
</p><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Depends</span></dt><dd><p>Will be turned to "Recommends" in the
resulting <code class="filename">debian/control</code> file. The
rationale behind this is to enable installing the
metapackage even if a package belonging to this task is
missing for whatever reason. It also allows finally to
remove the metapackage. This makes even more
sense since <span class="package">apt-get</span> considers "Recommends"
as default installation targets.</p></dd><dt><span class="term">Recommends</span></dt><dd><p>The packages that are listed as "Recommends" in the
tasks file should be installed on the machine where the
metapackage is installed and which are needed to work
on a specific task.</p></dd><dt><span class="term">Suggests</span></dt><dd><p>Use "Suggests" for packages of lesser importance that
might be possibly useful, or non-free packages.</p><p>
If a package is not available in the package pool of the
target distribution when creating
the <code class="filename">debian/control</code> file inside the meta
package source archive any "Depends" or "Recommends" are
turned into "Suggests" to enable a flawless installation
of the metapackage. Generally packages are concerned as missing if
they do not exist into Debian main component(default is testing release).
Packages that are specified with
"Suggests" will not be taken over to
the <span class="package">tasksel</span> control file
(Blend<code class="filename">-tasks.desk</code>,
see <a class="xref" href="apa.html#blends-tasks.desc" title="A.1.1. Blend-tasks.desk">Section A.1.1, “Blend<span class="package">-tasks.desk</span>”</a>) but only to the list of
suggested packages of the according metapackage.</p></dd><dt><span class="term">Ignore</span></dt><dd><p>The "Ignore" key can be used as kind of "Soft-Suggests"
to put a package on the radar of the Blend. Packages that
are tagged with Ignore will not be taken over into the
list of dependencies inside
the <code class="filename">debian/control</code> file of the resulting
metapackage neither to the Blend<code class="filename">-tasks.desk</code>
control file for <span class="package">tasksel</span> but will be taken
over onto the installation medium of a Blend in case there
is some space left. This key becomes especially
important for specifying not yet packaged software that
might be packaged in the future (prospective packages).
This is explained in detail in the paragraph about the
web sentinel (see <a class="xref" href="ch08.html#packageslist" title="8.1. Existing and prospective packages">Section 8.1, “Existing and prospective packages”</a>).</p></dd><dt><span class="term">Avoids</span></dt><dd><p>The "Avoids" key specifies existing packages that will
be listed in the the <code class="filename">debian/control</code> file as
"Recommends" or "Suggests" but, should not go to a
installation medium (CD, DVD, etc.) that might be
produced by the Blend. A reason to avoid a package might
be that it belongs to the non-free section.</p></dd></dl></div><p>
</p></div><p>
Example:
</p><div class="informalexample"><pre class="programlisting">
Task: finest
Description: the finest software
Depends: foo
Depends: bar
Suggests: foobar
</pre></div><p>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="statusdump"></a>A.1.3. <span class="package">statusdump</span></h3></div></div></div><p>
This target generates a json file containing the latest package dependencies
for the selected Blend. It parses the files from the <span class="package">tasks</span> directory
and generates a <code class="varname">blend</code><span class="package">_version.json</span> into a <span class="package">dependency_data</span>
directory. As <span class="package">version</span> it gets the latest version specified in the Blend's
<span class="package">debian/changelog</span> file. In case the <span class="package">dependency_data</span> directory
does not exist into a Blend's root directory it automatically creates it.
</p><p>
A user can also generate a json dependencies file manually
using the <span class="package">tasks_diff</span> script. The script can be called
from a Blend's root directory:
</p><div class="informalexample"><pre class="programlisting">
/usr/share/blends-dev/task_diff --status-dump --tasks . --output blend_version.json
</pre></div><p>
If the user does not specify the output argument the script by default
will generate the json file under the <span class="package">tasks.json</span> name in the
current directory.
</p><p>
Note: in case a user needs to generate a json file for a previous release
(rather than the latest) to get the <span class="package">changelogentry</span>
(see <a class="xref" href="apa.html#changelogentry" title="A.1.4. changelogentry">Section A.1.4, “changelogentry”</a>) target to work, must keep the following thing in mind:
The user must provide to <span class="package">task_diff</span> script the <span class="emphasis"><em>root</em></span> directory of a previous Blend release
(through the --task(-t) argument). He should also save the output into the <span class="package">dependency_data</span>
directory into the latest Blend release providing manually
the name <code class="varname">blend</code><span class="package">_version.json</span> (through the --output(-o) argument:
</p><div class="informalexample"><pre class="programlisting">
/usr/share/blends-dev/task_diff --status-dump -t blend/tags/previous/ -o latest_blend/dependency_data/blend_version.json
</pre></div><p>
For example if the name of the Blend is <span class="package">myblend</span> and the release is <span class="package">0.2.0</span>
then the json file must have the name <span class="package">myblend_0.2.0.json</span>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="changelogentry"></a>A.1.4. changelogentry</h3></div></div></div><p>
This target compares the latest and the previous Blend release and dumps the tasks'
package differences. It reports the added/removed packages
per task (or added/removed task files)
between releases. This "report" is automatically
added into the <code class="filename">debian/changelog</code>
in the latest relase section under the file's manual changes.
In case a previous difference report
exists, it overrides it. In case a Blend does not have more than release
(initial release) then this target is ignored.
</p><p>
In order the comparison to be properly performed the
<code class="varname">blend</code><code class="filename">_version.json</code> files for the two latest releases
must exist under the <code class="filename">dependency_data</code> directory. In case any of the
previous files is missing then the target will fail with an error
(specifying the missing version_file). The json file for the latest
release is automatically generated from the <span class="package">statusdump</span> target
so it this will not cause the problem.
</p><p>
This changelog entry is a new feature so the problem of this target failing
(because of a missing json file) will appear for existing Blends which have
more than one releases and do not have a <code class="varname">blend</code><code class="filename">_version.json</code>
for the previous release under their <code class="filename">dependency_data</code> directory.
Usually Blend's releases are tagged into the VCs, so the previous problem
can be solved by generating the dependency json file for the previous
release (using a previous VCs tag). This can be done by calling manually
the <span class="package">task_diff</span> script (see <a class="xref" href="apa.html#statusdump" title="A.1.3. statusdump">Section A.1.3, “<span class="package">statusdump</span>”</a>)
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm2013"></a>A.1.5. Apt <code class="filename">sources.list</code> files in <code class="filename">/etc/blends/</code></h3></div></div></div><p>
These files are used by <span class="citerefentry"><span class="refentrytitle">blend-gen-control</span>(1)</span> to
build valid <code class="filename">debian/control</code> files that contain only
available packages in their dependencies. This enables building meta
packages for <span class="package">stable</span>, <span class="package">testing</span>, <span class="package">unstable</span> or
even a completely different distribution that has valid
<code class="filename">sources.list</code> entries. The file
<code class="filename">/etc/blends/control.list</code> is used as default for
<span class="citerefentry"><span class="refentrytitle">blend-gen-control</span>(1)</span> and usually is a symbolic link
(see <span class="citerefentry"><span class="refentrytitle">ln</span>(1)</span>) to
<code class="filename">sources.list.</code><code class="varname">distribution</code>. It might be
changed using the <span class="package">-s </span><code class="varname">dist</code> option of <span class="citerefentry"><span class="refentrytitle">blend-gen-control</span>(1)</span>.
</p><p>
<span class="emphasis"><em>TODO:</em></span> <span class="emphasis"><em>Either parse the available
<code class="filename">/etc/apt/sources.list</code> or use a sane <span class="orgname">debconf</span>
question to use the "nearest" mirror.</em></span>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm2045"></a>A.1.6. Templates in <code class="filename">/usr/share/blends/templates</code></h3></div></div></div><p>
The directory <code class="filename">/usr/share/blends/templates</code> contains templates
that can be used to build a <code class="varname"><blend></code><span class="package">-config</span>,
which uses the tools that are contained in the
<span class="package">blends-common</span> package, and are useful to manage
<code class="varname"><blend></code> user groups (see <a class="xref" href="ch06.html#userroles" title="6.3. User roles">Section 6.3, “User roles”</a>).
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="blends-common"></a>A.2. Package <span class="package">blends-common</span></h2></div></div></div><p>
This package creates a common registry for all Blends in
<code class="filename">/etc/blends</code>. Each Blend should put the files that are used
into a subdirectory named like the Blend of <code class="filename">/etc/blends</code>. The
<span class="package">blends-common</span> package installs a common configuration
file <code class="filename">/etc/blends/blends.conf</code>, which can be used to influence the
behaviour of the tools described below.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm2063"></a>A.2.1. <span class="citerefentry"><span class="refentrytitle">blend-role</span>(8)</span></h3></div></div></div><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">NAME</span></dt><dd><p>
<span class="package">blend-role</span> - add/remove roles in registered Debian Pure Blend
</p></dd><dt><span class="term">SYNOPSIS</span></dt><dd><p>
<span class="package">blend-role</span> <code class="varname">add|del</code> <code class="varname">Blend</code>
[<code class="varname">Role</code>]</p></dd><dt><span class="term">DESCRIPTION</span></dt><dd><p>Add/remove (register/unregister) <code class="varname">Role</code> for the
specified <code class="varname">Blend</code>. If <code class="varname">Role</code> is not specified, it's
assumed to be named like <code class="varname">Blend</code>.</p></dd><dt><span class="term">OPTIONS</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">Blend</code></span></dt><dd><p>A registered Blend in /etc/blends, for example
one of <span class="package">med</span>, <span class="package">junior</span>,
<span class="package">edu</span> or <span class="package">science</span></p></dd></dl></div></dd><dt><span class="term">AUTHOR</span></dt><dd><p>Andreas Tille <code class="email"><<a class="email" href="mailto:tille@debian.org">tille@debian.org</a>></code>,
Cosimo Alfarano <code class="email"><<a class="email" href="mailto:kalfa@debian.org">kalfa@debian.org</a>></code>.</p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="blend-update-menus"></a>A.2.2. <span class="citerefentry"><span class="refentrytitle">blend-update-menus</span>(8)</span></h3></div></div></div><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">NAME</span></dt><dd><p>
<span class="package">blend-update-menus</span> - add menu of metapackage to all Blend users</p></dd><dt><span class="term">SYNOPSIS</span></dt><dd><p>
<span class="package">blend-update-menus</span> [<code class="varname">--blend Blend</code> | <code class="varname">--user
user</code>]</p></dd><dt><span class="term">DESCRIPTION</span></dt><dd><p>
blend-update-menus behaves differently depending on who run the
command:
</p><p>
If it is called by a user, it adds, and keeps updated, menu
entries for the user who runs it.
</p><p>
If it is called by root, it adds and keeps updated user's menu
entries (see menu package for users' menus) for all users who
belong to the group of the specified Blend, or only for a specified
user, depending on which parameter is passed to the script.
</p></dd><dt><span class="term">OPTIONS</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">Blend</code></span></dt><dd><p>one of the installed Blends, listed in /etc/blends/, for example
(if installed: <span class="package">med</span>, <span class="package">junior</span>,
<span class="package">edu</span> or <span class="package">science</span>.</p></dd><dt><span class="term"><code class="varname">user</code></span></dt><dd><p>system user</p></dd></dl></div></dd><dt><span class="term">AUTHOR</span></dt><dd><p>Andreas Tille <code class="email"><<a class="email" href="mailto:tille@debian.org">tille@debian.org</a>></code>,
Cosimo Alfarano <code class="email"><<a class="email" href="mailto:kalfa@debian.org">kalfa@debian.org</a>></code>.</p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm2159"></a>A.2.3. <span class="citerefentry"><span class="refentrytitle">blend-user</span>(8)</span></h3></div></div></div><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">NAME</span></dt><dd><p>
<span class="package">blend-user</span> - add/remove user to Role of a registered Blend</p></dd><dt><span class="term">SYNOPSIS</span></dt><dd><p>
<span class="package">blend-user</span> <code class="varname">add|del</code> <code class="varname">Blend</code> <code class="varname">user</code> [<code class="varname">Role</code>]
</p></dd><dt><span class="term">DESCRIPTION</span></dt><dd><p>Add/remove user to a <code class="varname">Role</code> of the specified <code class="varname">Blend</code>.
If <code class="varname">Role</code> is not specified, it's assumed to be named like
<code class="varname">Blend</code></p></dd><dt><span class="term">OPTIONS</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">Blend</code></span></dt><dd><p>A registered Blend in /etc/blends, for example
one of <span class="package">med</span>, <span class="package">junior</span>,
<span class="package">edu</span> or <span class="package">science</span>.</p></dd><dt><span class="term"><code class="varname">user</code></span></dt><dd><p>user to add</p></dd><dt><span class="term"><code class="varname">Role</code></span></dt><dd><p>the role in the <code class="varname">Blend</code> that <code class="varname">user</code> will
assume</p></dd></dl></div></dd><dt><span class="term">AUTHOR</span></dt><dd><p>Andreas Tille <code class="email"><<a class="email" href="mailto:tille@debian.org">tille@debian.org</a>></code>,
Cosimo Alfarano <code class="email"><<a class="email" href="mailto:kalfa@debian.org">kalfa@debian.org</a>></code>.</p></dd></dl></div><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm2219"></a>A.2.4. <span class="citerefentry"><span class="refentrytitle">blends.conf</span>(5)</span></h3></div></div></div><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">NAME</span></dt><dd><p>
<code class="filename">blends.conf</code> - configuration for Debian Pure Blends registry
</p></dd><dt><span class="term">DESCRIPTION</span></dt><dd><p>This file is sourced from shell scripts inside the Debian
Pure Blends package <span class="package">blends-common</span> and thus
it has to follow shell syntax. The variables that are set
inside this configuration file can be overriden by special
Blend configration files
<code class="filename">/etc/blends/</code><code class="varname">Blend></code>/<code class="varname">Blend></code><code class="filename">.conf</code>
for each single Blend.</p></dd><dt><span class="term">SYNTAX</span></dt><dd><p>The following variables can be set:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="package">DBBACKEND</span></span></dt><dd><p>Set the backend for the user role management system.
Currently the only implemented role management system is
<span class="package">unixgroups</span> but others might be implemented
later. Unsetting this variable leads to use no roles at all.</p></dd><dt><span class="term"><span class="package">UPDATEUSERMENU</span></span></dt><dd><p>If this is set to <span class="package">yes</span>, the user menus of meta
packages can be created automatically at install time of
the package if the postinst script of the package allows
this. It is suggested to use this option in the specific
configuration files of a special Debian Pure Blend that
override the settings of the general configuration file.</p></dd><dt><span class="term"><span class="package">SHAREDIR</span></span></dt><dd><p>Set the base directory for the user role management
system. While this is more or less a feature for
debugging this might be also used otherwise. </p></dd><dt><span class="term"><span class="package">DRYRUN</span></span></dt><dd><p>This variable can be set for debugging. Normally it
should be left unset (<span class="emphasis"><em>NOT</em></span> set to <span class="package">false</span>
or anything else!). If set to <span class="package">true</span> a dry run of
the tools is performed or <span class="package">echo DRYRUN:</span> would
print debugging information. </p></dd><dt><span class="term"><span class="package">DEBUG</span></span></dt><dd><p>If set to <span class="package">1</span> debugging mode is switched on.</p></dd></dl></div></dd><dt><span class="term">SEE ALSO</span></dt><dd><p>
<span class="citerefentry"><span class="refentrytitle">blend-role</span>(8)</span>, <span class="citerefentry"><span class="refentrytitle">blend-update-menus</span>(8)</span>,
<span class="citerefentry"><span class="refentrytitle">blend-user</span>(8)</span></p></dd><dt><span class="term">AUTHOR</span></dt><dd><p>Andreas Tille <code class="email"><<a class="email" href="mailto:tille@debian.org">tille@debian.org</a>></code>,
Cosimo Alfarano <code class="email"><<a class="email" href="mailto:kalfa@debian.org">kalfa@debian.org</a>></code>.</p></dd></dl></div><p>
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="developing_normal_packages"></a>A.3. How to develop new normal packages in Pure Blends</h2></div></div></div><p>
Sometimes you may want to develop new packages for your Pure Blend. It is almost
identical to creating a new debian package. But in Blends framework you can do it more
easily.
</p><p>
Assume that you have already had a well-defined blend. That is, those necessary files
like changelog, compat, copyright and control.stub are in your debian/ folder, maybe
with postinst.stub or prerm.stub for task metapackages. Notice that, all these control
and maintainer scripts are just for metapackages defined in your task, not for your new,
normal packages since they aren't listed in task.
</p><p>
When you want to develop and add new packages, just like debian packaging, you need to
add package informations and parameters in the control file. However in blends, you should
add them in debian/control.stub instead of defining their own control file. For the
maintainer script files, you need to add them in debian/ folder. However, notice that
the maintainer script files should not add ".stub" or blends-dev won't process them.
</p><p>
For example, in blend "foo", we want to add a new normal package "bar". In debian/control.stub,
we may have:
</p><pre class="programlisting">
Source: foo
Section: misc
Priority: extra
Maintainer: Foo Team <debian-foo@lists.org>
Uploaders: Foo bar <foo-bar@nowhere.com>
Build-Depends: debhelper (>= 7), blends-dev (>= 0.6.91)
Standards-Version: 3.9.3
Dm-Upload-Allowed: yes
Homepage: http://foo.bar/
Package: foo-bar
Architecture: all
Description: sample blends and packages
</pre><p>
</p><p>
In the control.stub it defines foo blends, and a new package foo-bar. Then, in the
debian folder, we can add our own preinst, postinst, prerm, and/or postrm maintainer
scripts. However the filename should be foo-bar.preinst, foo-bar.postinst, ... etc.,
instead of foo-bar.postinst.stub, since foo-bar doesn't exist in tasks.
</p><p>
After those control files are done, you can use
</p><pre class="programlisting">make dist</pre><p>
to create blends control files, and then use </p><pre class="programlisting">debuild</pre><p>
to start packaging.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="svn"></a>A.4. Working with the source repository (<code class="filename">svn</code> in process of moving to <code class="filename">git</code>)</h2></div></div></div><p>
Sometimes it might be interesting for developers to check out the
latest code of the Blend tools or a special Blend code for the meta
packages. In <a class="xref" href="ch09.html#communication" title="9.1. Establishing and using communication platforms">Section 9.1, “Establishing and using communication platforms”</a> the directory layout of the
<code class="filename">svn</code>-directory was described. How to derive the
Debian packages from this layout?
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Checkout</span></dt><dd><p>
For the Blend tools and this documentation
</p><div class="informalexample"><pre class="programlisting">
git clone git+ssh://<code class="varname">username</code>@git.debian.org/git/blends/blends.git
</pre></div><p>
or for the Debian Pure Blend <code class="varname">BLEND-name</code>
</p><div class="informalexample"><pre class="programlisting">
svn checkout svn+ssh://<code class="varname">username</code>@svn.debian.org/svn/blends/projects/<code class="varname">BLEND-name</code>/trunk
</pre></div><p>
Note: This will be moved to Git (at least) soon after Wheezy release.</p></dd><dt><span class="term">Build source package</span></dt><dd><p>
Change into the created directory and type
</p><div class="informalexample"><pre class="programlisting">
make -f debian/rules get-orig-source
</pre></div><p>
This creates a <code class="filename">tar.gz</code> source archive of the packages
you want to build. For your personal comfort you can create a
file <code class="filename">Makefile</code> in your package source directory containing
</p><div class="informalexample"><pre class="programlisting">
#!/usr/bin/make -f
include /usr/share/blends-dev/Makefile
</pre></div><p>
</p><pre class="programlisting">
Which enables you to simply say
</pre><p>
</p><div class="informalexample"><pre class="programlisting">
make dist
</pre></div><p>
to create the source tarball.
</p></dd><dt><span class="term">Build Debian packages</span></dt><dd><p>
Unpack the created source tarball and proceed like you build
Debian packages normally.</p></dd></dl></div><p>
</p><p>
The current Debian Med packages provide a working example how to use
the tools described below.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="webpagecreation"></a>A.5. How to create tasks and bugs pages of web sentinel</h2></div></div></div><p>
In <a class="xref" href="ch08.html" title="Chapter 8. The web sentinel">Chapter 8, <i>The web sentinel</i></a> the creation of so called tasks
pages <a class="xref" href="ch08.html#packageslist" title="8.1. Existing and prospective packages">Section 8.1, “Existing and prospective packages”</a> and bugs pages <a class="xref" href="ch08.html#bugs" title="8.3. Bugs overview">Section 8.3, “Bugs overview”</a> was
described. These pages are automatically build by a cron job on blends.debian.org
from the current state of the tasks files in the SVN repository.
If you have commited changes to the tasks pages and want to see the
effect immediately the steps to do are as follows:
</p><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Login to <span class="package">dillon.debian.org</span></p></li><li class="listitem"><p><span class="package">sudo -u blends -s</span></p></li><li class="listitem"><p><code class="filename">cd /srv/blends.debian.org/webtools/</code></p></li><li class="listitem"><p><code class="filename">./tasks.py <blend-name></code></p></li><li class="listitem"><p><code class="filename">/usr/local/bin/static-update-component blends.debian.org</code></p></li></ol></div><p>
</p><p>
To know what a valid <span class="package"><blend-name></span> might be have a look
into
<code class="filename">/srv/blends.debian.org/webtools/webconf</code>.
Each Blend has an according config file there. Leave out
the <code class="filename">.conf</code> extension and you have a
valid <span class="package"><blend-name></span>.
</p><p>
In case you are planing some more experimental changes there is
another host (sponsored by GPLhost.com)
called <span class="package">blends.debian.net</span> which is running a copy of
UDD and also hosts the latest development snapshot of the Blends web
tools. Just ask Andreas Tille <code class="email"><<a class="email" href="mailto:tille@debian.org">tille@debian.org</a>></code> in case
you like a login on this host.
</p><p>
The code which builds web and tasks pages is available in Git at
<code class="filename">git://git.debian.org/git/blends/website.git</code>. It is
using the <a class="ulink" href="http://genshi.edgewall.org/" target="_top">Genshi
templating system</a> which enables influencing the layout of the pages
by editing the templates in the
<code class="filename">templates</code> directory.
You can also influence some parameters of the web pages in the
configuration files in the <code class="filename">webconf</code> directory.
Last but not least you can provide translations for the web pages in
the <code class="filename">po</code> directory.
</p><p>
Once something on the web pages was changed you can activate the
changes as follows:
</p><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Login to <span class="package">dillon.debian.org</span> or <span class="package">blends.debian.net</span></p></li><li class="listitem"><p><code class="filename">sudo -u blends -s</code> (only on dillon.d.o)</p></li><li class="listitem"><p><code class="filename">cd /srv/blends.debian.org/</code></p></li><li class="listitem"><p><code class="filename">git pull</code></p></li><li class="listitem"><p><code class="filename">~/bin/my_static-update-component</code> (only on dillon.d.o to sync changes to the distributed host blends.debian.org)</p></li></ol></div><p>
</p><p>
Please note that the <code class="filename">css</code> and <code class="filename">js</code> files which are
influencing the layout of the automatically created pages are in
the same area as the static web pages (see below <a class="xref" href="apa.html#staticwebpages" title="A.6. Editing static web pages of Blends on blends.debian.org">Section A.6, “Editing static web pages of Blends on blends.debian.org”</a>).
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="staticwebpages"></a>A.6. Editing static web pages of Blends on blends.debian.org</h2></div></div></div><p>
A very simple entry page is created for each Blend which is linked
from the
<a class="ulink" href="http://blends.debian.org/" target="_top">list of all Blends</a>.
Most probably the maintainers of a Blend want to enhance this page a
bit. Maintainers of a Blend should care for this index page which currently is just
featuring links to the automatically updated pages as well as an image
which shows the activity of the
<a class="ulink" href="http://people.debian.org/~tille/talks/200808_lightning/liststats.pdf" target="_top">
relevant mailing list</a>. Maintaining these static pages is
not a "service" which is done for you. The maintainers of a Blend
should care for this!
</p><p>
The static pages are maintained in Git at
<code class="filename">git://git.debian.org/git/blends/website.git</code> in the
<code class="filename">websites</code> directory.
Once you have changed the content of the pages you can activate
the changes by doing:
</p><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Login to <span class="package">dillon.debian.org</span> or <span class="package">blends.debian.net</span></p></li><li class="listitem"><p><code class="filename">sudo -u blends -s</code> (only on dillon.d.o)</p></li><li class="listitem"><p><code class="filename">cd /srv/blends.debian.org/</code></p></li><li class="listitem"><p><code class="filename">git pull</code></p></li><li class="listitem"><p><code class="filename">~/bin/my_static-update-component</code> (only on dillon.d.o to sync changes to the distributed host blends.debian.org)</p></li></ol></div><p>
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch09.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="apb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. To do </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix B. Quick intro into building metapackages</td></tr></table></div></body></html>
|