// vim:set filetype=xml:
= DEBMAKE(1)
:man source:   DEBMAKE
:man manual:   Debmake Manual

== NAME

debmake - program to make a Debian source package

== SYNOPSIS

*debmake* [*-h*] [*-n*] [*-p* __package__] [*-u* __version__] [*-r* __revision__]
               [*-z* __extension__] [*-b* "__binarypackage____[:type], ...__]"
               [*-D* __value__] [*-e* __foo@example.org__] [*-f* "__firstname lastname__"]
               [*-i* [*debuild*|*sbuild*|*dgit sbuild*|*gbp buildpackage*|*dpkg-buildpackage*| ...]]
               [*-m*] [*-q*] [*-v*] [*-V*] [*-w* __"addon, ..."__] [*-x* [01234]] [*-y*] [*-B*]
               [__URL__]

== DESCRIPTION

*debmake* helps to build the Debian package from the upstream source.

Normally, this is done as follows:

* The upstream source is obtained as a tarball from a remote web site
   or a cloned work tree using "`**git clone**`".
** For a tarball, it is expanded to many files in the source directory.
** For a cloned work tree, it is used as the source directory.
* debmake is typically invoked in the source directory without any
   argument.
** The source directory is copied to ../__package-version__/ directory.
** If ../__package_version__**.orig.tar.xz** is missing, it is generated.
** The current directory is moved to ../package-version/.
** Template files are generated in the ../__package-version__**/debian/**
     directory
* Files in the ../__package-version__**/debian/** directory should be manually
   adjusted.
* *dpkg-buildpackage* (usually from its wrapper *debuild*, *sbuild*, ...) is
   invoked in the ../__package-version__/ directory to make Debian source
   and binary packages.

Also, *debmake* can be invoked with an argument.  This argument can be __URL__
for a tarball hosted on a remote web site or for a source code accessed
by "`**git clone**`"; or local __PATH__ to the tarball or the source code.

Arguments to *-b*, *-f*, and *-w* options need to be quoted to protect them from the shell.

Other tools also offer ways to obtain the upstream tarball and creating required symlink to build a Debian package depending on
your workflow.  For example, *origtargz*, *mk-origtargz*, *git-deborig*, and *pristine-tar*.

== Positional arguments

__URL__::
acquire the source tree from the tarball, the git repository or the source tree at this __URL__ (or __PATH__) (if missing, the source tree uses the current directory)

== Options

*-h*, *--help*::
show this help message and exit

*-n*, *--native*
make a native source package without *.orig.tar.xz*

*-p*, *--package package*::
set the Debian package name

*-u*, *--upstreamversion* __version__::
set the upstream package version ("*@*" in __version__ is replaced by "*0~yymmddHHMM*" timestamp)

*-r*, *--revision* __revision__::
set the Debian package revision ("*@*" in __revision__ is replaced by "*0~yymmddHHMM*" timestamp)

*-z*, *--tarz* __extension__::
set the tarball compression type for the missing upstream tarball, __extension__=(*tar.xz*|*tar.gz*|*tar.bz2*) (alias: *z*, *b*, *x*)

*-b*, *--binaryspec* __"binarypackage[:type], ..."__::
set the binary package specs by a comma separated list of __binarypackage:type__ pairs.  Here, __binarypackage__ is the binary package name, and the optional __type__ is chosen from the following __type__ values:
+
--
** *bin*: C/C++ compiled ELF binary code package (any, foreign) (default, alias: *""*, i.e., *null-string*)
** *data*: Data (fonts, graphics, ...) package (all, foreign) (alias: *da*)
** *dev*: Library development package (any, same) (alias: *de*)
** *doc*: Documentation package (all, foreign) (alias: *do*)
** *lib*: Library package (any, same) (alias: *l*)
** *perl*: Perl script package (all, foreign) (alias: *pl*)
** *python3*: Python (version 3) script package (all, foreign) (alias: *py3*, *python*, *py*)
** *ruby*: Ruby script package (all, foreign) (alias: *rb*)
** *nodejs*: Node.js based JavaScript package (all, foreign) (alias: *js*)
** *script*: Shell and other interpreted language script package (all, foreign) (alias: *sh*)
--
+
The pair values in the parentheses, such as (any, foreign), are the *Architecture* and *Multi-Arch* stanza values set in the *debian/control* file.  In many cases, the *debmake* command makes good guesses for __type__ from __binarypackage__.  If __type__ is not obvious, __type__ is set to *bin*.
+
Here are examples for typical binary package split scenarios where the upstream Debian source package name is *foo*:
+
--
** Generating an executable binary package *foo*:
*** "`*-b'foo:bin'*`", or its short form "`*-b'-'*`", or no *-b* option
** Generating an executable (python3) binary package *python3-foo*:
*** "`*-b'python3-foo:py'*`", or its short form "`*-b'python3-foo'*`"
** Generating a data package *foo*:
*** "`*-b'foo:data'*`", or its short form "`*-b'-:data'*`"
** Generating a executable binary package *foo* and a documentation one *foo-doc*:
*** "`*-b'foo:bin,foo-doc:doc'*`", or its short form "`*-b'-:-doc'*`"
** Generating a executable binary package *foo*, a library package *libfoo1*, and a library development package *libfoo-dev*:
*** "`*-b'foo:bin,libfoo1:lib,libfoo-dev:dev'*`" or its short form "`*-b'-,libfoo1,libfoo-dev'*`"
--
+
If the source tree contents do not match settings for __type__, the *debmake* command warns you.
*-e*, *--email* __foo@example.org__::
set e-mail address
+
The default is taken from the value of the environment variable *$DEBEMAIL*.

*-D*, *--debug* __value__::
set *DEBUG* environment variable to __value__ for debug logging (substring of "**spPd**", use "**_**" to unset **DEBUG**)

*-f*, *--fullname* __"firstname lastname"__::
set the fullname
+
The default is taken from the value of the environment variable *$DEBFULLNAME*.

*-i*, *--invoke* __[debuild|sbuild|dgit sbuild|gbp buildpackage|dpkg-buildpackage| ...]__::
invoke package build tool

*-m*, *--monoarch*::
force packages to be non-multiarch

*-q*, *--quitearly*::
quit early before creating files in the debian directory

*-v*, *--version*::
show version information

*-V*, *--verbose*::
use --verbose for shell commands if available

*-w*, *--with* __"addon ..."__::
set additional "`*dh --with*`" option arguments in *debian/rules*
+
For Autotools based packages, if they install Python (version 3) programs, setting *python3* as __addon__ to the *debmake* command argument is needed since this is non-obvious.  But for *pyproject.toml* based Python packages, setting *python3* as __addon__ to the *debmake* command argument is not needed since this is obvious and the *debmake* command automatically set it to the *dh*(1) command.

*-x*, *--extra* __[01234]__::
generate extra configuration files as templates (default: 2)
+
Please note *debian/changelog*, *debian/control*, *debian/copyright*, *debian/rules*, and *debian/source/format* are required configuration files to build a modern Debian binary package.
+
The number determines which configuration templates are generated.

* *-x0*: all 5 required configuration template files. (selected option if any of these required files already exist)
* *-x1*: all *-x0* files + desirable configuration template files with binary package type supports.
* *-x2*: all *-x1* files + normal configuration template files with maintainer script supports. (default)
* *-x3*: all *-x2* files + optional configuration template files.
* *-x4*: all *-x3* files + deprecated configuration template files.

Some configuration template files are generated with the extra *.ex* suffix to ease their removal. To activate these, rename their file names to the ones without the *.ex* suffix and edit their contents.
Existing configuration files are never overwritten.  If you wish to update some of the existing configuration files, please rename them  before  running  the *debmake* command and manually merge the generated configuration files with the old renamed ones.

*-y*, *--yes*::
use once to "`force yes`" for all prompts, twice to "`force no`"

*-B*, *--backup*::
keep the user editted ones without *.ex* suffix and create template files with *.ex* suffix

== EXAMPLES

For a well behaving source, you can build a good-for-local-use installable single Debian binary package easily with one command.  Test install of such a package generated in this way offers a good alternative to the traditional "`*make install*`" command installing into the */usr/local* directory since the Debian package can be  removed  cleanly  by  the "`*dpkg -P* '...'`" command. Here are some examples of how to build such test packages.

For a typical C program source tree packaged with *autoconf*/*automake*:

* *debmake -i sbuild*

For a typical Python (version 3) module source tree:

* *debmake -b":python3" -i sbuild*

For a typical Python (version 3) module in the __package-version__**.tar.xz** archive:

* *debmake*  __package-version__**.tar.xz -b":python3" -i sbuild**

For a typical Perl module in the __package-version__**.tar.xz** archive:

* *debmake* __package-version__**.tar.xz -b":perl" -i sbuild**

== HELPER PACKAGES

Packaging may require installation of some additional specialty helper packages.

* Python (version 3) programs may require the *pybuild-plugin-pyproject* package.

* The Autotools (*autoconf* + *automake*) build system may require *autotools-dev* or *dh-autoreconf* package.

* Ruby programs may require the *gem2deb* package.

* Node.js based JavaScript programs may require the *pkg-js-tools* package.

* Java programs may require the *javahelper* package.

* Gnome programs may require the *gobject-introspection* package.

* etc.

== CAVEAT

Although *debmake* is meant to provide template files for the package maintainer to work on, actual packaging activities are often performed without using *debmake* while referencing only existing similar packages and "`https://www.debian.org/doc/debian-policy/[Debian Policy Manual]`".  All template files generated by *debmake* are required to be modified manually.

There are some points for *debmake*:

* *debmake* helps to write terse packaging tutorial "`https://www.debian.org/doc/manuals/debmake-doc/[Guide for Debian Maintainers]`" (*debmake-doc* package).
* *debmake* provides short extracted license texts as *debian/copyright* in decent accuracy to help license review.
* "`Guide for Debian Maintainers`" also serves as a tutorial with examples for the usage of debmake.
* *debmake* internally calls *licensecheck* from the *licensecheck* package to create *debian/copyright* if it doesn't exist.
* *debmake* internally calls *lrc* from the *licenserecon* package to verify *debian/copyright* if it already exists.

// BEGIN: SNIP_FOR_VERSION

There are some limitations for what characters may be used as a part of the Debian package.  The most notable limitation is the prohibition of uppercase letters in the package name.  Here is a summary as a set of regular expressions:

* Upstream package name (*-p*): `[-+.a-z0-9]{2,}`
* Binary package name (*-b*): `[-+.a-z0-9]{2,}`
* Upstream version (*-u*): `[0-9][-+.:~a-z0-9A-Z]*`
* Debian revision (*-r*): `[0-9][+.~a-z0-9A-Z]*`

See the exact definition in "`https://www.debian.org/doc/debian-policy/#document-ch-controlfields[Chapter 5 - Control files and their fields]`" in the "`Debian Policy Manual`".

// END: SNIP_FOR_VERSION

*debmake* assumes relatively simple packaging cases.  So all programs related to the interpreter are assumed to be "`*Architecture: all*`".  This is not always true.

== DEBUG

Please report bugs to the *debmake* package using the *reportbug* command.

The character set in the environment variable *$DEBUG* determines the logging output level.

* *s*: program progress logging
* *p*: key para[..] value logging
* *P*: all para[..] value logging
* *d*: para["debs"] value logging

Use this feature as:

----
[base_dir] $ export DEBUG=spd; debmake ...
----

or

----
[base_dir] $ debmake -D spd ...
----

See *README.md* in the source for more.

== AUTHOR

Copyright © 2014-2026 Osamu Aoki <osamu@debian.org>

== LICENSE

Expat License

== SEE ALSO

The *debmake-doc* package provides the "`https://www.debian.org/doc/manuals/debmake-doc/[Guide for Debian Maintainers]`" in plain text, HTML and PDF formats under the */usr/share/doc/debmake-doc/* directory.

See also *licensecheck*(1), *lrc*(1), *dpkg-source*(1), *deb-control*(5), *debhelper*(7), *dh*(1), *dpkg-buildpackage*(1), *debuild*(1), *quilt*(1), *dpkg-depcheck*(1), *sbuild*(1), *gbp-buildpackage*(1), and *gbp-pq*(1) manpages.
