If you are making a Debian package with an upstream program, the typical workflow of Debian package building involves generating several specifically named files for each step as follows.

Please note that the character separating package and version was changed from - (hyphen) in the tarball name to _ (underscore) in the Debian package filenames.

In the file names above, replace the package part with the package name, the version part with the upstream version, the revision part with the Debian revision, and the arch part with the package architecture, as defined in the Debian Policy Manual. ^[5]

If instead you are making a Debian-specific package with no upstream, the typical workflow of Debian package building is simpler.

Each step of this outline is explained with detailed examples in later sections.

You have probably chosen the package you want to create. The first thing you need to do is check if the package is in the distribution archive already by using the following.

If the package already exists, well, install it! :-) If it happens to be orphaned (that is, if its maintainer is set to Debian QA Group), you may be able to pick it up if it's still available. You may also adopt a package whose maintainer has filed a Request for Adoption (RFA).^[6]

There are several package ownership status resources.

As a side note, it's important to point out that Debian already has packages for most kinds of programs, and the number of packages already in the Debian archive is much larger than that of contributors with upload rights. Thus, contributions to packages already in the archive are far more appreciated (and more likely to receive sponsorship) by other developers ^[7]. You can contribute in various ways.

If you are able to adopt the package, get the sources (with something like apt-get source packagename) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable for your case.

如果你要制作的软件包是全新的，并且希望它出现在 Debian 中，请按照以下的步骤进行：

Of course, the last one is just a safety measures, and intended to save you from enraging users if you do something wrong in some setuid daemon... When you gain more experience in packaging, you'll be able to package such software.

As a new maintainer, you are encouraged to get some experience in packaging with easier packages and discouraged from creating complicated packages.

Packaging high complexity packages is not too hard, but it requires a bit more knowledge. You should seek specific guidance for every complex feature. For example, some languages have their own sub-policy documents:

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball hello-sh-1.0.tar.gz created as followings may offer a good starting point.^[8]

$ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
$ cat > hello <<EOF
#!/bin/sh
# (C) 2011 Foo Bar, GPL2+
echo "Hello!"
EOF
$ chmod 755 hello
$ cd ..
$ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

So the first thing to do is to find and download the original source code. Presumably you already have the source file that you picked up at the author's homepage. Sources for free Unix programs usually come in tar+gzip format with the extension .tar.gz, tar+bzip2 format with the extension .tar.bz2, or tar+xz format with the extension .tar.xz. These usually contain a directory called package-version with all the sources inside.

If the latest version of the source is available through a VCS such as Git, Subversion, or CVS, you need to get it with git clone, svn co, or cvs co and repack it into tar+gzip format yourself by using the --exclude-vcs option.

If your program's source comes as some other sort of archive (for instance, the filename ends in .Z or .zip^[9]), you should also unpack it with the appropriate tools and repack it.

If your program's source comes with some contents which do not comply with DFSG, you should also unpack it to remove such contents and repack it with a modified upstream version containing dfsg.

As an example, I'll use a program called gentoo, a GTK+ file manager. ^[10]

Create a subdirectory under your home directory named debian or deb or anything you find appropriate (e.g. just ~/gentoo would do fine in this case). Place the downloaded archive in it, and extract it (with tar xzf gentoo-0.9.12.tar.gz). Make sure there are no warning messages, even irrelevant ones, because other people's unpacking tools may or may not ignore these anomalies, so they may have problems unpacking them. Your shell command line may look something like this:

$ mkdir ~/gentoo ; cd ~/gentoo
$ wget http://www.example.org/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz

Now you have another subdirectory, called gentoo-0.9.12. Change to that directory and thoroughly read the provided documentation. Usually there are files named README*, INSTALL*, *.lsm or *.html. You must find instructions on how to compile and install the program (most probably they'll assume you want to install to the /usr/local/bin directory; you won't be doing that, but more on that later in 第 3.3 节 “Installation of files to their destination”).

开始打包时源代码目录应当是绝对干净(原始)的，或者直接使用刚刚解包得到的源代码。

Simple programs usually come with a Makefile and can be compiled just by invoking make.^[11] Some of them support make check, which runs included self-tests. Installation to the destination directories is usually done with make install.

现在尝试编译和运行你的程序，确保它工作正常，且在安装和运行时不会导致其他问题。

你还可以运行 make clean (或更好的 make distclean)来清理编译目录。有时还会带有 make uninstall 用以卸载已经安装了的文件。

A lot of free software programs are written in the C and C++ languages. Many of these use Autotools or CMake to make them portable across different platforms. These build tools need to be used to generate the Makefile and other required source files first. Then, such programs are built using the usual make; make install.

Autotools is the GNU build system comprising Autoconf, Automake, Libtool, and gettext. You can recognize such sources by the configure.ac, Makefile.am, and Makefile.in files. ^[12]

The first step of the Autotools workflow is usually that upstream runs autoreconf -i -f in the source directory and distributes the generated files along with the source.

configure.ac-----+-> autoreconf -+-> configure
Makefile.am -----+        |      +-> Makefile.in
src/Makefile.am -+        |      +-> src/Makefile.in
                          |      +-> config.h.in
                      automake
                      aclocal
                      aclocal.m4
                      autoheader

