dh_make.1 8.73 KB
Newer Older
Craig Small's avatar
Craig Small committed
1
.\" (C) Copyright 1998-2016 Craig Small <csmall@debian.org>
Craig Small's avatar
Craig Small committed
2 3 4 5 6
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
7
.TH DH_MAKE 1 2016-01-08 "Debian Project"
8
.SH NAME
9
dh_make \- prepare Debian packaging for an original source archive
10 11
.SH SYNOPSIS
.B dh_make
Craig Small's avatar
Craig Small committed
12
[\fIoption\fR]...
13 14 15 16 17 18
.SH DESCRIPTION
.B dh_make
is a tool to convert a regular source code package into one formatted
according to the requirements of the Debian Policy.
.B dh_make
must be invoked within a directory containing the source code, which must
Ben Wiederhake's avatar
Ben Wiederhake committed
19 20 21 22 23 24 25
be named <packagename>\-<version>.
The <packagename> must be all lowercase,
The <packagename> and <version>
must be all lowercase,
digits and dashes. The <version> can also contain digits, and the symbols
plus, dot, tilde. The <version> must start with a digit.
If the directory name does not conform to this scheme,
26 27
you must rename it before using 
.B dh_make.
28
Alternatively, you may be able to use the \fB\-\-packagename\fR option to force 
29 30
the package name.
.br
31
.SS PACKAGE CLASSES
Craig Small's avatar
Craig Small committed
32 33
Classes can be set with the single direct options (such as \-\-s for single)
or with the -C,--packageclass option (\-C=s for single).
34 35 36 37 38
.TP
.B Single binary (s)
The package will generate a single binary .deb package. It is the standard
case, so if you don't know what to do, choose this.
.TP
39
.B Arch-Independent (i)
Craig Small's avatar
Craig Small committed
40
The package will generate a single package that is arch-independent.
41
.TP
42 43
.B Library (l)
The package will generate at least two binaries. One library package
44
containing just the lib in \fI/usr/lib\fR and another *\-dev_*.deb package
45 46
containing documentation and C headers.
.TP
47 48
.SS ACTIONS PERFORMED
Unless \fB\-\-native\fR was given, 
49
.B dh_make
50
makes sure a original source archive (<packagename>_<version>.orig.tar.gz)
51 52 53 54 55 56
exists. The archive can either end with .gz or one of the other supported
compression extensions such as bz2 or lzma.
If no such file exists, the file specified with \fB\-f\fR is copied in place.
If no \fB\-f\fR is supplied either but \fB\-\-createorig\fR is, the current
directory is created into a news archive
.I ../<packagename>\-<version>.orig.tar.gz
57 58
The original archive is needed for other Debian tools to generate the
diffs to the original sources required by the Debian packaging format.
59
Unless there are reasons against it, this file should be the pristine
60
upstream archive.
61 62 63 64 65
.PP
Then
.B dh_make
proceeds to generate a "debian" subdirectory and the necessary control
files in the program source directory. Those control files are customized
66 67 68 69 70 71 72 73
with the packagename and version extracted from the directory name.

.B dh_make
makes several attempts to obtain the username. It first checks for the 
environment variables \fB$DEBFULLNAME\fR, \fB$LOGNAME\fR is used to
find a name in the \fI/etc/passwd\fR file, and through NIS, YP
and LDAP.

Craig Small's avatar
Craig Small committed
74
The e\-mail address can either be specified with the -fB\-\-email\fR option
75
or
76 77 78 79 80 81 82 83 84
.B dh_make
will attempt to find it. It will first check the environment variables
\fB$DEBEMAIL\fR and then \fB$EMAIL. If they are not set then 
.B dh_make
will search an available LDAP directory using
.BR ldapsearch (1)
using \fB$LOGNAME\fR as the uid to search under.  Finally it will use
\fB$LOGNAME\fR and \fI/etc/mailname\fR to generate an email address.

