This file contains various values which dpkg, dselect, apt-get, apt-cache, aptitude, and other package management tools will use to manage the package. It is defined by the Debian Policy Manual, 5 "Control files and their fields".

Here is the control file dh_make created for us:

 1 Source: gentoo
 2 Section: unknown
 3 Priority: extra
 4 Maintainer: Josip Rodin <joy-mg@debian.org>
 5 Build-Depends: debhelper (>=9)
 6 Standards-Version: 3.9.4
 7 Homepage: <insert the upstream URL, if relevant>
 8
 9 Package: gentoo
10 Architecture: any
11 Depends: ${shlibs:Depends}, ${misc:Depends}
12 Description: <insert up to 60 chars description>
13  <insert long description, indented with spaces>

(注：我爲它添加了行號。)

Lines 1-7 are the control information for the source package. Lines 9-13 are the control information for the binary package.

第 1 行是原始碼套件的名稱。

第 2 行是該源碼包要進入發行版中的分類。

As you may have noticed, the Debian archive is divided into multiple areas: main (the free software), non-free (the not really free software) and contrib (free software that depends on non-free software). Each of these is divided into sections that classify packages into rough categories. So we have admin for administrator-only programs, devel for programmer tools, doc for documentation, libs for libraries, mail for email readers and daemons, net for network apps and daemons, x11 for X11 programs that don't fit anywhere else, and many more. ^[28]

我們將本例設置爲 x11。( main/ 前綴是默認值，可以省略。)

Line 3 describes how important it is that the user installs this package. ^[29]

Section and priority are used by front-ends like aptitude when they sort packages and select defaults. Once you upload the package to Debian, the value of these two fields can be overridden by the archive maintainers, in which case you will be notified by email.

由於這是一個常規優先級的軟體，並不與其他套件衝突，我們將優先級改爲 optional。

Line 4 is the name and email address of the maintainer. Make sure that this field includes a valid To header for email, because after you upload it, the bug tracking system will use it to deliver bug emails to you. Avoid using commas, ampersands, or parentheses.

Line 5 includes the list of packages required to build your package as the Build-Depends field. You can also have the Build-Depends-Indep field as an additional line, here. ^[30] Some packages like gcc and make which are required by the build-essential package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary package dependencies to find out more about the syntax of these lines.

如果你不知道應該使用哪一個，則使用 Build-Depends 以保證安全。^[31]

要找出編譯你的軟體所需的套件可以使用這個命令：

$ dpkg-depcheck -d ./configure

To manually find exact build dependencies for /usr/bin/foo, execute

$ objdump -p /usr/bin/foo | grep NEEDED

對於列出的每個函式庫，例如 libfoo.so.6，運行：

$ dpkg -S libfoo.so.6

Then just take the -dev version of every package as a Build-Depends entry. If you use ldd for this purpose, it will report indirect lib dependencies as well, resulting in the problem of excessive build dependencies.

gentoo 需要 xlibs-dev、libgtk1.2-dev 和 libglib1.2-dev 才能編譯，所以我們將這些套件加在 debhelper 之後。

第 6 行是此套件所依據的 Debian Policy Manual 標準版本號。

On line 7 you can put the URL of the software's upstream homepage.

第 9 行是二進位套件的名稱。通常情況下與原始碼套件相同，但不是必須的。

Line 10 describes the architectures the binary package can be compiled for. This value is usually one of the following depending on the type of the binary package. ^[32]

We leave line 10 as is since this is written in C. dpkg-gencontrol(1) will fill in the appropriate architecture value for any machine this source package gets compiled on.

如果你的套件是平臺獨立的(例如一個 shell 或 Perl 腳本，或一些文件)，將這項改變爲 all，然後繼續閱讀 節 4.4, “rules” 中關於使用 binary-indep 指令替代 binary-arch 來編譯套件的內容。

第 11 行顯示了 Debian 套件系統中最強大的特性之一。每個套件都可以和其他套件有各種不同的關係。除 Depends 外，還有 Recommends、Suggests、Pre-Depends、Breaks、Conflicts、Provides 和 Replaces。

