#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass article
\language american
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize 12
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 2cm
\topmargin 2cm
\rightmargin 2cm
\bottommargin 2cm
\secnumdepth 2
\tocdepth 2
\paragraph_separation skip
\defskip medskip
\quotes_language swedish
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle plain

\layout Title

YADA -- Yet Another Debianisation Aid
\layout Date

23 Nov 2003 
\layout Author

Copyright 1999 Charles Briscoe-Smith.
\layout Author

Copyright 1999-2003 Piotr Roszatycki.
\layout Abstract

YADA is a Debian packaging helper.
 It parses a special file, debian/packages, in a source package, and generates
 an appropriate debian/rules to control building of the package.
\layout Section

How YADA works
\layout Standard

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 /usr/bin or into
 your debian/ directory.
 You can do this with the command "yada yada".
 debian/rules, debian/control and optional debian/templates are now generated
 from debian/packages by YADA.
 Most of the other files there will then likely be redundant.
\layout Standard

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

When you've written debian/packages, you'll need to run "yada generate"
 in order to generate your new debian/control and debian/rules.
 After that, your rules file should automatically regenerate both itself
 and debian/control as necessary.
\layout Section

yada command
\layout Standard

yada is a just perl script so it can be installed globally in the system
 in /usr/bin directory or can be placed in local debian/ directory.
 It is also possible to use newer yada script in debian/ directory than
 installed in /usr/bin directory.
 
\layout Standard

Commands available:
\layout Itemize

yada yada
\begin_deeper 
\layout Standard

This command creates an skeleton debian/packages file for you to fill in,
 if you don't already have one and creates debian/changelog for initial
 release.
\end_deeper 
\layout Itemize

yada rebuild rules
\begin_deeper 
\layout Standard

yada reads debian/packages and generates a new rules file, debian/rules.
 Note that any existing rules file will be overwritten, and no backup will
 be kept.
 
\end_deeper 
\layout Itemize

yada rebuild control
\begin_deeper 
\layout Standard

yada reads debian/packages and generates a new control file, debian/control.
 Note that any existing control file will be overwritten, and no backup
 will be kept.
\end_deeper 
\layout Itemize

yada rebuild templates
\begin_deeper 
\layout Standard

yada reads debian/packages and generates a new optional templates file,
 debian/templates.
 Note that any existing templates file will be overwritten, and no backup
 will be kept.
 This file is created only if debian/packages contains any Templates: field.
 The file might be used with debconf-updatepo(1) command of po-debconf(7)
 system to regenerate DebConf translations located in debian/po/ directory.
\end_deeper 
\layout Itemize

yada rebuild
\begin_deeper 
\layout Standard

Regenerates all above required files if they don't exists already.
\end_deeper 
\layout Section

The format of debian/packages
\layout Standard

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

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.)
\layout Standard

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.
\layout Standard

Lines beginning with a percent mark ("%") at the left margin means macro
 commands similar to macros used by C preprocessor.
 The defined macro variables can be further used in common paragraphs or
 as parameters for other macro commands.
\layout Standard

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-insen
sitive 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.
\layout Standard

Here are a couple of example paragraphs in this format:
\layout LyX-Code

Word: gnu
\newline 
Part-Of-Speech: noun
\newline 
# Note to myself: must fix this pronunciation
\newline 
Pronunciation: guh-NOO
\newline 
Definition: a large animal in the
\newline 
 antelope family, which has a hairy
\newline 
 coat.
\newline 
 
\newline 
Word: gnat
\newline 
Part-of-speech: noun
\newline 
Definition: a small insect which bites
\newline 
 anything that moves.
\layout Standard

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.
\layout Standard

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.
\layout Standard

So, we can include blank lines like this:
\layout LyX-Code

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

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.
\layout Section

How to write debian/packages
\layout Standard

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.
\layout Subsection

Merged fields
\layout Standard

YADA merges several fields with the same keyword into one field.
 So, if we have several "Postinst: ..." sections, they will be concatenate
 (or a error will be generated if different shells are requested).
 There are also added two general keyword: "After-" and "Before-" that can
 be prepend to the classical keywords.
 With this, these section are concatenate after or before the regular section.
\layout Standard

In example, the section:
\layout LyX-Code

