.TH DEBSTD 1 "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/share/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/share/doc usr/share/info\fP
and \fIusr/share/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
\fI/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
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.
.TP
.B -d
Switches off the automatic generation of symlinks for the FHS doc
transition.

.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/share/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/share/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/share/doc/\fP\fIpackage\fP.
Only processed for the base package.
.TP
.B postinst postrm preinst prerm config
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 config script can later be executed using the
\fBdebconf\fP(1)
command.
.br
The config script is not written to at all right now by
debstd and is at
your full free disposal.
See \fB/usr/share/doc/debconf-doc/tutorial.txt.gz\fP for more details and
other \fBdebconf\fP specific files.
.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/share/doc/\fP\fIpackage\fP\fB/examples\fP.
.TP
.B docs
This file can contain a list of files/directories to be installed in
\fB/usr/share/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/share/debmake/debian/info.ex\fP and customize it.
.TP
.B aliases services inittab crontab protocols profile
.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/share/debmake/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.
.PP
.B WARNING:
Please note that, in general, modifying a configuration file from another
package is not ok according to policy. This feature does still work
but it generates a visible WARNING message and it may not work in a
future debmake release.
.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 menu
The file is installed in \fB/usr/share/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 " dpkg "(1), and "
.BR /usr/share/doc/debconf-doc/tutorial.txt.gz .
.SH AUTHOR
Christoph Lameter <clameter@debian.org>