Description of development tools Package `blends-dev`

If metapackages are builded using the tools inside the `blends-dev` package it can be ensured that the resulting metapackages will work nicely with the same version of `blends-common` 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 `blends` source package changes. Thus it is strongly recommended to use the tools described below.

The usage of the tools in the `blends-dev` package might introduce a versioned dependency in the `<blend>-config` package from which all other metapackages of the Blend in question will depend. This `<blend>-config` package instantiates the Blend in the common registry for all Blends in /etc/blends.

The best idea to use the tools provided by the `blends-dev` is to put a Makefile into the build directory containig one single line

include /usr/share/blends-dev/Makefile
(see /usr/share/doc/blends-dev/examples/Makefile). Using this Makefile all tools that were contained in `blends-dev` package versions before 0.4. These tools are moved to /usr/share/blends-dev/ because there is no need to call them directly. Here is a list of the make targets.
Blend`-tasks.desk`

This target is the description file that is used in tasksel to enable selecting the tasks belonging to the Blend. The file will be moved to the blend`-tasks`. All information is obtained from the single task files in the tasks directory of the Blend source.

`debian/control`

The debian/control file of a Blend metapackage source archive is auto generated out of dependencies that are specified in so called tasks 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 tasks just define which dependencies the Blend maintainer group wants to be fulfilled and the script blend-gen-control verifies whether these dependencies exist in the specified package pool and create the debian/control file 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.

The syntax of the tasks files which serve as the central database for the information in the debian/control file is defined by RFC822. Some of the tags were mentioned formerly in to explain how the tasks files can be used to create the web sentinel pages. Now the tags that influence the creation of the debian/control file are given.

`Depends` Will be turned to "Recommends" in the resulting debian/control 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 apt-get considers "Recommends" as default installation targets. `Recommends` 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. `Suggests`

Use "Suggests" for packages of lesser importance that might be possibly useful, or non-free packages.

If a package is not available in the package pool of the target distribution when creating the debian/control file inside the meta package source archive any "Depends" or "Recommends" are turned into "Suggests" to enable a flawless installation of the metapackage. Packages that are specified with "Suggests" will not be taken over to the tasksel control file (Blend-tasks.desk, see ) but only to the list of suggested packages of the according metapackage. `Ignore` 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 debian/control file of the resulting metapackage neither to the Blend-tasks.desk control file for tasksel 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 ). `Avoids` The "Avoids" key specifies existing packages that will be listed in the the debian/control 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.

Apt sources.list files in /etc/blends/

These files are used by to build valid debian/control files that contain only available packages in their dependencies. This enables building meta packages for `stable`, `testing`, `unstable` or even a completely different distribution that has valid sources.list entries. The file /etc/blends/control.list is used as default for and usually is a symbolic link (see ) to sources.list.distribution. It might be changed using the `-s` dist option of .

TODO: Either parse the available /etc/apt/sources.list or use a sane debconf question to use the "nearest" mirror.

Templates in /usr/share/blends/templates

The directory /usr/share/blends/templates contains templates that can be used to build a <blend>`-config`, which uses the tools that are contained in the `blends-common` package, and are useful to manage <blend> user groups (see ).

Package `blends-common`

This package creates a common registry for all Blends in /etc/blends. Each Blend should put the files that are used into a subdirectory named like the Blend of /etc/blends. The `blends-common` package installs a common configuration file /etc/blends/blends.conf, which can be used to influence the behaviour of the tools described below.

`blend-role(8)`

`NAME` blend-role - add/remove roles in registered Debian Pure Blend `SYNOPSIS` blend-role add|del Blend [Role] `DESCRIPTION` Add/remove (register/unregister) Role for the specified Blend. If Role is not specified, it's assumed to be named like Blend. `OPTIONS` `Blend` A registered Blend in /etc/blends, for example one of `med`, `junior`, `edu` or `science` `AUTHOR` Andreas Tille tille@debian.org, Cosimo Alfarano kalfa@debian.org.

`blend-update-menus(8)`

`NAME` blend-update-menus - add menu of metapackage to all Blend users `SYNOPSIS` blend-update-menus [--blend Blend | --user user] `DESCRIPTION`

blend-update-menus behaves differently depending on who run the command:

If it is called by a user, it adds, and keeps updated, menu entries for the user who runs it.

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.