Build: sh
\newline 
 echo test build
\newline 
After-Build: sh
\newline 
 echo test after-build
\newline 
Before-Build: sh
\newline 
 echo test before-build
\layout Standard

will be concatenated into one field:
\layout LyX-Code

Build: sh
\newline 
 echo test before-build
\newline 
 echo test build
\newline 
 echo test after-build
\layout Subsection

Executable fields
\layout Standard

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.
\layout Standard

At present, the only command processor recognised by YADA is "sh" and "bash",
 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.
\layout LyX-Code

Source: libxyz
\newline 
[...]
\newline 
Build: bash
\newline 
 ./configure --prefix=/usr
\newline 
 CC=gcc
\newline 
 CFLAGS="-Wall -g"
\newline 
 LDFLAGS=
\newline 
 if [ "${DEB_BUILD_OPTIONS#*noopt}" != "$DEB_BUILD_OPTIONS" ]; then
\newline 
     CFLAGS="$CFLAGS -O0"
\newline 
 else
\newline 
     CFLAGS="$CFLAGS -O2"
\newline 
 fi
\newline 
 make CFLAGS="$CFLAGS" LDFLAGS="$LDFLAGS" CC="$CC"
\newline 
Clean: sh
\newline 
 make distclean || true
\layout Standard

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

Environment variables
\layout Standard

Several extra environment variables are available to use with Build, Install,
 Finalize, Preinst, Postinst, Prerm, Postrm, Config and Init fields.
\layout Description

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

