debstd - Tool for generating single + multi binary packages and setting up scriptfiles

debstd [ options... ] [ documentation... ]

debstd is to be called from the debian/rules makefile and puts files into debian/tmp (for multi-binary capabilities see below) which are later used by dpkg(1) to generate a .deb file.

debstd looks for control files in the debian subdirectory and installs them in the proper locations in debian/tmp (generating the necessary directories) or performs some more complex action (see the list of controlfiles below).

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 debian/tmp. If not those manpages are installed (unless the -m option is specified to disable the scan).

All the files mentioned after the packagename on the commandline are put into the proper directory for documentation (/usr/share/doc/packagename). Please specify an eventual upstream changelog file first. If debstd finds "change" (irrelevant of case) in the first filename then that file is installed as changelog.

debstd will search through the binary archive that is generated and look for ELF binaries. dpkg-shlibdeps(1) will be run on those binaries.

debstd will look through the generated usr/share/doc usr/share/info and usr/share/man 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.

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.

debstd will also search the binary package for libraries provided in /lib /usr/lib and /usr/X11R6/lib. Those libraries are properly registered with dpkg through a .shlibs file, and a ldconfig(1) call is placed into postinst.

debstd will add appropriate commands to the installation scripts postinst, postrm, prerm, and preinst if certain control files are present in the 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.

debstd calculates checksums for all files in the package (if not switched off with the -s option) and puts them into the debian/tmp/DEBIAN. Files in packages with checksums can be verified with the debsums(1) command.

-m

will switch off the automatic installation of manpages found in the source archive.

-c

switches off automatic compression of documentation

-u

Switches on the automatic manpage symlink generation to the undocumented(1) manpage.

-s

Switch off checksum generation.

-p

Switches on checking of permissions in the debian/tmp directories.

-d

Switches off the automatic generation of symlinks for the FHS doc transition.

copyright

A required file containing a description of the packages copyrights. The file is installed in /usr/share/doc/package. It is required and processed only for the base package of a multi-binary source archive.

changelog

A required file containing the history of changes to the package. The file is copied and will be installed in /usr/share/doc/package/changelog.Debian. Required and processed only for the base package.

README.debian

Optional file containing debian specific instructions for the package. Installed in /usr/share/doc/package. Only processed for the base package.

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.

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.

The config script can later be executed using the debconf(1) command.

The config script is not written to at all right now by debstd and is at your full free disposal. See /usr/share/doc/debconf-doc/tutorial.txt.gz for more details and other debconf specific files.

conffiles

An optional file containing the list of configuration files of the package. Installed in the location for control information about the package.

cron.daily cron.weekly cron.monthly rc.boot

Scripts to perform maintenance for the package. They are installed finally into the proper directory in /etc.

init.d init

Scripts to be put into /etc/init.d. The script is named according to the package name if init.d is used. Using init means that the last "d" should be removed from the package name to generate the scriptname in /etc/init.d. Cutting off the d is commonly done for daemons.

If one of these scripts is present then appropriate commands are generated in the postinst, postrm, and prerm scripts for the maintenance of the links in /etc/rc?.d. If there is a FLAGS= line in the init-script then the contents of that variable can be used to customize the way update-rc.d is called. If the script contains the word NO_RESTART_ON_UPGRADE then the daemon will not be restarted when upgrading the system.

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 postrm script to erase the files listed in purge.

examples

This file should contain a list of files/directories to be installed in /usr/share/doc/package/examples.

docs

This file can contain a list of files/directories to be installed in /usr/share/doc/package. This is in addition to the possibility of naming doc files on invocation of debstd. The docs-file 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).

info

If this file is present then the necessary calls to install info files are included in the scripts. Get the template from /usr/share/debmake/debian/info.ex and customize it.

aliases services inittab crontab protocols profile

rpc shells syslog.conf conf.modules modules X11/Xresources X11/config X11/window-managers X11/xinit

If any of those files is present in the debian directory then debstd will generate scripts to add the contents of these files to the corresponding config file in /etc. The lines that were added will stay in these files in /etc 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 /etc, then set up a postinst script that erases the sections you want to upgrade from those configfiles. Have a look at /usr/share/debmake/etc.postrm to see how it can be accomplished with the way debstd encapsulates package specific parts of configuration files.

If the /etc/aliases file is modified then instructions will be added to postinst and postrm to call newaliases(1) (if there is a newaliases command that is - smail(1) does not install one!).

Modifications to /etc/services 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 /etc/services file.

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.

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.

inetd.conf

debstd will create calls to add the lines (contained in the file inetd.conf ) to /etc/inetd.conf using update-inetd on installation and also take care of the proper script setup for removal.

If a line in the file has the form #:<SECTIONNAME>: then the following line(s) will be put into the corresponding section.

menu

The file is installed in /usr/share/menu/package and appropriate commands are added to postinst and postrm to register/unregister the menu item. This is supporting Joost Witteveen's menu package. Simply add that file and you will be done.

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 files control files into other subpackages.

nodeps

If a file with the name 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.

A scan will be made for multiple "Package:" lines in the control 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 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:

Create a file with the name package.files (Replace package 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 debian/tmp 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 debian/package yourself in the rules file then you can put binaries into the package the same way done for debian/tmp (the base package) and avoid using the 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!

A script named package.prebuild 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. package.prebuild may contain statements to set special permissions. The current directory is the binary directory (debian/package) when invoked.

deb-make(1), debchange(1), dch(1) and dpkg(1), and /usr/share/doc/debconf-doc/tutorial.txt.gz.

Christoph Lameter <clameter@debian.org>