[[debianconf]]
=== Other debian/* Files

Optional configuration files may be added under the *debian/* directory.  Most of them are to control *dh_** commands offered by the *debhelper* package but there are some for *dpkg-source*, *lintian* and *gbp* commands.

TIP: Check *debhelper*(7) for the latest available set of the *dh_** commands.

These **debian/**'binarypackage'**.*** files provide very powerful means to set the installation path of files.  Even an upstream source without its build system can be packaged just by using these files.  See <<nomakefile>> as an example.

The "^*-x[1234]*^" superscript notation that appears in the following list indicates the minimum value for the *debmake* *-x* option that will generate the associated template file.  See <<xoption>> or *debmake*(1) for details.

Here is the alphabetical list of notable optional configuration files.

'binarypackage'*.bug-control*  ^*-x3*^::
installed as *usr/share/bug/*'binarypackage'*/control* in 'binarypackage'. See <<bug>>.

'binarypackage'*.bug-presubj*  ^*-x3*^::
installed as *usr/share/bug/*'binarypackage'*/presubj* in 'binarypackage'. See <<bug>>.

'binarypackage'*.bug-script*  ^*-x3*^::
installed as *usr/share/bug/*'binarypackage' or *usr/share/bug/*'binarypackage'*/script* in 'binarypackage'. See <<bug>>.

'binarypackage'*.bash-completion*::
List `bash` completion scripts to be installed.
+
The `bash-completion` package is required for both build and user environments.
+
See *dh_bash-completion*(1).

*clean* ^*-x2*^::
List files that should be removed but are not cleaned by the *dh_auto_clean* command.
+
See *dh_auto_clean*(1) and *dh_clean*(1).

*compat* ^*-x3*^::
Previously, this set the *debhelper* compatibility level.
+
Now, use `Build-Depends: debhelper-compat (= @@@dhcompat@@@)` in *debian/control* to specify the compatibility level.
+
See ``COMPATIBILITY LEVELS'' in *debhelper*(7).

'binarypackage'*.conffile*::
No need for this file now since all files in the *etc/* directory are conffiles for recent ``compat >= 3''.
+
--
If the program you're packaging requires every user to modify the configuration files in the */etc* directory, there are two popular ways to arrange for them not to be conffiles, keeping the *dpkg* command happy and quiet.

* Create a symlink under the */etc* directory pointing to a file under the */var* directory generated by the maintainer scripts.
* Create a file generated by the maintainer scripts under the */etc* directory.

--
+
See *dh_installdeb*(1).

'binarypackage'*.config*::
This is the *debconf* *config* script used for asking any questions necessary to configure the package.  See <<debconf>>.