The package management tools usually behave the same way when dealing with these relations; if not, it will be explained. (See dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

Here is a simplified description of package relationships. ^[33]

所有的這些項都使用相同的語法。它們是一個套件列表，套件名稱間使用半形逗號分隔。也可以寫出有多個可選的套件名稱，這些套件使用 | 符號分隔。

The fields may restrict their applicability to particular versions of each named package. The restriction of each individual package is listed in parentheses after its name, and should contain a relation from the list below followed by a version number value. The relations allowed are: <<, <=, =, >=, and >> for strictly lower, lower or equal, exactly equal, greater or equal, and strictly greater, respectively. For example,

Depends: foo (>= 1.2), libbar1 (= 1.3.4)
Conflicts: baz
Recommends: libbaz4 (>> 4.0.7)
Suggests: quux
Replaces: quux (<< 5), quux-foo (<= 7.6)

The last feature you need to know about is ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc.

dh_shlibdeps(1) calculates shared library dependencies for binary packages. It generates a list of ELF executables and shared libraries it has found for each binary package. This list is used for substituting ${shlibs:Depends}.

dh_perl(1) calculates Perl dependencies. It generates a list of a dependencies on perl or perlapi for each binary package. This list is used for substituting ${perl:Depends}.

Some debhelper commands may cause the generated package to depend on some additional packages. All such commands generate a list of required packages for each binary package. This list is used for substituting ${misc:Depends}.

dh_gencontrol(1) generates DEBIAN/control for each binary package while substituting ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc.

Having said all that, we can leave the Depends field exactly as it is now, and insert another line after it saying Suggests: file, because gentoo can use some features provided by the file package.

Line 9 is the Homepage URL. Let's assume this to be at http://www.obsession.se/gentoo/.

Line 12 is the short description. Terminals are conventionally 80 columns wide so this shouldn't be longer than about 60 characters. I'll change it to fully GUI-configurable, two-pane X file manager.

Line 13 is where the long description goes. This should be a paragraph which gives more details about the package. Column 1 of each line should be empty. There must be no blank lines, but you can put a single . (dot) in a column to simulate that. Also, there must be no more than one blank line after the long description. ^[34]

We can insert Vcs-* fields to document the Version Control System (VCS) location between lines 6 and 7. ^[35] Let's assume that the gentoo package has its VCS located in the Debian Alioth Git Service at git://git.debian.org/git/collab-maint/gentoo.git.

到此爲止，我們做好了 control 檔案：

 1 Source: gentoo
 2 Section: x11
 3 Priority: optional
 4 Maintainer: Josip Rodin <joy-mg@debian.org>
 5 Build-Depends: debhelper (>=9), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 3.9.4
 7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
 9 Homepage: http://www.obsession.se/gentoo/
10
11 Package: gentoo
12 Architecture: any
13 Depends: ${shlibs:Depends}, ${misc:Depends}
14 Suggests: file
15 Description: fully GUI-configurable, two-pane X file manager
16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
17  user do (almost) all of the configuration and customizing from within the
18  program itself. If you still prefer to hand-edit configuration files,
19  they're fairly easy to work with since they are written in an XML format.
20  .
21  gentoo features a fairly complex and powerful file identification system,
22  coupled to an object-oriented style system, which together give you a lot
23  of control over how files of different types are displayed and acted upon.
24  Additionally, over a hundred pixmap images are available for use in file
25  type descriptions.
26  .
29  gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
30  for its interface.

(注：我爲它添加了行號。)

This file contains information about the copyright and license of the upstream sources. Debian Policy Manual, 12.5 "Copyright information" dictates its content and DEP-5: Machine-parseable debian/copyright provides guidelines for its format.

dh_make 可以給出一個 copyright 檔案的模板。在這裏我們使用 --copyright gpl2 參數來獲得一個模板寫明 gentoo 套件是發佈於 GPL-2 許可證下。

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, or the Artistic license), you can just refer to the appropriate file in the /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.

