path: root/doc/PROGRAMMING

This file documents things you should know to write a new debhelper program.
Any program with a name that begins with dh_ should conform to these
guidelines (with the historical exception of dh_make).

Standardization:
---------------

There are lots of debhelper commands. To make the learning curve shallower,
I want them all to behave in a standard manner:

All debhelper programs have names beginning with "dh_". This is so we don't
pollute the name space too much.

Debhelper programs should never output anything to standard output except
error messages, important warnings, and the actual commands they run that
modify files under debian/ (this last only if they are passed -v, and if you
output the commands, you should indent them with 1 tab). This is so we don't
have a lot of noise output when all the debhelper commands in a debian/rules
are run, so the important stuff is clearly visible.

An exception to above rule are dh_auto_* commands and dh itself. They will
also print the commands interacting with the upstream build system and which
of the simple debhelper programms are called. (i.e. print what a traditional
non-dh(1) using debian/rules would print but nothing else).

Debhelper programs should accept all options listed in the "SHARED
DEBHELPER OPTIONS" section of debhelper(7), including any long forms of
these options, like --verbose . If necessary, the options may be ignored.

If debhelper commands need config files, they should use
debian/package.filename as the name of the config file (replace filename
with whatever your command wants), and debian/filename should also be
checked for config information for the first binary package in
debian/control. Also, debhelper commands should accept the same sort of
information that appears in the config files, on their command lines, if
possible, and apply that information to the first package they act on.
The config file format should be as simple as possible, generally just a
list of files to act on.

Debhelper programs should never modify the debian/postinst, debian/prerm,
etc scripts. Instead, they can add lines to debian/postinst.debhelper, etc. 
The autoscript() function (see below) is one easy way to do this.
dh_installdeb is an exception, it will run after the other commands and
merge these modifications into the actual postinst scripts.