TMPROOT The temporary directory shared with all binary packages.
 It can be used for `make install DESTDIR=$TMPROOT'.
\layout Description

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.
\layout Description

PACKAGE The name of the binary package being built.
 This variable is set only for binary packages.
\layout Description

SOURCE The name of the source package being built.
\layout Description

VERSION The version of the Debian source package.
\layout Description

DEB_* The variables will be set by "dpkg-architecture" command.
 You will need these variables if you use different settings for various
 architectures (i.e.
 special optimalization for i386 or alpha).
\layout Subsection

Fields in the source paragraph
\layout Standard

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

Source The name of the source package.
\layout Description

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.
\layout Description

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

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.
\layout Description

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

Origin 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 "Origin" field.
\layout Description

Bugs The URI for Bugs Tracking System, i.e.
 "debbugs://bugs.debian.org" for packages from Debian distribution.
\layout Description

Build-Depends
\layout Description

Build-Depends-Indep These fields specify relationships between this package
 and other packages at build time.
 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.
 The YADA automatically adds build depends on 
\begin_inset Quotes sld
\end_inset 

file, patch, perl
\begin_inset Quotes srd
\end_inset 

 if called debian/yada or 
\begin_inset Quotes sld
\end_inset 

yada
\begin_inset Quotes srd
\end_inset 

 if called /usr/bin/yada.
\layout Standard

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

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-nat
ive package.
\layout Description

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.
\layout Description

Major-Changes 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.
\layout Description

Packaged-For This field overwrites dpkg's "Origin" field in copyright file,
 but it doesn't appear in generated control file.
\layout Description

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 Descripti
on 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.
\layout Description

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

yada fixup libtool [<pathname>]
\begin_deeper 
\layout Standard

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>.
\end_deeper 
\layout Standard

This field is called with 
\begin_inset Quotes sld
\end_inset 

build
\begin_inset Quotes srd
\end_inset 

 target.
\end_deeper 
\layout Description

Build-Arch An executable field describing how to build architecture depended
 code in the package.
 This field is called with 
\begin_inset Quotes sld
\end_inset 

build-arch" and "build" targets.
\layout Description

Build-Indep An executable field describing how to build architecture independed
 code in the package.
 This field is called with "build-indep" and "build" targets.
\layout Description

Clean An executable field describing how to reverse the effects of the Build
 field.
 There are no extra commands or variables available.
 This field is called with "clean" target.
\layout Standard

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

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

Upstream-Authors The names and email addressed of upstream authors.
\layout Description

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

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

Patches A wildcard matching those files in the debian/ directory which should
 be treated as patches, and automatically patched into the source.
 It means that "yada patch ..." command is called before Build script and "yada
 unpatch" command is called after Clean script.
 Automatic patching is not activated unless you specify this field.
 This feature was inspired by the "*.dpatch" system in the egcs packages.
\begin_deeper 
\layout Standard

Most often, this field would be used like this:
\layout LyX-Code

Patches: *.diff
\layout Standard

The matchings can be separated with whitespace:
\layout LyX-Code

Patches: patches/*-all.diff patches/*-i386.diff
\layout Standard

The second example is equivalent of:
\layout LyX-Code

Build: sh
\newline 
 yada patch "debian/patches/*-all.diff"
\newline 
 yada patch "debian/patches/*-i386.diff"
\layout Standard

Basically, it works as follows.
 Instead of applying patches to the source tree directly, and letting dpkg-sourc
e 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.diff".
\layout Standard

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".)
\layout Standard

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.
\end_deeper 
\layout Subsection

Fields in binary paragraphs
\layout Standard

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

Package The name of the binary package.
\layout Description

Version If this field in binary package's paragraph exists, the package
 can contain different version number than source package version.
\layout Description

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).
 Macros "linux", "hurd", "darwin", "freebsd", 
\begin_inset Quotes sld
\end_inset 

netbsd
\begin_inset Quotes srd
\end_inset 

 and "openbsd" are expanded to native dpkg's architecture names.
\begin_deeper 
\layout LyX-Code

Package: package-linuxonly
\newline 
Architecture: linux
\newline 
 
\newline 
Package: package-doc
\newline 
Architecture: all
\newline 
 
\newline 
Package: package-intelonly
\newline 
Architecture: i386
\end_deeper 
\layout Description

Section
\layout Description

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

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.
\layout Description

Pre-Depends
\layout Description

Depends
\layout Description

Recommends
\layout Description

Suggests
\layout Description

Enchances 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.
\begin_deeper 
\layout Standard

For example, most packages containing ELF binaries will use the line:
\layout LyX-Code

Package: mypackage
\newline 
Depends: [/usr/bin/*]
\layout Standard

In this case, yada will generate ${shlibs:mypackage:Depends} variable.
 All ${*:mypackage:Depends} variables will be joined to one ${mypackage:Depends}
 variable.
\layout Standard

If the "Depends" field is ommited, and the package have ELF binaries, this
 field will be generated automatically.
\layout Standard

The substvars variables will be generated automatically for some of the
 special fields, i.e.
 ${doc-base:$PACKAGE:Suggests} for "Doc-Base" field or ${menu:$PACKAGE:Suggests}
 for "Menu" field.
\layout Standard

The square brackets without filenames will be replaced by ${$PACKAGE:Field}.
\layout Standard

If package name contains dot (.) or colon (:), you have to replace it with
 hyphen (-) in shlibs variables.
\layout Standard

More advanced example:
\layout LyX-Code

Package: mypackage
\newline 
Depends: ${shlibs:mypackage:Depends}, perl5 | perl
\newline 
Suggests: ${mypackage:Suggests}, www-browser
\newline 
Recommends: mypackage-plugins, []
\newline 
 
\newline 
Package: mypackage-bin
\newline 
Install: sh
\newline 
 yada shlibdeps
\newline 
 
\newline 
Package: mypackage-libc++
\newline 
Depends: ${shlibs:mypackage-libc--:Depends}, [/usr/lib/mypackage/*]
\end_deeper 
\layout Description

Provides
\layout Description

Conflicts
\layout Description

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

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.
\layout Description

Install An executable field, used to build the filesystem image for the
 binary package.
 This field is called with 
\begin_inset Quotes sld
\end_inset 

binary
\begin_inset Quotes srd
\end_inset 

 target and 
\begin_inset Quotes sld
\end_inset 

binary-indep
\begin_inset Quotes srd
\end_inset 

 target for 
\begin_inset Quotes sld
\end_inset 

all
\begin_inset Quotes srd
\end_inset 

 architecture or 
\begin_inset Quotes sld
\end_inset 

binary-arch
\begin_inset Quotes srd
\end_inset 

 for other architecture.
\begin_deeper 
\layout Standard

Several extra commands are available: 
\layout Itemize

yada install [-bin|-conf|-data|-dir|-doc|-game|-include|-lib|-libexec|-man|-sbin
|-script|-src|-sscript] [-x|-non-x] [-stripped|-unstripped] [-exec|-no-exec]
 [-into <dir>] [-as <name>] [-subdir <subdir>] [-section <mansect>] [-gzip|-bzip
2] [-ucf] <file>...
\begin_deeper 
\layout Standard

Install the <file>s named into the binary package filesystem image.
 There are many options to affect how the installation is done.
\layout Description

-bin Install user binaries (into /usr/bin).
\layout Description

-conf Install configuration files (into /etc).
\layout Description

-data Install data files.
 (This is the default.)
\layout Description

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

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

-game Install game binaries (into /usr/games).
\layout Description

-include Install include headers (into /usr/include).
\layout Description

-lib Install shared libraries (into /usr/lib).
\layout Description

-libexec Install additional executables (into /usr/lib).
\layout Description

-man Install man pages (into /usr/man/man?).
\layout Description

-sbin Install system binaries (into /usr/sbin).
\layout Description

-script Install user scripts (into /usr/bin).
\layout Description

-src Install source files (into /usr/src).
\layout Description

-sscript Install system scripts (into /usr/sbin).
\layout Description

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

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

-stripped Strip the files after installing them (the default for binaries
 and shared libraries if environment variable DEB_BUILD_OPTIONS matches
 "nostrip" string).
\layout Description

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

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

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

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

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

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

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

-gzip Compress file with gzip -9 after install.
\layout Description

-bzip2 Compress file with bzip2 after install.
\layout Description

-ucf Use Update Configuration File (ucf) handling for configuration files.
 The original file will be installed into /usr/share/ucf/<path> and additional
 ucf calls with --three-way option will be used in postinst and postrm scripts.
 This offers a chance to see a merge of the changes between old maintainer
 version and the new maintainer version into the local copy of the configuration
 file.
\end_deeper 
\layout Itemize

yada copy [-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script
|-src|-sscript] [-x|-non-x] [-into <dir>] [-as <name>] [-subdir <subdir>]
 [-section <mansect>] <file|dir>...
\begin_deeper 
\layout Standard

Copy <file>s with preserving file attributes into the binary package filesystem
 image.
 See `yada install' for additional arguments.