`OPTIONS` `Blend` one of the installed Blends, listed in /etc/blends/, for example (if installed: `med`, `junior`, `edu` or `science`. `user` system user `AUTHOR` Andreas Tille tille@debian.org, Cosimo Alfarano kalfa@debian.org.
`blend-user(8)`

`NAME` blend-user - add/remove user to Role of a registered Blend `SYNOPSIS` blend-user add|del Blend user [Role] `DESCRIPTION` Add/remove user to a Role of the specified Blend. If Role is not specified, it's assumed to be named like Blend `OPTIONS` `Blend` A registered Blend in /etc/blends, for example one of `med`, `junior`, `edu` or `science`. `user` user to add `Role` the role in the Blend that user will assume `AUTHOR` Andreas Tille tille@debian.org, Cosimo Alfarano kalfa@debian.org.

`blends.conf(5)`

`NAME` blends.conf - configuration for Debian Pure Blends registry `DESCRIPTION` This file is sourced from shell scripts inside the Debian Pure Blends package `blends-common` 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 /etc/blends/<>Blend>/<>Blend>.conf for each single Blend. `SYNTAX` The following variables can be set: ``DBBACKEND`` Set the backend for the user role management system. Currently the only implemented role management system is `unixgroups` but others might be implemented later. Unsetting this variable leads to use no roles at all. ``UPDATEUSERMENU`` If this is set to `yes`, 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. ``SHAREDIR`` 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. ``DRYRUN`` This variable can be set for debugging. Normally it should be left unset (NOT set to `false` or anything else!). If set to `true` a dry run of the tools is performed or `echo DRYRUN:` would print debugging information. ``DEBUG`` If set to `1` debugging mode is switched on. `SEE ALSO` blend-role (8), blend-update-menus (8), blend-user (8) `AUTHOR` Andreas Tille tille@debian.org, Cosimo Alfarano kalfa@debian.org.

Working with the source repository (svn in process of moving to git)

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 the directory layout of the svn-directory was described. How to derive the Debian packages from this layout? `Checkout` For the Blend tools and this documentation

git clone git+ssh://username@git.debian.org/git/blends/blends.git
or for the Debian Pure Blend BLEND-name
svn checkout svn+ssh://username@svn.debian.org/svn/blends/projects/BLEND-name/trunk
Note: This will be moved to Git (at least) soon after Wheezy release. `Build source package` Change into the created directory and type
make -f debian/rules get-orig-source
This creates a tar.gz source archive of the packages you want to build. For your personal comfort you can create a file Makefile in your package source directory containing
#!/usr/bin/make -f include /usr/share/blends-dev/Makefile
Which enables you to simply say
make dist
to create the source tarball. `Build Debian packages` Unpack the created source tarball and proceed like you build Debian packages normally.

The current Debian Med packages provide a working example how to use the tools described below.

How to create tasks and bugs pages of web sentinel

In the creation of so called tasks pages and bugs pages was described. These pages are automatically build by a cron job on Alioth 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:

Login to `alioth.debian.org` `cd /var/lib/gforge/chroot/home/groups/blends/webtools/` `./tasks.py <blend-name>`

To know what a valid `<blend-name>` might be have a look into `/var/lib/gforge/chroot/home/groups/blends/webtools/webconf`. Each Blend has an according config file there. Leave out the `.conf` extension and you have a valid `<blend-name>`.

In case you are planing some more experimental changes there is another host which was kindly sponsored by Frédéric Hébert for Debian Med called `blends.debian.net` which is running a copy of UDD and also hosts the latest development snapshot of the Blends web tools. Just ask Andreas Tille tille@debian.org in case you like a login on this host.

The code which builds web and tasks pages is available in Git at `git://git.debian.org/git/blends/website.git`. It is using the which enables influencing the layout of the pages by editing the templates in the templates directory. You can also influence some parameters of the web pages in the configuration files in the webconf directory. Last but not least you can provide translations for the web pages in the po directory.

Once something on the web pages was changed you can activate the changes as follows:

Login to `alioth.debian.org` or `blends.debian.net` `cd /var/lib/gforge/chroot/home/groups/blends/webtools/` `./deploy-dynamic-pages`

Please note that the `css` and `js` files which are influencing the layout of the automatically created pages are in the same area as the static web pages (see below ).

Editing static web pages of Blends on Alioth

A very simple entry page is created for each Blend which is linked from the . Most probably the maintainers of a Blend want to enhance this page a bit. It is actually intended that this simple template will be enhanced as it is done for instance for the which has a quite complex PHP driven web with a lot of other features than just linking to the tasks and bugs pages. 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 . Maintaining these static pages is not a "service" which is done for you. The maintainers of a Blend should care for this!

The static pages are maintained in Git at `git://git.debian.org/git/blends/website.git` in the websites directory. Once you have changed the content of the pages you can activate the changes by doing:

Login to `alioth.debian.org` or `blends.debian.net` `cd /var/lib/gforge/chroot/home/groups/blends/webtools/` `git pull`