.TH DEBSTD 1L "29 March 1997" "Debian Utilities" "DEBIAN" \" -*- nroff -*-
.SH NAME
debstd \- Tool for generating single + multi binary packages and setting up scriptfiles
.SH SYNOPSIS
\fBdebstd\fP [ \fIoptions...\fP ] [ \fIdocumentation...\fP ]
.br
.SH DESCRIPTION
.B debstd
is to be called from the
.I debian/rules
makefile and puts files into
.I debian/tmp
(for multi-binary capabilities see below) which are later used by
\fBdpkg\fP(1)
to generate a .deb file.
.SH ACTIONS PERFORMED
.B debstd
looks for control files in the \fIdebian\fP subdirectory
and installs them in the proper locations in \fIdebian/tmp\fP
(generating the necessary directories) or performs some more complex action
(see the list of controlfiles below).
.br
A search for manpages of the form *.[1-8] will be done
throughout the sourcecode archive. Each manpage will be checked
if it is installed in
.I debian/tmp.
If not those manpages are installed (unless the -m option is
specified to disable the scan).
.br
All the files mentioned after the packagename on the commandline are put into the proper
directory for documentation (\fB/usr/doc/\fP\fIpackagename\fP). Please specify an
eventual upstream \fBchangelog\fP file first. If debstd finds "change" (irrelevant
of case) in the first filename then that file is installed as
.B changelog.

.br
debstd will search through the binary archive that is generated and look for
ELF binaries. \fBdpkg-shlibdeps\fP(1) will be run on those binaries.
.PP
debstd will look through the generated \fIusr/doc usr/info\fP and \fIusr/man\fP and
compress files according to the appropriate current policy (if debstd is up to date ...).
debstd will automatically convert manpages containing only a .so command to a symlink.
.PP
A pass will then be made through
the whole binary package looking for dangling symlinks and symlinks that
were pointing to files now compressed. Those symlinks are fixed up or a
message is generated.
.PP
debstd will also search the binary package for libraries provided in \fI/lib
/usr/lib\fP and \fI/usr/X11R6/lib\fP. Those libraries are properly registered with
\fBdpkg\fP through a .shlibs file, and a \fBldconfig\fP(1) call is placed into \fBpostinst\fP.
.PP
Another pass will be made through the binary package and setsid/setgid
permissions will be processed in a special way (see the
.B suid
file below for details).
.PP
debstd will add appropriate commands to the installation scripts
\fBpostinst\fP, \fBpostrm\fP, \fBprerm\fP, and \fBpreinst\fP
if certain control files are present in the
.I debian
subdirectory. If those scripts are also supplied by
the package maintainer then scripts should not end with an exit
command!
debstd
will add commands to the end of those files and thus the
added things will not work.
.PP
debstd
calculates checksums for all files in the package (if not switched off with
the \fB-s\fP option) and puts them into the \fIdebian/tmp/DEBIAN\fP. Files in packages
with checksums can be verified with the
\fBdebsums\fP(1)
command.
.SH OPTIONS
.TP
.B -m
will switch off the automatic installation of manpages found in the source
archive.
.TP
.B -c
switches off automatic compression of documentation
.TP
.B -u
Switches on the automatic manpage symlink generation to the \fBundocumented\fP(1) manpage.
.TP
.B -s
Switch off checksum generation.
.TP
.B -p
Switches on checking of permissions in the \fIdebian/tmp\fP directories.