\end_deeper 
\layout Itemize

yada move [-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script
|-src|-sscript] [-x|-non-x] [-into <dir>] [-as <name>] [-subdir <subdir>]
 [-section <mansect>] <file|dir>
\begin_deeper 
\layout Standard

Move a <file> or <dir> in the binary package filesystem image.
 See `yada install' for additional arguments.
\end_deeper 
\layout Itemize

yada symlink [-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-scr
ipt|-src|-sscript] [-x|-non-x] [-into <dir>] [-as <name>] [-subdir <subdir>]
 [-section <mansect>] <file|dir>
\begin_deeper 
\layout Standard

Make a symlink of <file> or <dir> as <name> in the binary package filesystem
 image.
 See `yada install' for additional arguments.
\end_deeper 
\layout Itemize

yada undocumented [-x|-non-x] [-section <mansect>] <name>...
\begin_deeper 
\layout Standard

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".
\end_deeper 
\layout Itemize

yada shlibdeps [args]
\begin_deeper 
\layout Standard

This command finds the files execlutables and libraries which are dynamicaly
 linked.
 The command is called automatically, but you call use it explicity if you
 need to set LD_LIBRARY_PATH environment variable.
 All arguments will be passed to dpkg-shlibdeps.
\end_deeper 
\layout Itemize

yada makeshlibs [-V[<deps>]|--version[=<deps>]] [-X<item>|--exclude=<item>]
\begin_deeper 
\layout Standard

This command automatically scans for shared libraries, and generates a shlibs
 file for the libraries it finds.
\layout Description

-V[<deps>] By default, the shlibs file generated by this command program
 does not make packages depend on any particular version of the package
 containing the shared library.
 It may be necessary for you to add some version dependancy information
 to the shlibs file.
 If -V is specified with no dependancy information, the current version
 of the package is plugged into a dependancy that looks like "package-name
 (>= packageversion)".
 If -V is specified with parameters, the parameters can be used to specify
 the exact dependancy information needed (be sure to include the package
 name).
\layout Description

-X<item> Exclude files that contain "item" anywhere in their filename from
 being treated as shared libraries.
\end_deeper 
\layout Itemize

