debian-cd-clone/tasks/README.tasksel

This README explains how packages are added to full CDs and DVDs based
on tasks defined in tasksel.

Note that this document describes the default configuration for debian-cd.

Overview
========
One of the main factors deciding in what order packages are added,
especially for the first DVD and earlier CDs, is the definition of which
tasksel tasks should be used.

The list of packages to be added is generated dynamically at build time.
The procedure is somewhat complex and involves a number of (intermediate)
files.

The general sequence in which packages are added for "complete" images is:
1) Packages required by Debian Installer
2) Packages required to install the base system (debootstrap)
3) Any packages with priority "standard" or higher
4) Packages from tasksel tasks
   a) Packages defined as "key" packages for primary tasksel tasks
   b) Packages defined as "key" packages for language tasks (in the order:
      '<language>', '<language>-desktop', '<language>-<desktop>-desktop');
      only language desktop tasks that correspond to a primary task are
      included
   c) Regular packages from primary tasksel tasks
   d) Regular packages from language tasks
   e) Key packages from secondary tasksel tasks
   f) Key packages from language tasks corresponding to secondary tasksel
      tasks
   g) Regular packages from secondary tasksel tasks
   h) Regular packages from language tasks corresponding to secondary
      tasksel tasks
5) Other packages in the order of their popularity (popcon score)

A tasksel task is defined as "secondary" by adding a '-' after its name
in a task.list file; other tasksel tasks are "primary".

Language tasks are added grouped per type, not per language. So with three
languages (A, B, C) and 'desktop' and 'gnome-desktop' as tasks you'll get:
A
B
C
A-desktop
B-desktop
C-desktop
A-gnome-desktop
B-gnome-desktop
C-gnome-desktop

Note that <language>-desktop tasks are always sorted before any
<language>-<desktop>-desktop tasks.

Files involved
==============
Static task files (can be found in tasks/codename):
- Debian-generic or Debian-<desktop>:
  top level task file; defines order of other task files to be used,
  including task-essential-[generic|<desktop>] and
  task-full-[generic|<desktop>]
- tasksel_d-i.languages:
  list of languages used to add language tasks at build time (see detailed
  explanation below)
- task.list.generic or task.list.<desktop>:
  tasksel tasks to be included

Dynamically generated task files created at build time (can be found in
the subdirectory tasks under the working directory for the build):
- task.languages
  copy of the actual language list to be used to add language tasks
  (see "Language list used at build time" below)
- task.gen.[generic|<desktop>].primary:
  contains primary tasks from task.list.[generic|<desktop>] followed by
  corresponding language tasks
- task.gen.[generic|<desktop>].secondary:
  contains secondary tasks from task.list.[generic|<desktop>] and
  corresponding language tasks
- task-essential-[generic|<desktop>]:
  list of key packages based on task.gen.[generic|<desktop>].primary;
  corresponds to 3a/3b from overview above
- task-full-[generic|<desktop>]:
  list of packages based on both task.gen.[generic|<desktop>].primary and
  task.gen.[generic|<desktop>].secondary; corresponds to 3c-3h from overview
  above

The generation of these files is done early in a build by the script
tools/update_tasks.

The file <codename>/tasksel_d-i.languages
=========================================
This file contains the superset of all languages that have language tasks
in the <codename> version of tasksel. The list should contain the language
names as used in tasksel.
Any languages that are not supported in the <codename> version of Debian
Installer should be commented out. Reason is that it makes no sense to
include them on early CDs as they will never be used during installations
and thus the space can be better used for other packages.

The following procedure can be used to update the language list:
- delete the current list of languages (leaving leading comments) from
  <codename>/tasksel_d-i.languages
- get the current source for tasksel and do:
  $ cd tasks
  $ grep -l "Test-lang" * | sed "s/-desktop//" | sort -u
- add the resulting list to <codename>/tasksel_d-i.languages
- check what languages are supported in the version of localechooser for
  <codename> by checking the file 'languagelist' in its source
- comment out any languages not supported by localechooser (either not
  present or commented out in 'languagelist')
- check the diff between the old and new version and double check any
  changes

Language list used at build time
================================
The language list that is used to add languages tasks is a copy of
tasks/$DI_CODENAME/$TASKSEL_LANGLIST. By default TASKSEL_LANGLIST is set
to 'tasksel_d-i.languages' (see CONF.sh).

Note that the file is taken based on DI_CODENAME and not CODENAME! Reason
is that if those differ DI_CODENAME will almost always be the "newer"
release and it is better to have a list that reflects the languages
supported by the version of Debian Installer that is used, especially
since any languages not supported by the CODENAME version of tasksel will
be filtered out automatically by the tools/update_tasks script.

Using a custom language list
----------------------------
In some cases it may be desirable to only include a subset of the language
tasks available in tasksel. For example if you're building images for a
derived distribution targeted at a specific language or set of languages
and would prefer to not waste space on language-specific packages that
would never be used but instead include as many "regular" package as
possible.

In that case you should create a custom language list file. We'd suggest
to create it in one tasks/<codename> directory and add symlinks in other
tasks/<codename> directories.
Then change TASKSEL_LANGLIST in CONF.sh to use your custom list.

Another option is to set 'TASKSEL_LANGLIST=empty' and add the desired
language tasks (note: the full task names, not just the language names!)
to all relevant task.list* files.