diff options
Diffstat (limited to '')
-rw-r--r-- | debhelper.pod | 1637 |
1 files changed, 1637 insertions, 0 deletions
diff --git a/debhelper.pod b/debhelper.pod new file mode 100644 index 0000000..9b00ec7 --- /dev/null +++ b/debhelper.pod @@ -0,0 +1,1637 @@ +=encoding UTF-8 + +=head1 NAME + +debhelper - the debhelper tool suite + +=head1 SYNOPSIS + +B<dh_>I<*> [B<-v>] [B<-a>] [B<-i>] [B<--no-act>] [B<-p>I<package>] [B<-N>I<package>] [B<-P>I<tmpdir>] + +=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<debian/rules> 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<debian/rules> file that uses debhelper will call several debhelper +commands in sequence, or use L<dh(1)> to automate this process. Examples of +rules files that use debhelper are in F</usr/share/doc/debhelper/examples/> + +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<dh-make> +package, which contains a L<dh_make|dh_make(1)> command that partially +automates the process. For a more gentle introduction, the B<maint-guide> Debian +package contains a tutorial about making your first package using debhelper. + +Except where the tool explicitly denotes otherwise, all of the debhelper +tools assume that they run from the root directory of an unpacked source +package. This is so they can locate find files like F<debian/control> +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<dh_>, 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<debian/> to control what they +do. Besides the common F<debian/changelog> and F<debian/control>, 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<package>.foo (where I<package> of course, +is replaced with the package that is being acted on). + +For example, B<dh_installdocs> uses files named F<debian/package.docs> 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<debian/control>, debhelper will use F<debian/foo> when there's no +F<debian/I<package>.foo> file. However, it is often a good idea to keep +the F<I<package>.> 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<debian/copyright> or F<debian/changelog>). + +In some rare cases, you may want to have different versions of these files +for different architectures or OSes. If files named debian/I<package>.foo.I<ARCH> +or debian/I<package>.foo.I<OS> exist, where I<ARCH> and I<OS> are the same as the +output of "B<dpkg-architecture -qDEB_HOST_ARCH>" / +"B<dpkg-architecture -qDEB_HOST_ARCH_OS>", +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 Substitutions in debhelper config files + +In compatibility level 13 and later, it is possible to use simple +substitutions in debhelper config files for the following tools: + +=over 4 + +=item * + +dh_clean + +=item * + +dh_install + +=item * + +dh_installcatalogs + +=item * + +dh_installdeb + +=item * + +dh_installdirs + +=item * + +dh_installdocs + +=item * + +dh_installexamples + +=item * + +dh_installinfo + +=item * + +dh_installman + +=item * + +dh_installwm + +=item * + +dh_link + +=item * + +dh_missing + +=item * + +dh_ucf + +=back + +All substitution variables are of the form I<${foo}> and the braces +are mandatory. Variable names are case-sensitive and consist of +alphanumerics (a-zA-Z0-9), hyphens (-), underscores (_), and colons (:). +The first character must be an alphanumeric. + +If you need a literal dollar sign that cannot trigger a substitution, +you can either use the B<${Dollar}> substitution or the sequence B<${}>. + +The following expansions are available: + +=over 4 + +=item B<DEB_HOST_*>, B<DEB_BUILD_*>, B<DEB_TARGET_*> + +Expands to the relevant L<dpkg-architecture(1)> value (similar to +I<dpkg-architecture -qVARIABLE_HERE>). + +When in doubt, the B<DEB_HOST_*> variant is the one that will work both +for native and cross builds. + +For performance reasons, debhelper will attempt to resolve these +names from the environment first before consulting +L<dpkg-architecture(1)>. This is mostly mentioned for completeness +as it will not matter for most cases. + +=item B<Dollar> + +Expands to a single literal B<$>-symbol. This symbol will I<never> +be considered part of a substitution variable. That is: + + # Triggers an error + ${NO_SUCH_TOKEN} + # Expands to the literal value "${NO_SUCH_TOKEN}" + ${Dollar}{NO_SUCH_TOKEN} + +This variable equivalent to the sequence B<${}> and the two can be +used interchangeably. + +=item B<Newline>, B<Space>, B<Tab> + +Expands to a single ASCII newline, space and tab respectively. + +This can be useful if you need to include a literal whitespace +character (e.g. space) where it would otherwise be stripped or +used as a separator. + +=item B<< env:I<NAME> >> + +Expands to the environment variable I<NAME>. The environment +variable must be set (but can be set to the empty string). + +=back + +Note that all variables must expand to a defined value. As an example, +if debhelper sees I<${env:FOO}>, then it will insist that the environment +variable I<FOO> is set (it can be set to the empty string). + +=head3 Substitution limits + +To avoid infinite loops and resource exhaustion, debhelper will stop +with an error if the text contains many substitution variables (50) or +they expand beyond a certain size (4096 characters or 3x length of +the original input - whichever is bigger). + +=head2 Executable debhelper config files + +If you need additional flexibility, many of the debhelper tools +(e.g. L<dh_install(1)>) 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<package>.install >>) and the tool will +attempt to execute it and use the output of the script. In many +cases, you can use L<dh-exec(1)> 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<must> exit with success (i.e. its return +code should indicate success). + +=item * + +In compatibility level 13+, the output will be subject to substitutions +(see L</Substitutions in debhelper config files>) where the tool +support these. Remember to be careful if your generator I<also> provides +substitutions as this can cause unnecessary confusion. + +Otherwise, the output will be used exactly as-is. Notably, debhelper +will I<not> expand wildcards or strip comments or strip whitespace +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<dh-exec(1)> and its +B<strip-output> 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<DEB_HOST_ARCH> architecture. + +=item B<-i>, B<--indep> + +Act on all architecture independent packages. + +=item B<-p>I<package>, B<--package=>I<package> + +Act on the package named I<package>. 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<package>, B<--no-package=>I<package> + +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<-P>I<tmpdir>, B<--tmpdir=>I<tmpdir> + +Use I<tmpdir> for package build directory. The default is debian/I<package> + +=item B<--mainpackage=>I<package> + +This little-used option changes the package which debhelper considers the +"main package", that is, the first one listed in F<debian/control>, and the +one for which F<debian/foo> files can be used instead of the usual +F<debian/package.foo> files. + +=item B<-O=>I<option>|I<bundle> + +This is used by L<dh(1)> when passing user-specified options to all the +commands it runs. If the command supports the specified option or option +bundle, it will take effect. If the command does not support the option (or +any part of an option bundle), it will be ignored. + +=back + +=head1 COMMON DEBHELPER OPTIONS + +The following command line options are supported by some debhelper programs. +See the man page of each program for a complete explanation of what each +option does. + +=over 4 + +=item B<-n> + +Do not modify F<postinst>, F<postrm>, etc. scripts. + +=item B<-X>I<item>, B<--exclude=>I<item> + +Exclude an item from processing. This option may be used multiple times, +to exclude more than one thing. The I<item> is typically part of a +filename, and any file containing the specified text will be excluded. + +=item B<-A>, B<--all> + +Makes files or other items that are specified on the command line take effect +in ALL packages acted on, not just the first. + +=back + +=head1 BUILD SYSTEM OPTIONS + +The following command line options are supported by all of the B<dh_auto_>I<*> +debhelper programs. These programs support a variety of build systems, +and normally heuristically determine which to use, and how to use them. +You can use these command line options to override the default behavior. +Typically these are passed to L<dh(1)>, which then passes them to all the +B<dh_auto_>I<*> programs. + +=over 4 + +=item B<-S>I<buildsystem>, B<--buildsystem=>I<buildsystem> + +Force use of the specified I<buildsystem>, instead of trying to auto-select +one which might be applicable for the package. + +Pass B<none> as I<buildsystem> to disable auto-selection. + +=item B<-D>I<directory>, B<--sourcedir=>I<directory>, B<--sourcedirectory=>I<directory> + +Assume that the original package source tree is at the specified +I<directory> rather than the top level directory of the Debian +source package tree. + +B<Warning>: The B<--sourcedir> variant matches a similar named option in +B<dh_install> and B<dh_missing> (etc.) for historical reasons. While they +have a similar name, they have very distinct purposes and in some cases +it can cause errors when this variant is passed to B<dh> (when then passes +it on to all tools). + +=item B<-B>[I<directory>], B<--builddir>[I<=directory>], B<--builddirectory>[I<=directory>] + +Enable out of source building and use the specified I<directory> as the build +directory. If I<directory> parameter is omitted, a default build directory +will be chosen. + +If this option is not specified, building will be done in source by default +unless the build system requires or prefers out of source tree building. +In such a case, the default build directory will be used even if +B<--builddirectory> is not specified. + +If the build system prefers out of source tree building but still +allows in source building, the latter can be re-enabled by passing a build +directory path that is the same as the source directory path. + +=item B<--parallel>, B<--no-parallel> + +Control whether parallel builds should be used if underlying build +system supports them. The number of parallel jobs is controlled by +the B<DEB_BUILD_OPTIONS> environment variable (L<Debian Policy, +section 4.9.1>) at build time. It might also be subject to a build +system specific limit. + +If neither option is specified, debhelper currently defaults to +B<--parallel> in compat 10 (or later) and B<--no-parallel> otherwise. + +As an optimization, B<dh> will try to avoid passing these options to +subprocesses, if they are unnecessary and the only options passed. +Notably this happens when B<DEB_BUILD_OPTIONS> does not have a +I<parallel> parameter (or its value is 1). + +=item B<--max-parallel=>I<maximum> + +This option implies B<--parallel> and allows further limiting the number of +jobs that can be used in a parallel build. If the package build is known to +only work with certain levels of concurrency, you can set this to the maximum +level that is known to work, or that you wish to support. + +Notably, setting the maximum to 1 is effectively the same as using +B<--no-parallel>. + +=item B<--reload-all-buildenv-variables> + +By default, L<dh(1)> will compute several environment (e.g. by using +L<dpkg-buildflags(1)>) and cache them to avoid having all B<dh_auto_*> +tool recompute them. + +When passing this option, the concrete B<dh_auto_*> tool will ignore +the cache from L<dh(1)> and retrigger a rebuild of these variables. +This is useful in the very rare case where the package need to do +multiple builds but with different B<...FLAGS> options. A concrete +example would be needing to change the B<-O> parameter in B<CFLAGS> in +the second build: + + export DEB_CFLAGS_MAINT_APPEND=-O3 + + %: + dh $@ + + override_dh_auto_configure: + dh_auto_configure -Bbuild-deb ... + DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \ + --reload-all-buildenv-variables -Bbuild-udeb ... + +Without B<--reload-all-buildenv-variables> in the second call to +L<dh_auto_configure(1)>, the change in B<DEB_CFLAGS_MAINT_APPEND> +would be ignored as L<dh_auto_configure(1)> would use the cached value +of B<CFLAGS> set by L<dh(1)>. + +This option is only available with B<< debhelper (>= 12.7~) >> when +the package uses compatibility level 9 or later. + +=item B<--list>, B<-l> + +List all build systems supported by debhelper on this system. The list +includes both default and third party build systems (marked as such). Also +shows which build system would be automatically selected, or which one +is manually specified with the B<--buildsystem> option. + +=back + +=head1 COMPATIBILITY LEVELS + +From time to time, major non-backwards-compatible changes need to be made +to debhelper, to keep it clean and well-designed as needs change and its +author gains more experience. To prevent such major changes from breaking +existing packages, the concept of debhelper compatibility levels was +introduced. You must tell debhelper which compatibility level it should use, and +it modifies its behavior in various ways. + +In current debhelper, you can specify the compatibility level in +F<debian/control> by adding a Build-Depends on the debhelper-compat package. +For example, to use v#RECOMMENDED_COMPAT# mode, ensure F<debian/control> has: + + Build-Depends: debhelper-compat (= #RECOMMENDED_COMPAT#) + +This also serves as an appropriate versioned build dependency on a sufficient +version of the debhelper package, so you do not need to specify a separate +versioned build dependency on the debhelper package unless you need a specific +point release of debhelper (such as for the introduction of a new feature or +bugfix within a compatibility level). + +Note that debhelper does not provide debhelper-compat for experimental or beta +compatibility levels; packages experimenting with those compatibility levels +should use F<debian/compat> or B<DH_COMPAT>. + +Prior versions of debhelper required specifying the compatibility level in the +file F<debian/compat>, and current debhelper still supports this for backward +compatibility, though a package may not specify a compatibility level via +multiple methods at once. To use this method, F<debian/compat> should contain +the compatibility level as a single number, and no other content. If you +specify the compatibility level by this method, your package will also need a +versioned build dependency on a version of the debhelper package equal to (or +greater than) the compatibility level your package uses. So, if you specify +compatibility level #RECOMMENDED_COMPAT# in F<debian/compat>, ensure +F<debian/control> has: + + Build-Depends: debhelper (>= #RECOMMENDED_COMPAT#~) + +Unless otherwise indicated, all debhelper documentation assumes that you +are using the most recent compatibility level, and in most cases does not +indicate if the behavior is different in an earlier compatibility level, so +if you are not using the most recent compatibility level, you're advised to +read below for notes about what is different in earlier compatibility +levels. + +=head2 Supported compatibility levels + +These are the available compatibility levels: + +=over 4 + +=item v5 + +This is the lowest supported compatibility level. + +If you are upgrading from an earlier compatibility level, please +review L<debhelper-obsolete-compat(7)>. + +This mode is deprecated. + +=item v6 + +Changes from v5 are: + +=over 8 + +=item - + +Commands that generate maintainer script fragments will order the +fragments in reverse order for the F<prerm> and F<postrm> scripts. + +=item - + +B<dh_installwm> will install a slave manpage link for F<x-window-manager.1.gz>, +if it sees the man page in F<usr/share/man/man1> in the package build +directory. + +=item - + +B<dh_builddeb> did not previously delete everything matching +B<DH_ALWAYS_EXCLUDE>, if it was set to a list of things to exclude, such as +B<CVS:.svn:.git>. Now it does. + +=item - + +B<dh_installman> allows overwriting existing man pages in the package build +directory. In previous compatibility levels it silently refuses to do this. + +=back + +This mode is deprecated. + +=item v7 + +Changes from v6 are: + +=over 8 + +=item - + +B<dh_install>, will fall back to looking for files in F<debian/tmp> if it doesn't +find them in the current directory (or wherever you tell it look using +B<--sourcedir>). This allows B<dh_install> to interoperate with B<dh_auto_install>, +which installs to F<debian/tmp>, without needing any special parameters. + +=item - + +B<dh_clean> will read F<debian/clean> and delete files listed there. + +=item - + +B<dh_clean> will delete toplevel F<*-stamp> files. + +=item - + +B<dh_installchangelogs> will guess at what file is the upstream changelog if +none is specified. + +=back + +This mode is deprecated. + +=item v8 + +Changes from v7 are: + +=over 8 + +=item - + +Commands will fail rather than warning when they are passed unknown options. + +=item - + +B<dh_makeshlibs> will run B<dpkg-gensymbols> on all shared libraries that it +generates shlibs files for. So B<-X> can be used to exclude libraries. +Also, libraries in unusual locations that B<dpkg-gensymbols> would not +have processed before will be passed to it, a behavior change that +can cause some packages to fail to build. + +=item - + +B<dh> requires the sequence to run be specified as the first parameter, and +any switches come after it. Ie, use "B<dh $@ --foo>", not "B<dh --foo $@>". + +=item - + +B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>. + +=back + +This mode is deprecated. + +=item v9 + +Changes from v8 are: + +=over 8 + +=item - + +Multiarch support. In particular, B<dh_auto_configure> passes +multiarch directories to autoconf in --libdir and --libexecdir. + +=item - + +dh is aware of the usual dependencies between targets in debian/rules. +So, "dh binary" will run any build, build-arch, build-indep, install, +etc targets that exist in the rules file. There's no need to define an +explicit binary target with explicit dependencies on the other targets. + +=item - + +B<dh_strip> compresses debugging symbol files to reduce the installed +size of -dbg packages. + +=item - + +B<dh_auto_configure> does not include the source package name +in --libexecdir when using autoconf. + +=item - + +B<dh> does not default to enabling --with=python-support + +(Obsolete: As the B<dh_pysupport> tool was removed from Debian +stretch. Since debhelper/10.3, B<dh> no longer enables this sequence +add-on regardless of compat level) + +=item - + +All of the B<dh_auto_>I<*> debhelper programs and B<dh> set +environment variables listed by B<dpkg-buildflags>, unless +they are already set. + +=item - + +B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and +LDFLAGS to perl F<Makefile.PL> and F<Build.PL> + +=item - + +B<dh_strip> puts separated debug symbols in a location based on their +build-id. + +=item - + +Executable debhelper config files are run and their output used as the +configuration. + +=back + +This mode is deprecated. + +=item v10 + +Changes from v9 are: + +=over 8 + +=item - + +B<dh_installinit> will no longer install a file named debian/I<package> +as an init script. + +=item - + +B<dh_installdocs> will error out if it detects links created with +--link-doc between packages of architecture "all" and non-"all" as it +breaks binNMUs. + +=item - + +B<dh_installdeb> no longer installs a maintainer-provided +debian/I<package>.shlibs file. This is now done by B<dh_makeshlibs> +instead. + +=item - + +B<dh_installwm> refuses to create a broken package if no man page +can be found (required to register for the x-window-manager alternative). + +=item - + +Debhelper will default to B<--parallel> for all buildsystems that +support parallel building. This can be disabled by using either +B<--no-parallel> or passing B<--max-parallel> with a value of 1. + +=item - + +The B<dh> command will not accept any of the deprecated "manual +sequence control" parameters (B<--before>, B<--after>, etc.). Please +use override targets instead. + +B<Retroactively applied to earlier compat levels>: B<dh> no longer +accepts any of these since debhelper/12.4. + +=item - + +The B<dh> command will no longer use log files to track which commands +have been run. The B<dh> command I<still> keeps track of whether it +already ran the "build" sequence and skip it if it did. + +The main effects of this are: + +=over 4 + +=item - + +With this, it is now easier to debug the I<install> or/and I<binary> +sequences because they can now trivially be re-run (without having to +do a full "clean and rebuild" cycle) + +=item - + +The main caveat is that B<dh_*> now only keeps track of what happened +in a single override target. When all the calls to a given B<dh_cmd> +command happens in the same override target everything will work as +before. + +Example of where it can go wrong: + + override_dh_foo: + dh_foo -pmy-pkg + + override_dh_bar: + dh_bar + dh_foo --remaining + +In this case, the call to B<dh_foo --remaining> will I<also> include +I<my-pkg>, since B<dh_foo -pmy-pkg> was run in a separate override +target. This issue is not limited to B<--remaining>, but also includes +B<-a>, B<-i>, etc. + +=back + +=item - + +The B<dh_installdeb> command now shell-escapes the lines in the +F<maintscript> config file. This was the original intent but it did +not work properly and packages have begun to rely on the incomplete +shell escaping (e.g. quoting file names). + +=item - + +The B<dh_installinit> command now defaults to +B<--restart-after-upgrade>. For packages needing the previous +behaviour, please use B<--no-restart-after-upgrade>. + +=item - + +The B<autoreconf> sequence is now enabled by default. Please pass +B<--without autoreconf> to B<dh> if this is not desirable for a given +package + +=item - + +The B<systemd> sequence is now enabled by default. Please pass +B<--without systemd> to B<dh> if this is not desirable for a given +package. + +=item - + +B<Retroactively removed>: B<dh> no longer creates the package build +directory when skipping running debhelper commands. This will not +affect packages that only build with debhelper commands, but it may +expose bugs in commands not included in debhelper. + +This compatibility feature had a bug since its inception in +debhelper/9.20130516 that made it fail to apply in compat 9 and +earlier. As there has been no reports of issues caused by this bug in +those ~5 years, this item have been removed rather than fixed. + +=back + +=item v11 + +This mode is discouraged. + +The compat 11 is discouraged for new packages as it suffers from +feature interaction between L<dh_installinit> and L<dh_installsystemd> +causing services to not run correctly in some cases. Please consider +using compatibility mode 10 or 12 instead. More details about the +issue are available in Debian#887904 and +L<https://lists.debian.org/debian-release/2019/04/msg01442.html>. + +Changes from v10 are: + +=over 8 + +=item - + +B<dh_installinit> no longer installs F<service> or F<tmpfile> files, +nor generates maintainer scripts for those files. Please use the new +B<dh_installsystemd> helper. + +=item - + +The B<dh_systemd_enable> and B<dh_systemd_start> helpers have been +replaced by the new B<dh_installsystemd> helper. For the same reason, +the B<systemd> sequence for B<dh> has also been removed. If you need +to disable the B<dh_installsystemd> helper tool, please use an empty +override target. + +Please note that the B<dh_installsystemd> tool has a slightly +different behaviour in some cases (e.g. when using the B<--name> +parameter). + +=item - + +B<dh_installdirs> no longer creates debian/I<package> directories +unless explicitly requested (or it has to create a subdirectory in +it). + +The vast majority of all packages will be unaffected by this change. + +=item - + +The B<makefile> buildsystem now passes B<INSTALL="install +--strip-program=true"> to L<make(1)>. Derivative buildsystems +(e.g. B<configure> or B<cmake>) are unaffected by this change. + +=item - + +The B<autoconf> buildsystem now passes B<--runstatedir=/run> to +F<./configure>. + +=item - + +The B<cmake> buildsystem now passes +B<-DCMAKE_INSTALL_RUNSTATEDIR=/run> to L<cmake(1)>. + +=item - + +B<dh_installman> will now prefer detecting the language from the +path name rather than the extension. + +=item - + +B<dh_auto_install> will now only create the destination +directory it needs. Previously, it would create the package build +directory for all packages. This will not affect packages that only +build with debhelper commands, but it may expose bugs in commands not +included in debhelper. + +=item - + +The helpers B<dh_installdocs>, B<dh_installexamples>, B<dh_installinfo>, +and B<dh_installman> now error out if their config has a pattern that +does not match anything or reference a path that does not exist. + +Known exceptions include building with the B<nodoc> profile, where the +above tools will silently permit failed matches where the patterns +are used to specify documentation. + +=item - + +The helpers B<dh_installdocs>, B<dh_installexamples>, B<dh_installinfo>, +and B<dh_installman> now accept the parameter B<--sourcedir> with same +meaning as B<dh_install>. Furthermore, they now also fall back to +F<debian/tmp> like B<dh_install>. + +Migration note: A bug in debhelper 11 up to 11.1.5 made +B<dh_installinfo> incorrectly ignore B<--sourcedir>. + +=item - + +The B<perl-makemaker> and B<perl-build> build systems no longer pass +B<-I.> to perl. Packages that still need this behaviour can emulate +it by using the B<PERL5LIB> environment variable. E.g. by adding +B<export PERL5LIB=.> in their debian/rules file (or similar). + +=item - + +The B<PERL_USE_UNSAFE_INC> environment variable is no longer set by +B<dh> or any of the B<dh_auto_*> tools. It was added as a temporary +work around to avoid a lot of packages failing to build at the same +time. + +Note this item will eventually become obsolete as upstream intends +to drop support for the B<PERL_USE_UNSAFE_INC> environment variable. +When perl drops support for it, then this variable will be removed +retroactively from existing compat levels as well. + +=item - + +The B<dh_makeshlibs> helper will now exit with an error if objdump +returns a non-zero exit from analysing a given file. + +=item - + +The B<dh_installdocs> and B<dh_installexamples> tools may now install +I<most> of the documentation in a different path to comply with the +recommendation from Debian policy ยง12.3 (since version 3.9.7). + +Note that if a given source package only contains a single binary +package in F<debian/control> or none of the packages are I<-doc> +packages, then this change is not relevant for that source package and +you can skip to the next change. + +By default, these tools will now attempt to determine a "main package +for the documentation" (called a I<doc-main-package> from here on) for +every I<-doc> package. If they find such a I<doc-main-package>, they +will now install the documentation into the path F<< +/usr/share/doc/I<doc-main-package> >> in the given doc package. +I.e. the path can change but the documentation is still shipped in the +I<-doc> package. + +The B<--doc-main-package> option can be used when the auto-detection +is insufficient or to reset the path to its previous value if there is +a reason to diverge from Debian policy recommendation. + +Some documentation will not be affected by this change. These +exceptions include the copyright file, changelog files, README.Debian, +etc. These files will still be installed in the path F<< +/usr/share/doc/I<package> >>. + +=item - + +The B<dh_strip> and B<dh_shlibdeps> tools no longer uses filename +patterns to determine which files to process. Instead, they open the +file and look for an ELF header to determine if a given file is an +shared object or an ELF executable. + +This change may cause the tools to process more files than previously. + +=back + +=item v12 + +Changes from v11 are: + +=over 8 + +=item - + +The B<dh_makeshlibs> tool now generates shlibs files with versioned +dependency by default. This means that B<-VUpstream-Version> +(a.k.a. B<-V>) is now the default. + +If an unversioned dependency in the shlibs file is wanted, this can be +obtained by passing B<-VNone> instead. However, please see +L<dh_makeshlibs(1)> for the caveat of unversioned dependencies. + +=item - + +The B<-s> (B<--same-arch>) option is removed. Please use B<-a> (B<--arch>) instead. + +=item - + +Invoking B<dh_clean -k> now causes an error instead of a deprecation +warning. + +=item - + +The B<--no-restart-on-upgrade> option in B<dh_installinit> has been removed. +Please use the new name B<--no-stop-on-upgrade> + +=item - + +There was a bug in the B<doit> (and similar) functions from +L<Debian::Debhelper::Dh_Lib> that made them spawn a shell in one +particular circumstance. This bug is now removed and will cause +helpers that rely on the bug to fail with a "command not found"-error. + +=item - + +The B<--list-missing> and B<--fail-missing> in B<dh_install> has been +removed. Please use B<dh_missing> and its corresponding options, +which can also see the files installed by other helpers. + +=item - + +The B<dh_installinit> helper no longer installs configuration for +the upstart init system. Instead, it will abort the build if it +finds an old upstart configuration file. The error is there to +remind the package maintainer to ensure the proper removal of the +conffiles shipped in previous versions of the package (if any). + +=item - + +The B<dh_installdeb> tool will do basic validation of some +L<dpkg-maintscript-helper(1)> commands and will error out if the +commands appear to be invalid. + +=item - + +The B<dh_missing> tool will now default to B<--list-missing>. + +=item - + +The B<dh_makeshlibs> tool will now only pass libraries to L<dpkg-gensymbols(1)> +if the ELF binary has a SONAME (containing ".so"). + +=item - + +The B<dh_compress> tool no longer compresses examples (i.e. anything installed +in F<</usr/share/doc/I<package>/examples>>.) + +=item - + +The standard sequence in B<dh> now includes B<dh_dwz> and +B<dh_installinitramfs> by default. This makes the B<dwz> and +B<installinitramfs> sequences obsolete and they will now fail with an +error. If you want to skip these commands, then please insert an +empty override target for them in F<debian/rules> +(e.g. I<override_dh_dwz:>) + +=item - + +The build systems B<meson> and B<autoconf> no longer explicitly set +the B<--libexecdir> variable and thus relies on the build system +default - which should be B</usr/libexec> (per FHS 3.0, adopted in +Debian Policy 4.1.5). + +If a particular upstream package does not use the correct default, the +parameter can often be passed manually via L<dh_auto_configure(1)>. E.g. +via the following example: + + override_dh_auto_configure: + dh_auto_configure -- --libexecdir=/usr/libexec + +Note the B<--> before the B<--libexecdir> parameter. + +=item - + +The B<dh_installdeb> tool no longer installs the maintainer provided +F<conffiles> file. The file has mostly been obsolete since +compatibility level 3, where B<dh_installdeb> began to automatically +compute the resulting F<conffiles> control file. + +=item - + +The B<dh_installsystemd> tool no longer relies on B<dh_installinit> for +handling systemd services that have a sysvinit alternative. Both tools +must now be used in such a case to ensure the service is properly started +under both sysvinit and systemd. + +If you have an override for B<dh_installinit> (e.g. to call it with +B<--no-start>) then you will probably need one for +B<dh_installsystemd> as well now. + +This change makes B<dh_installinit> inject a I<misc:Pre-Depends> for +B<< init-system-helpers (>= 1.54~) >>. Please ensure that the package +lists B<${misc:Pre-Depends}> in its B<Pre-Depends> field before +upgrading to compat 12. + +=item - + +The third-party B<dh_golang> tool (from B<dh-golang> package) now defaults on +honoring B<DH_GOLANG_EXCLUDES> variable for source installation in -dev +packages and not only during the building process. Please set +B<DH_GOLANG_EXCLUDES_ALL> to false to revert to the previous behaviour. See +B<Debian::Debhelper::Buildsystem::golang(3pm)> for details and examples. + +=item - + +B<dh_installsystemduser> is now included in the B<dh> standard +sequence by default. + +=item - + +The B<python-distutils> buildsystem is now removed. Please use the +third-party build system B<pybuild> instead. + +=back + +=item v13 + +This is the recommended mode of operation. + +Changes from v12 are: + +=over 8 + +=item - + +The B<meson+ninja> build system now uses B<meson test> instead of +B<ninja test> when running the test suite. Any override of +B<dh_auto_test> that passes extra parameters to upstream test runner +should be reviewed as B<meson test> is not command line compatible +with B<ninja test>. + +=item - + +All debhelper like tools based on the official debhelper library +(including B<dh> and the official B<dh_*> tools) no longer accepts +abbreviated command parameters. At the same time, B<dh> now +optimizes out calls to redundant B<dh_*> helpers even when passed +long command line options. + +=item - + +The ELF related debhelper tools (B<dh_dwz>, B<dh_strip>, +B<dh_makeshlibs>, B<dh_shlibdeps>) are now only run for arch dependent +packages by default (i.e. they are excluded from B<*-indep> targets +and are passed B<-a> by default). If you need them for B<*-indep> +targets, you can add an explicit Build-Depends on +B<dh-sequence-elf-tools>. + +=item - + +The third-party B<gradle> build system (from B<gradle-debian-helper> +package) now runs the upstream-provided test suite automatically. To +suppress such behavior, override B<dh_auto_test>. + +=item - + +The B<dh_installman> tool now aborts if it sees conflicting +definitions of a manpage. This typically happens if the upstream +build system is installing a compressed version and the package lists +an uncompressed version of the manpage in F<< +debian/I<package>.manpages >>. Often the easiest fix is to remove the +manpage from F<< debian/I<package>.manpages >> (assuming both versions +are identical). + +=item - + +The B<dh_auto_*> helpers now reset the environment variables B<HOME> +and common B<XDG_*> variable. Please see description of the +environment variables in L</ENVIRONMENT> for how this is handled. + +I<This feature changed between debhelper 13 and debhelper 13.2.> + +=item - + +The B<dh> command will now error if an override or hook target for an +obsolete command are present in F<debian/rules> +(e.g. B<override_dh_systemd_enable:>). + +=item - + +The B<dh_missing> command will now default to B<--fail-missing>. This +can be reverted to a non-fatal warning by explicitly passing +B<--list-missing> like it was in compat 12. + +If you do not want the warning either, please omit the call to +B<dh_missing>. If you use the B<dh> command sequencer, then you can +do this by inserting an empty override target in the +F<debian/rules> file of the relevant package. As an example: + + # Disable dh_missing + override_dh_missing: + +=item - + +The B<dh> command sequencer now runs B<dh_installtmpfiles> in the +default sequence. The B<dh_installtmpfiles> takes over handling of +tmpfiles.d configuration files. Related functionality in +B<dh_installsystemd> is now disabled. + +Note that B<dh_installtmpfiles> responds to +F<< debian/I<package>.tmpfiles >> where B<dh_installsystemd> used +a name without the trailing "s". + +=item - + +Many B<dh_*> tools now support limited variable expansion via the +B<${foo}> syntax. In many cases, this can be used to reference paths +that contain either spaces or L<dpkg-architecture(1)> values. While +this can reduce the need for L<dh-exec(1)> in some cases, it is B<not> +a replacement L<dh-exec(1)> in general. If you need filtering, +renaming, etc., the package will still need L<dh-exec(1)>. + +Please see L</Substitutions in debhelper config files> for syntax and +available substitution variables. To B<dh_*> tool writers, substitution +expansion occurs as a part of the B<filearray> and B<filedoublearray> +functions. + +=item - + +The B<dh> command sequencer will now skip all hook and override targets +for B<dh_auto_test>, B<dh_dwz> and B<dh_strip> when B<DEB_BUILD_OPTIONS> +lists the relevant B<nocheck> / B<nostrip> options. + +Any package relying on these targets to always be run should instead +move relevant logic out of those targets. E.g. non-test related +packaging code from B<override_dh_auto_test> would have to be moved to +B<execute_after_dh_auto_build> or B<execute_before_dh_auto_install>. + +=item - + +The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON> +to L<cmake(1)> to speed up automatic installation process. If for some reason +you need previous behavior, override the flag: + + dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ... + +=back + +=item v14 + +This compatibility level is still open for development; use with caution. + +Changes from v13 are: + +=over 8 + +=item - + +The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_RPATH=ON> +and B<-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON> to L<cmake(1)> to avoid some reproducibility +issues. + +This can cause issues with running binaries directly from the build directories +as they might now require a manually set B<LD_LIBRARY_PATH>. If you need to +override this change, we recommend that you try to pass the +B<-DCMAKE_SKIP_RPATH=OFF> option first to see if that fixes the problem (leaving +B<CMAKE_BUILD_RPATH_USE_ORIGIN> at its new default). This should undo the need for +B<LD_LIBRARY_PATH> and avoid the reproducibility issues on Linux, where B<$ORIGIN> +is supported by the runtime linkers. + +=item - + +The tool B<dh_installsysusers> is now included in the default sequence. + +=back + +=back + +=head1 NOTES + +=head2 Multiple binary package support + +If your source package generates more than one binary package, debhelper +programs will default to acting on all binary packages when run. If your +source package happens to generate one architecture dependent package, and +another architecture independent package, this is not the correct behavior, +because you need to generate the architecture dependent packages in the +binary-arch F<debian/rules> target, and the architecture independent packages +in the binary-indep F<debian/rules> target. + +To facilitate this, as well as give you more control over which packages +are acted on by debhelper programs, all debhelper programs accept the +B<-a>, B<-i>, B<-p>, and B<-s> parameters. These parameters are cumulative. +If none are given, debhelper programs default to acting on all packages listed +in the control file, with the exceptions below. + +First, any package whose B<Architecture> field in B<debian/control> does not +match the B<DEB_HOST_ARCH> architecture will be excluded +(L<Debian Policy, section 5.6.8>). + +Also, some additional packages may be excluded based on the contents of the +B<DEB_BUILD_PROFILES> environment variable and B<Build-Profiles> fields in +binary package stanzas in B<debian/control>, according to the draft policy at +L<https://wiki.debian.org/BuildProfileSpec>. + +=head3 Interaction between package selections and Build-Profiles + +Build-Profiles affect which packages are included in the package +selections mechanisms in debhelper. Generally, the package selections +are described from the assumption that all packages are enabled. This +section describes how the selections react when a package is disabled +due to the active Build-Profiles (or lack of active Build-Profiles). + +=over 4 + +=item -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call) + +The package disabled by Build-Profiles is silently excluded from the +selection. + +Note you will receive a warning if I<all> packages related to these +selections are disabled. In that case, it generally does not make +sense to do the build in the first place. + +=item -N I<package> / --no-package I<package> + +The option is accepted and effectively does nothing. + +=item -p I<package> / --package I<package> + +The option is accepted, but debhelper will not act on the package. + +=back + +Note that it does not matter whether a package is enabled or disabled +by default. + +=head2 Automatic generation of Debian install scripts + +Some debhelper commands will automatically generate parts of Debian +maintainer scripts. If you want these automatically generated things +included in your existing Debian maintainer scripts, then you need to add +B<#DEBHELPER#> to your scripts, in the place the code should be added. +B<#DEBHELPER#> will be replaced by any auto-generated code when you run +B<dh_installdeb>. + +If a script does not exist at all and debhelper needs to add something to +it, then debhelper will create the complete script. + +All debhelper commands that automatically generate code in this way let it +be disabled by the -n parameter (see above). + +Note that the inserted code will be shell code, so you cannot directly use +it in a Perl script. If you would like to embed it into a Perl script, here +is one way to do that (note that I made sure that $1, $2, etc are set with +the set command): + + my $temp="set -e\nset -- @ARGV\n" . << 'EOF'; + #DEBHELPER# + EOF + if (system($temp)) { + my $exit_code = ($? >> 8) & 0xff; + my $signal = $? & 0x7f; + if ($exit_code) { + die("The debhelper script failed with error code: ${exit_code}"); + } else { + die("The debhelper script was killed by signal: ${signal}"); + } + } + +=head2 Automatic generation of miscellaneous dependencies. + +Some debhelper commands may make the generated package need to depend on +some other packages. For example, if you use L<dh_installdebconf(1)>, your +package will generally need to depend on debconf. Or if you use +L<dh_installxfonts(1)>, your package will generally need to depend on a +particular version of xutils. Keeping track of these miscellaneous +dependencies can be annoying since they are dependent on how debhelper does +things, so debhelper offers a way to automate it. + +All commands of this type, besides documenting what dependencies may be +needed on their man pages, will automatically generate a substvar called +B<${misc:Depends}>. If you put that token into your F<debian/control> file, it +will be expanded to the dependencies debhelper figures you need. + +This is entirely independent of the standard B<${shlibs:Depends}> generated by +L<dh_makeshlibs(1)>, and the B<${perl:Depends}> generated by L<dh_perl(1)>. +You can choose not to use any of these, if debhelper's guesses don't match +reality. + +=head2 Package build directories + +By default, all debhelper programs assume that the temporary directory used +for assembling the tree of files in a package is debian/I<package>. + +Sometimes, you might want to use some other temporary directory. This is +supported by the B<-P> flag. For example, "B<dh_installdocs -Pdebian/tmp>", will +use B<debian/tmp> as the temporary directory. Note that if you use B<-P>, the +debhelper programs can only be acting on a single package at a time. So if +you have a package that builds many binary packages, you will need to also +use the B<-p> flag to specify which binary package the debhelper program will +act on. + +=head2 udebs + +Debhelper includes support for udebs. To create a udeb with debhelper, +add "B<Package-Type: udeb>" to the package's stanza in F<debian/control>. +Debhelper will try to create udebs that comply with debian-installer +policy, by making the generated package files end in F<.udeb>, not +installing any documentation into a udeb, skipping over +F<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc. + +=head1 ENVIRONMENT + +This section describes some of the environment variables that influences +the behaviour of debhelper or which debhelper interacts with. + +It is important to note that these must be actual environment variables in +order to affect the behaviour of debhelper (not simply F<Makefile> variables). +To specify them properly in F<debian/rules>, be sure to "B<export>" them. For +example, "B<export DH_VERBOSE>". + +=over 4 + +=item B<DH_VERBOSE> + +Set to B<1> to enable verbose mode. Debhelper will output every command it +runs. Also enables verbose build logs for some build systems like autoconf. + +=item B<DH_QUIET> + +Set to B<1> to enable quiet mode. Debhelper will not output commands calling +the upstream build system nor will dh print which subcommands are called +and depending on the upstream build system might make that more quiet, too. +This makes it easier to spot important messages but makes the output quite +useless as buildd log. +Ignored if DH_VERBOSE is also set. + +=item B<DH_COMPAT> + +Temporarily specifies what compatibility level debhelper should run at, +overriding any value specified via Build-Depends on debhelper-compat or via the +F<debian/compat> file. + +=item B<DH_NO_ACT> + +Set to B<1> to enable no-act mode. + +=item B<DH_OPTIONS> + +All debhelper tools will parse command line arguments listed in this variable +before any command option (as if they had been prepended to the command +line arguments). Unfortunately, some third-party provided tools may not +support this variable and will ignore these command line arguments. + +When using L<dh(1)>, it can be passed options that will be passed on to each +debhelper command, which is generally better than using DH_OPTIONS. + +=item B<DH_ALWAYS_EXCLUDE> + +If set, this adds the value the variable is set to to the B<-X> options of all +commands that support the B<-X> option. Moreover, B<dh_builddeb> will B<rm -rf> +anything that matches the value in your package build tree. + +This can be useful if you are doing a build from a CVS source tree, in +which case setting B<DH_ALWAYS_EXCLUDE=CVS> will prevent any CVS directories +from sneaking into the package you build. Or, if a package has a source +tarball that (unwisely) includes CVS directories, you might want to export +B<DH_ALWAYS_EXCLUDE=CVS> in F<debian/rules>, to make it take effect wherever +your package is built. + +Multiple things to exclude can be separated with colons, as in +B<DH_ALWAYS_EXCLUDE=CVS:.svn> + +=item B<DH_EXTRA_ADDONS> + +If set, this adds the specified dh addons to be run in the appropriate places +in the sequence of commands. This is equivalent to specifying the addon to run +with the --with flag in the debian/rules file. Any --without calls specifying +an addon in this environment variable will not be run. + +This is intended to be used by downstreams or specific local configurations +that require a debhelper addon to be run during multiple builds without +having to patch a large number of rules file. If at all possible, this should +be avoided in favor of a --with flag in the rules file. + +=item B<DH_COLORS>, B<DPKG_COLORS> + +These variables can be used to control whether debhelper commands should use +colors in their textual output. Can be set to "always", "auto" (the default), +or "never". + +Note that B<DPKG_COLOR> also affects a number of dpkg related tools and +debhelper uses it on the assumption that you want the same color setting for +dpkg and debhelper. In the off-hand chance you want different color setting +for debhelper, you can use B<DH_COLORS> instead or in addition to +B<DPKG_COLORS>. + +=item B<NO_COLOR> + +If no explicit request for color has been given (e.g. B<DH_COLORS> and +B<DPKG_COLORS> are both unset), the presence of this environment variable +cause the default color setting to be "never". + +The variable is defined according to L<https://no-color.org/>. In this +project, the environment variables (such as B<DH_COLORS>) are considered +an explicit request for color. + +=item B<CFLAGS>, B<CPPFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, B<GCJFLAGS>, B<FFLAGS>, B<FCFLAGS>, B<LDFLAGS> + +By default (in any non-deprecated compat level), debhelper will automatically +set these flags by using L<dpkg-buildflags(1)>, when they are unset. If you +need to change the default flags, please use the features from +L<dpkg-buildflags(1)> to do this (e.g. B<DEB_BUILD_MAINT_OPTIONS=hardening=all> +or B<DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true>) rather than setting the +concrete variable directly. + +=item B<HOME>, B<XDG_*> + +In compat 13 and later, these environment variables are reset before invoking +the upstream build system via the B<dh_auto_*> helpers. The variables B<HOME> +(all B<dh_auto_*> helpers) and B<XDG_RUNTIME_DIR> (B<dh_auto_test> only) will +be set to a writable directory. All remaining variables and B<XDG_RUNTIME_DIR> +(except for during B<dh_auto_test>) will be cleared. + +The B<HOME> directory will be created as an empty directory but it will be +reused between calls to B<dh_auto_*>. Any content will persist until +explicitly deleted or B<dh_clean>. + +=item B<DEB_BUILD_OPTIONS> + +Please see L</Supported flags in DEB_BUILD_OPTIONS> for this environment +variable. + +Please note that this variable should I<not> be altered by package maintainers +inside F<debian/rules> to change the behaviour of debhelper. Instead, where +the package maintainer need these features, they should look disabling the +relevant feature directly (e.g. by overriding the concrete tools). + +=item B<DEB_MAINT_BUILD_OPTIONS> + +This is a dpkg specific environment variable (see e.g. L<dpkg-buildflags(1)>). +The debhelper tool suite silently ignores it. + +It is documented here because it has a similar name to B<DEB_BUILD_OPTIONS>, +which make some people mistakenly assume that debhelper will also react to this +variable. + +=back + +=head2 Supported flags in DEB_BUILD_OPTIONS + +The debhelper tool suite reacts to the following flags in B<DEB_BUILD_OPTIONS>. + +=over 4 + +=item B<dherroron=obsolete-compat-levels> + +I<This is a debhelper specific value.> + +When B<dherroron> is present and set to B<obsolete-compat-levels>, then +debhelper tools will promote deprecation warnings for usage of old soon +to be removed compat levels into errors. + +This is useful for automated checking for code relying on deprecated +compat levels that is scheduled for removal. + +This option is intended for testing purposes; not production builds. + +=item B<nostrip> + +I<This value will change the content of the debs being built. The .deb +packages built when this is set is therefore not bit-for-bit reproducible +with a regular build in the general case.> + +This value will cause the official debhelper tools will skip actions and +helpers that either remove, detach or deduplicate debugging symbols in +ELF binaries. + +This value affects L<dh_dwz(1)> and L<dh_strip(1)>. + +=item B<nocheck> + +This value will cause the official debhelper build systems to skip runs +of upstream test suites. + +Package maintainers looking to avoid running the upstream tests should +B<not> rely on this. Instead, they can add an empty override target +to skip B<dh_auto_test>. + +This value affects L<dh_auto_test(1)>. + +=item B<nodoc> + +I<This value will change the content of the debs being built. The .deb +packages built when this is set is therefore not bit-for-bit reproducible +with a regular build in the general case.> + +This value will cause several debhelper tools to skip installation of +documentation such as manpages or upstream provided documentation. +Additionally, the tools will also ignore if declared documentation is +"missing" on the assumption that the documentation has not been built. + +This value effects tools I<like> L<dh_installdocs(1)>, which I<knows> +it is working with documentation. + +=item B<noautodbgsym>, B<noddebs> + +I<The official name is autodbgsym. The noddebs variant is accepted +for historical reasons.> + +This value causes debhelper to skip the generation of automatically +generated debug symbol packages. + +This value affects L<dh_strip(1)>. + +=item B<parallel=N> + +This value enables debhelper to use up to B<N> threads or processes +(subject to parameters like B<--no-parallel> and B<--max-parallel=M>). +Not all debhelper tools work with parallel tasks and may silently +ignore the request. + +This value affects many debhelper tools. Most notably B<dh_auto_*>, +which will attempt to run the underlying upstream build system with +that number of threads. + +=item B<terse> + +This value will cause the official debhelper build systems to configure +upstream builds to be terse (i.e. reduce verbosity in their output). +This is subject to the upstream and the debhelper build system +supporting such features. + +This value affects most B<dh_auto_*> tools. + +=back + +Unknown flags are silently ignored. + +Note third-party debhelper-like tools or third-party provided build systems +may or may not react to the above flags. This tends to depend on +implementation details of the tool. + +=head1 SEE ALSO + +=over 4 + +=item F</usr/share/doc/debhelper/examples/> + +A set of example F<debian/rules> files that use debhelper. + +=item L<http://joeyh.name/code/debhelper/> + +Debhelper web site. + +=back + +=head1 AUTHOR + +Joey Hess <joeyh@debian.org> + +=cut |