// 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* | *-a* __package-version__**.orig.tar.gz** | *-d* | *-t* ] [*-p* __package__] [*-u* __version__] [*-r* __revision__] [*-z* __extension__] [*-b* "__binarypackage____[:type], ...__]" [*-e* __foo@example.org__] [*-f* "__firstname lastname__"] [*-i* "__buildtool__" | *-j*] [*-m*] [*-o* __file__] [*-q*] [*-s*] [*-v*] [*-w* "__addon, ...__"] [*-x* [__01234__]] [*-y*] [*-T*] [*-B*]


== DESCRIPTION

*debmake* helps to build a Debian package from the upstream source.  Normally, this is done as follows:

* The upstream tarball is downloaded as the __package-version__**.tar.gz** file.
* It is untarred to create many files under the __package-version/__ directory.
* debmake is invoked in the __package-version/__ directory, possibly without any arguments.
* Files in the __package-version__**/debian/** directory are manually adjusted.
* *dpkg-buildpackage* (usually from its wrapper *debuild* or *sbuild*) is invoked in the __package-version/__ directory to make Debian packages.

Make sure to protect the arguments of the *-b*, *-f*, and *-w* options from shell interference by quoting them properly.

Recently, the upstream may release its source code using the Git repository only without the tarball. *debmake* can offer a way to
work with this situation:

* "`**git clone https://**__git.site.org/project/package__**.git**`" downloads upstream source to the __package/__ directory.
* "`**cd** __project/__ ; **debmake -u** __version__ **--tar ; cd -**`" generates the __package-version__**.tar.xz** file, the __package_version__**.orig.tar.xz** symlink, and the __package-version/__ directory.
* Files in the __package-version__/**debian/** directory shall be manually adjusted.
* *dpkg-buildpackage* (usually from its wrapper *debuild* or *sbuild*) is invoked in the __package-version/__ directory to make Debian packages.

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*.

=== optional arguments:

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

*-n*, *--native*::
make a native Debian source package without *.orig.tar.gz*.  This makes a Debian source format "`**3.0 (native)**`" package.
+
If you are thinking of packaging a Debian-specific source tree with *debian/* in it into a native Debian package, please think otherwise.  You can use the "`*debmake -d  -i debuild*`" or "`*debmake -t -i debuild*`" commands to make a Debian non-native package using the Debian source format "`**3.0 (quilt)**`"  The only difference is that the *debian/changelog* file must use the non-native version scheme: __version-revision__.  The non-native package is more friendly to downstream distributions.

*-a* __package-version__**.tar.gz**, *--archive* __package-version__**.tar.gz**::
use the upstream source tarball directly. (*-p*, *-u*, *-z*: overridden)
+
The upstream tarball may be specified as __package_version__**.orig.tar.gz** and *tar.gz*.  For other cases, it may be *tar.bz2*, or *tar.xz*.
+
If the specified upstream tarball name contains uppercase letters, the Debian package name is generated by converting them to lowercase letters.
+
If the specified argument is the URL (`http://`, `https://`, or `ftp://`) to the upstream tarball, the upstream tarball is downloaded from the URL using *wget* or *curl*.

*-d*, *--dist*::
run the "`*make dist*`" command equivalents first to generate the upstream tarball and use it.
+
The "`*debmake -d*`" command is designed to run in the __package/__ directory hosting the upstream VCS with the build system supporting the "`*make dist*`" command equivalents.  (`automake`/`autoconf`, ...)

*-t*, *--tar*::
run the "`*tar*`" command to generate the upstream tarball and use it.
+
The "`*debmake -t*`" command is designed to run in the __package/__ directory hosting the upstream VCS.  Unless you provide the upstream version with the *-u* option or with the *debian/changelog* file, a snapshot upstream version is generated in the *0\~%y%m%d%H%M* format, e.g., __0~1403012359__, from the UTC date and time.  The generated tarball excludes the *debian/* directory found in the upstream VCS. (It also excludes typical VCS directories: *.git/*, *.hg/*, *.svn/*, *.CVS/*.)

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

*-u* __version__, *--upstreamversion* __version__::
set the upstream package version.

*-r* __revision__, *--revision* __revision__::
set the Debian package revision.

*-z* __extension__, *--targz* __extension__::
set the tarball type, __extension__=(*tar.gz*|*tar.bz2*|*tar.xz*). (alias: *z*, *b*, *x*)

*-b* "__binarypackage[:type],...__", *--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* __foo@example.org__, *--email* __foo@example.org__::
set e-mail address.
+
The default is taken from the value of the environment variable *$DEBEMAIL*.

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

*-i* "__buildtool__", *--invoke* "__buildtool__"::
invoke "__buildtool__" at the end of execution.  __buildtool__ may be "`*dpkg-buildpackage*`", "`*debuild*`", "`*sbuild*`", etc.
+
The default is not to execute any program.
+
Setting this option automatically sets the *--local* option.

*-j*, *--judge*::
run *dpkg-depcheck* to judge build dependencies and identify file paths.  Log files are in the parent directory.

* __package__**.build-dep.log**: Log file for *dpkg-depcheck*.
* __package__**.install.log**: Log file recording files in the *debian/tmp* directory.

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

*-o* __file__, *--option* __file__::
read optional parameters from __file__. (This is not for everyday use.)
+
The content of __file__ is sourced as the Python code at the end of *para.py*.  For example, the package description can be specified by the following file.
+
----
para['desc'] = 'program short description'
para['desc_long'] = '''\
 program long description which you wish to include.
 .
 Empty line is space + .
 You keep going on ...
'''
----

//

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

*-s*, *--spec*::
use upstream spec (*pyproject.py* for Python, etc.) for the package description.

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

*-w* "__addon,...__", *--with* "__addon,...__"::
add extra arguments to the *--with* option of the *dh*(1) command as __addon__ in *debian/rules*.
+
The __addon__ values are listed all separated by "`*,*`", e.g., "`*-w "python3,autoreconf"*`".
+
For  Autotools based packages, *autoreconf* as __addon__ to run "`*autoreconf -i -v -f*`" for every package building is default behavior of the *dh*(1) command.
+
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* __n__, *--extra* __n__::
generate configuration files as templates.  (Please note *debian/changelog*, *debian/control*, *debian/copyright*, and *debian/rules* are required configuration files to build a Debian binary package.)
+
The number __n__ determines which configuration templates are generated.

* *-x0*: all 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*::
"`force yes`" for all prompts. (without option: "`ask [Y/n]`"; doubled option: "`force no`")

*-T*, *--tutorial*::
output tutorial comment lines in template files.  default when *-x3* or *-x4* is set.

*-B*, *--backup*::
for existing template files, create new template files with *.bkup* suffix and keep the existing ones.

== 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. (These should work in most cases.  If the *-d* option does not work, try the *-t* option instead.)

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

* *debmake -d -i debuild*

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

* *debmake -s -d -b":python3" -i debuild*

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

* *debmake -s -a* __package-version__**.tar.gz -b":python3" -i debuild**

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

* *debmake -a* __package-version__**.tar.gz -b":perl" -i debuild**

== 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:

----
 $ DEBUG=spd debmake ...
----

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.