In general, files named debian/*.debhelper and all content in
debian/.debhelper are internal to debhelper, and their existence or
use should not be relied on by external programs such as the build
process of a package. These files will be deleted by dh_clean.

Debhelper programs should default to doing exactly what policy says to do.

There are always exceptions. Just ask me.

Introducing Dh_Lib:
------------------

Dh_Lib is the library used by all debhelper programs to parse their
arguments and set some useful variables. It's not mandatory that your
program use Dh_Lib.pm, but it will make it a lot easier to keep it in sync
with the rest of debhelper if it does, so this is highly encouraged.

Use Dh_Lib like this:

use Debian::Debhelper::Dh_Lib
init();

The init() function causes Dh_lib to parse the command line and do some other
initialization tasks.

Argument processing:
-------------------

All debhelper programs should respond to certain arguments, such as -v, -i,
-a, and -p. To help you make this work right, Dh_Lib.pm handles argument
processing. Just call init().

You can add support for additional options to your command by passing an
options hash to init(). The hash is then passed on the Getopt::Long to
parse the command line options. For example, to add a --foo option, which
sets $dh{FOO}:

init(options => { foo => \$dh{FOO} });

After argument processing, some global variables are used to hold the
results; programs can use them later. These variables are elements of the
%dh hash.

switch		variable	description
-v		VERBOSE		should the program verbosely output what it is
				doing?
--no-act	NO_ACT		should the program not actually do anything?
-i,-a,-p,-N	DOPACKAGES	a space delimited list of the binary packages
				to act on (in Dh_Lib.pm, this is an array)
-i		DOINDEP		set if we're acting on binary independent
				packages
-a		DOARCH		set if we're acting on binary dependent
				packages
-n		NOSCRIPTS	if set, do not make any modifications to the 
				package's postinst, postrm, etc scripts.
-o		ONLYSCRIPTS	if set, only make modifications to the
				package's scripts, but don't look for or
				install associated files.
-X		EXCLUDE		exclude a something from processing (you
				decide what this means for your program)
				(This is an array)
-X              EXCLUDE_FIND	same as EXCLUDE, except all items are put
				into a string in a way that they will make
				find find them. (Use ! in front to negate
				that, of course) Note that this should
				only be used inside complex_doit(), not in
				doit().
-d		D_FLAG		you decide what this means to your program
-k		K_FLAG		used to turn on keeping of something
-P		TMPDIR		package build directory (implies only one
				package is being acted on)
-u		U_PARAMS	will be set to a string, that is typically
				parameters your program passes on to some
				other program. (This is an array)
-V		V_FLAG		will be set to a string, you decide what it
				means to your program
-V		V_FLAG_SET	will be 1 if -V was specified, even if no
				parameters were passed along with the -V
-A		PARAMS_ALL	generally means that additional command line
				parameters passed to the program (other than
				those processed here), will apply to all 
				binary packages the program acts on, not just
				the first
--priority	PRIORITY	will be set to a number
--mainpackage	MAINPACKAGE	controls which package is treated as the
				main package to act on
--name		NAME		a name to use for installed files, instead of
				the package name
--error-handler	ERROR_HANDLER	a function to call on error

Any additional command line parameters that do not start with "-" will be 
ignored, and you can access them later just as you normally would.

Global variables:
----------------

The following keys are also set in the %dh hash when you call init():

MAINPACKAGE	the name of the first binary package listed in
		debian/control
FIRSTPACKAGE	the first package we were instructed to act on. This package
		typically gets special treatment; additional arguments
		specified on the command line may effect it.

Functions:
---------

Dh_Lib.pm also contains a number of functions you may find useful.

doit(@command)
	Pass this function an array that is a 
	shell command. It will run the command (unless $dh{NO_ACT} is set), and
	if $dh{VERBOSE} is set, it will also output the command to stdout. You
	should use this function for almost all commands your program performs
	that manipulate files in the package build directories.
print_and_doit(@command)
        Like doit but will print unless $dh{QUIET} is set. See "Standardization"
        above for when this is allowed to be called.
complex_doit($command)
	Pass this function a string that is a shell command, it will run it
	similarly to how doit() does. You can pass more complicated commands 
	to this (ie, commands involving piping redirection), however, you 
	have to worry about things like escaping shell metacharacters.
verbose_print($message)
	Pass this command a string, and it will echo it if $dh{VERBOSE} is set.
nonquiet_print($message)
	Pass this command a string, and it will echo it unless $dh{QUIET} is set.
	See "Standardization" above for when this is allowed to be called.
error($errormsg)
	Pass this command a string, it will output it to standard error and
	exit.
error_exitcode($cmd)
	Pass this subroutine a string (representing a command line), it will
	output a message describing that the command failed to standard error
	and exit.  Note that this relies on the value of $? to produce a
	meaningful error message.  Even if $? is 0, this /will/ still terminate
	the program (although with a rather unhelpful message).
warning($message)
	Pass this command a string, and it will output it to standard error
	as a warning message.
tmpdir($dir)
	Pass this command the name of a binary package, it will return the
	name of the tmp directory that will be used as this package's
	package build directory. Typically, this will be "debian/package".
compat($num)
	Pass this command a number, and if the current compatibility level
	is less than or equal to that number, it will return true.
	Looks at DH_COMPAT to get the compatibility level.
pkgfile($package, $basename)
	Pass this command the name of a binary package, and the base name of a
	file, and it will return the actual filename to use. This is used
	for allowing debhelper programs to have configuration files in the
	debian/ directory, so there can be one config file per binary
	package. The convention is that the files are named
	debian/package.filename, and debian/filename is also allowable for
	the $dh{MAINPACKAGE}. If the file does not exist, nothing is returned.

	If the *entire* behavior of a command, when run without any special
	options, is determined by the existence of 1 or more pkgfiles,
	or by the existence of a file or directory in a location in the
	tmpdir, it can be marked as such, which allows dh to automatically
	skip running it. This is done by inserting a special comment,
	of the form:

	# PROMISE: DH NOOP WITHOUT pkgfilea pkgfileb tmp(need/this)

pkgext($package)
	Pass this command the name of a binary package, and it will return
	the name to prefix to files in debian/ for this package. For the
	$dh{MAINPACKAGE}, it returns nothing (there is no prefix), for the other
	packages, it returns "package.".
isnative($package)
	Pass this command the name of a package, it returns 1 if the package
	is a native debian package.
	As a side effect, $dh{VERSION} is set to the version number of the
	package.
autoscript($package, $scriptname, $snippetname, $sedcommands || $sub)
	Pass parameters:
	 - binary package to be affected
	 - script to add to
	 - filename of snippet
	 - (optional) EITHER sed commands to run on the snippet. Ie,
	   s/#PACKAGE#/$PACKAGE/ Note: Passed to the shell inside double
           quotes.
	   OR a perl sub to invoke with $_ set to each line of the snippet in
           turn.
	This command automatically adds shell script snippets to a debian
	maintainer script (like the postinst or prerm).
	Note that in v6 mode and up, the snippets are added in reverse
	order for the removal scripts.
autotrigger($package, $trigger_type, $trigger_target)
	This command automatically adds a trigger to the package.  The
	parameters:
	- binary package to be affected
	- the type of trigger (e.g. "activate-noawait")
	- the target (e.g. "ldconfig" or "/usr/share/foo")
dirname($pathname)
	Return directory part of pathname.
basename($pathname)
	Return base of pathname,
addsubstvar($package, $substvar, $deppackage, $verinfo, $remove)
	This function adds a dependency on some package to the specified
	substvar in a package's substvar's file. It needs all these
	parameters:
	- binary package that gets the item
	- name of the substvar to add the item to
	- the package that will be depended on
	- version info for the package (optional) (ie: ">= 1.1")
	- if this last parameter is passed, the thing that would be added
	  is removed instead. This can be useful to ensure that a debhelper
	  command is idempotent. (However, we generally don't bother,
	  and rely on the user calling dh_prep.) Note that without this
	  parameter, if you call the function twice with the same values it
	  will only add one item to the substvars file.
delsubstvar($package, $substvar)
	This function removes the entire line for the substvar from the
	package's shlibs file.
excludefile($filename)
	This function returns true if -X has been used to ask for the file
	to be excluded.
is_udeb($package)
	Returns true if the package is marked as a udeb in the control
	file.
getpackages($type)
	Returns a list of packages in the control file.
	Pass "arch" or "indep" to specify arch-dependent or
	-independent. If $type is omitted, returns all
	packages (including packages that are not built
	for this architecture). Pass "both" to get the union
	of "arch" and "indep" packages.
	Note that "both" is *not* the same omitting the $type parameter.
	As a side effect, populates %package_arches and %package_types with
	the types of all packages (not only those returned).
get_source_date_epoch()
	Return the value of $ENV{SOURCE_DATE_EPOCH} if exists.
	Otherwise compute the value from the first changelog entry,
	use it to set the ENV variable and return it.
inhibit_log()
	Prevent logging the program's successful finish to
	debian/*debhelper.log
load_log($package, $hashref)
	Loads the log file for the given package and returns a list of
	logged commands.
	(Passing a hashref also causes it to populate the hash.)
write_log($cmd, $package ...)
	Writes the log files for the specified package(s), adding
	the cmd to the end.
make_symlink($src, $dest, $tmp)
	Creates a Policy compliant sytem link called $dest pointing to
	$src. If $tmp is given, then $tmp will be prefixed to $dest when
	creating the actual symlink.
install_dh_config_file($src, $dest[, $mode])
	Installs $src into $dest with $mode (defaults to 0644).  If
	compat is 9 (or later) and $src is executable, $src will be
	executed instead and its output will be used to generate the
	$dest file.
install_dir($dir)
	Create the directory denoted by the path $dir and all parent
	entries as well (as needed).
install_file($src, $dest)
	Installs $src into $dest with mode 0644.  The parent dir of
	$dest must exist (can be created with install_dir).
	This is intended for installing regular non-executable files.
install_prog($src, $dest)
	Installs $src into $dest with mode 0755.  The parent dir of
	$dest must exist (can be created with install_dir).
	This is intended for installing scripts or binaries.
install_lib($src, $dest)
	Installs a library at the path $src into $dest.  The parent
	dir of $dest must exist (can be created with install_dir).
	This is intended for installing libraries.

Sequence Addons:
---------------

The dh(1) command has a --with <addon> parameter that can be used to load
a sequence addon module named Debian::Debhelper::Sequence::<addon>. 
These modules can add/remove commands to the dh command sequences, by
calling some functions from Dh_Lib:

insert_before($existing_command, $new_command)
	Insert $new_command in sequences before $existing_command

insert_after($existing_command, $new_command)
	Insert $new_command in sequences after $existing_command

remove_command($existing_command)
	Remove $existing_command from the list of commands to run
	in all sequences.

add_command($new_command, $sequence)
	Add $new_command to the beginning of the specified sequence.
	If the sequence does not exist, it will be created.

add_command_options($command, $opt1, $opt2, ...)
	Append $opt1, $opt2 etc. to the list of additional options which
	dh passes when running the specified $command. These options are
	not relayed to debhelper commands called via $command override.

remove_command_options($command)
	Clear all additional $command options previously added with
	add_command_options().

remove_command_options($command, $opt1, $opt2, ...)
	Remove $opt1, $opt2 etc. from the list of additional options which
	dh passes when running the specified $command.

Buildsystem Classes:
-------------------

The dh_auto_* commands are frontends that use debhelper buildsystem
classes. These classes have names like Debian::Debhelper::Buildsystem::foo,
and are derived from Debian::Debhelper::Buildsystem, or other, related
classes.

A buildsystem class needs to inherit or define these methods: DESCRIPTION,
check_auto_buildable, configure, build, test, install, clean. See the comments
inside Debian::Debhelper::Buildsystem for details. Note that this interface
is still subject to change.

Note that third-party buildsystems will not automatically be used by default,
but can be forced to be used via the --buildsystem parameter.

-- Joey Hess <joeyh@debian.org>