[[control]]
=== debian/control

The *debian/control* file consists of blocks of meta data separated by the blank line.  Each block of meta data defines the following in this order:

* meta data for the Debian source package
* meta data for the Debian binary packages

The *debmake* command with the *-b* option (see <<boption>>) creates the initial template *debian/control* file with followings:

* a set of *Package* stanzas defining the split of the Debian binary packages
* a basic set of substvar used in each pertinent stanza

[[split]]
==== Split of the Debian binary package

For well behaving build systems, the split of the Debian binary package into small ones can be realized as follows.

* Create binary package entries for all binary packages in the *debian/control* file.
* List all file paths (relative to *debian/tmp*) in the corresponding *debian/*'binarypackage'**.install** files.

Please check examples in this guide:

* <<multipkg>> (simple multi binary package example)
* <<librarypkg>> (library related multi binary package example)

[[substvar]]
==== Substvar

The *debian/control* file also defines the package dependency in which the http://www.debian.org/doc/debian-policy/ch-source.html#s-substvars[variable substitutions mechanism] (substvar) may be used.  See *deb-substvars*(5).

The *debmake* command supports following substvars.

* *$\{misc:Depends}* for all binary packages
* *$\{misc:Pre-Depends}* for all multiarch packages
* *$\{shlibs:Depends}* for all binary executable and library packages
* *$\{python:Depends}* for all Python packages
* *$\{python3:Depends}* for all Python3 packages
* *$\{perl:Depends}* for all Perl packages
* *$\{ruby:Depends}* for all Ruby packages

[[binnmu]]
==== binNMU safe

For the safe https://wiki.debian.org/binNMU[binNMU], the dependency among binary packages from a same source package needs attention if there are both "*Architecture: any*" and "*Architecture: all*" packages involved in it.

* "*Architecture: any*" package depends on "*Architecture: any*" 'foo' package
** *Depends:* 'foo' *(== $\{binary:Version})*
* "*Architecture: any*" package depends on "*Architecture: all*" 'bar' package
** *Depends:* 'bar' *(== $\{source:Version}*
* "*Architecture: all*" package depends on "*Architecture: any*" 'baz' package
** *Depends:* 'baz' *(>= $\{source:Version})*, 'baz' *(<< $\{source:Upstream-Version}.0~)*

[[libnames]]
==== The library package name

Let's consider that the upstream source tarball of the *lib*'foo' library is updated from *lib*'foo-7.0'*.tar.gz* to *lib*'foo-8.0'*.tar.gz* with the new SONAME major version.

In order to distinguish the SONAME major version, their binary library pakages are named as *lib*'foo7' and *lib*'foo8' respectively. 

You need to transition all dependent packages using https://wiki.debian.org/binNMU[binNMU] by working with the https://wiki.debian.org/Teams/ReleaseTeam[release team].

In order to transition smoothly, the *-dev* package must follow one of the following naming rules:

* Use the *unversioned -dev* package name: *lib*'foo'*-dev*
** This is the normal rule.
** Only one version of the library package is allowed in the archive.
** This is good idea if the number of dependent packages are limited.
* Use the *versioned -dev* package names: *lib*'foo7'*-dev* and *lib*'foo8'*-dev*
** This is the special rule when you need to support both *lib*'foo7' and *lib*'foo8' simultaneously.
*** Make all dependent packages depend on *lib*'foo'*-dev*.
*** Make both *lib*'foo7'*-dev* and *lib*'foo8'*-dev* provide *lib*'foo'*-dev*.
*** The source package needs to be renamed as *lib*'foo7-7.0'*.tar.gz* and *lib*'foo8-8.0'*.tar.gz* respectively to make them both available in the archive.
*** The package specific install file path including *lib*'foo7' and *lib*'foo8' respectively for header files etc. needs to be chosen to make them co-installable.
** This is useful if the number of dependent packages are huge and their migration poses major resource drain such as manual code updates, etc.  Otherwise, please do not do this.

See http://www.debian.org/doc/debian-policy/ch-sharedlibs.html[Chapter 8 - Shared libraries] of the ``Debian Policy Manual''.

