=encoding UTF-8 =head1 NAME debhelper - the debhelper tool suite =head1 SYNOPSIS BI<*> [B<-v>] [B<-a>] [B<-i>] [B<--no-act>] [B<-p>I] [B<-N>I] [B<-P>I] =head1 DESCRIPTION Debhelper is used to help you build a Debian package. The philosophy behind debhelper is to provide a collection of small, simple, and easily understood tools that are used in F to automate various common aspects of building a package. This means less work for you, the packager. It also, to some degree means that these tools can be changed if Debian policy changes, and packages that use them will require only a rebuild to comply with the new policy. A typical F file that uses debhelper will call several debhelper commands in sequence, or use L to automate this process. Examples of rules files that use debhelper are in F To create a new Debian package using debhelper, you can just copy one of the sample rules files and edit it by hand. Or you can try the B package, which contains a L command that partially automates the process. For a more gentle introduction, the B Debian package contains a tutorial about making your first package using debhelper. Except where tool explicitly denotes otherwise, all of the debhelper tools assumes that they run from root directory of an unpacked source package. This is so they can locate find files like F when needed. =head1 DEBHELPER COMMANDS Here is the list of debhelper commands you can use. See their man pages for additional documentation. =over 4 #LIST# =back =head2 Deprecated Commands A few debhelper commands are deprecated and should not be used. =over 4 #LIST_DEPRECATED# =back =head2 Other Commands If a program's name starts with B, and the program is not on the above lists, then it is not part of the debhelper package, but it should still work like the other programs described on this page. =head1 DEBHELPER CONFIG FILES Many debhelper commands make use of files in F to control what they do. Besides the common F and F, which are in all packages, not just those using debhelper, some additional files can be used to configure the behavior of specific debhelper commands. These files are typically named debian/I.foo (where I of course, is replaced with the package that is being acted on). For example, B uses files named F to list the documentation files it will install. See the man pages of individual commands for details about the names and formats of the files they use. Generally, these files will list files to act on, one file per line. Some programs in debhelper use pairs of files and destinations or slightly more complicated formats. Note for the first (or only) binary package listed in F, debhelper will use F when there's no F.foo> file. However, it is often a good idea to keep the F.> prefix as it is more explicit. The primary exception to this are files that debhelper by default installs in every binary package when it does not have a package prefix (such as F or F). In some rare cases, you may want to have different versions of these files for different architectures or OSes. If files named debian/I.foo.I or debian/I.foo.I exist, where I and I are the same as the output of "B" / "B", then they will be used in preference to other, more general files. Mostly, these config files are used to specify lists of various types of files. Documentation or example files to install, files to move, and so on. When appropriate, in cases like these, you can use standard shell wildcard characters (B and B<*> and B<[>I<..>B<]> character classes) in the files. You can also put comments in these files; lines beginning with B<#> are ignored. The syntax of these files is intentionally kept very simple to make them easy to read, understand, and modify. =head2 Executable debhelper config files If you need additional flexibility, many of the debhelper tools (e.g. L) support executing a config file as a script. To use this feature, simply mark the config file as executable (e.g. B<< chmod +x debian/I.install >>) and the tool will attempt to execute it and use the output of the script. In many cases, you can use L as interpreter of the config file to retain most of the original syntax while getting the additional flexibility you need. When using executable debhelper config files, please be aware of the following: =over 4 =item * The executable config file B exit with success (i.e. its return code should indicate success). =item * The output will be used exactly as it is. Notably, debhelper will I expand wildcards or strip comments in the output. =back If you need the package to build on a file system where you cannot disable the executable bit, then you can use L and its B script. =head1 SHARED DEBHELPER OPTIONS The following command line options are supported by all debhelper programs. =over 4 =item B<-v>, B<--verbose> Verbose mode: show all commands that modify the package build directory. =item B<--no-act> Do not really do anything. If used with -v, the result is that the command will output what it would have done. =item B<-a>, B<--arch> Act on architecture dependent packages that should be built for the B architecture. =item B<-i>, B<--indep> Act on all architecture independent packages. =item B<-p>I, B<--package=>I Act on the package named I. This option may be specified multiple times to make debhelper operate on a given set of packages. =item B<-s>, B<--same-arch> Deprecated alias of B<-a>. This option is removed in compat 12. =item B<-N>I, B<--no-package=>I Do not act on the specified package even if an B<-a>, B<-i>, or B<-p> option lists the package as one that should be acted on. =item B<--remaining-packages> Do not act on the packages which have already been acted on by this debhelper command earlier (i.e. if the command is present in the package debhelper log). For example, if you need to call the command with special options only for a couple of binary packages, pass this option to the last call of the command to process the rest of packages with default settings. =item B<--ignore=>I Ignore the specified file. This can be used if F contains a debhelper config file that a debhelper command should not act on. Note that F, F, and F can't be ignored, but then, there should never be a reason to ignore those files. For example, if upstream ships a F that you don't want B to install, use B<--ignore=debian/init> =item B<-P>I, B<--tmpdir=>I Use I for package build directory. The default is debian/I =item B<--mainpackage=>I This little-used option changes the package which debhelper considers the "main package", that is, the first one listed in F, and the one for which F files can be used instead of the usual F files. =item B<-O=>I