yada strip [-X<item>|--exclude=<item>]
\begin_deeper 
\layout Standard

This command strips executables, shared libraries, and some static libraries.
 It assumes that files that have names like lib*_g.a are static libraries
 used in debugging, and will not strip them.
 The command is called automatically if environment variable DEB_BUILD_OPTIONS
 does not match "nostrip" string and the package doesn't have "Contains:
 unstripped" field.
\layout Description

-Xitem Exclude files that contain "item" anywhere in their filename from
 being stripped.
 You may use this option multiple times to build up a list of things to
 exclude.
\end_deeper 
\layout Itemize

yada patch <patchfiles>
\begin_deeper 
\layout Standard

This command applies patches that match command argument.
 See description of Patch field for more informations.
 The standalone using of yada patch command could be useful for conditional
 applying the patches.
 I.e.:
\layout LyX-Code

Build: sh
\newline 
 yada patch "debian/patches/any/*"
\newline 
 if [ "$DEB_BUILD_ARCH" = "i386" ]; then
\newline 
     yada patch "debian/patches/i386/*"
\newline 
 fi
\layout Standard

The command is automatically called at the start of Build script if the
 Patch field is used.
\end_deeper 
\layout Itemize

yada unpatch
\begin_deeper 
\layout Standard

This command removes all patches previously applied by yada patch command.
 The command is automatically called at the end of Clean script if the Patch
 field is used.
 If not, the command have to be called explicity:
\layout LyX-Code

Clean: sh
\newline 
[...]
\newline 
 yada unpatch
\end_deeper 
\end_deeper 
\layout Description

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.
\begin_deeper 
\layout Standard

The ROOT, CONTROL, PACKAGE, VERSION and DEB_* variables are available as
 in the "Install" field.
\end_deeper 
\layout Description

Preinst
\layout Description

Postinst
\layout Description

Prerm
\layout Description

Postrm
\layout Description

Config 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.
 The PACKAGE and VERSION variables are set for these fields.
\layout Description

Templates If this field is specified, its value is placed into a control
 file "templates" used by debconf system.
 The YADA supports po-debconf(7) system, so translatable fields can be prepended
 with an underscore.
 If the file debian/po/templates.pot exists, the po2debconf(1) command for
 merging translations are called at build time.
\begin_deeper 
\layout Standard

You can update debian/po/ directory with debconf-updatepo(1) command.
\end_deeper 
\layout Description

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.
\layout Description

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

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).
\layout Standard

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.
\layout Standard

An example:
\layout LyX-Code

Alternatives: 
\newline 
 /usr/bin/editor -> editor -> /usr/bin/nvi (30)
\newline 
 >> /usr/man/man1/editor.1.gz -> editor.1.gz -> /usr/man/man1/nvi.1.gz
\end_deeper 
\layout Description

Diversions If your package includes files to be registered using dpkg-divert,
 specify them using this field.
 Please read the man page for dpkg-divert(8) to understand the terminology
 in the following.
 Each diversion to be installed is specified by a single line.
 The diversion is specified by a line containing the path of overriding
 file, followed by the path of overriden file.
 The two names are separated by right-arrows (each made of a hyphen followed
 by a greater-than symbol: "->").
\begin_deeper 
\layout Standard

An example:
\layout LyX-Code

Diversions:
\newline 
 /usr/sbin/smail -> /usr/sbin/smail.real
\end_deeper 
\layout Description

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.
\layout Description

Init This executable field is transformed into the init script placed in
 /etc/init.d/ directory, and update-rc.d is called at the appropriate moments
 during package installation and removal.
 The first line of this script have to contain the arguments for update-rc.d
 command.
 If the init script name is ommited (the first argument), then the package
 name is used.
\begin_deeper 
\layout Standard

An example:
\layout LyX-Code

Init: sh
\newline 
 defaults 20
\newline 
 # The example init script
\newline 
 # The first line contains arguments for update-rc.d
\newline 
 # The first argument is ommited, so the full string might be: 
\newline 
 # package-name defaults 20
\newline 
 #
\newline 
 NAME=daemon
\newline 
 DAEMON=/usr/bin/daemon
\newline 
 case "$1" in
\newline 
   start)
\newline 
     start-stop-daemon --start --quiet --pidfile /var/run/$NAME.pid 