'binarypackage'*.cron.hourly* ^*-x3*^::
Installed into the *etc/cron/hourly/*'binarypackage' file in 'binarypackage'.
+
See *dh_installcron*(1) and *cron*(8).

'binarypackage'*.cron.daily* ^*-x3*^::
Installed into the *etc/cron/daily/*'binarypackage' file in 'binarypackage'.
+
See *dh_installcron*(1) and *cron*(8).

'binarypackage'*.cron.weekly* ^*-x3*^::
Installed into the *etc/cron/weekly/*'binarypackage' file in 'binarypackage'.
+
See *dh_installcron*(1) and *cron*(8).

'binarypackage'*.cron.monthly* ^*-x3*^::
Installed into the *etc/cron/monthly/*'binarypackage' file in 'binarypackage'.
+
See *dh_installcron*(1) and *cron*(8).

'binarypackage'*.cron.d* ^*-x3*^::
Installed into the *etc/cron.d/*'binarypackage' file in 'binarypackage'.
+
See *dh_installcron*(1), *cron*(8), and *crontab*(5).

'binarypackage'*.default* ^*-x3*^::
If this exists, it is installed into *etc/default/*'binarypackage' in 'binarypackage'.
+
See *dh_installinit*(1).

'binarypackage'*.dirs* ^*-x3*^::
List directories to be created in 'binarypackage'.
+
See *dh_installdirs*(1).
+
Usually, this is not needed since all *dh_install** commands create required directories automatically.  Use this only when you run into trouble.

'binarypackage'*.doc-base* ^*-x2*^::
Installed as the *doc-base* control file in 'binarypackage'.
+
See *dh_installdocs*(1) and file:///usr/share/doc/doc-base/doc-base.html/index.html[Debian doc-base Manual] provided by the *doc-base* package.

'binarypackage'*.docs* ^*-x2*^::
List documentation files to be installed in 'binarypackage'.
+
See *dh_installdocs*(1).

'binarypackage'*.emacsen-compat* ^*-x3*^::
Installed into *usr/lib/emacsen-common/packages/compat/*'binarypackage' in 'binarypackage'.
+
See *dh_installemacsen*(1).

'binarypackage'*.emacsen-install* ^*-x3*^::
Installed into *usr/lib/emacsen-common/packages/install/*'binarypackage' in 'binarypackage'.
+
See *dh_installemacsen*(1).

'binarypackage'*.emacsen-remove* ^*-x3*^::
Installed into *usr/lib/emacsen-common/packages/remove/*'binarypackage' in 'binarypackage'.
+
See *dh_installemacsen*(1).

'binarypackage'*.emacsen-startup* ^*-x3*^::
Installed into *usr/lib/emacsen-common/packages/startup/*'binarypackage' in 'binarypackage'.
+
See *dh_installemacsen*(1).

'binarypackage'*.examples* ^*-x2*^::
List example files or directories to be installed into *usr/share/doc/*'binarypackage'*/examples/* in 'binarypackage'.
+
See *dh_installexamples*(1).

*gbp.conf*::
If this exists, it functions as the configuration file for the *gbp* command.
+
See *gbp.conf*(5), *gbp*(1), and *git-buildpackage*(1).

'binarypackage'*.info* ^*-x2*^::
List info files to be installed in 'binarypackage'.
+
See *dh_installinfo*(1).

'binarypackage'*.init* ^*-x3*^::
Installed into *etc/init.d/*'binarypackage' in 'binarypackage'.
+
See *dh_installinit*(1).

'binarypackage'*.install* ^*-x2*^::
List files which should be installed but are not installed by the *dh_auto_install* command.
+
See *dh_install*(1) and *dh_auto_install*(1).

*license-examples/** ^*-x4*^::
These are copyright file examples generated by the *debmake* command.  Use these as the reference for making the *copyright* file.
+
Please make sure to erase these files.

'binarypackage'*.links* ^*-x2*^::
List pairs of source and destination files to be symlinked. Each pair should be put on its own line, with the source and destination separated by whitespace.
+
See *dh_link*(1).

'binarypackage'*.lintian-overrides* ^*-x3*^::
Installed into *usr/share/lintian/overrides/*'binarypackage' in the package build directory. This file is used to suppress erroneous *lintian* diagnostics.
+
See *dh_lintian*(1), *lintian*(1) and https://lintian.debian.org/manual/index.html[Lintian User's Manual].

*manpage.** ^*-x3*^::
These are manpage template files generated by the *debmake* command.  Please rename these to appropriate file names and update their contents.
+
Debian Policy requires that each program, utility, and function should have an associated manual page included in the same package. Manual pages are written in *nroff*(1).
+
If you are new to making a manpage, use *manpage.asciidoc* or *manpage.1* as the starting point.

'binarypackage'*.manpages* ^*-x2*^::
List man pages to be installed.
+
See *dh_installman*(1).

'binarypackage'*.menu* (deprecated, no more installed)::
https://bugs.debian.org/741573[tech-ctte #741573] decided "Debian should use
*.desktop* files as appropriate".
+
Debian menu file installed into *usr/share/menu/*'binarypackage' in 'binarypackage'.
+
See *menufile*(5) for its format.  See *dh_installmenu*(1).

*NEWS*::
Installed into *usr/share/doc/*'binarypackage'*/NEWS.Debian*.
+
See *dh_installchangelogs*(1).