85 86 87 88 89 90 91
.B dh_make
will also generate example files that are also customized for the package
generated. You can remove all files with *.ex if you wish. You can also
delete the README.Debian file if you don't have anything to put in it.
Renaming the example files to their name without the .ex at the end (and
editing them if necessary) will activate that feature of debhelper.
.PP
92
If the \fB\-\-templates\fR or \fB\-o\fR (\fB\-\-overlay\fR) option is used
93 94 95 96 97
.B dh_make
will apply a customizing template to the "debian" directory. See the
templates described in the FILES section of this manpage for samples.
.SH OPTIONS
.TP
98 99
.BR \-c ", " \-\-copyright\  \fIlicense\fR
Use \fIlicense\fR type in copyright file.  \fIlicense\fR can be gpl, gpl2,
Craig Small's avatar
Craig Small committed
100
gpl3, lgpl, lgpl2 lgpl3, artistic, apache, bsd, mit or custom.
101
If this field is not specified the copyright file has a space to
102
fill in which sort of license is used. The field is case-insensitive so
103 104 105
\-c GPL works as well as \-c gpl. gpl and lgpl will give you version 3
of the corresponding license, apache implies Apache v2.0. If you need a 
different version, change the
Craig Small's avatar
Craig Small committed
106 107 108 109 110 111 112 113
license file afterwards or use the gpl2 and lgpl2 options.  If you select
custom here you will need to use the \fB\-\-copyrightfile\fR option as well.
.TP
.BR \-\-copyrightfile\ \fIfilename\fR
When using the custom \fB\-\-copyright\fR option this is the location of
your custom copyright file. \fBdh_make\fR will process this file just like
the standard copyright files. It is suggested you use one of the existing
license files as a starting point.
114
.TP
Craig Small's avatar
Craig Small committed
115 116 117 118
.B \-\-docs
Create a separate \fIPACKAGE-doc\fR binary package. All found documents
in the source package will be installed here.
.TP
119 120
.BR \-e ", " \-\-email\ \fIaddress\fR
Use \fIaddress\fR as the e\-mail address in the Maintainer: field of
121 122
debian/control file.
.TP
123
.BR \-n ", " \-\-native
124 125
Create a native Debian packages, i.e. do not generate a .orig archive, 
since it will be generated when building with dpkg-buildpackage.
126
The version number will not have a Debian revision number (e.g. \-1)
127 128
appended to it.
.TP
129 130
.BR \-f ", " \-\-file\ \fIfile\fR
Use \fIfile\fR as the original source archive, and skip the copying of the
131 132
current program tree to program.orig.
.TP
133
.BR \-l ", " \-\-library
134 135
Automatically set the package class to Library, skipping the question.
.TP
136
.BR \-s ", " \-\-single
137 138
Automatically set the package class to Single binary, skipping the question.
.TP
139
.BR \-i ", " \-\-indep
140 141
Automatically set the package class to arch-independent binary, skipping the question.
.TP
142
.BR \-a ", " \-\-addmissing
143 144
Adds missing example and control files on an existing debian source directory.
.TP
145 146
.BR \-t ", " \-\-templates\ \fIdirectory\fR
Applies the customizing templates in \fIdirectory\fR to the debian directory.
147
.TP
148
.BR \-o ", " \-\-overlay\ \fIdirectory\fR
149 150
Applies a customization template to an existing debian directory.
.TP
151 152 153 154
.BR \-p ", " \-\-packagename\ \fIname\fR
Force the package name to be \fIname\fR, good for packages with hyphens in their
name or other strangeness. You can also make the parameter
.IR name \_ version
155 156
which will set both the package name and version and bypass and directory
checking.
157
.TP
158
.BR \-d ", " \-\-defaultless
159 160 161
Skips applying the default templates to the target debian directory. Generally
used in conjuction with either the \fB\-\-overlay\fR or \fB\-\-templates\fR
options.
162
.TP
163
.BR \-h ", " \-\-help
164 165 166
Display the name, version, available options and authors, and exit
successfully.
.TP
167
.BR \-v ", " \-\-version
168
Show the program name and version, and exit successfully.
Craig Small's avatar
Craig Small committed
169 170 171 172
.TP
.BR \-y ", " \-\-yes
Automatic yes to prompts and run non-interactively.  The package class
needs to be set for \fBdh\_make\fR to run fully automatically.
173
.SH ENVIRONMENT
csmall's avatar
csmall committed
174
The following environment settings are used by \fBdh\_make\fR:
175 176 177 178 179 180 181 182 183 184
.TP
.B DEBEMAIL
Email address to use in control and changelog entries.
.TP
.B DEBFULLNAME
You full name, eg "John Doe" which will appear in the control and changelog
entries.
.TP
.B EMAIL
Email address to use in control and changelog entries, only used if \fBDEBEMAIL\fR is no set.
185 186 187
.TP
.B LOGNAME
Default username used for looking up email and full name in other directories.
188 189 190 191 192
.SH FILES
.TP
.I /usr/share/debhelper/dh_make
Directory that contains all the template files, separated in six
directories: 
193 194
.TP
.I debian/
195
with files for all package classes,
196 197
.TP
.I debians/
198
with files specific to the Single binary class,
199 200
.TP
.I debianl/
201
with files specific to the Library class, and finally,
202 203
.TP
.I native/
204
with files specific to the native Debian packages.
205 206
.TP
.I licenses/
207
template files for the more common licenses used in Debian packages
208
.SH EXAMPLES
209 210 211 212 213 214 215 216 217 218 219
.PP
To get \fBdh\_make\fR to use the defaults and ask you various questions
about the package
.in +4n
.nf

dh_make

.fi
.in
.PP
220
Create your single class package using the with the GPL license:
221 222 223 224 225 226 227 228
.in +4n
.nf

dh_make \-s \-c gpl

.fi
.in
.PP
229 230
A more involved example where you set your name in the environment, contact \
email and license in the options and specify the upstream file:
231 232 233 234
.in +4n
.nf

DEBFULLNAME="John Doe"
235
.br
236
dh_make \-\-email contact@example.com \-\-copyright=bsd \\
237
.br
238
\ \-\-file ../foo.tar.gz 
239

240 241
.fi
.in
242 243 244
.SH BUGS
.B dh_make 
may not detect your username and email address correctly when using sudo.
245
.SH SEE ALSO
Craig Small's avatar
Craig Small committed
246
.BR dpkg (1), dpkg\-buildpackage (1), dh (1), make\-kpkg (1), debhelper (7)
247
.P
248 249 250
You may also want to read the Debian Policy (in
\fI/usr/share/doc/debian\-policy \fR) and the New Maintainers' Guide (in
\fI/usr/share/doc/maint-guide\fR).