编辑 configure.ac 和 Makefile.am 等文件需要一些关于 autoconf 和 automake 的知识。参看 info autoconf 和 info automake。

The second step of the Autotools workflow is usually that the user obtains this distributed source and runs ./configure && make in the source directory to compile the program into an executable command binary.

Makefile.in -----+                +-> Makefile -----+-> make -> binary
src/Makefile.in -+-> ./configure -+-> src/Makefile -+
config.h.in -----+                +-> config.h -----+
                 |
  config.status -+
  config.guess --+

You can change many things in the Makefile; for instance you can change the default location for file installation using the option ./configure --prefix=/usr.

Although it is not required, updating the configure and other files with autoreconf -i -f may improve the compatibility of the source. ^[13]

CMake is an alternative build system. You can recognize such sources by the CMakeLists.txt file.

If the upstream source comes as gentoo-0.9.12.tar.gz, you can take gentoo as the (source) package name and 0.9.12 as the upstream version. These are used in the debian/changelog file described later in 第 4.3 节 “changelog”, too.

Although this simple approach works most of the times, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing ones. It is a good idea to keep its length within 30 characters. ^[14]

If upstream uses some generic term such as test-suite for its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution. ^[15]

You should choose the upstream version to consist only of alphanumerics (0-9A-Za-z), plus (+), tildes (~), and periods (.). It must start with a digit (0-9). ^[16] It is good idea to keep its length within 8 characters if possible. ^[17]

If upstream does not use a normal versioning scheme such as 2.30.32 but uses some kind of date such as 11Apr29, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as 0.1 in future, use the 0~YYMMDD format such as 0~110429 as upstream version, instead.

Version strings ^[18] can be compared using dpkg(1) as follows.

$ dpkg --compare-versions ver1 op ver2

The version comparison rule can be summarized as:

One tricky case occurs when upstream releases gentoo-0.9.12-ReleaseCandidate-99.tar.gz as the pre-release of gentoo-0.9.12.tar.gz. You need to make sure that the upgrade works properly by renaming the upstream source to gentoo-0.9.12~rc99.tar.gz.

Set up the shell environment variables $DEBEMAIL and $DEBFULLNAME so that various Debian maintenance tools recognize your email address and name to use for packages. ^[19]

$ cat >>~/.bashrc <<EOF
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

Normal Debian packages are non-native Debian packages made from upstream programs. If you wish to create a non-native Debian package of an upstream source gentoo-0.9.12.tar.gz, you can create an initial non-native Debian package for it by issuing the dh_make command as follows.

$ cd ~/gentoo
$ wget http://example.org/gentoo-0.9.12.tar.gz
$ tar -xvzf gentoo-0.9.12.tar.gz
$ cd gentoo-0.9.12
$ dh_make -f ../gentoo-0.9.12.tar.gz

Of course, replace the filename with the name of your original source archive. ^[20] See dh_make(8) for details.

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package - it creates only one binary package, i.e, one .deb file - so we will select the first option (with the s key), check the information on the screen, and confirm by pressing ENTER. ^[21]

This execution of dh_make creates a copy of the upstream tarball as gentoo_0.9.12.orig.tar.gz in the parent directory to accommodate the creation of the non-native Debian source package with the name debian.tar.gz later.

$ cd ~/gentoo ; ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
gentoo_0.9.12.orig.tar.gz

Please note two key features of this filename gentoo_0.9.12.orig.tar.gz:

You should also notice that many template files are created in the source under the debian directory. These will be explained in 第 4 章 debian 目录中的必须内容 and 第 5 章 debian 目录下的其他文件. You should also understand that packaging cannot be a fully automated process. You will need to modify the upstream source for Debian (see 第 3 章 修改源代码). After this, you need to use the proper methods for building Debian packages (第 6 章 构建软件包), testing them (第 7 章 检查软件包中的错误), and uploading them (第 8 章 上传软件包). All the steps will be explained.

如果你在修改过程中不小心删除或弄坏了某些模板文件，你可以使用 dh_make 加上 --addmissing 参数来将其还原。

Updating an existing package may get complicated since it may be using older techniques. While learning the basics, please stick to creating a fresh package; further explanations are given in 第 9 章 更新软件包.

Please note that the source file does not need to contain any build system discussed in 第 2.4 节 “Simple build systems” and 第 2.5 节 “Popular portable build systems”. It could be just a collection of graphical data etc. Installation of files may be carried out using only debhelper configuration files such as debian/install (see 第 5.11 节 “install”).

If a package contains source files you are only maintaining for Debian, possibly only for local use, it may be simpler to create it as a Debian native package. If you have source files in ~/mypackage-1.0, you can create an initial native Debian package for it by issuing the dh_make command as follows.

$ cd ~/mypackage-1.0
$ dh_make --native

Then the debian directory and its contents are created just like 第 2.8 节 “Initial non-native Debian package”. This does not create a tarball since this is a native Debian package. But that is the only difference. The rest of the packaging activities are practically the same.