\backslash 

\newline 
       --exec $DAEMON;;
\newline 
   stop)
\newline 
     start-stop-daemon --stop --quiet --pidfile /var/run/$NAME.pid 
\backslash 

\newline 
       --exec $DAEMON;;
\newline 
 esac
\end_deeper 
\layout Description

Logrotate If this field is specified, its value is placed into a file in
 the /etc/logrotate/ directory.
\layout Description

Cron If this field is specified, its value is used as system-wide crontab
 file in the /etc/cron.d/ directory.
\layout Description

Cron-Daily
\layout Description

Cron-Weekly
\layout Description

Cron-Monthly These executable fields are transformed into the system-wide
 crontab scripts for the binary package.
 These scripts will be installed into /etc/cron.{daily,weekly,monthly} directorie
s.
\layout Description

Modutils If this field is specified, its value is placed into a file in
 the /etc/modutils/ directory.
\layout Description

Pam If this field is specified, its value is placed into a file in the /etc/pam.d
/ directory.
\layout Description

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

Contains This field controls additional calls from maintainer's scripts.
 The value is a list of tags:
\begin_deeper 
\layout Description

libs Assumes the package contains shared libraries, and calls ldconfig at
 the appropriate point during package installation.
\layout Description

unstripped Assumes the package contains unstripped binaries, so it is not
 stripped automatically by yada strip.
\layout Description

xfonts Assumes the package contains X Window System's fonts, and calls update-fo
nts-alias and update-fonts-scale.
\layout Description

kernel-modules Assumes the package contains kernel modules, and this package
 can be used with make-kpkg utility.
 It also doesn't strip binaries.
\layout Standard

An example:
\layout LyX-Code

Contains: libs
\end_deeper 
\layout Description

Overrides Lintian is a Debian package checker which generates information
 about policy violations of package.
 The format of Lintian's output is:
\begin_deeper 
\layout LyX-Code

X: package: full information about violation
\layout Standard

i.e.:
\layout LyX-Code

W: securecgi: setuid-binary usr/lib/cgi-bin/securecgi 4755 root/root
\layout Standard

The Overrides field allows to ignore some Lintian's messages.
 In this example, to ignore above message it is required to put the Overrides
 field at binary section:
\layout LyX-Code

Package: securecgi
\newline 
Overrides: setuid-binary usr/lib/cgi-bin/securecgi 4755 root/root
\end_deeper 
\layout Section

Macro preprocessor
\layout Standard

Macro preprocessor resolves all macro commands and macro variables used
 in debian/packages file and produces a temporary file debian/packages-tmp.
\layout Standard

Macro commands begin with percent mark (
\begin_inset Quotes sld
\end_inset 

%
\begin_inset Quotes srd
\end_inset 

):
\layout Description

%define Definition of macro variable.
 This variable can be used further in common section or another macro command.
\layout Description

%include The preprocessor will include another file specified as parameter
 for this macro command.
\layout Description

%if
\layout Description

%else
\layout Description

%endif These macro commands are used to make conditional skipping.
 The first should be followed by text.
 If the condition text is not equal 0 or is not an empty string then the
 condition is true.
 The conditional macro commands can be nested.
\layout Standard

Macro variables:
\layout Description

%{MACRO_VAR} Expands to variable predefined with 
\begin_inset Quotes sld
\end_inset 

%define
\begin_inset Quotes srd
\end_inset 

 command or generates error if the variable is not defined already.
\layout Description

%{$ENV_VAR} Expands to environment variable.
 If variable is not defined, expands to empty string.
\layout Description

%{?MACRO_VAR:string} Expands to given string if macro variable is set and
 its value is true.
\layout Description

%{!?MACRO_VAR:string} Expands to given string if macro variable is not defined
 or its value is not true.
\layout Description

%{?$ENV_VAR:string} Expands to given string if environment variable is set
 and its value is true.
\layout Description

%{!?$ENV_VAR:string} Expands to given string if environment variable is
 not defined or its value is not true.
\layout Description

%`command` Executes given command and expands to its output.
\layout Standard

There are two predefined macro variables:
\layout Description

VERSION Defines the version of the source package.
\layout Description

SOURCE Defines the name of the source package.
\layout Description

