// vim:set filetype=asciidoc:
[[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: Even an upstream source without its build system can be packaged just by using these files.  See "`<<nomakefile>>`" as an example.

The alphabetical list of notable optional **debian/**__binarypackage__**.*** configuration files listed below provides very powerful means to set the installation path of files.  Please note:

* The "`*-x[01234]*`" superscript notation that appears in the following list indicates the minimum value for the **debmake** **-x** option that generates the associated template file.  See "`<<xoption>>`" or **debmake**(1) for details.
* 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.
* Some configuration template files generated by the *debmake* command with an extra *.ex* suffix need to be activated by removing that suffix.
* The *debmake -B* command adds template files with an extra *.ex* suffix for all existing template files without *.ex* and they 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.

__binarypackage__**.bug-control**  ^pass:q[*-x2*]^::
installed as **usr/share/bug/**__binarypackage__**/control** in __binarypackage__. See "`<<bug>>`".

__binarypackage__**.bug-presubj**  ^pass:q[*-x2*]^::
installed as **usr/share/bug/**__binarypackage__**/presubj** in __binarypackage__. See "`<<bug>>`".

__binarypackage__**.bug-script**  ^pass:q[*-x2*]^::
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* ^pass:q[*-x1*]^::
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* ^pass:q[*-x4*]^::
Set the *debhelper* compatibility level. (deprecated)
+
Use "`*Build-Depends: debhelper-compat (= @@@dhcompat@@@)*`" in *debian/control* to specify the compatibility level and remove *debian/compat*.
+
See "`*COMPATIBILITY LEVELS*`" in *debhelper*(7).

__binarypackage__**.conffiles** ^pass:q[*-x3*]^::
This optional file is installed into the *DEBIAN* directory within the binary package while supplementing it with all the conffiles auto-detected by *debhelper*.
+
This file is primarily useful for using "special" entries such as the remove-on-upgrade feature from *dpkg*(1).
+
--
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** ^pass:q[*-x3*]^::
Installed into the **etc/cron/hourly/**__binarypackage__ file in __binarypackage__.
+
See **dh_installcron**(1) and **cron**(8).

__binarypackage__**.cron.daily** ^pass:q[*-x3*]^::
Installed into the **etc/cron/daily/**__binarypackage__ file in __binarypackage__.
+
See **dh_installcron**(1) and **cron**(8).

__binarypackage__**.cron.weekly** ^pass:q[*-x3*]^::
Installed into the **etc/cron/weekly/**__binarypackage__ file in __binarypackage__.
+
See **dh_installcron**(1) and **cron**(8).

__binarypackage__**.cron.monthly** ^pass:q[*-x3*]^::
Installed into the *etc/cron/monthly/*__binarypackage__ file in __binarypackage__.
+
See **dh_installcron**(1) and **cron**(8).

__binarypackage__**.cron.d** ^pass:q[*-x3*]^::
Installed into the **etc/cron.d/**__binarypackage__ file in __binarypackage__.
+
See **dh_installcron**(1), **cron**(8), and **crontab**(5).

__binarypackage__**.default** ^pass:q[*-x3*]^::
If this exists, it is installed into **etc/default/**__binarypackage__ in __binarypackage__.
+
See **dh_installinit**(1).

__binarypackage__**.dirs** ^pass:q[*-x1*]^::
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** ^pass:q[*-x1*]^::
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] (**doc-base.html**)`" provided by the *doc-base* package.

__binarypackage__**.docs** ^pass:q[*-x1*]^::
List documentation files to be installed in __binarypackage__.
+
See **dh_installdocs**(1).

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

__binarypackage__**.emacsen-install** ^pass:q[*-x3*]^::
Installed into **usr/lib/emacsen-common/packages/install/**__binarypackage__ in __binarypackage__.
+
See **dh_installemacsen**(1).

__binarypackage__**.emacsen-remove** ^pass:q[*-x3*]^::
Installed into **usr/lib/emacsen-common/packages/remove/**__binarypackage__ in __binarypackage__.
+
See **dh_installemacsen**(1).

__binarypackage__**.emacsen-startup** ^pass:q[*-x3*]^::
Installed into **usr/lib/emacsen-common/packages/startup/**__binarypackage__ in __binarypackage__.
+
See **dh_installemacsen**(1).

__binarypackage__**.examples** ^pass:q[*-x1*]^::
List example files or directories to be installed into **usr/share/doc/**__binarypackage__**/examples/** in __binarypackage__.
+
See **dh_installexamples**(1).

*gbp.conf* ^pass:q[*-x1*]^::
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** ^pass:q[*-x1*]^::
List info files to be installed in __binarypackage__.
+
See **dh_installinfo**(1).

__binarypackage__**.init** ^pass:q[*-x4*]^::
Installed into **etc/init.d/**__binarypackage__ in __binarypackage__. (deprecated)
+
See **dh_installinit**(1).

__binarypackage__**.install** ^pass:q[*-x1*]^::
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).

__binarypackage__**.links** ^pass:q[*-x1*]^::
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** ^pass:q[*-x2*]^::
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]`".

__binarypackage__**.maintscript** ^pass:q[*-x2*]^::
If this optional file exists, *debhelper* uses this as the template to generate **DEBIAN/**__binarypackage__**.{pre,post}{inst,rm}** files within the binary package while adding "`**-- "$@"**`" to the **dpkg-maintscript-helper**(1) command.
+
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`".

*manpage.** ^pass:q[*-x2*]^::
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** ^pass:q[*-x3*]^ or *manpage.1* ^pass:q[*-x3*]^ as the starting point.

__binarypackage__**.manpages** ^pass:q[*-x1*]^::
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.
+
No patch files are generated by the *debmake* command.
+
See **dpkg-source**(1), "`<<quilt-setup>>`" and "`<<alt-patch>>`".

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

__binarypackage__**.preinst** ^pass:q[*-x3*]^::
__binarypackage__**.postinst** ^pass:q[*-x3*]^::
__binarypackage__**.prerm** ^pass:q[*-x3*]^::
__binarypackage__**.postrm** ^pass:q[*-x3*]^::
If these optional files exist, the corresponding files are installed into the *DEBIAN* directory within the binary package after enriched by *debhelper*.  Otherwise, these files in the *DEBIAN* directory within the binary package is generated by *debhelper*.
+
Whenever possible, simpler __binarypackage__**.maintscript** should be used instead.
+
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* ^pass:q[*-x1*]^::
Installed into the first binary package listed in the *debian/control* file as **usr/share/doc/**__binarypackage__**/README.Debian**.
+
This file provides the information specific to the Debian package.
+
See **dh_installdocs**(1).

*README.source* ^pass:q[*-x1*]^::
Installed into the first binary package listed in the *debian/control* file as **usr/share/doc/**__binarypackage__**/README.source**.
+
If running "`*dpkg-source -x*`" on a source package doesn’t produce the source of the package, ready for editing, and allow one to make changes and run *dpkg-buildpackage* to produce a modified package without taking any additional steps, creating this file is recommended.
+
See "`https://www.debian.org/doc/debian-policy/ch-source.html#source-package-handling-debian-readme-source[Debian policy manual section 4.14]`".

__binarypackage__**.service** ^pass:q[*-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* ^pass:q[*-x1*]^::
+
--
The Debian package format.

* Use "`**3.0 (quilt)**`" to make this non-native package (popular)
* Use "`**3.0 (native)**`" to make this native package
--
+
See "`SOURCE PACKAGE FORMATS`" in **dpkg-source**(1).

*source/lintian-overrides* ^pass:q[*-x2*]^::
This file is not installed, but is scanned by the *lintian* command to provide overrides for the source package.
+
See **dh_lintian**(1) and **lintian**(1).

*source/local-options* and *source/local-patch-header* ^pass:q[*-x4*]^::
+
NOTE: These files are not compatible with the *dgit* workflow.  See "`<<dgit>>`".
+
There is no reason to use these with the current version of **dpkg-source**(1).

*source/options* ^pass:q[*-x2*]^::
+
--
The *dpkg-source* command uses this content as its options.  This is typically used with "`<<git-patch-applied>>`" and options may be:

* *auto-commit*
* *single-debian-patch*
--
+
This is included in the generated source package.
+
See "`FILE FORMATS`" in **dpkg-source**(1).

*source/patch-header* ^pass:q[*-x2*]^::
Free form text that is put on top of the automatic patch generated.
+
This is included in the generated source package and is meant to be committed to the "`<<git-patch-applied>>`.".
+
See "`FILE FORMATS`" in **dpkg-source**(1).

__binarypackage__**.symbols** ^pass:q[*-x1*]^::
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* ^pass:q[*-x1*]^::
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** ^pass:q[*-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** ^pass:q[*-x4*]^::
If this exists, it is installed into *etc/init/package.conf* in the package build directory. (deprecated)
+
See **dh_installinit**(1).

*upstream/metadata* ^pass:q[*-x1*]^::
Per-package machine-readable metadata about upstream (https://dep-team.pages.debian.net/deps/dep12/[DEP-12]). See "`https://wiki.debian.org/UpstreamMetadata[Upstream MEtadata GAthered with YAml (UMEGAYA)]`".

// ======= //