.SH SUPPORTED CONTROLFILES in debian directory
.TP
.B copyright
A required file containing a description of the packages copyrights. The
file is installed in \fB/usr/doc/\fP\fIpackage\fP. It is required and processed only for
the base package of a multi-binary source archive.
.TP
.B changelog
A required file containing the history of changes to the package. The file
is copied and will be installed in \fB/usr/doc/\fP\fIpackage\fP\fB/changelog.Debian\fP.
Required and processed only for the base package.
.TP
.B README.debian
Optional file containing debian specific instructions for the package.
Installed in \fB/usr/doc/\fP\fIpackage\fP.
Only processed for the base package.
.TP
.B postinst postrm preinst prerm configure
These are optional scripts to be executed on installation or deinstallation
of the package. They are copied into the proper location for control scripts.
.br
Please avoid using the scripts in favor of having debstd automatically write
the scripts for you. Be aware that debstd will add necessary housekeeping
commands to the end of the files if you use any of the features that need to
execute scripts on installation.
.br
The configure script can later be executed using the
\fBdebconf\fP(1)
command.
.br
The configure script is not written to at all right now by
debstd and is at
your full free disposal.
.TP
.B conffiles
An optional file containing the list of configuration files of the package.
Installed in the location for control information about the package.
.TP
.B cron.daily cron.weekly cron.monthly rc.boot
Scripts to perform maintenance for the package. They are installed finally into the
proper directory in \fI/etc\fP.
.TP
.B init.d init
Scripts to be put into \fI/etc/init.d\fP. The script is named according to the
package name if init.d is used. Using \fBinit\fP means that the last "d" should be
removed from the package name to generate the scriptname in \fI/etc/init.d\fP.
Cutting off the d is commonly done for daemons.
.br
If one of these scripts is present then appropriate commands are generated
in the
\fBpostinst\fP, \fBpostrm\fP, and \fBprerm\fP
scripts for the maintenance of the links in
\fI/etc/rc?.d\fP. If there is a \fBFLAGS=\fP line in the init-script then the contents of
that variable can be used to customize the way
.B update-rc.d
is called.
If the script contains the word
.B NO_RESTART_ON_UPGRADE
then the daemon will not be restarted when upgrading the system.
.TP
.B purge
This file should contain a list of files/directories to be removed when the package is
purged from the system. The presence of this file will lead to commands
being added to the \fBpostrm\fP script to erase the files listed in \fBpurge\fP.
.TP
.B examples
This file should contain a list of files/directories to be installed in
\fB/usr/doc/\fP\fIpackage\fP\fB/examples\fP.
.TP
.B docs
This file can contain a list of files/directories to be installed in
\fBusr/doc/\fP\fIpackage\fP. This is in addition to the possibility of naming doc files
on invocation of debstd. The \fBdocs-file\fP is the preferred way of installing
documentation and is the only way documentation can be installed in a
non-base binary package (See multi-binary support below).
.TP
.B info
If this file is present then the necessary calls to install info files are
included in the scripts. Get the template from
\fI/usr/lib/deb-make/debian/info.ex\fP and customize it.
.TP
.B aliases services inittab crontab protocols profile shells
.B rpc shells syslog.conf conf.modules modules
.B X11/Xresources X11/config X11/window-managers X11/xinit
.br
If any of those files is present in the \fIdebian\fP directory then debstd will
generate scripts to add the contents of these files to the corresponding
config file in \fI/etc\fP. The lines that were added will stay in these files in
\fI/etc\fP until the package is purged from the system. The user may change these
lines manually later therefore the contents must not be overwritten on an
update! If you want an update to put your additions into
those configfiles in \fI/etc\fP, then set up a \fBpostinst\fP script that erases the
sections you want to upgrade from those configfiles. Have a look at
\fI/usr/lib/deb-make/etc.postrm\fP to see  how it can be accomplished with the way
debstd encapsulates package specific parts of configuration files.
.br
If the
.B /etc/aliases
file is modified then instructions will be added to \fBpostinst\fP
and \fBpostrm\fP to call \fBnewaliases\fP(1) (if there is a \fBnewaliases\fP command that is -
\fBsmail\fP(1) does not install one!).
.br
Modifications to
\fI/etc/services\fP
should only be made for local packages or temporary fixes. Those changes
have to be submitted to the maintainer of the "netbase" package to be
incorporated into a future standard \fI/etc/services\fP file.
.TP
.B diversions
debstd will generate calls to set up diversions if this file is present. The
file should not contain any comments but just lines with 2 elements
separated by blanks. First the name of the file to be diverted. Second the
file it should be diverted to.
.TP
.B inetd.conf
debstd will create calls to add the lines (contained in the file
.B inetd.conf
) to
\fI/etc/inetd.conf\fP
using
.B update-inetd
on installation and also take care of the
proper script setup for removal.
.br
If a line in the file has the form
\fB#:<\fP\fISECTIONNAME\fP\fB>:\fP
then the following line(s) will be put into the corresponding section.
.TP
.B suid
This file is only necessary if you want to control which files are to be
managed by the
.B suidmanager
package.
Make sure that the filenames are relative to \fIdebian/tmp\fP and that the file
has the proper permissions.
.br
If the
.B suid
file does not exist then an automatic scan for setgid/setsid binaries will
be made. Those files will be registered using \fBsuidmanager\fP (See
.B suid.conf(5)
).
.br
If the \fBsuid\fP file is empty or if it contains the string "off" then no special processing will be done for
setsid/setgid binaries and you have everything under your complete control
from the \fBpostinst\fP and \fBpostrm\fP scripts.
.br
The scripts generated by
debstd
check for the presence of the \fBsuidmanager\fP(1) package. If \fBsuidmanager\fP is not present then
the scripts will go ahead and manually set permissions using
\fBchmod\fP(1)
and
\fBchown\fP(1)
the old fashioned way.
.TP
.B menu
The file is installed in \fB/usr/lib/menu/\fP\fIpackage\fP and appropriate commands are
added to \fBpostinst\fP and \fBpostrm\fP to register/unregister the menu item.
This is supporting Joost Witteveen's \fBmenu\fP package. Simply add that file and
you will be done.
.TP
.B clean
If a file like this exists in the base package then all empty directories
will be erased in the base package before processing. This can be useful if
parts of the base package have been moved by \fBfiles\fP control files into
other subpackages.
.TP
.B nodeps
If a file with the name
.B nodeps
exists in a package directory then no scan for the dependency of binaries
will be done. The maintainer has to specify dependencies explicitly or find
some other way of doing ELF dependency checks on his own.
.SH MULTI-BINARY SUPPORT
A scan will be made for multiple "Package:" lines in the \fBcontrol\fP file.
For the first package (the base package) debstd will work in the usual way.
The second and following "Package:"
lines are processed in order to generate additional binary packages. For
additional binary packages to work
you need to name files in the debian directory
.B subpackagename.file .
Those files will then control the generation of that specific subpackage.
You can use most of the control files mentioned above in this fashion. Some
additional control files:
.PP
Create a file with the name \fIpackage\fP\fB.files\fP
(Replace \fIpackage\fP with the actual subpackage name! Same way later when
"package" is mentioned.)
in that directory and list in that file all directories and files which you want to be in
that package instead of the main package. When debstd is called it
will move those files out of \fIdebian/tmp\fP into the special binary directory
for that partial package and generate a package based on the contents of
that directory. If you generate the directory
\fBdebian/\fP\fIpackage\fP
yourself in the \fBrules\fP file then you can put binaries into the package the same way
done for \fIdebian/tmp\fP (the base package) and
avoid using the
.B files
to list the parts to be moved over to the other package. The pathnames
listed MUST NOT begin with a slash (/). A slash might be disastrous for
your system's health!
.PP
A script named
\fIpackage\fP\fB.prebuild\fP
in the debian directory will be executed if it exists after debstd has
changed all the ownerships of the files to root.root and set the permissions
to defaults. That script must be executable.
\fIpackage\fP\fB.prebuild\fP
may contain statements to set special permissions. The current directory is
the binary directory (\fBdebian/\fP\fIpackage\fP) when invoked.
.SH SEE ALSO
.BR deb-make "(1), " debchange "(1), " dch (1)
and
.BR dpkg (1).
.SH AUTHOR
Christoph Lameter <clameter@debian.org>