YADA -- Yet Another Debianisation Aid
-------------------------------------

As if the Debian world really needed another packaging helper.  Well, I
got tired of writing and maintaining rules files, so I wrote YADA instead.
Here it is; I hope you find it helpful.

 -- Charles Briscoe-Smith <cpbs@debian.org>  Sat,  6 Mar 1999

(Last updated 18 May 1999)

How YADA works
--------------

The basic idea is very simple: everything that used to be scattered
amongst many little files in your debian/ directory is now concentrated
into a single file, debian/packages.  There are only a couple of
exceptions: debian/changelog is unchanged, and debian/yada is the YADA
script, which you must copy into your debian/ directory.  You can do this
with the command "yada yada".  debian/rules and debian/control are now
generated from debian/packages by YADA.  Most of the other files there
will then likely be redundant.

So the only thing you now need to know to switch to YADA is how to
write debian/packages!  Read on.

When you've written debian/packages, you'll need to copy yada into
your debian/ directory, and run "debian/yada generate rules" in order
to generate your new debian/rules.  After that, your rules file should
automatically regenerate both itself and debian/control as necessary.
Failing that, run "debian/yada generate rules" or "debian/yada generate
control" as required.

The format of debian/packages
-----------------------------

debian/packages is based on the format of debian/control, but with
several differences.  I'll explain the format from scratch.