*patches/**::
Collection of *-p1* patch files which are applied to the upstream source before building the source.
+
See *dpkg-source*(1), <<quilt-setup>> and <<alt-patch>>.
+
No patch files are generated by the *debmake* command.

*patches/series* ^*-x1*^::
The application sequence of the *patches/** patch files.

'binarypackage'*.preinst* ^*-x2*^::
'binarypackage'*.postinst* ^*-x2*^::
'binarypackage'*.prerm* ^*-x2*^::
'binarypackage'*.postrm* ^*-x2*^::
These maintainer scripts are installed into the *DEBIAN* directory.
+
Inside the scripts, the token *\#DEBHELPER#* is replaced with shell script snippets generated by other *debhelper* commands.
+
See *dh_installdeb*(1) and https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html[Chapter 6 - Package maintainer scripts and installation procedure] in the ``Debian Policy Manual''.
+
See also *debconf-devel*(7) and https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts[3.9.1 Prompting in maintainer scripts] in the ``Debian Policy Manual''.

*README.Debian* ^*-x1*^::
Installed into the first binary package listed in the *debian/control* file as *usr/share/doc/*'binarypackage'*/README.Debian*.
+
See *dh_installdocs*(1).
+
This file provides the information specific to the Debian package.

'binarypackage'*.service* ^*-x3*^::
If this exists, it is installed into *lib/systemd/system/*'binarypackage'*.service* in 'binarypackage'.
+
See *dh_systemd_enable*(1), *dh_systemd_start*(1), and *dh_installinit*(1).

*source/format* ^*-x1*^::
+
--
The Debian package format.

* Use ``*3.0 (quilt)*'' to make this non-native package (recommended)
* Use ``*3.0 (native)*'' to make this native package

--
+
See ``SOURCE PACKAGE FORMATS'' in *dpkg-source*(1).

*source/lintian-overrides* or *source.lintian-overrides* ^*-x3*^::
These files are not installed, but will be scanned by the *lintian* command to provide overrides for the source package.
+
See *dh_lintian*(1) and *lintian*(1).

*source/local-options* ^*-x1*^::
+
--
The *dpkg-source* command uses this content as its options.  Notable options are:

* *unapply-patches*
* *abort-on-upstream-changes*
* *auto-commit*
* *single-debian-patch*

--
+
This is not included in the generated source package and is meant to be committed to the VCS of the maintainer.
+
See ``FILE FORMATS'' in *dpkg-source*(1).

*source/local-patch-header*::
Free form text that is put on top of the automatic patch generated.
+
This is not included in the generated source package and is meant to be committed to the VCS of the maintainer.
+
+
See ``FILE FORMATS'' in *dpkg-source*(1).

'binarypackage'*.symbols* ^*-x2*^::
The symbols files, if present, are passed to the *dpkg-gensymbols* command to be processed and installed.
+
See *dh_makeshlibs*(1) and <<symbols>>..

'binarypackage'*.templates*::
This is the *debconf* *templates* file used for asking any questions necessary to configure the package.  See <<debconf>>.

*tests/control*::
This is the RFC822-style test meta data file defined in https://dep-team.pages.debian.net/deps/dep8/[DEP-8].  See *autopkgtest*(1) and <<ci>>.

*TODO*::
Installed into the first binary package listed in the *debian/control* file as *usr/share/doc/*'binarypackage'*/TODO.Debian*.
+
See *dh_installdocs*(1).

'binarypackage'*.tmpfile* ^*-x3*^::
If this exists, it is installed into *usr/lib/tmpfiles.d/*'binarypackage'*.conf* in 'binarypackage'.
+
See *dh_systemd_enable*(1), *dh_systemd_start*(1), and *dh_installinit*(1).

'binarypackage'*.upstart* ^*-x3*^::
If this exists, it is installed into etc/init/package.conf in the package build directory. (deprecated)
+
See *dh_installinit*(1) and <<emptypkg>>.

*watch* ^*-x1*^::
The control file for the *uscan* command to download the latest upstream version.
+
This control file may be configured to verify the authenticity of the tarball using its openPGP signature (see <<signing-key>>).
+
See <<dfsg>> and *uscan*(1).

// ======= //

Here are a few reminders for the above list.

* For a single binary package, the 'binarypackage'*.* part of the filename in the list may be removed.
* For a multi binary package, a configuration file missing the 'binarypackage'*.* part of the filename is applied to the first binary package listed in the *debian/control*.
* When there are many binary packages, their configurations can be specified independently by prefixing their name to their configuration filenames such as 'package-1'*.install*, 'package-2'*.install*, etc.
* Some template configuration files may not be created by the *debmake* command. In such cases, you need to create them with an editor.
* Unusual configuration template files generated by the *debmake* command with an extra *.ex* suffix need to be activated by removing that suffix.
* Unused configuration template files generated by the *debmake* command should be removed.
* Copy configuration template files as needed to the filenames matching their pertinent binary package names.