In short, here's what gentoo's copyright file should look like:

 1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
 2 Name: gentoo
 3 Maintainer: Josip Rodin <joy-mg@debian.org>
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
 7 License: GPL-2+
 8
 9 Files: icons/*
10 Copyright: 1998 Johan Hanson <johan@tiq.com>
11 License: GPL-2+
12
13 Files: debian/*
14 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
15 License: GPL-2+
16
17 License: GPL-2+
18  This program is free software; you can redistribute it and/or modify
19  it under the terms of the GNU General Public License as published by
20  the Free Software Foundation; either version 2 of the License, or
21  (at your option) any later version. 
22  .
23  This program is distributed in the hope that it will be useful,
24  but WITHOUT ANY WARRANTY; without even the implied warranty of
25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26  GNU General Public License for more details.
27  .
28  You should have received a copy of the GNU General Public License along
29  with this program; if not, write to the Free Software Foundation, Inc.,
30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
31  .
32  On Debian systems, the full text of the GNU General Public
33  License version 2 can be found in the file
34  `/usr/share/common-licenses/GPL-2'.

(注：我爲它添加了行號。)

Please follow the HOWTO provided by the ftpmasters and sent to debian-devel-announce: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

This is a required file, which has a special format described in Debian Policy Manual, 4.4 "debian/changelog". This format is used by dpkg and other programs to obtain the version number, revision, distribution, and urgency of your package.

對於你而言，詳細描述你所做出的更改也是很好且很重要的。它將幫助下載你的套件的人瞭解這個套件中是否有他們需要知道的事情。它會被作爲 /usr/share/doc/gentoo/changelog.Debian.gz 保存在二進位套件中。

dh_make created a default one, and this is what it looks like:

1  gentoo (0.9.12-1) unstable; urgency=low
2
3   * Initial release (Closes: #nnnn)  <nnnn is the bug number of your ITP>
4
5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
6

(注：我爲它添加了行號。)

Line 1 is the package name, version, distribution, and urgency. The name must match the source package name; distribution should be unstable, and urgency shouldn't be changed to anything higher than low. :-)

Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes - there is a special file for that purpose, created by the upstream authors, which you will later install as /usr/share/doc/gentoo/changelog.gz). Let's assume your ITP (Intent To Package) bug report number was 12345. New lines must be inserted just below the uppermost line that begins with * (asterisk). You can do it with dch(1), or manually with a text editor.

In order to prevent a package being accidentally uploaded before completing the package, it is good idea to change the distribution value to an invalid distribution value UNRELEASED.

最後它會成爲以下的樣子：

1  gentoo (0.9.12-1) UNRELEASED; urgency=low
2
3   * Initial Release. Closes: #12345
4   * This is my first Debian package.
5   * Adjusted the Makefile to fix $(DESTDIR) problems.
6
7  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
8

(注：我爲它添加了行號。)

Once you are satisfied with all the changes and documented them in changelog, you should change the distribution value from UNRELEASED to the target distribution value unstable (or even experimental). ^[36]

你可以在關於更新的 章 9, 更新套件 中瞭解更多關於 changelog 的內容。

Now we need to take a look at the exact rules which dpkg-buildpackage(1) will use to actually create the package. This file is in fact another Makefile, but different from the one(s) in the upstream source. Unlike other files in debian, this one is marked as executable.

 1 #!/usr/bin/make -f
 2 # -*- makefile -*-
 3 # Sample debian/rules that uses debhelper.
 4 # This file was originally written by Joey Hess and Craig Small.
 5 # As a special exception, when this file is copied by dh-make into a
 6 # dh-make output file, you may use that output file without restriction.
 7 # This special exception was added by Craig Small in version 0.37 of dh-make.
 8
 9 # Uncomment this to turn on verbose mode.
10 #export DH_VERBOSE=1
11
12 %:
13        dh $@

override_dh_auto_configure:
        dh_auto_configure -- --sysconfig=/etc/gentoo

override_dh_auto_build:
        dh_auto_build -- build

override_dh_auto_clean:
        $(MAKE) packageclean

override_dh_auto_test:

override_dh_installchangelogs:
        dh_installchangelogs FIXES