debian/packages is formed from a series of paragraphs, separated by
blank lines.  Empty paragraphs are ignored, so you can add extra blank
lines before and after paragraphs without problems.  ALL lines are
stripped of trailing whitespace, in order to ensure that what you see
is what YADA sees.  (I'm paranoid about trailing whitespace.)

Lines beginning with a hash mark ("#") at the left margin are ignored
completely.  If the hash mark has white space in front of it, the
line is treated as part of an extended field if appropriate; if not,
it is ignored.

Each paragraph is made up of fields, each of which associates a keyword
with a textual value.  A field's value can be single-line or multi-line.
The first (or only) line of a field starts at the left margin with a
case-insensitive keyword containing alphanumerics and hyphens, followed
by a colon, followed by the first (or only) line of the field's value.
Subsequent lines of the field start with a space character at the left
margin, and are followed by one line of the field's value.

Here are a couple of example paragraphs in this format:

Word: gnu
Part-Of-Speech: noun
# Note to myself: must fix this pronunciation
Pronunciation: guh-NOO
Definition: a large animal in the
 antelope family, which has a hairy
 coat.

Word: gnat
Part-of-speech: noun
Definition: a small insect which bites
 anything that moves.

The observant will have noticed that this leaves no way to include a blank
line in a field's value; since trailing whitespace is stripped, a line
containing only a space would be treated as the end of the paragraph.
There is an escape sequence for this: a line containing a single dot
(a.k.a. full stop or period) after the initial space will be treated
as blank.

In fact, any line containing only dots after that initial space will
have one of them stripped off before being processed.  Lines starting
with a space and a dot, but which contain a character other than a dot
anywhere in the line are left unmolested.

So, we can include blank lines like this:

Dish:           Boiled lobster
Ingredients:
 1 lobster
 1 anvil
 1 saucepan
Method:
 First, catch your lobster.
 .
 When you have it cornered, stun it
 by hitting it over the head with the
 anvil, then quickly put it into the
 saucepan and boil it.
 .
 You should take great care not to let
 the lobster take posession of the
 anvil; a lobster with an anvil can
 make your life hell.

That example also demonstrates another minor feature: blank space is
stripped from the beginning of the first line of a multi-line value.
If that first line is entirely white space, the whole line is ignored,
and the value starts on the line AFTER the line containing the keyword.

How to write debian/packages
----------------------------

There are two kinds of paragraph in debian/packages.  The first paragraph
in the file describes the source package, describing how to build it,
how to clean it, what it's called, where it came from, who maintains
it, etc.  The following paragraphs each describe a binary package which
can be built from the source package.

Executable fields
-----------------

Several fields contain commands to be executed at appropriate points
during the processing of the package.  The first line of one of these
executable fields specifies which command processor is to be used to
execute the field; subsequent lines are the commands to be executed.

At present, the only command processor recognised by YADA is "sh", the
bourne shell.  The rest of the field is interpreted as a shell script
fragment.  The fragment will be executed with the shell's -e option set,
so that if any command fails, the whole script will fail.

Source: libxyz
[...]
Build: sh
 ./configure --prefix=/usr
 make
Clean: sh
 make distclean

In some cases, extra variables or commands may be available for use by
an executable field.  These are described below.

Fields in the source paragraph
------------------------------

The following fields have the same meaning as they do in debian/control,
and should all be present in debian/packages:

Source
  The name of the source package.

Section
  The section (main, contrib, non-free or non-us) and subsection (admin,
  devel, games, x11, etc.) of the source package in the archive, separated
  by a forward slash.  If the section is main, give only the subsection.

Priority
  How necessary the programs or data contained in source package are
  to the running of the system (required, important, standard, optional
  or extra).

Maintainer
  The full name and email address of the person currently responsible
  for this source package.  The email address should be separated from
  the name by a single space, and surrounded by angle-brackets.

Standards-version
  Which version of Debian policy the maintainer believes this package
  conforms to.

The following fields are defined by YADA, and you should use them in
debian/packages.  YADA uses the first four of these to construct the
/usr/share/doc/<package>/copyright file, so it is important they are correct.

Upstream-Source
  The URI of the upstream source code, in the standard URI format
  surrounded by angle-brackets.  (Note that a URL can be turned into
  a URI by prefixing it with "URL:".)  If this field is not present,
  YADA will assume that the package is a Debian-native package.

Copyright
  The first line of this field gives the names of the standard copyright
  licence which applies to this package, if any.  The following lines
  should contain a copy of the source package's copyright notice and
  copyright licence.  If any of the standard licences are mentioned, you
  need not write where their full text can be found on a Debian system;
  yada will add that information for you.  The standard licence names
  defined at present are "GPL", "LGPL", "Artistic" and "BSD".  If none
  apply, place a single dot on the first line, and include the complete
  copyright and licence notice.

Major-Changes
  This field must be present if the package contains an Upstream-Source
  field.  If any major changes have been made to the upstream source,
  list them here.  This fulfils the Debian policy requirement that
  changes be listed, and fulfils the legal requirements of several common
  copyright licences.  If there are no significant changes with respect
  to the upstream version, leave this field blank; the field must be
  present, however.

Packaged-For
  The name of the project or organisation for which you produced the
  package.  For packages produced by registered Debian developers, this
  field should read "Debian".  For others, it might read, for example,
  "GNU", or "Hungry Programmers", or "Corel Corp.".  If you didn't
  create the package as part of your work for anyone other than yourself,
  then don't include a "Packaged-For" field.

Description
  The first line of this field gives the human-readable name of
  the package.  For example, if the Source field reads "libc6", the
  first line of the Description field might read "The GNU C library,
  version 2".  The rest of the field should contain any descriptive text
  which pertains to ALL the binary packages this source package produces.
  It will be prepended to the Description field of each binary package,
  followed by a blank line.

Build
  An executable field describing how to build the software contained in
  the package.  One extra command is available in this field:

  yada fixup libtool [<pathname>]
      Performs the fixups described in Lintian's "libtool-workarounds.txt"
      to prevent libtool hardcoding shared library directories into
      binaries.  This should be called AFTER the configure script has
      generated libtool, but before libtool gets used.  If the libtool
      script is not named "libtool" in the current directory, specify
      its <pathname>.

Clean
  An executable field describing how to reverse the effects of the
  Build field.  There are no extra commands or variables available.

These fields are also defined by YADA, but you may not need to use them:

Home-Page
  The URI of the World-Wide Web home page of the upstream package,
  in angle-brackets.  You should include this if possible.

Packager
  The name and email address of the person who originally created
  Debianised this package, if not the current maintainer.

Other-Maintainers
  The names and email addresses of any previous maintainers of this
  package, excluding the original packager and the current maintainer.

Patches
  A wildcard matching those files in the debian/ directory which should
  be treated as patches, and automatically patched into the source.
  Automatic patching is not activated unless you specify this field.
  This feature was inspired by the "*.dpatch" system in the egcs packages.

  Most often, this field would be used like this:

    Patches: *.dpatch

  Basically, it works as follows.  Instead of applying patches to the
  source tree directly, and letting dpkg-source handle them, you place
  the patches in files in your debian/ directory.  The names of these
  files should be matched by the contents of the "Patches:" field; this
  is how yada recognises patch files.  So, for example, if you are sent
  an optimiser patch for your compiler, you can simply copy the email
  to "debian/optimiser.dpatch".

  When your source package is built, each patch is applied to the
  source tree.  When your package is cleaned, the patches are unapplied.
  Yada takes some care to keep track of the status (applied or not) of
  every patch using files named like "debian/patch-*-applied", and it
  applies and unapplies the patches as necessary.  (For safety's sake,
  you should make sure your pattern cannot match files of the form
  "patch-*-applied".)

  If you decide you don't want a particular patch to be applied, but you
  still want to keep it in your source package, rename it to add the
  extension ".disabled" to its name.  For example, if you found a bug
  in the optimiser patch, you could rename "debian/optimiser.dpatch"
  to "debian/optimiser.dpatch.disabled".  Yada will then take care of
  unapplying the patch, if necessary, and then will not reapply it until
  you rename the patch back to its original name.

  Often, patches are intended to patch files in subdirectories.
  This means that `patch' needs to be given the -p<n> option to tell it
  how many pathname components to strip from filenames.  You can give
  options to `patch' by putting a PATCHOPTIONS line in the patch file.
  The line must contain the text "#PATCHOPTIONS:" at the start of a line.
  The rest of the line gives options which will be passed to `patch'
  when applying or unapplying that patch file.

    Note: to avoid endlessly recompiling your package, yada creates a file
    "debian/patch-stamp" when it finishes applying your patches.  If you
    change any of your patch files, use "debian/rules unpatch" first.
    If you enable or disable any patches, remove "debian/patch-stamp"
    so that your rules file will make the appropriate changes.

Build-Conflicts
  Binary packages which interfere with the building of this package if
  they are installed on the system where this package is being built.
  This field takes the same format as the "Conflicts" field in binary
  packages.  You should not use this field unless absolutely necessary,
  because it hinders auto-building.  At present, YADA does not take into
  account virtual packages when checking Build-Conflicts.

Build-Depends
  Binary packages which must be installed on the system in order to
  build this package.  This field takes the same format as the "Depends"
  field in binary packages.  At present, YADA does not take into account
  virtual packages when checking Build-Depends.

Build-Sequence
  If present, this field may have the value "conserve-space" or
  "avoid-root".  If not present, "conserve-space" is the default.
  This field affects the generated debian/rules.  In "conserve-space"
  mode, YADA will arrange for each binary package's filesystem image to be
  created separately during the "debian/rules binary" stage.  This allows
  each package's image to be removed after its binary package has been
  created, which saves space.  In "avoid-root" mode, filesystem images
  for each binary package are created during the "debian/rules build"
  stage, and all exist simultaneously on the system.  This takes more
  space, but ensures that the "Install" field of each binary package is
  not run with root privileges, which is somewhat safer.

Fields in binary paragraphs
---------------------------

The following fields can be used in the paragraphs describing binary
packages.  First, the fields which have the same meaning as in
debian/control:

Package
  The name of the binary package.

Architecture
  The architecture(s) for which this binary package may be built.  "all"
  means that it is architecture-independent; "any" means that it is
  not architecture-independent, but may be built for any architecture.
  "none" is a YADA extension and means that this binary package will
  never be built (useful for "commenting out" binary packages).

Section
Priority
  Analogous to the Section and Priority fields in the source paragraph,
  these classify the binary package.

Essential
  If "yes", dpkg will prevent the end-user from removing the binary
  package from the system unless --force-remove-essential is specified.
  Do not use this unless you have discussed it on debian-devel and the
  concensus opinion is that you may.

Pre-Depends
Depends
Recommends
Suggests
  These fields specify relationships between this package as other
  packages which may be installed on the target system.  They each
  comprise a comma-separated list of dependencies, which are treated
  as set out in the Debian packaging manual.  A dependency is either a
  single package, a list of alternative packages separated by vertical
  bars, or (a yada extension) one or more filenames or file-globs in
  square brackets.  Filenames in square brackets should be absolute
  filenames on the installed system, and are fed to dpkg-shlibdeps to be
  analysed for shared library dependencies.  The output of dpkg-shlibdeps
  is substituted for the square brackets and the file-globs before the
  field is placed into the binary package.

  For example, most packages containing ELF binaries will use the line:

    Depends: [/usr/bin/*]

Provides
Conflicts
Replaces
  These fields affect the interaction between packages installed on the
  same system.  They are fully documented in the Debian packaging manual.

Description
  This field is fully documented in the Debian packaging manual.
  If the source package paragraph contains a multi-line "Description"
  field, its value (apart from the first line) will be prepended to the
  Description field of each binary package, separated by a blank line.

The following fields are defined by YADA.  Often, only the "Install"
field need be used.

Install
  An executable field, used to build the filesystem image for the
  binary package.  Several extra variables and commands are available:

  ROOT
      The root of the temporary filesystem image to install into.
      You won't need to use this in most cases.

  CONTROL
      The directory into which control files are to be installed.
      You probably won't need to use this unless you install control
      files that yada doesn't already know about.

  PACKAGE
      The name of the binary package being built.  You probably won't
      need to use this either.

  yada install [-dir|-data|-doc|-bin|-script|-game|-lib|-man|-conffile]
               [-x|-non-x] [-stripped|-unstripped] [-exec|-no-exec]
               [-into <dir>] [-as <name>] [-subdir <subdir>]
               [-section <mansect>] <file>...
      Install the <file>s named into the binary package filesystem image.
      There are many options to affect how the installation is done.

        -dir                Create directories in the filesystem image
                            corresponding to each <file>, which should
                            be specified as absolute pathnames on the
                            installed destination system.

        -data               Install data files.  (This is the default.)

        -doc                Install documentation files (into
                            /usr/share/doc/$PACKAGE).

        -bin                Install user binaries (into /usr/bin).

        -game               Install game binaries (into /usr/games).

        -lib                Install shared libraries (into /usr/lib).

        -man                Install man pages (into /usr/man/man?).

        -conffile           Install configuration files (into /etc).

        -x                  Install X-related files (they will be
                            installed into the /usr/X11R6 hierarchy
                            instead of into /usr).

        -non-x              Install ordinary, non-X-related files
                            (the default).

        -stripped           Strip the files after installing them (the
                            default for binaries and shared libraries).

        -unstripped         Do not strip (the default for everything
                            else).

        -exec               Make the installed files executable (the
                            default for binaries).

        -no-exec            Make the installed files non-executable
                            (the default for everything else).

        -into <dir>         Override the normal destination directory
                            with <dir> (specified as an absolute pathname
                            on the destination system).

        -as <name>          Rename the <file> to <name> when installing
                            it (only available when installing a single
                            <file>).

        -subdir <subdir>    Put the file into a subdirectory of the
                            location it would normally be installed into.

        -section <mansect>  Install man pages into section <mansect>,
                            overriding yada's normal smarts for working
                            out the appropriate section.

  yada undocumented [-x|-non-x] [-section <mansect>] <name>...
      Mark the <name>s as undocumented, by creating manpage symlinks to
      "undocumented.7".  You can either give names with the man page
      section appended (e.g. foo.1 or blurzle.3x) or give the section
      explicitly, in which case the names will not have suffixes which
      look like sections stripped.  "-x" and "-non-x" work as for
      "yada install".

  yada dpkg-shlibdeps [-d<dependencyfield>] [-L<localshlibsfile>]
                      <executable>|-e<executable>...
      This command is obsolete.  This command was a misfeature and is
      replaced by the extended "[...]" syntax of the dependency fields,
      described above.

Finalise (or Finalize)
  After the "Install" field is executed, all user and group ownerships
  in the filesystem image are set to "root", and all permissions are
  set to "rwxr-xr-x" for directories and for plain files which have an
  execute bit already set, and "rw-r--r--" for all other plain files.
  The Finalise executable field is used to set up any permissions
  or ownerships needed in the filesystem image which differ from the
  defaults.

  The ROOT, CONTROL and PACKAGE variables are available as in the
  "Install" field.

Preinst
Postinst
Prerm
Postrm
  These executable fields are transformed into the maintainer scripts for
  the binary package.  Several common tasks done by maintainer scripts
  are prepended automatically if certain other fields are specified.
  There are no extra commands or variables available in these fields.

Changelog
  Names the file in the source package which is the main upstream
  changelog file.  This will be compressed and installed as changelog.gz
  in the binary package's /usr/share/doc/<package>/ directory.  THIS IS NOT
  YET IMPLEMENTED.

Doc-Depends
  Normally, YADA creates a directory named /usr/share/doc/<package>/
  automatically and places the copyright file and changelogs in it.
  If the package depends on another binary package, created by the same
  source package, whose /usr/share/doc/<package>/ directory is appropriate,
  give that package's name as the value of this field, and an appropriate
  symlink will be created.

Alternatives
  If your package includes files to be registered using
  update-alternatives, specify them using this field.  Please read the
  man page for update-alternatives(8) to understand the terminology in
  the following.  Each alternative to be installed is specified by a
  single line.

  Master links are specified by a line containing the full generic
  pathname, followed by the name of the symlink in the alternatives
  directory, followed by the full pathname of the alternative, followed
  by the priority of the alternative.  The three names are separated by
  right-arrows (each made of a hyphen followed by a greater-than symbol:
  "->"), and the priority is surrounded by round brackets (parentheses).

  Slave links are specified by a line starting with two greater-than
  symbols (">>"), followed by the full generic pathname, followed by the
  name of the slave symlink in the alternatives directory, followed by
  the full pathname of the alternative.  The three names are separated by
  right-arrows (each made of a hyphen followed by a greater-than symbol:
  "->").  Each line describing a slave link is grouped together with
  the master link most recently described.

  An example:

    Alternatives:
     /usr/bin/editor -> editor -> /usr/bin/nvi (30)
     >> /usr/man/man1/editor.1.gz -> editor.1.gz -> /usr/man/man1/nvi.1.gz

Menu
  If this field is specified, its value is placed into a file in the
  /usr/lib/menu/ directory, and update-menus is called at the appropriate
  moments during package installation and removal.  See menufile(5)
  for documentation on how to write this field.

Shlibs
  If this field is specified, its value is used as the contents of the
  package's "shlibs" control area file.

Contains-Libs
  If this field is present, YADA assumes the package contains shared
  libraries, and calls ldconfig at the appropriate point during package
  installation.