// 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*]  [*-c* | *-k*] [*-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*] [*-l* __license_file__] [*-m*] [*-o* __file__] [*-q*] [*-s*] [*-v*] [*-w* "__addon, ...__"] [*-x* [__01234__]] [*-y*] [*-L*] [*-P*] [*-T*]


== 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*, *-l*, and *-w* options from shell interference by quoting them properly.

=== optional arguments:

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

*-c*, *--copyright*::
scan source for copyright+license text and exit.
+
* *-c*: simple output style
* *-cc*: normal output style (similar to the *debian/copyright* file)
* *-ccc*: debug output style

*-k*, *--kludge*::
compare the *debian/copyright* file with the source and exit.
+
The *debian/copyright* file must be organized to list the generic file patterns before the specific exceptions.
+
* *-k*: basic output style
* *-kk*: verbose output style

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

*-l* "__license_file,...__", *--license* "__license_file,...__"::
add formatted license text to the end of the *debian/copyright* file holding license scan results.
+
The default is to add *COPYING* and *LICENSE*, and __license_file__ needs to list only the additional file names all separated by "`*,*`".

*-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 bare minimum 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 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.
* *-x3*: all *-x2* files + optional configuration template files. (default option)
* *-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`")

*-L*, *--local*::
generate configuration files for the local package to fool *lintian*(1) checks.

*-P*, *--pedantic*::
pedantically check auto-generated files.

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

== 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 2 positive 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.

Please double check copyright with the **licensecheck**(1) command.

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

// Use script to check available choices:
//     rg type=|sed -e 's/^.*type="\([^"]\)".*$/type="\1"/'|sort|uniq
//   type="a"
//   type="b"
//   type="c"
//   type="e"
//   type="f"
//   type="i"
//   type="k"
//   type="l"
//   type="m"
//   type="n"
//   type="p"
//   type="r"
//   type="s"
//   type="w"
//   type="y"

* *i*: `main.py` logging
* *p*: `para.py` logging
* *s*: `checkdep5.py` `check_format_style()` logging
* *y*: `checkdep5.py` `split_years_name()` logging
* *b*: `checkdep5.py` `parse_lines()` 1 logging -- content_state scan loop: begin-loop
* *m*: `checkdep5.py` `parse_lines()` 2 logging -- content_state scan loop: after regex match
* *e*: `checkdep5.py` `parse_lines()` 3 logging -- content_state scan loop: end-loop
* *a*: `checkdep5.py` `parse_lines()` 4 logging -- print author/translator section text
* *f*: `checkdep5.py` `check_all_license()` 1 logging -- input filename for the copyright scan
* *l*: `checkdep5.py` `check_all_license()` 2 logging -- print license section text
* *c*: `checkdep5.py` `check_all_license()` 3 logging -- print copyright section text
* *k*: `checkdep5.py` `check_all_license()` 4 logging -- sort key for debian/copyright stanza
* *r*: `sed.py` logging
* *w*: `cat.py` logging
* *n*: `kludge.py` logging ("`*debmake -k*`")

Use this feature as:

----
 $ DEBUG=ipsybmeaflckrwn debmake ...
----

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

== AUTHOR

Copyright © 2014-2024 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 *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.