YADA_COMMAND Defines how 
\begin_inset Quotes sld
\end_inset 

yada
\begin_inset Quotes srd
\end_inset 

 program is called.
\layout Description

YADA_VERSION Defines YADA version.
\layout Standard

Macro variables can be nested.
 The example usage of macro preprocessor:
\layout LyX-Code

%define KSRC %{?$KSRC:%{$KSRC}}%{!?$KSRC:/usr/src/linux}
\newline 
%define KVERS %{?$KVERS:%{$KVERS}}%{!?$KVERS:%`sed -n -e '/UTS_RELEASE/s/^[^"]*"
\backslash 
([^"]*
\backslash 
)".*$/
\backslash 
1/p' %{KSRC}/include/linux/version.h` 2>/dev/null || echo "UNKNOWN"`}
\newline 
%define KDREV %{?$KDREV:%{$KDREV}}%{!?$KDREV:UNKNOWN}
\newline 
%define APPEND_TO_VERSION %{$APPEND_TO_VERSION}
\newline 
%define FLAVOUR %{$FLAVOUR}
\newline 
%define KMAINT %{?$KMAINT:%{$KMAINT}}%{!?$KMAINT:%{$DEBFULLMAIL}}
\newline 
%define KEMAIL %{?$KEMAIL:%{$KEMAIL}}%{!?$KEMAIL:%{$DEBEMAIL}}
\newline 
 
\newline 
%define with_foo %{?$with_foo:1}%{!?$with_foo:0}
\newline 
 
\newline 
Source: foo-modules-source
\newline 
Build-Depends: yada (>= %{YADA_VERSION})
\newline 
[...]
\newline 
 
\newline 
Package: foo-modules-%{KVERS}
\newline 
Architecture: any
\newline 
%if %{KDREV}
\newline 
Recommends: kernel-image-%{KVERS} (= %{KDREV})
\newline 
%else
\newline 
Recommends: kernel-image-%{KVERS}
\newline 
%endif
\newline 
Description: Some foo kernel modules
\newline 
 The example usage of YADA macro preprocessor.
\newline 
Contains: unstripped
\newline 
Install: sh
\newline 
%if %{with_foo}
\newline 
 yada install -lib -unstripped -into /lib/modules/%{KVERS}/kernel/foo src/foo.o
 
\newline 
%endif
\newline 
[...]
\layout Section

FAQ
\layout Description

Q: Can I export DebConf templates or other script to external file?
\layout Description

A: You can use macro commands.
 Example debian/package file:
\begin_deeper 
\layout LyX-Code

[...]
\newline 
Package: mypackage
\newline 
Depends: otherpackage, []
\newline 
Install:
\newline 
 # some installing commands
\newline 
Templates:
\newline 
%`sed -e 's/^$/./' -e 's/^/ /' debian/packages.templates`
\newline 
# no space in first row!
\newline 
Config: sh
\newline 
[...]
\layout Standard

Example debian/package.templates file:
\layout LyX-Code

Template: %{PACKAGE}/debconf-template
\newline 
Type: note
\newline 
Description: DebConf template in external file
\newline 
 As you see, you can use macros in the template file.
\layout Standard

Don't use debian/templates file.
 This file is automatically created based on debian/packages file.
\end_deeper 
\layout Description

Q: How YADA supports po-debconf?
\layout Description

A: Run 
\begin_inset Quotes sld
\end_inset 

yada rebuild templates
\begin_inset Quotes srd
\end_inset 

 and then 
\begin_inset Quotes sld
\end_inset 

debconf-gettextize
\begin_inset Quotes srd
\end_inset 

 or 
\begin_inset Quotes sld
\end_inset 

debconf-updatepo
\begin_inset Quotes srd
\end_inset 

.
 Delete debian/templates file after all.
\layout Description

Q: Is there any syntax highlighting for debian/packages?
\layout Description

A: There is a file prepared for Midnight Commander.
 You can find debian-control.syntax file in documentation directory, then
 put it into ~/.mc/cedit directory.
 Make sure there is a line in ~/.mc/cedit/Syntax file:
\begin_deeper 
\layout LyX-Code

file (control|packages)$ Debian
\backslash 
scontrol
\backslash 
sfile
\newline 
include debian-control.syntax
\the_end