1
=== modified file 'debian/changelog'
2
--- debian/changelog	2009-04-18 08:45:33 +0000
3
+++ debian/changelog	2009-04-19 01:26:05 +0000
4
@@ -1,4 +1,4 @@
6
1
ubuntu-docs (9.10.1) karmic; urgency=low
1
ubuntu-docs (9.10.1) UNRELEASED; urgency=low
7
2
2
8
3
  * [Matthew East]
3
  * [Matthew East]
9
4
    - First release for Karmic
4
    - First release for Karmic
10
@@ -7,8 +7,9 @@
11
7
    - hardware.xml - computer-janitor updates
7
    - hardware.xml - computer-janitor updates
12
8
  * [Bhuvaneswaran A] - improvements to exim section in serverguide/mail
8
  * [Bhuvaneswaran A] - improvements to exim section in serverguide/mail
13
9
  * [Dean Sas] - typo fix in serverguide/jeos
9
  * [Dean Sas] - typo fix in serverguide/jeos
14
10
  * [Nathan Handler] Add packaging guide
15
10
11
17
11
 -- Matthew East <mdke@ubuntu.com>  Sat, 04 Apr 2009 11:00:21 +0100
12
 -- Nathan Handler <nhandler@ubuntu.com>  Sat, 11 Apr 2009 19:53:21 -0500
18
12
13
19
13
ubuntu-docs (9.04.9) jaunty; urgency=low
14
ubuntu-docs (9.04.9) jaunty; urgency=low
20
14
15
21
15
16
22
=== modified file 'libs/shipped-docs'
23
--- libs/shipped-docs	2008-04-05 09:58:36 +0000
24
+++ libs/shipped-docs	2009-04-11 13:27:11 +0000
25
@@ -13,6 +13,7 @@
26
13
musicvideophotos
13
musicvideophotos
27
14
newtoubuntu
14
newtoubuntu
28
15
office
15
office
29
16
packaging
30
16
printing
17
printing
31
17
programming
18
programming
32
18
serverguide
19
serverguide
33
19
20
34
=== added directory 'packaging'
35
=== added directory 'packaging/C'
36
=== added file 'packaging/C/packaging-C.omf'
37
--- packaging/C/packaging-C.omf	1970-01-01 00:00:00 +0000
38
+++ packaging/C/packaging-C.omf	2009-04-11 13:27:11 +0000
39
@@ -0,0 +1,18 @@
40
1
<?xml version="1.0" encoding="UTF-8"?>
41
2
<!DOCTYPE omf PUBLIC "-//OMF//DTD Scrollkeeper OMF Variant V1.0"
42
3
    "http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd">
43
4
<omf>
44
5
  <resource>
45
6
    <creator>nhandler@ubuntu.com (Nathan Handler)</creator>
46
7
    <maintainer>nhandler@ubuntu.com (Nathan Handler)</maintainer>
47
8
    <title>Packaging Guide</title>
48
9
    <date>2009-04-07</date>
49
10
    <subject category="General|Linux|Distributions|Other"/>
50
11
    <description>Placeholder.</description>
51
12
    <format mime="text/xml" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
52
13
    <identifier url="file:///usr/share/gnome/help/packaging/C/packaging.xml"/>
53
14
    <language code="C"/>
54
15
    <relation seriesid="4a717632-6242-11dc-9237-cb4d9da61949"/>
55
16
    <rights type="CC-by-SA" license.version="2.5" holder="Canonical Ltd."/>
56
17
  </resource>
57
18
</omf>
58
0
19
59
=== added file 'packaging/C/packaging.xml'
60
--- packaging/C/packaging.xml	1970-01-01 00:00:00 +0000
61
+++ packaging/C/packaging.xml	2009-04-12 00:14:42 +0000
62
@@ -0,0 +1,1752 @@
63
1
<?xml version="1.0" encoding="UTF-8"?>
64
2
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
65
3
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
66
4
<!ENTITY % globalent SYSTEM "../../libs/global.ent">
67
5
%globalent;
68
6
<!ENTITY % gnome-menus-C SYSTEM "../../libs/gnome-menus-C.ent">
69
7
%gnome-menus-C;
70
8
<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">
71
9
%xinclude;
72
10
<!ENTITY language "en">
73
11
<!ENTITY ubuntu '<phrase>Ubuntu</phrase>'>
74
12
]>
75
13
76
14
<article id="packaging" status="review">
77
15
<articleinfo>
78
16
	<title>Packaging Guide/Complete</title>
79
17
	&legalnotice;
80
18
	</articleinfo>
81
19
	<para>This section contains information to help you get started creating your own Ubuntu packages.</para>
82
20
83
21
	<sect1 id="introduction" status="review">
84
22
		<title>Introduction</title>
85
23
		<para>Welcome to the Ubuntu Packaging Guide! This guide is primarily addressed to those who would like to make and maintain Ubuntu packages. Although many of the concepts in this guide could be used to make binary packages for personal use, it is designed for those people wanting to distribute their packages to and for others. While it is also written with the Ubuntu Linux distribution in mind, it should also be useful for any Debian-based distribution.
86
24
87
25
There are several reasons you might want to learn how to package for Ubuntu. First, building and fixing Ubuntu packages is a great way to contribute to the Ubuntu community. It is also a good way to learn how Ubuntu and the applications you have installed work. Maybe you want to install a package that is not in the Ubuntu repositories. Hopefully after you have completed this guide you will have the tools and knowledge you need to do all of these things.</para>
88
26
		<sect2 id="where-begin" status="review">
89
27
                	<title>Where to Begin</title>
90
28
                	<para>If you are completely new to Debian-based packaging then you will want to read this guide completely through, paying special attention to the section called <link linkend="prerequisites">Prerequisites</link>, and the section <link linkend="basic-packaging">Basic Packaging</link>. People who are experienced with Debian-based packaging will find section <ulink url="https://wiki.ubuntu.com/PackagingGuide/Ubuntu">Ubuntu Packaging</ulink> and section Bugs most helpful.</para>
91
29
		</sect2>
92
30
93
31
		<sect2 id="prerequisites" status="review">
94
32
                	<title>Prerequisites</title>
95
33
                	<para>This guide assumes that the reader has a reasonable knowledge of building and installing software from source on Linux distributions. The guide also uses the Command Line Interface (CLI) throughout, so you should be comfortable using a terminal. You should be able to at least use the following:</para>
96
34
			<itemizedlist>
97
35
				<listitem><para><emphasis role="bold">make:</emphasis> GNU Make is a very important software building tool. It is used to transform a complex compilation task into a trivial one. It is important that you know how to use it, because we will store most of the information about the packaging process in a Makefile. Documentation is available at the <ulink url="http://www.gnu.org/software/make/manual/make.html">GNU</ulink> website.</para></listitem>
98
36
				<listitem><para><emphasis role="bold">./configure:</emphasis> This script is included in almost all Linux source, especially for software written in compiled languages such as C and C++. It is used to generate a Makefile (file used by make) that is properly configured for your system. Standard Debian packaging tools use it, so it is important that you know what the configure script does. Information on ./configure can be found in the make documentation.</para></listitem>
99
37
				<listitem><para><emphasis role="bold">Apt/Dpkg:</emphasis> Beyond the basic use of installing programs, apt and dpkg have many features that are useful for packaging.
100
38
				<itemizedlist>
101
39
					<listitem><para><emphasis role="bold">apt-cache dump</emphasis> - lists every package in the cache. This command is especially helpful in combination with a grep pipe such as apt-cache dump | grep foo to search for packages whose names or dependencies include foo.</para></listitem>
102
40
					<listitem><para><emphasis role="bold">apt-cache policy</emphasis> - lists the repositories (main/restricted/universe/multiverse) in which a package exists.</para></listitem>
103
41
					<listitem><para><emphasis role="bold">apt-cache show</emphasis> - displays information about a binary package.</para></listitem>
104
42
					<listitem><para><emphasis role="bold">apt-cache showsrc</emphasis> - displays information about a source package.</para></listitem>
105
43
					<listitem><para><emphasis role="bold">apt-cache rdepends</emphasis> - shows reverse dependencies for a package (which packages require the queried one.</para></listitem>
106
44
					<listitem><para><emphasis role="bold">dpkg -S</emphasis> - lists the binary package to which a particular file belongs.</para></listitem>
107
45
					<listitem><para><emphasis role="bold">dpkg -l</emphasis> - lists currently installed packages. This is similar to apt-cache dump but for installed packages.</para></listitem>
108
46
					<listitem><para><emphasis role="bold">dpkg -c</emphasis> - lists the contents of a binary package. It is useful for ensuring that files are installed to the right places.</para></listitem>
109
47
					<listitem><para><emphasis role="bold">dpkg -f</emphasis> - shows the control file for a binary package. It is useful for ensuring that the dependencies are correct.</para></listitem>
110
48
					<listitem><para><emphasis role="bold">grep-dctrl</emphasis> - searches for specialized information in packages. It is a specific use of the grep package (but not installed by default).</para></listitem>
111
49
				</itemizedlist>
112
50
				</para></listitem>
113
51
				<listitem><para><emphasis role="bold">diff</emphasis> and <emphasis role="bold">patch:</emphasis>
114
52
				<itemizedlist>
115
53
                        		<listitem><para>The diff program can be used to compare two files and to make patches. A typical example might be diff -ruN file.old file.new > file.diff. This command will create a diff (recursively if directories are used) that shows the changes, or delta, between the two files.</para></listitem>
116
54
					<listitem><para>The patch program is used to apply a patch (usually created by diff or another similar program) to a file or directory. To apply the patch created above, we can invoke patch -p0 &lt; file.diff. The option -p tells patch how much it should strip from the paths for the file names in the patch. The option -p0 means to strip nothing, or leave the path intact.</para></listitem>
117
55
				</itemizedlist>
118
56
				</para></listitem>
119
57
			</itemizedlist>
120
58
		</sect2>
121
59
	</sect1>
122
60
			
123
61
	<sect1 id="getting-started" status="review">
124
62
		<title>Getting Started</title>
125
63
		<sect2 id="binary-source-packages" status="review">
126
64
			<title>Binary and Source Packages</title>
127
65
			<para>Most users of a Debian-based distribution such as Ubuntu will never have to deal with the actual source code that is used to create all of the applications on their computers. Instead, the source code is compiled into binary packages from the source package that contains both the source code itself and the rules for making the binary package. Package maintainers upload the source packages with their changes to the build systems that then compile the binary packages for each architecture. A separate system distributes the generated binary .deb files and source changes to the repository mirrors.</para>
128
66
		</sect2>
129
67
		
130
68
		<sect2 id="packaging-tools" status="review">
131
69
			<title>Packaging Tools</title>
132
70
			<para>There are many tools written specifically for packaging on Debian-based systems. Many of them are not essential to creating packages but are very helpful and often automate repetitive tasks. Their man and info pages are good sources of information. However, the following is a list of packages that are deemed necessary to begin packaging:</para>
133
71
			<itemizedlist>
134
72
				<listitem><para><emphasis role="bold">build-essential</emphasis> is a metapackage that depends on libc6-dev, gcc, g++, make, and dpkg-dev. One package that you might not be familiar with is dpkg-dev. It contains tools such as dpkg-buildpackage and dpkg-source that are used to create, unpack, and build source and binary packages.</para></listitem>
135
73
				<listitem><para><emphasis role="bold">devscripts</emphasis> contains many scripts that make the packager's maintenance work much easier. Some of the more commonly used are debdiff, dch, debuild, and debsign.</para></listitem>
136
74
				<listitem><para><emphasis role="bold">ubuntu-dev-tools</emphasis> is also a collection of scripts (like devscripts), but specific for Ubuntu. It contains tools like update-maintainer, dgetlp, what-patch, pbuilder-dist, etc.</para></listitem>
137
75
				<listitem><para><emphasis role="bold">debhelper</emphasis> are scripts that perform common packaging tasks.</para></listitem>
138
76
				<listitem><para><emphasis role="bold">dh-make</emphasis> can be used to create a template for your packaging.</para></listitem>
139
77
				<listitem><para><emphasis role="bold">diff</emphasis> and <emphasis role="bold">patch</emphasis> are used to create and apply patches, respectively. They are used extensively in packaging because it is easier, cleaner, and more efficient to represent small changes as patches rather than to have multiple copies of a file.</para></listitem>
140
78
				<listitem><para><emphasis role="bold">quilt</emphasis> manages a series of patches by keeping track of the changes each of them makes. They are logically organized as a stack, and you can apply, un-apply, refresh them easily by traveling into the stack (push/pop). This package completely integrates into the CDBS, allowing maintainers using this new paradigm for their packaging scripts to benefit from the comfort of quilt when editing their diff against upstream. The package also provides some basic support for those not using CDBS.</para></listitem>
141
79
				<listitem><para><emphasis role="bold">gnupg</emphasis> is a complete and free replacement for PGP used to digitally sign files (including packages).</para></listitem>
142
80
				<listitem><para><emphasis role="bold">lintian</emphasis> and <emphasis role="bold">linda</emphasis> dissect Debian packages and report bugs and Policy violations. They contain automated checks for many aspects of Debian Policy as well as for common errors. <emphasis role="bold">linda</emphasis> is not available from the <emphasis role="bold">hardy heron</emphasis> repositories, but is still available in previous releases repositories.</para></listitem>
143
81
				<listitem><para><emphasis role="bold">pbuilder</emphasis> constructs a chroot system and builds a package inside the chroot. It is an ideal system to use to check that a package has correct build dependencies and to build clean packages to be tested and distributed.</para></listitem>
144
82
			</itemizedlist>
145
83
		</sect2>
146
84
		<sect2 id="personal-builder-pbuilder" status="review">
147
85
			<title>The Personal Builder: pbuilder</title>
148
86
			<para>Using pbuilder as a package builder allows you to build the package from within a chroot environment. You can build binary packages without using pbuilder, but you must have all the build dependencies installed on your system first. However, pbuilder allows the packager to check the build dependencies because the package is built within a minimal Ubuntu installation, and the build dependencies are downloaded according to the debian/control file.</para>
149
87
			<para><ulink url="https://wiki.ubuntu.com/PbuilderHowto">PbuilderHowto</ulink> is a comprehensive guide to almost anything you could wish to do with pbuilder.</para>
150
88
			<para>A short overview:</para>
151
89
			<itemizedlist>
152
90
				<listitem><para>to create a pbuilder environment, run</para>
153
91
					  <screen><command>sudo pbuilder create --distribution &lt;ubuntu_version&gt; \
154
92
--othermirror "deb http://archive.ubuntu.com/ubuntu &lt;ubuntu_version&gt; main restricted \
155
93
universe multiverse"</command></screen>
156
94
				</listitem>
157
95
				<listitem><para>to build a package using pbuilder, run</para>
158
96
					  <screen><command>sudo pbuilder build *.dsc</command></screen>
159
97
				</listitem>
160
98
				<listitem><para>to update a pbuilder environment, run</para>
161
99
					  <screen><command>sudo pbuilder update</command></screen>
162
100
				</listitem>
163
101
				<listitem><para>use pbuilder-dist (of the ubuntu-dev-tools) to have several different pbuilder setups for different Ubuntu releases.</para></listitem>
164
102
			</itemizedlist>
165
103
		</sect2>
166
104
	</sect1>
167
105
	
168
106
	<sect1 id="basic-packaging" status="review">
169
107
		<title>Basic Packaging</title>
170
108
		<para>Two of the problems that many novice packagers face are that there are multiple ways of packaging, and there is more than one tool to do the job.</para>
171
109
		<para>Package development often requires installing many packages (especially -dev packages containing headers and other common development files) that are not part of a normal desktop Ubuntu installation. If you want to avoid installing extra packages or would like to develop for a different Ubuntu release (the development one, for instance) from what you currently have, the use of a chroot environment is highly recommended. A guide to setting up a chroot can be found at <ulink url="https://wiki.ubuntu.com/DebootstrapChroot">DebootstrapChroot</ulink>.</para>
172
110
		<para>We will go through two examples with the common build systems. We will use debhelper, the most common build system in Debian. It helps the packager by automating repetitive tasks. Then we will briefly cover the <emphasis role="bold">C</emphasis>ommon <emphasis role="bold">D</emphasis>ebian <emphasis role="bold">B</emphasis>uild <emphasis role="bold">S</emphasis>ystem (CDBS), a more streamlined build system that uses debhelper.</para>
173
111
			<sect2 id="packaging-from-scratch" status="review">
174
112
				<title>Packaging From Scratch</title>
175
113
				<para><emphasis role="italics">Requirements:</emphasis> build-essential, automake, gnupg, lintian, fakeroot, pbuilder, debhelper and dh-make. In this example we will be using the GNU hello program as our example. You can download the source tarball from <ulink url="http://ftp.gnu.org/gnu/hello/hello-2.1.1.tar.gz">ftp.gnu.org</ulink>. For the purposes of this example, we will be using the ~/hello/ directory.</para>
176
114
				<screen><command>mkdir ~/hello
177
115
cd ~/hello
178
116
wget http://ftp.gnu.org/gnu/hello/hello-2.1.1.tar.gz
179
117
</command></screen>
180
118
				<para>If you are packaging your own software, or the software is not available as a tar.gz file, you can create the required .tar.gz from an unpacked source directory with a command like the following: </para>
181
119
				<screen><command>tar czf hello-2.1.1.tar.gz hello-2.1.1</command></screen>
182
120
				<para>For the purpose of this example, we will also compare our package (hello) to one that is already packaged in the Ubuntu repository (called hello-debhelper). For now, we will place it in the ubuntu directory so we can look at it later. To get the source package, make sure you have a "deb-src" line in your /etc/apt/sources.list file for the Main repository. Then, simply execute: </para>
183
121
				<screen><command>mkdir ubuntu
184
122
cd ubuntu
185
123
apt-get source hello-debhelper
186
124
cd ..
187
125
</command></screen>
188
126
				<para>Unlike most apt-get commands, you do not need to have root privileges to get the source package, because it is downloaded to the current directory. In fact, it is recommended that you only use apt-get source as a regular user, because then you can edit files in the source package without needing root privileges. What the apt-get source command does is:</para>
189
127
				<orderedlist>
190
128
					<listitem><para>Download the source package. A source package commonly contains a .dsc file describing the package and giving md5sums for the source package, an .orig.tar.gz file containing the source code from the author(s), and a .diff.gz file containing the packaging (in the debian/ directory) and patches applied against the source code.</para></listitem>
191
129
					<listitem><para>Untar the .orig.tar.gz file into the current directory.</para></listitem>
192
130
					<listitem><para>Apply the unzipped .diff.gz to the unpacked source directory.</para></listitem>
193
131
				</orderedlist>
194
132
				<para>If you manually download the source package (.dsc, .orig.tar.gz, and .diff.gz files), you can unpack them in the same way apt-get source does by using dpkg-source as follows:</para>
195
133
				<screen><command>dpkg-source -x *.dsc</command></screen>
196
134
				<para>We want to recreate the above from scratch. The first thing you will need to do is make a copy of the original (sometimes called "upstream") tarball in the following format: &lt;packagename&gt;_&lt;version&gt;.orig.tar.gz. This step does two things. First, it creates two copies of the source code. If you accidentally change or delete the working copy you can use the one you downloaded. Second, it is considered poor packaging practice to change the original source tarball unless absolutely necessary. See the section called “Common Mistakes” for reasons.</para>
197
135
				<screen><command>cp hello-2.1.1.tar.gz hello_2.1.1.orig.tar.gz
198
136
tar -xzvf hello_2.1.1.orig.tar.gz
199
137
</command></screen>		<para>The underscore, "_", between the package name (hello) and the version (2.1.1), as opposed to a hyphen, "-", is very important. The packaging tools will look for a file with that exact name. If you get it wrong, the result is that the tools will incorrectly assume that there is no original source at all and the package will be built as a Debian native package.</para>
200
138
				<para>We now have a hello-2.1.1 directory containing the source files. Now we need to create the customary debian directory where all the packaging information is stored, allowing us to separate the packaging files from the application source files. We will let dh_make do the work for us:</para>
201
139
				<screen><command>cd hello-2.1.1
202
140
dh_make -e your.maintainer@address
203
141
</command></screen>
204
142
				<para>dh_make will then ask you a series of questions about your package:</para>
205
143
				<programlisting>Type of package: single binary, multiple binary, library, kernel module or cdbs?
206
144
[s/m/l/k/b] s
207
145
</programlisting>
208
146
				<programlisting>Maintainer name : Your Name
209
147
Email-Address   : your.maintainer@address
210
148
Date            : Thu,  6 Apr 2006 10:07:19 -0700
211
149
Package Name    : hello
212
150
Version         : 2.1.1
213
151
License         : blank
214
152
Type of Package : Single
215
153
Hit &lt;enter&gt; to confirm: Enter
216
154
</programlisting>
217
155
				<para>Only run dh_make once. If you run it again after you do it the first time, it will not work properly. If you want to change it or made a mistake, remove the source directory and untar the upstream tarball afresh. Then you can migrate into the source directory and try again.</para>
218
156
				<para>Running dh_make creates the basic files needed in debian/ and many template files (.ex) that may be needed. The Hello program is not very complicated, and as we have seen in the section called “Packaging From Scratch”, packaging it does not require much more than the basic files. Therefore, let us remove the .ex files:</para>
219
157
				<screen><command>cd debian
220
158
rm *.ex *.EX
221
159
</command></screen>
222
160
				<para>For hello, you will also not need some of the files into the debian directory:</para>
223
161
				<itemizedlist>
224
162
					<listitem><para>README.Debian: the README file for specific Debian issues, not the program's README.</para></listitem>
225
163
					<listitem><para>dirs: Used by dh_installdirs to create needed directories.</para></listitem>
226
164
					<listitem><para>docs: Used by dh_installdocs to install program documentation.</para></listitem>
227
165
					<listitem><para>info: Used by dh_installinfo to install the info file.</para></listitem>
228
166
				</itemizedlist>
229
167
				<para>Keep in mind that for most packages, these files are required. For more information on them, see the section called “dh_make example files”.</para>
230
168
				<para>At this point, you should have only changelog, compat, control, copyright, and rules files in the debian directory.</para>
231
169
				<sect3 id="changelog" status="review">
232
170
					<title>changelog</title>
233
171
					<para>The changelog file is, as its name implies, a listing of the changes made in each version. It has a specific format that gives the package name, version, distribution, changes, and who made the changes at a given time. If you have a GPG key, make sure to use the same name and email address in changelog as you have in your key. The following is a template changelog:</para>
234
172
					<programlisting>package (version) distribution; urgency=urgency
235
173
236
174
  * change details
237
175
    more change details
238
176
  * even more change details
239
177
240
178
 -- maintainer name &lt;email address&gt;[two spaces]  date
241
179
</programlisting>
242
180
					<para>The format (especially of the date) is important. The date should be in RFC822 format, which can be obtained by using the command <emphasis role="bold">date -R</emphasis>. For convenience, the command dch may be used to edit changelog. It will update the date automatically.</para>
243
181
					<para>Minor bullet points are indicated by a dash "-", while major points use an asterisk "*".</para>
244
182
					<para>Here is a sample changelog file for hello:</para>
245
183
					<programlisting>hello (2.1.1-0ubuntu1) jaunty; urgency=low
246
184
247
185
   * New upstream release with lots of bug fixes.
248
186
249
187
 -- Captain Packager &lt;packager@coolness.com&gt;  Wed,  5 Jan 2009 22:38:49 -0700
250
188
</programlisting>
251
189
					<para>Notice that the version has a -0ubuntu1 appended to it, this is the distro revision, used so that the packaging can be updated (to fix bugs for example) with new uploads within the same source release version.</para>
252
190
					<para>Ubuntu and Debian have slightly different package versioning schemes to avoid conflicting packages with the same source version. If a Debian package has been changed in Ubuntu, it has ubuntuX (where X is the Ubuntu revision number) appended to the end of the Debian version. So if the Debian hello 2.1.1-1 package was changed by Ubuntu, the version string would be 2.1.1-1ubuntu1. If a package for the application does not exist in Debian, then the Debian revision is 0 (e.g., 2.1.1-0ubuntu1).</para>
253
191
					<para>Now look at the changelog for the <emphasis role="italics">Ubuntu</emphasis> source package that we downloaded earlier:</para>
254
192
					<screen><command>less ../../ubuntu/hello-debhelper-2.2/debian/changelog</command></screen>
255
193
					<para>Notice that in this case the <emphasis role="italics">distribution is unstable</emphasis> (a Debian branch), because the Debian package has not been changed by Ubuntu. Remember to set the <emphasis role="italics">distribution</emphasis> to your target distribution release.</para>
256
194
					<para>Consult <ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog">Debian changelog Policy</ulink> for more information.</para>
257
195
				</sect3>
258
196
				<sect3 id="control" status="review">
259
197
					<title>control</title>
260
198
					<para>The control file contains the information that the package manager (such as apt-get, synaptic, and adept) uses, build-time dependencies, maintainer information, and much more.</para>
261
199
					<para>For the Ubuntu hello package, the control file looks something like:</para>
262
200
					<programlisting>Source: hello
263
201
Section: devel
264
202
Priority: optional
265
203
Maintainer: Ubuntu MOTU Developers &lt;ubuntu-motu@lists.ubuntu.com&gt;
266
204
XSBC-Original-Maintainer: Captain Packager &lt;packager@coolness.com&gt;
267
205
Standards-Version: 3.7.3
268
206
Build-Depends: debhelper (&gt;= 5)
269
207
Homepage: http://www.gnu.org/software/hello/
270
208
271
209
Package: hello
272
210
Architecture: any
273
211
Depends: ${shlibs:Depends}
274
212
Description: The classic greeting, and a good example
275
213
 The GNU hello program produces a familiar, friendly greeting. It
276
214
 allows non-programmers to use a classic computer science tool which
277
215
 would otherwise be unavailable to them. . Seriously, though: this is
278
216
 an example of how to do a Debian package. It is the Debian version of
279
217
 the GNU Project's `hello world' program (which is itself an example
280
218
 for the GNU Project).
281
219
</programlisting>
282
220
					<para>In Ubuntu we set the Maintainer field to a general address because anyone can change any package (this differs from Debian where changing packages is usually restricted to an individual or a team).</para>
283
221
					<para>Edit control using the information above (making sure to provide your information for the XSBC-Original-Maintainer field).</para>
284
222
					<para>The first paragraph gives information about the source package. Let us go through each line:</para>
285
223
					<itemizedlist>
286
224
						<listitem><para><emphasis role="bold">Source:</emphasis> This is the name of the source package.</para></listitem>
287
225
						<listitem><para><emphasis role="bold">Section:</emphasis> The apt repositories are split up into sections for ease of browsing and categorization of software.</para></listitem>
288
226
						<listitem><para><emphasis role="bold">Priority:</emphasis>This sets the importance of the package to users. It should be one of the following:</para>
289
227
							<itemizedlist>
290
228
								<listitem><para><emphasis role="bold">Required</emphasis>- packages that are essential for the system to work properly. If they are removed it is highly likely that your system will break in an unrecoverable way.</para></listitem>
291
229
								<listitem><para><emphasis role="bold">Important</emphasis> - minimal set of packages for a usable system. Removing these packages will not produce an unrecoverable breakage of your system, but they are generally considered important tools without which any Linux installation would be incomplete. Note: This does not include things like Emacs or even the X Window System.</para></listitem>
292
230
								<listitem><para><emphasis role="bold">Standard</emphasis> - Somewhat self explanatory.</para></listitem>
293
231
								<listitem><para><emphasis role="bold">Optional</emphasis>- in essence this category is for non-required packages, or the bulk of packages. However, these packages should not conflict with each other.</para></listitem>
294
232
								<listitem><para><emphasis role="bold">Extra</emphasis> - packages that may conflict with packages in one of the above categories. Also used for specialized packages that would only be useful to people who already know the purpose of the package.</para></listitem>
295
233
							</itemizedlist>
296
234
						</listitem>
297
235
						<listitem><para><emphasis role="bold">Maintainer:</emphasis> The name of the package maintainer and their email address.</para></listitem>
298
236
						<listitem><para><emphasis role="bold">Standards-Version:</emphasis> The version of the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink> to which the package adheres. An easy way to find the current version is apt-cache show debian-policy | grep Version .</para></listitem>
299
237
						<listitem><para><emphasis role="bold">Build-Depends:</emphasis> One of the most important fields and often the source of bugs, this line lists the binary packages (with versions if necessary) that need to be installed in order to create the binary package(s) from the source package. Packages that are essential are required by build-essential and do not need to be included in the Build-Depends line. Note, that you don't need to list packages that are a part of build-essential. The list of build-essential packages can be found at /usr/share/doc/build-essential/list.</para></listitem>
300
238
						<listitem><para><emphasis role="bold">Homepage:</emphasis> A URL where more information on the software can be found.</para></listitem>
301
239
					</itemizedlist>
302
240
					<para>The second paragraph is for the binary package that will be built from the source. If multiple binary packages are built from the source package, there should be one section for each one. Again, let us go through each line:</para>
303
241
					<itemizedlist>
304
242
						<listitem><para><emphasis role="bold">Package:</emphasis> The name for the binary package. Many times for simple programs (such as hello), the source and binary packages' names are identical.</para></listitem>
305
243
						<listitem><para><emphasis role="bold">Architecture:</emphasis> The architectures for which the binary package(s) will be built. Examples are:</para>
306
244
							<itemizedlist>
307
245
								<listitem><para><emphasis role="bold">all</emphasis> - The source is not architecture-dependent. Programs that use Python or other interpreted languages would use this. The resulting binary package would end with _all.deb.</para></listitem>
308
246
								<listitem><para><emphasis role="bold">any</emphasis> - The source is architecture-dependent and should compile on all the supported architectures. There will be a .deb file for each architecture (_i386.deb for instance)</para></listitem>
309
247
								<listitem><para>A subset of architectures (i386, amd64, ppc, etc.) can be listed to indicate that the source is architecture-dependent and does not work for all architectures supported by Ubuntu.</para></listitem>
310
248
							</itemizedlist>
311
249
						</listitem>
312
250
						<listitem><para><emphasis role="bold">Depends:</emphasis> The list of packages that the binary package depends on for functionality. For hello, we see ${shlibs:Depends}, which is a variable that is used by dpkg-shlibdeps to add the shared library packages needed by the binaries to <emphasis role="bold">Depends:</emphasis>. See the dpkg-source(1) and dpkg-shlibdeps(1) man page for more information.</para></listitem>
313
251
						<listitem><para><emphasis role="bold">Recommends:</emphasis> Used for packages that are highly recommended and usually are installed with the package. Some package managers, most notably aptitude, automatically install Recommended packages.</para></listitem>
314
252
						<listitem><para><emphasis role="bold">Suggests:</emphasis> Used for packages that are similar or useful when this package is installed.</para></listitem>
315
253
						<listitem><para><emphasis role="bold">Conflicts:</emphasis> Used for packages that will conflict with this package. Both cannot be installed at the same time. If one is being installed, the other will be removed.</para></listitem>
316
254
						<listitem><para><emphasis role="bold">Description:</emphasis> Both short and long descriptions are used by package managers. Note that there is one space at the beginning of each line in the long description. More information on how to make a good description can be found at <ulink url="http://people.debian.org/~walters/descriptions.html">http://people.debian.org/~walters/descriptions.html</ulink></para></listitem>
317
255
					</itemizedlist>
318
256
				</sect3>
319
257
				<sect3 id="copyright" status="review">
320
258
					<title>copyright</title>
321
259
					<para>This file gives the copyright information. Generally, copyright information is found in the COPYING file in the program's source directory. This file should include such information as the names of the author and the packager, the URL from which the source came, a Copyright line with the year and copyright holder, and the text of the copyright itself. An example template would be:</para>
322
260
					<programlisting>This package was debianized by {Your Name} &lt;your email address&gt;
323
261
{Date}
324
262
325
263
It was downloaded from: {URL of webpage} 
326
264
327
265
Upstream Author(s): {Name(s) and email address(es) of author(s)}
328
266
329
267
Copyright:
330
268
        Copyright (C) {Year(s)} by {Author(s)} {Email address(es)}
331
269
332
270
License:
333
271
334
272
        {Add licence text here.  For GNU licences add the licence header
335
273
          and a link to the appropriate file in /usr/share/common-licences.}
336
274
337
275
Packaging:
338
276
        Copyright (C) {Year(s)} by {Your Name} &lt;your email address&gt;
339
277
        released under {the licence you choose for your packaging}
340
278
</programlisting>
341
279
					<para>As one can imagine, hello is released under the GPL license. In this case it is easiest to just copy the copyright file from the <emphasis role="italics">Ubuntu</emphasis> package:</para>
342
280
					<screen><command>cp ../../ubuntu/hello-debhelper-2.2/debian/copyright .</command></screen>
343
281
					<para>Notice that the Ubuntu package's copyright includes a license statement for the manual. It is important that all the files in the source be covered by a license statement.</para>
344
282
					<para>More information, caveats and tips are available in the <ulink url="https://wiki.ubuntu.com/PackagingGuide/Basic#Copyright">Copyright section</ulink>.</para>
345
283
				</sect3>
346
284
				<sect3 id="rules" status="review">
347
285
					<title>rules</title>
348
286
					<para>The last file we need to look at is rules. This does all the work for creating our package. It is a Makefile with targets to compile and install the application, then create the .deb file from the installed files. It also has a target to clean up all the build files so you end up with just a source package again.</para>
349
287
					<para>Here is a simplified version of the rules file created by dh-make:</para>
350
288
					<programlisting>package = hello
351
289
352
290
CC = gcc
353
291
CFLAGS = -g -Wall
354
292
355
293
ifeq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
356
294
  CFLAGS += -O2
357
295
endif
358
296
359
297
#export DH_VERBOSE=1
360
298
361
299
clean:
362
300
        dh_testdir
363
301
        dh_clean
364
302
        rm -f build
365
303
        -$(MAKE) -i distclean
366
304
367
305
install: build
368
306
        dh_clean
369
307
        dh_installdirs
370
308
        $(MAKE) prefix=$(CURDIR)/debian/$(package)/usr \
371
309
                mandir=$(CURDIR)/debian/$(package)/usr/share/man \
372
310
                infodir=$(CURDIR)/debian/$(package)/usr/share/info \
373
311
                install
374
312
375
313
build:
376
314
        ./configure --prefix=/usr
377
315
        $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)"
378
316
        touch build
379
317
380
318
binary-indep: install
381
319
# There are no architecture-independent files to be uploaded
382
320
# generated by this package.  If there were any they would be
383
321
# made here.
384
322
385
323
binary-arch: install
386
324
        dh_testdir -a
387
325
        dh_testroot -a
388
326
        dh_installdocs -a NEWS
389
327
        dh_installchangelogs -a ChangeLog
390
328
        dh_strip -a
391
329
        dh_compress -a
392
330
        dh_fixperms -a
393
331
        dh_installdeb -a
394
332
        dh_shlibdeps -a
395
333
        dh_gencontrol -a
396
334
        dh_md5sums -a
397
335
        dh_builddeb -a
398
336
399
337
binary: binary-indep binary-arch
400
338
401
339
.PHONY: binary binary-arch binary-indep clean checkroot
402
340
</programlisting>
403
341
					<para>Let us go through this file in some detail. One of the first parts you will see is the declaration of some variables:</para>
404
342
					<programlisting>:package = hello
405
343
406
344
CC = gcc
407
345
CFLAGS = -g -Wall
408
346
409
347
ifeq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
410
348
  CFLAGS += -O2
411
349
endif
412
350
413
351
#export DH_VERBOSE=1
414
352
</programlisting>
415
353
					<para>This section sets the flags for the compiler and also handles the noopt options for debugging.</para>
416
354
					<para>Now look at the build rule:</para>
417
355
					<programlisting>build:
418
356
        ./configure --prefix=/usr
419
357
        $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)"
420
358
        touch build
421
359
</programlisting>
422
360
					<para>This rule runs ./configure with the proper prefix, runs make, and creates a build file that is a timestamp of the build to prevent erroneous multiple compilations.</para>
423
361
					<para>The next rule is clean, which runs make -i distclean and removes the files that are made during the package building.</para>
424
362
					<programlisting>clean:
425
363
        dh_testdir
426
364
        dh_clean
427
365
        rm -f build
428
366
        -$(MAKE) -i distclean
429
367
</programlisting>
430
368
					<para>Next we see an empty binary-indep rule. Some packages create architecture-independent .debs if they do not contain files that are specific to the processor. Most Python or artwork packages would be examples of this, their packages end with _all.deb.</para>
431
369
					<para>hello is a C program, so it compiles different code for each architecture. The packages will end with _i386.deb for 32bit, _amd64.deb for 64bit, _lpia.deb for MIDs and etc. For these architecture-dependent packages, binary-arch field is used:</para>
432
370
					<programlisting>binary-arch: install
433
371
        dh_testdir -a
434
372
        dh_testroot -a
435
373
        dh_installdocs -a NEWS
436
374
        dh_installchangelogs -a ChangeLog
437
375
        dh_strip -a
438
376
        dh_compress -a
439
377
        dh_fixperms -a
440
378
        dh_installdeb -a
441
379
        dh_shlibdeps -a
442
380
        dh_gencontrol -a
443
381
        dh_md5sums -a
444
382
        dh_builddeb -a
445
383
</programlisting>
446
384
					<para>This is running a number of debhelper scripts which create our .deb packages. dh_testdir and dh_testroot make some sanity checks. dh_installdocs and dh_installchangelogs install files which you can specify in *.doc and *.changelog files. dh_strip will take debugging symbols out of the application files making them much smaller. dh_compress runs gzip on some documentation files. dh_shlibdeps adds library dependencies to the "Depends: ${shlibs:Depends}" field in debian/control. Finally dh_builddeb builds our .deb file. You do not have to worry too much about these scripts, they should create the packages without problems.</para>
447
385
					<para>There is one other file, compat which just contains a version number for the debhelper scripts. Occationally new versions of debhelper are released, the current version is 6 so you should set compat to 6. If it is set to an older version then the debhelper scripts will behave slightly differently.</para>
448
386
				</sect3>
449
387
				<sect3 id="building-the-package" status="review">
450
388
					<title>Building the Package</title>
451
389
					<para>You are now ready to build the package. There is a simple command to do this.</para>
452
390
					<screen><command>debuild</command></screen>
453
391
					<para>Debuild will first check that all the build-depends packages are installed, it will then use dpkg-buildpackage to compile, install and build the .debs using the rules in debian/rules. If that succeeds it will attempt to digitally sign the packages with GPG, if it gives an error that it can not find your key that means it has successfully compiled the .deb packages but you do not have a GPG key with the same name, comment, and e-mail as you used in debian/changelog. See <ulink url="https://wiki.ubuntu.com/GnuPrivacyGuardHowto">GnuPrivacyGuardHowto</ulink> for instructions on creating your key.</para>
454
392
					<para>Your finished package should now be in the directory above your source. Have a look at it and install it.</para>
455
393
					<screen><command>cd ..
456
394
lesspipe *deb
457
395
sudo dpkg --install *deb
458
396
</command></screen>
459
397
				</sect3>
460
398
				<sect3 id="building-the-source-package" status="review">
461
399
					<title>Building the Source Package</title>
462
400
					<para>Now that we have gone through the files in the debian directory for hello in detail, we can build the source (and binary) packages. First let us move into the root of the extracted source then we build the source package using debuild:</para>
463
401
					<screen><command>debuild -S</command></screen>
464
402
					<para>The -S flag tells debuild to build a source package using another script dpkg-buildpackage and fakeroot to allow us to have fake root privileges when making the package. It will take the .orig.tar.gz file and produce a .diff.gz (the difference between the original tarball from the author and the directory we have created, debian/ and its contents) and a .dsc file that has the description and md5sums for the source package. The .dsc and *_source.changes (used for uploading the source package) files are signed using your GPG key.</para>
465
403
					<para>If you do not have a gpg key set up you will get an error from debuild. You can either set up a gpg key or use the -us -uc keys with debuild to turn off signing. However, you will not be able to have your packages uploaded to Ubuntu without signing them. To make sure debuild finds the right gpg key you should set the DEBFULLNAME and DEBEMAIL environment variables (in your ~/.bashrc for instance) to the name and email address you use for your gpg key and in the debian/changelog. Some people have reported that they were unable to get debuild to find their gpg key properly, even after setting the above environment variables. To get around this you can give debuild the -k&lt;keyid&gt; flag where &lt;keyid&gt; is your gpg key ID.</para>
466
404
					<para>To check the package builds in a clean environement we can also build the binary package with pbuilder:</para>
467
405
					<screen><command>sudo pbuilder build ../*.dsc</command></screen>
468
406
					<para>Using pbuilder to build the binary packages is very important. It ensures that the build dependencies are correct, because pbuilder provides only a minimal environment, so all the build-time dependencies are determined by the control file.</para>
469
407
					<para>We can check the source package for common mistakes using lintian:</para>
470
408
					<screen><command>cd ..
471
409
lintian -Ivi *.dsc
472
410
</command></screen>
473
411
				</sect3>
474
412
				<sect3 id="requirements-for-new-ubuntu-packages" status="review">
475
413
					<title>Requirements for new Ubuntu packages</title>
476
414
					<para>When a source package is uploaded to Ubuntu which does not yet exist in the archive, or builds a new binary package, it will be held in the <ulink url="http://people.ubuntu.com/~ubuntu-archive/queue/">NEW queue</ulink> and has to be reviewed by an <ulink url="https://launchpad.net/~ubuntu-archive">Ubuntu archive team</ulink> member.</para>
477
415
					<sect4 id="packaging2" status="review">
478
416
						<title>Packaging</title>
479
417
						<itemizedlist>
480
418
							<listitem><para>Most importantly: see <link linkend="copyright-information">copyright and licensing information</link> below.</para></listitem>
481
419
							<listitem><para>The source and binary packages should have a sane name: neither they should clutter the namespace (such as "editor") nor should they have an entirely nonsensical name (such as "new-stuff-manager").</para></listitem>
482
420
							<listitem><para>debian/control and debian/rules should build packages with the right Architecture:, Build-Depends[-Indep]:, and rules target (binary-arch vs. binary-indep).</para></listitem>
483
421
							<listitem><para>Maintainer and init scripts should not excessively mess up the system.</para></listitem>
484
422
							<listitem><para>A more comprehensive list of package checks is available from the <ulink url="https://wiki.ubuntu.com/UbuntuDevelopment/CodeReviews">Code Review</ulink> page.</para></listitem>
485
423
						</itemizedlist>
486
424
					</sect4>
487
425
					<sect4 id="other" status="review">
488
426
						<title>Other</title>
489
427
						<itemizedlist>
490
428
							<listitem><para>The <ulink url="http://ftp-master.debian.org/REJECT-FAQ.html">Debian NEW Reject FAQ</ulink> lists some important special cases which mostly apply to Ubuntu as well.</para></listitem>
491
429
							<listitem><para>Process documentation: <ulink url="https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages">UbuntuDevelopment/NewPackages</ulink></para></listitem>
492
430
						</itemizedlist>
493
431
					</sect4>
494
432
				</sect3>
495
433
			</sect2>
496
434
			<sect2 id="packaging-with-cdbs" status="review">
497
435
				<title>Packaging With CDBS</title>
498
436
				<para>CDBS is a set of Makefile includes that uses debhelper to make building and maintaining Debian packages even easier. It uses advanced features of Makefiles to abstract the build process, so rules files end up primarily as a series of include statements. It has many advantages:</para>
499
437
				<itemizedlist>
500
438
					<listitem><para>It produces a short, readable, and efficient debian/rules</para></listitem>
501
439
					<listitem><para>It automates debhelper use for you, so you do not have to worry about repetitive tasks</para></listitem>
502
440
					<listitem><para>It helps you focus on more important packaging problems, because it helps without limiting customization</para></listitem>
503
441
					<listitem><para>Its classes have been well tested, so you can avoid dirty hacks to solve common problems</para></listitem>
504
442
					<listitem><para>Switching to CDBS is easy</para></listitem>
505
443
					<listitem><para>It is extendable</para></listitem>
506
444
				</itemizedlist>
507
445
				<para>However if your package has an oddity about how it is built you may need to tackle some of the Makefile syntax to extend CDBS and tell it what is needed.</para>
508
446
				<para>Using CDBS for Ubuntu packages is very easy, if the software you are packaging can be configured and built using the GNU autoconf tools (the "configure-make-make install" idiom). After adding cdbs to the Build-Depends in debian/control, a basic debian/rules file using CDBS can fit in 2 lines. For a simple C/C++ application with no extra rules, such as hello, debian/rules can look like this :</para>
509
447
				<programlisting>#!/usr/bin/make -f
510
448
                                
511
449
include /usr/share/cdbs/1/rules/debhelper.mk
512
450
include /usr/share/cdbs/1/class/autotools.mk
513
451
</programlisting>
514
452
				<para>That is all you need to build the program! CDBS handles installing and cleaning. You can then use the .install and .info files to tune your package with the usual debhelper functions in the various sections for debian/rules.</para>
515
453
				<para>Sometimes the upstream author has hardwired non-standard defaults into the autoconf scripts. For example, a package may place man pages in /usr/man/. In this case, you can specify the correct path by specifying:</para>
516
454
				<programlisting>DEB_CONFIGURE_MANDIR=/usr/share/man</programlisting>
517
455
				<para>Another situation frequently seen in configure scripts is that you need to specify certain optional configuration options provided by the software author. This is handled by putting this option in the variable, for example:</para>
518
456
				<programlisting>DEB_CONFIGURE_EXTRA_FLAGS = --enable-graphics --with-gsl=/usr</programlisting>
519
457
				<para>Here is the list of standard configure options that are always passed to configure:</para>
520
458
				<programlisting>--prefix=$(DEB_CONFIGURE_PREFIX)
521
459
--includedir=$(DEB_CONFIGURE_INCLUDEDIR) 
522
460
--mandir=$(DEB_CONFIGURE_MANDIR) 
523
461
--infodir=$(DEB_CONFIGURE_INFODIR) 
524
462
--sysconfdir=$(DEB_CONFIGURE_SYSCONFDIR) 
525
463
--localstatedir=$(DEB_CONFIGURE_LOCALSTATEDIR) 
526
464
--libexecdir=$(DEB_CONFIGURE_LIBEXECDIR)
527
465
</programlisting>
528
466
				<para>CDBS mostly works by including .mk Makefiles in debian/rules. The cdbs package provides such files in /usr/share/cdbs/1/ that allow you to do quite a lot of packaging tasks. Other packages, such as quilt, add modules to CDBS and can be used as Build-Depends. Note that you can also use your own CDBS rules and include them in the package. The most useful modules included with the cdbs package are:</para>
529
467
				<itemizedlist>
530
468
					<listitem><para>rules/debhelper.mk: Calls debhelper in all required sections</para></listitem>
531
469
					<listitem><para>rules/dpatch.mk: Allows you to use dpatch to ease patching the source. Must be included before any other rule.</para></listitem>
532
470
					<listitem><para>rules/simple-patchsys.mk: Provides a very easy way to patch the source</para></listitem>
533
471
					<listitem><para>rules/tarball.mk: Allows you to build packages using the compressed tarball in the package</para></listitem>
534
472
					<listitem><para>class/autotools.mk: Calls autotools in all required sections</para></listitem>
535
473
					<listitem><para>class/gnome.mk: Builds GNOME programs (requires the proper Build-Depends in debian/control)</para></listitem>
536
474
					<listitem><para>class/kde.mk: Builds KDE programs (requires the proper Build-Depends in debian/control)</para></listitem>
537
475
					<listitem><para>class/xfce.mk: Build Xfce4 programs (requires the proper Build-Depends in debian/control)</para></listitem>
538
476
					<listitem><para>class/python-distutils.mk: Facilitates packaging Python programs</para></listitem>
539
477
				</itemizedlist>
540
478
				<para>It may happen that you need to patch files belonging to the autoconf system. In such cases, you typically need to run aclocal, automake and autoconf after the patch has been applied. CDBS has options to assist you in this situation. It will run patch first, then rebuild the autotools, and finally run configure "et al." Here is an example, where versions 1.10 of autoconf and automake are chosen:</para>
541
479
				<programlisting>include /usr/share/cdbs/1/rules/dpatch.mk
542
480
include /usr/share/cdbs/1/rules/debhelper.mk
543
481
include /usr/share/cdbs/1/class/autotools.mk
544
482
545
483
DEB_AUTO_UPDATE_ACLOCAL = 1.10 -I ./config
546
484
DEB_AUTO_UPDATE_LIBTOOL = pre
547
485
DEB_AUTO_UPDATE_AUTOMAKE = 1.10 --foreign --add-missing --copy
548
486
DEB_AUTO_UPDATE_AUTOCONF = 1.10
549
487
</programlisting>
550
488
				<para>The DEB_AUTO_UPDATE_LIBTOOL variable can take the values "pre" or "post", depending on how you want libtool to be run. Notice that (curiously) aclocal is only invoked if aclocal.m4 is already present in the top level directory.</para>
551
489
				<para>A word of warning is in place at this point: Some packagers do not trust that the autoconf system can be generated correctly on a foreign build system.</para>
552
490
				<para>CDBS runs the debhelper scripts after the package has been compiled and installed. Sometimes you may need to modify the behaviour of certain debhelper scripts. A bunch of variables are available for this purpose:</para>
553
491
				<informaltable frame="all">
554
492
					<tgroup cols="2">
555
493
						<thead>
556
494
							<row>
557
495
								<entry><emphasis role="bold">debhelper script</emphasis></entry>
558
496
								<entry><emphasis role="bold">CDBS variable</emphasis></entry>
559
497
							</row>
560
498
						</thead>
561
499
						<tbody>
562
500
							<row>
563
501
								<entry>dh_builddeb</entry>
564
502
								<entry>DEB_BUILD_DEB_ARGS</entry>
565
503
							</row>
566
504
							<row>
567
505
								<entry>dh_compress</entry>
568
506
								<entry>DEB_COMPRESS_ARGS</entry>
569
507
							</row>
570
508
							<row>
571
509
								<entry>dh_fixperms</entry>
572
510
								<entry>DEB_FIX_PERMS_ARGS</entry>
573
511
							</row>
574
512
							<row>
575
513
								<entry>dh_gencontrol</entry>
576
514
								<entry>DEB_GENCONTROL_ARGS</entry>
577
515
							</row>
578
516
							<row>
579
517
								<entry>dh_installcatalog</entry>
580
518
								<entry>DEB_INSTALLCATALOG_ARGS</entry>
581
519
							</row>
582
520
							<row>
583
521
								<entry>dh_installchangelogs</entry>
584
522
								<entry>DEB_INSTALLCHANGELOGS_ARGS</entry>
585
523
							</row>
586
524
							<row>
587
525
								<entry>dh_installdebconf</entry>
588
526
								<entry>DEB_INSTALLDEBCONF_ARGS</entry>
589
527
							</row>
590
528
							<row>
591
529
								<entry>dh_installdeb</entry>
592
530
								<entry>DEB_INSTALL_DEB_ARGS</entry>
593
531
							</row>
594
532
							<row>
595
533
								<entry>dh_installemacsen</entry>
596
534
								<entry>DEB_INSTALLEMACSEN_ARGS</entry>
597
535
							</row>
598
536
							<row>
599
537
								<entry>dh_installinit</entry>
600
538
								<entry>DEB_INSTALLINIT_ARGS</entry>
601
539
							</row>
602
540
							<row>
603
541
								<entry>dh_installlogcheck</entry>
604
542
								<entry>DEB_INSTALLLOGCHECK_ARGS</entry>
605
543
							</row>
606
544
							<row>
607
545
								<entry>dh_installlogrotate</entry>
608
546
								<entry>DEB_INSTALLLOGROTATE_ARGS</entry>
609
547
							</row>
610
548
							<row>
611
549
								<entry>dh_installmime</entry>
612
550
								<entry>DEB_INSTALLMIME_ARGS</entry>
613
551
							</row>
614
552
							<row>
615
553
								<entry>dh_installpam</entry>
616
554
								<entry>DEB_INSTALLPAM_ARGS</entry>
617
555
							</row>
618
556
							<row>
619
557
								<entry>dh_installudev</entry>
620
558
								<entry>DEB_INSTALLUDEV_ARGS</entry>
621
559
							</row>
622
560
							<row>
623
561
								<entry>dh_install</entry>
624
562
								<entry>DEB_INSTALL_ARGS</entry>
625
563
							</row>
626
564
							<row>
627
565
								<entry>dh_makeshlibs</entry>
628
566
								<entry>DEB_MAKESHLIBS_ARGS</entry>
629
567
							</row>
630
568
							<row>
631
569
								<entry>dh_md5sums</entry>
632
570
								<entry>DEB_MD5SUMS_ARGS</entry>
633
571
							</row>
634
572
							<row>
635
573
								<entry>dh_perl</entry>
636
574
								<entry>DEB_PERL_ARGS</entry>
637
575
							</row>
638
576
							<row>
639
577
								<entry>dh_shlibdeps</entry>
640
578
								<entry>DEB_SHLIBDEPS_ARGS</entry>
641
579
							</row>
642
580
							<row>
643
581
								<entry>dh_strip</entry>
644
582
								<entry>DEB_STRIP_ARGS</entry>
645
583
							</row>
646
584
						</tbody>
647
585
					</tgroup>
648
586
				</informaltable>
649
587
				<para>See the manpages of the individual debhelper scripts to see what options are available. One thing that is commonly needed is to exclude files from the action of certain debhelper scripts. For example, you may arrange that a certain file maintains the permissions with which it was installed, and not become modified by the dh_fixperms script:</para>
650
588
				<programlisting>DEB_FIXPERMS_EXCLUDE = /usr/sbin/suid-program</programlisting>
651
589
				<para>The complete list of CDBS' exclude variables is:</para>
652
590
				<informaltable frame="all">
653
591
					<tgroup cols="1">
654
592
						<tbody>
655
593
							<row>
656
594
								<entry>DEB_COMPRESS_EXCLUDE</entry>
657
595
							</row>
658
596
							<row>
659
597
								<entry>DEB_FIXPERMS_EXCLUDE</entry>
660
598
							</row>
661
599
							<row>
662
600
								<entry>DEB_CLEAN_EXCLUDE</entry>
663
601
							</row>
664
602
							<row>
665
603
								<entry>DEB_DH_ALWAYS_EXCLUDE</entry>
666
604
							</row>
667
605
							<row>
668
606
								<entry>DEB_DEB_STRIP_EXLUCDE</entry>
669
607
							</row>
670
608
						</tbody>
671
609
					</tgroup>
672
610
				</informaltable>
673
611
			</sect2>
674
612
			<sect2 id="packaging-python-modules-with-cdbs" status="review">
675
613
				<title>Packaging Python modules with CDBS</title>
676
614
				<para>CDBS is also very well suited for packaging Python modules, when these make use of the distutils building system. Following is an example of a debian/rules file, which in fact could be used ad verbatim for a great number of not-too-complicated modules. Notice that we also tell CDBS not to compress Python source files:</para>
677
615
				<programlisting>DEB_PYTHON_SYSTEM=pysupport
678
616
679
617
include /usr/share/cdbs/1/rules/debhelper.mk
680
618
include /usr/share/cdbs/1/class/python-distutils.mk
681
619
682
620
# Don't compress .py files
683
621
DEB_COMPRESS_EXCLUDE := .py
684
622
</programlisting>
685
623
				<para>Important note on DEB_AUTO_UPDATE_DEBIAN_CONTROL:: Do not use DEB_AUTO_UPDATE_DEBIAN_CONTROL:=yes to automatically change debian/control. It can cause bad things, and Debian considers it a reason to reject a package from entering the archives. See <ulink url="http://ftp-master.debian.org/REJECT-FAQ.html">http://ftp-master.debian.org/REJECT-FAQ.html</ulink> for more information.</para>
686
624
				<para>For more information on CDBS, see Marc Dequènes's guide at <ulink url="https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml">https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml</ulink>.</para>
687
625
				<para>See also <ulink url="https://wiki.ubuntu.com/PackagingGuide/Python">this tutorial</ulink>.</para>
688
626
			</sect2>
689
627
			<sect2 id="advanced-packaging" status="review">
690
628
				<title>Advanced Packaging</title>
691
629
				<sect3 id="creating-more-than-one-binary-package" status="review">
692
630
					<title>Creating More Than One Binary Package</title>
693
631
					<para>Often you will want to split a source package into more than one binary package.</para>
694
632
					<para>For single binary packages files are installed to debian/&lt;packagename&gt; and packaged from there. For multiple packages they are installed to debian/tmp and split up by using multiple &lt;packagename&gt;.install files</para>
695
633
				</sect3>
696
634
			</sect2>
697
635
			<sect2 id="packaging-shared-libraries" status="review">
698
636
				<title>Packaging Shared Libraries</title>
699
637
				<para>This document explains what shared libraries are, focusing on exported symbols, and explains some of the details of how to package them.</para>
700
638
				<para>It is a work in progress, based on a <ulink url="https://wiki.ubuntu.com/MOTU/School">MOTU/School</ulink> session. To see the log of that session please see <ulink url="https://wiki.ubuntu.com/MOTU/School/LibraryPackaging">MOTU/School/LibraryPackaging</ulink></para>
701
639
				<sect3 id="shared-libraries" status="review">
702
640
					<title>Shared Libraries</title>
703
641
					<para>Shared libraries are object files containing compiled code that can be linked in to an executable. This is usually done for one of two reasons:</para>
704
642
					<orderedlist>
705
643
						<listitem><para>To provide a dynamically loaded plugin mechanism using dlopen.</para></listitem>
706
644
						<listitem><para>To share code between multiple applications.</para></listitem>
707
645
					</orderedlist>
708
646
					<para>This guide will mainly concern itself with the second application.</para>
709
647
					<para>The structure of an (ELF) shared library is an object file containing "symbols" split in to "sections". Usually the details of the sections used are not important when packaging, merely the list of symbols, and as such we will focus on those.</para>
710
648
					<para>A symbol is an item that is exported from the shared object. This means that it is accessible from an executable that loads the shared library. A symbol can be a variable, or a function, or something else like a struct. If it is a variable then the executable can read and write the value of the variable, and if it is a function then the executable can call the function.</para>
711
649
					<para>The important thing to note is that if an executable contains code to call a function do_foo that it expects to find in libfoo.so and libfoo.so does not export a function with that name the program will not run. There are more complications that arise if the program and the library differ in what they think the definition of a symbol are, and so we must strive to make sure that this never happens.</para>
712
650
					<sect4 id="where-a-symbol-comes-from" status="review">
713
651
						<title>Where a symbol comes from</title>
714
652
						<para>Symbols are created by the compiler from certain constructs in the source code. Consider the following code:</para>
715
653
						<programlisting>#include &lt;stdio.h&gt;
716
654
717
655
static int static_global = 42;
718
656
int extern_global;
719
657
const int const_extern_global = 42;
720
658
721
659
static void
722
660
local_function(int n)
723
661
{
724
662
        int local_var = 3;
725
663
        static int static_local_var = 23;
726
664
727
665
        if (n &gt; 3) {
728
666
                local_var = n;
729
667
                static_local_var = 2 * n;
730
668
        }
731
669
732
670
        if (local_var &gt; 4) {
733
671
                fprintf(stderr, "static_var=%d\n", static_global);
734
672
        } else {
735
673
                fprintf(stderr, "static_local_var=%d\n", static_local_var);
736
674
        }
737
675
}
738
676
739
677
void 
740
678
global_function(int n) 
741
679
{
742
680
        fprintf(stderr, "extern_global=%d\n", extern_global);
743
681
}
744
682
745
683
int
746
684
main(int argc, char **argv)
747
685
{
748
686
        local_function(argc);
749
687
        global_function(argc);
750
688
751
689
        return 0;
752
690
}
753
691
</programlisting>
754
692
						<para>When this code is compiled the compiler will decide whether each of the variables, functions etc. used in the code should be exported as a symbol. If we compile this code we will be able to see what becomes a symbol. Save the code to a file named example.c and then run the following command to compile it:</para>
755
693
						<screen><command>$ gcc -c example.c -o example.o</command></screen>
756
694
						<para>This doesn't create a shared library yet, just an object file, but we are able to see some of the symbol information. Use nm to see the symbol list:</para>
757
695
						<programlisting>$ nm example.o
758
696
00000000 R const_extern_global
759
697
00000004 C extern_global
760
698
         U fprintf
761
699
0000006b T global_function
762
700
00000000 t local_function
763
701
00000092 T main
764
702
00000000 d static_global
765
703
00000004 d static_local_var.1781
766
704
         U stderr
767
705
</programlisting>
768
706
						<para>In the rightmost column you can see the name of each of the symbols. There is one created for most of the variables and functions used in the file. However, local_var is not there, as this is a local variable to a function, and as such is allocated on the stack.</para>
769
707
						<para>The other interesting feature is the number that is included in the name of static_local_var. This is to avoid name clashes if you were to have a static variable named static_local_var in another function in the file. (However, as we will see, this symbol will not make it in to the shared object, so this point is not too important.)</para>
770
708
						<para>In the middle column of the output there are letters that correspond to the type of symbol. You can find the definitions in man nm. The ones listed above are</para>
771
709
						<itemizedlist>
772
710
							<listitem><para><emphasis role="bold">R</emphasis> - The symbol is in the read only data section.</para></listitem>
773
711
							<listitem><para><emphasis role="bold">C</emphasis> - Common symbol, i.e. uninitialized data.</para></listitem>
774
712
							<listitem><para><emphasis role="bold">U</emphasis> - The symbol is defined somewhere other than this file.</para></listitem>
775
713
							<listitem><para><emphasis role="bold">T</emphasis> - The symbol is in the text section, i.e. it is code.</para></listitem>
776
714
							<listitem><para><emphasis role="bold">t</emphasis> - The symbol is in the text section.</para></listitem>
777
715
							<listitem><para><emphasis role="bold">d</emphasis> - The symbol is in the initialized data section.</para></listitem>
778
716
						</itemizedlist>
779
717
						<para>You may notice that the local symbols are given a lowercase letter, and the global symbols an uppercase letter. This means that only symbols with an uppercase letter will make it in to the shared object.</para>
780
718
						<para>The interesting symbols are the ones given the symbol <emphasis role="bold">U</emphasis>, which indicates that they refer to the symbol, but do not define it, which means that it must be defined elsewhere. In this case stderr and fprintf fall in to that category, as they are defined in libc. The symbols will be matched up by the linker later.</para>
781
719
					</sect4>
782
720
				</sect3>
783
721
			</sect2>
784
722
			<sect2 id="common-mistakes" status="review">
785
723
				<title>Common Mistakes</title>
786
724
				<sect3 id="dh-make-example-files" status="review">
787
725
					<title>dh_make Example Files</title>
788
726
					<para>When you use dh_make to create the initial "debianisation", example files for various tasks are created in the debian/ directory. The templates have a .ex extension. If you want to use one, rename it to remove the extension. If you do not need it, remove it to keep the debian/ directory clean.</para>
789
727
				</sect3>
790
728
				<sect3 id="abusing-dh-installdirs-dirs-files" status="review">
791
729
					<title>Abusing dh_installdirs .dirs files</title>
792
730
					<para>Many packages wrongly use dh_installdirs and .dirs files to create directories. 99% of those cases are not necessary, since dh_install and .install files will automatically take care of creating directories. You only need to use dh_installdirs if your package needs to ship empty nonstandard directories, e. g. /etc/mypackage/plugins.d/.</para>
793
731
				</sect3>
794
732
				<sect3 id="changing-the-original-tarball" status="review">
795
733
					<title>Changing the Original Tarball</title>
796
734
					<sect4 id="solutions" status="review">
797
735
						<title>Solutions</title>
798
736
						<itemizedlist>
799
737
							<listitem><para>get-orig-source target:</para>
800
738
							<programlisting>get-orig-source:
801
739
        cd ..; wget http://somesite.org/stuff/somesoftware-4.2.tar.bz2
802
740
        bzcat ../somesoftware-4.2.tar.bz2 | gzip -9fn -c - &gt; ../somesoftware-4.2.tar.gz
803
741
        ln -s somesoftware-4.2.tar.gz ../${DEB_SOURCE_PACKAGE}_4.2.orig.tar.gz
804
742
</programlisting>
805
743
							</listitem>
806
744
							<listitem><para>get-orig-source for zip files:</para>
807
745
							<programlisting>PACKAGE := $(shell dpkg-parsechangelog | sed -n 's/^Source: //p')
808
746
VERSION := $(shell dpkg-parsechangelog | sed -ne 's/^Version: \(.*\)-.*/\1/p')
809
747
810
748
get-orig-source:
811
749
        rm -rf $@
812
750
        mkdir -p $@/$(PACKAGE)-$(VERSION)
813
751
        cd $@ &amp;&amp; wget http://somesite.org/stuff/somesoftware-$(VERSION).zip
814
752
        unzip -o $@/somesoftware-$(VERSION).zip -d $@/$(PACKAGE)-$(VERSION)
815
753
        cd $@ &amp;&amp; tar -cf - $(PACKAGE)-$(VERSION) | gzip -9f - &gt; ../../$(PACKAGE)_$(VERSION).orig.tar.gz
816
754
        rm -r $@
817
755
</programlisting>
818
756
							</listitem>
819
757
							<listitem><para>another get-orig-source target:</para>
820
758
							<programlisting>get-orig-source:
821
759
        cd .. &amp;&amp; wget http://somesite.org/stuff/somesoftware-4.2.tar.bz2
822
760
        tar xjf ../somesoftware-4.2.tar.bz2
823
761
        rm ../somesoftware-4.2.tar.bz2
824
762
        mv somesoftware-4.2 somesoftware-4.2.orig
825
763
        tar -cf ../somesoftware-4.2.orig.tar somesoftware-4.2.orig
826
764
        rm -fr somesoftware-4.2.orig
827
765
        gzip -9fn ../somesoftware-4.2.orig.tar
828
766
</programlisting>
829
767
							<para>(and maybe also provide the rule  ../somesoftware_4.2.orig.tar.gz: get-orig-source , or list get-orig-source within .PHONY). </para></listitem>
830
768
							<listitem><para>if you use a watch file, this can be:</para>
831
769
							<programlisting># Path to the debian directory
832
770
DEBIAN_DIR := $(shell echo ${MAKEFILE_LIST} | awk '{print $$1}' | xargs dirname )
833
771
UPSTREAM_VERSION ?=$(shell uscan --dehs | sed -n 's/.*&lt;upstream-version&gt;\(.*\)&lt;\/upstream-version&gt;.*/\1/p')
834
772
835
773
get-orig-source:
836
774
        cd ${DEBIAN_DIR}/.. &amp;&amp; uscan --force-download
837
775
        bzcat ../somesoftware-${UPSTREAM_VERSION}.tar.bz2 | gzip -9fn -c - &gt; \
838
776
        ${CURDIR}/${DEB_SOURCE_PACKAGE}_${UPSTREAM_VERSION}.orig.tar.gz
839
777
</programlisting>
840
778
							</listitem>
841
779
							<listitem><para>directly imported from cvs</para>
842
780
							<programlisting>CVSDATE+=22 May 2007
843
781
SW_VERSION+=4.2
844
782
845
783
TARFILE+=somesoftware_$(SW_VERSION)~cvs$(shell date -d "$(CVSDATE)" +%Y%m%d).orig.tar.gz
846
784
CVSHOME+=:pserver:anonymous@somesoftware.cvs.sourceforge.net:/cvsroot/somesoftware
847
785
848
786
get-orig-source::
849
787
        cvs -d$(CVSHOME) login
850
788
        cvs -d$(CVSHOME) export -D "$(CVSDATE)" somesoftware
851
789
        tar czf $(CURDIR)/../$(TARFILE) $(CURDIR)/somesoftware
852
790
        rm -rf $(CURDIR)/somesoftware
853
791
854
792
../$(TARFILE):: get-orig-source
855
793
</programlisting>
856
794
							</listitem>
857
795
						</itemizedlist>
858
796
							
859
797
					</sect4>
860
798
					<sect4 id="tips" status="review">
861
799
						<title>Tips</title>
862
800
						<itemizedlist>
863
801
							<listitem><para>Always remember to reference get-orig-source: in debian/rules when you need to repack the orig.tar.gz, explaining why you repacked it, and how others can verify your work.</para></listitem>
864
802
							<listitem><para>It's always a good idea to contact upstream and ask that stuff like autoconf-issues or directory layout (or old FSF-address) or other things you need to "patch" afterwards in .diff.gz be corrected.</para></listitem>
865
803
							<listitem><para>Older packages (from Debian Policy 3.3.8 or earlier) keep the information on repacking in debian/README.Debian-source. When updating an older package, it is acceptable to leave it here, although when upgrading or packaging new software, debian/copyright is much preferred.</para></listitem>
866
804
							<listitem><para>If a package already contains a debian/ dir: Do not repackage it. You can ask the author(s) to delete the debian/ dir and provide a diff.gz instead. This makes it easier to review their work, and it separates packaging from program source. It is always a good idea to contact the program's author(s) and ask if you may correct autoconf issues, directory layout, an outdated Free Software Foundation address in COPYRIGHT files, or other things that are not specific to the packaging but would be convenient for you so you do not need to "patch" the source in .diff.gz.</para></listitem>
867
805
						</itemizedlist>
868
806
					</sect4>
869
807
				</sect3>
870
808
				<sect3 id="copyright-information" status="review">
871
809
					<title>Copyright Information</title>
872
810
					<para>When dealing with copyright information of packages, the following points are critical, since they determine whether we are allowed at all to redistribute the package. Packages must not be accepted if any of these points is not fulfilled:</para>
873
811
					<itemizedlist>
874
812
						<listitem><para>The upstream tarball must contain verbatim copies of all licenses that are used by the files in the tarball. References to URLs or paths to system files (such as /usr/share/common-licenses/) are not sufficient. The license(s) must accompany the source code.</para></listitem>
875
813
						<listitem><para>For all files it must be clear under which license they fall. Source code files should usually have a short comment at the top which points out the license.</para></listitem>
876
814
						<listitem><para>Files shipped under the GPL must be in the 'preferred form of modification' format. This applies to some other free licenses like the MPL, too (but e. g. not to BSD). Negative examples are Flash animations (*.swf), most PostScript/PDF files, and automatically generated source code. The suspicious-source script in the ubuntu-dev-tools package helps to spot such files.</para></listitem>
877
815
						<listitem><para>debian/copyright must list the primary copyright holders and all licenses (use pointers to /usr/share/common-licenses/ licenses included there), and declare which licenses apply to which parts of the package.</para></listitem>
878
816
						<listitem><para>Since there are now multiple versions of the GPL and LGPL, the copyright headers and files must be clear about which version(s) apply.</para></listitem>
879
817
					</itemizedlist>
880
818
					<para>Common errors:</para>
881
819
					<itemizedlist>
882
820
						<listitem><para>Not shipping a copy of the LGPL when e. g. the build system is under LGPL, but the actual source is GPL</para></listitem>
883
821
						<listitem><para>Shipping PDFs and other files without source like a LaTeX or OpenOffice document</para></listitem>
884
822
						<listitem><para>Documentation is actually under GFDL, but debian/copyright does not mention it. As of gutsy, the GFDL is in /usr/share/common-licenses/, so a pointer there is sufficient for debian/copyright.</para></listitem>
885
823
						<listitem><para>debian/copyright only mentions a license, but no copyright</para></listitem>
886
824
						<listitem><para>The source files and/or debian/copyright are not clear about which files fall under which license</para></listitem>
887
825
						<listitem><para>Source is shipped under "GPL 2 only", while debian/copyright says "GPL 2 or later"</para></listitem>
888
826
						<listitem><para>GPLed packages link against OpenSSL (directly or indirectly)</para></listitem>
889
827
						<listitem><para>Different copyright holders and different licenses not mentioned in debian/copyright. Please grep -ir copyright * your package's directorys to make sure you got them all. In the case of large numbers of trivial copyright holders, not all need be mentioned (ask on IRC if you are in doubt), but all licenses must be listed.</para></listitem>
890
828
					</itemizedlist>
891
829
					<para>The rule of thumb is: look at copyright definitions in the source code, the accompaning COPYING/AUTHORS file and at the involved licenses. There is no such thing as a general rule of thumb to get it right: Different licenses have different requirements for redistribution. While a public domain license may even state that you can do everything with the source code (which would mean that you need not put anything into debian/copyright, or could even choose your own "may be distributed in cd form only on rainy saturday's"-license), other licenses will impose certain restrictions like including the copyright statement and/or authors and making it clear if the source code is altered from its original form. Sometimes the involved licenses even conflict with each other (e.g. GPL and OpenSSL-license), which means that the resulting binary package cannot be distributed.</para>
892
830
					<sect4 id="example-1-gpl" status="review">
893
831
						<title>Example 1: GPL</title>
894
832
						<para>The GPL requires that the complete license text is distributed (you can refer to /usr/share/common-licenses/GPL, which is always there on debian/ubuntu systems), the authors and the short disclaimer of warranty (which you should include into debian/copyright). For example</para>
895
833
						<programlisting>License: GPL-2
896
834
 &lt;one line to give the program's name and a brief idea of what it does.&gt;
897
835
 Copyright (C) &lt;year&gt;  &lt;name of author&gt;
898
836
 .
899
837
 This program is free software; you can redistribute it and/or modify
900
838
 it under the terms of the GNU General Public License as published by
901
839
 the Free Software Foundation; either version 2 of the License, or
902
840
 (at your option) any later version.
903
841
 .
904
842
 This program is distributed in the hope that it will be useful,
905
843
 but WITHOUT ANY WARRANTY; without even the implied warranty of
906
844
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
907
845
 GNU General Public License for more details.
908
846
 .
909
847
 You should have received a copy of the GNU General Public License
910
848
 along with this program; if not, write to the Free Software
911
849
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
912
850
913
851
X-Comment: On Debian GNU/Linux systems, the complete text of the GNU General
914
852
 Public License can be found in the /usr/share/common-licenses/GPL file.
915
853
</programlisting>
916
854
						<para>Please note that we use the <ulink url="http://wiki.debian.org/Proposals/CopyrightFormat">new machine-readable copyright format</ulink> here.</para>
917
855
						<para>Please also note, that upstream may also choose to restrict the license to one specific version of the GPL, then you'll need to modify the text above. Usually that very disclaimer can be found in the sourcecode of a package. Then you can simply paste it to debian/copyright.</para>
918
856
						<para>Always ensure you are using the correct version, GPL 2 or 3, LGPL 2.0, 2.1 or 3. Use licencecheck to check that the licence of all files is consistent. Make sure full copies of the licences used are included by upstream, it is not uncommon for LGPL or FDL to be missing.</para>
919
857
					</sect4>
920
858
					<sect4 id="general-advice" status="review">
921
859
						<title>General advice</title>
922
860
						<para>Combining GPL and another license will always make the combined work to be GPL or, if the licenses conflict, undistributable. What licenses can be combined can be found at <ulink url="http://www.gnu.org/licenses/license-list.html">http://www.gnu.org/licenses/license-list.html</ulink>.</para>
923
861
						<para>Usually you will need to list the different licenses as well in debian/copyright. A good way to do this, is to list files with a different license together with the license in question. Whether you will actually need to list the different licenses depends solely on the license involved.</para>
924
862
						<para>What you don't need to mention is licenses from libraries against which the package links. They are accompanied by their own copyright file and the package in question can never be installed w.o. the library in question. Of course there are exceptions which impose different restrictions, like the OpenSSL license which requires a disclaimer to be present in debian/copyright if it's used (as in linked against) in a project. But these additional restriction mean, that the used library is incompatible with the GPL.</para>
925
863
						<para>While usually most of the projects don't have any legal issues, it's very simple to introduce these with inaccurate copyright-files. Finally there is a rule of thumb: Better safe than sorry - be verbose and list everything which you are not sure if it should go into debian/copyright or not.</para>
926
864
					</sect4>
927
865
				</sect3>
928
866
			</sect2>
929
867
			<sect2 id="reference-packages" status="review">
930
868
				<title>Reference Packages</title>
931
869
				<informaltable frame="all">
932
870
					<tgroup cols="1">
933
871
						<thead>
934
872
							<row>
935
873
								<entry><emphasis role="bold">Simple installation of files</emphasis></entry>
936
874
							</row>
937
875
						</thead>
938
876
						<tbody>
939
877
							<row>
940
878
								<entry>ubuntu-artwork</entry>
941
879
							</row>
942
880
							<row>
943
881
								<entry>example-content</entry>
944
882
							</row>
945
883
						</tbody>
946
884
					</tgroup>
947
885
				</informaltable>
948
886
				<informaltable frame="all">
949
887
					<tgroup cols="1">
950
888
						<thead>
951
889
							<row>
952
890
								<entry><emphasis role="bold">PHP</emphasis></entry>
953
891
							</row>
954
892
						</thead>
955
893
						<tbody>
956
894
							<row>
957
895
								<entry>gallery2</entry>
958
896
							</row>
959
897
							<row>
960
898
								<entry>roundcube</entry>
961
899
							</row>
962
900
						</tbody>
963
901
					</tgroup>
964
902
				</informaltable>
965
903
				<informaltable frame="all">
966
904
					<tgroup cols="2">
967
905
						<thead>
968
906
							<row>
969
907
								<entry><emphasis role="bold">Python</emphasis></entry>
970
908
							</row>
971
909
						</thead>
972
910
						<tbody>
973
911
							<row>
974
912
								<entry><emphasis role="bold">Python Central</emphasis></entry>
975
913
								<entry><emphasis role="bold">Python Support</emphasis></entry>
976
914
							</row>
977
915
							<row>
978
916
								<entry>jokosher</entry>
979
917
								<entry>linda</entry>
980
918
							</row>
981
919
							<row>
982
920
								<entry>scribes</entry>
983
921
								<entry>bittornado</entry>
984
922
							</row>
985
923
							<row>
986
924
								<entry>pyenchant</entry>
987
925
								<entry>aptoncd</entry>
988
926
							</row>
989
927
							<row>
990
928
								<entry>python-imaging</entry>
991
929
								<entry>exaile</entry>
992
930
							</row>
993
931
							<row>
994
932
								<entry>pyparallel</entry>
995
933
								<entry>rhythmbox</entry>
996
934
							</row>
997
935
						</tbody>
998
936
					</tgroup>
999
937
				</informaltable>
1000
938
				<informaltable frame="all">
1001
939
					<tgroup cols="1">
1002
940
						<thead>
1003
941
							<row>
1004
942
								<entry><emphasis role="bold">debconf</emphasis></entry>
1005
943
							</row>
1006
944
						</thead>
1007
945
						<tbody>
1008
946
							<row>
1009
947
								<entry>wvdial</entry>
1010
948
							</row>
1011
949
						</tbody>
1012
950
					</tgroup>
1013
951
				</informaltable>
1014
952
				<informaltable frame="all">
1015
953
					<tgroup cols="1">
1016
954
						<thead>
1017
955
							<row>
1018
956
								<entry><emphasis role="bold">Maintainer scripts</emphasis> (postinst, postrm, prerm, preinst)</entry>
1019
957
							</row>
1020
958
						</thead>
1021
959
					</tgroup>
1022
960
				</informaltable>
1023
961
				<informaltable frame="all">
1024
962
					<tgroup cols="1">
1025
963
						<thead>
1026
964
							<row>
1027
965
								<entry>Java packages</entry>
1028
966
							</row>
1029
967
						</thead>
1030
968
					</tgroup>
1031
969
				</informaltable>
1032
970
			</sect2>
1033
971
		</sect1>
1034
972
		<sect1 id="patch-systems" status="review">
1035
973
			<title>Patch Systems</title>
1036
974
			<sect2 id="general-tips" status="review">
1037
975
				<title>General Tips</title>
1038
976
				<para>There will almost always be the need to apply patches before building a package. Here are a few patching tips taken from <ulink url="http://wiki.debian.org/Games/ToolsDiscuss">http://wiki.debian.org/Games/ToolsDiscuss</ulink> .</para>
1039
977
				<para>Some tips on how to use patches efficiently (Thanks Linas Žvirblis):</para>
1040
978
				<itemizedlist>
1041
979
					<listitem><para>Provide descriptive file names for your patches: 'fix-loading-libfoo-on-architecture-bar.patch' is a good name, '001.patch' is not;</para></listitem>
1042
980
					<listitem><para>Make your patches stand-alone. Each patch should apply cleanly without depending on any other patch being applied;</para></listitem>
1043
981
					<listitem><para>Avoid modifying the same file in multiple patches;</para></listitem>
1044
982
					<listitem><para>If you absolutely need to create patches that depend on each other, specify that in the filenames: '00patchfoo-do-this.patch', '01patchfoo-do-that.patch' or similar;</para></listitem>
1045
983
					<listitem><para>Do not include multiple unrelated modifications into a single patch;</para></listitem>
1046
984
					<listitem><para>Patch your packages at build time. There is no need to ship a patch plus an already patched source. This only increases the size of the diff.</para></listitem>
1047
985
					<listitem><para>Make sure patch is applied before anything else happens with your package. Make configure rule depend on the patch rule;</para></listitem>
1048
986
					<listitem><para>Clean first, unpatch afterwards. Some files could have been modified during the build so unpatching may fail, unless you restore them. If simply makecleaning the sources does not restore their state, it may be a good idea to make backup copies, for example, in patch rule.</para></listitem>
1049
987
					<listitem><para>Debian policy 3.8.0 imposes that packages specify explicit how to apply their patches when using a patch system (cf. [WWW] <ulink url="http://lists.debian.org/%E2%80%A6ce/2008/06/msg00001.html">http://lists.debian.org/…ce/2008/06/msg00001.html</ulink>). The page <ulink url="https://wiki.ubuntu.com/README.sourceHowTo">README.sourceHowTo</ulink> attempts to collect sample README.source file for each packaging systems.</para></listitem>
1050
988
					<listitem><para>To find out which patch system is used, use what-patch from the ubuntu-dev-tools package (also requires CDBS to be installed):</para>
1051
989
					<programlisting>daniel@lovegood:~/jokosher-0.9$ what-patch
1052
990
cdbs
1053
991
daniel@lovegood:~/jokosher-0.9$
1054
992
</programlisting>
1055
993
					<para>or</para>
1056
994
					<programlisting>daniel@lovegood:~/seahorse-2.22.2$ what-patch
1057
995
quilt
1058
996
daniel@lovegood:~/seahorse-2.22.2$ 
1059
997
</programlisting>
1060
998
					</listitem>
1061
999
				</itemizedlist>
1062
1000
			</sect2>
1063
1001
			<sect2 id="patching-without-a-patch-system" status="review">
1064
1002
				<title>Patching Without a Patch System</title>
1065
1003
				<para>As was mentioned above, one can patch the original source by simply making the changes in the unpacked source directory. A real-life example of this is cron. If you grab cron's source package and look at the .diff.gz you will see that several of the original source's files were changed. </para>
1066
1004
				<screen><command>apt-get source cron
1067
1005
zgrep +++ cron*.diff.gz
1068
1006
</command></screen>
1069
1007
				<para>But as we mentioned before this is not really the best way to represent patches. One better way is to create individual patch files, put them in debian/patches/ and apply the patches (using patch) in debian/rules. This is what is done for udev: </para>
1070
1008
				<screen><command>apt-get source udev
1071
1009
zgrep +++ udev*.diff.gz
1072
1010
ls udev*/debian/patches/
1073
1011
less udev*/debian/rules
1074
1012
</command></screen>
1075
1013
				<para>The rules file has the following rules for applying and unapplying the patches:</para>
1076
1014
				<programlisting>
1077
1015
# Apply patches to the package
1078
1016
patch: patch-stamp
1079
1017
patch-stamp:
1080
1018
        dh_testdir
1081
1019
        @patches=debian/patches/*.patch; for patch in $$patches; do \
1082
1020
                test -f $$patch || continue; \
1083
1021
                echo "Applying $$patch"; \
1084
1022
                patch -stuN -p1 &lt; $$patch || exit 1; \
1085
1023
        done
1086
1024
        touch $@
1087
1025
1088
1026
# Remove patches from the package
1089
1027
unpatch:
1090
1028
        dh_testdir
1091
1029
        @if test -f patch-stamp; then \
1092
1030
                patches=debian/patches/*.patch; \
1093
1031
                for patch in $$patches; do \
1094
1032
                        reversepatches="$$patch $$reversepatches"; \
1095
1033
                done; \
1096
1034
                for patch in $$reversepatches; do \
1097
1035
                        test -f $$patch || continue; \
1098
1036
                        echo "Reversing $$patch"; \
1099
1037
                        patch -suRf -p1 &lt; $$patch || exit 1; \
1100
1038
                done; \
1101
1039
                rm -f patch-stamp; \
1102
1040
        fi
1103
1041
</programlisting>
1104
1042
				<para>That is all very nice, but how do we create new patches for udev using this scheme? The general approach is:</para>
1105
1043
				<orderedlist>
1106
1044
					<listitem><para>copy the clean source tree to a temporary directory</para></listitem>
1107
1045
					<listitem><para>apply all patches up to the one you want to edit; if you want to create a new patch, apply all existing ones (this is necessary since in general patches depend on previous patches)</para>
1108
1046
					<para>if you want, you can use debian/rules for this: remove the patches that come *after* the one you want to edit, and call 'debian/rules patch'. The actual name for the patch target varies, I have seen the following ones so far: patch setup apply-patches unpack patch-stamp. You have to look in debian/rules to see what it is called.</para></listitem>
1109
1047
					<listitem><para>copy the whole source tree again: cp -a /tmp/old /tmp/new</para></listitem>
1110
1048
					<listitem><para>go into /tmp/new, do your modifications</para></listitem>
1111
1049
					<listitem><para>go back into your original source tree, generate the patch with: diff -Nurp /tmp/old /tmp/new &gt; mypatchname.patch</para></listitem>
1112
1050
				</orderedlist>
1113
1051
				<sect3 id="example-1" status="review">
1114
1052
					<title>Example 1.</title>
1115
1053
					<para>Let us make a new patch for udev called 90_penguins.patch which replaces Linux with Penguin in the udev README file:</para>
1116
1054
					<screen><command>cd udev*/
1117
1055
cp -a . /tmp/old
1118
1056
pushd /tmp/old
1119
1057
debian/rules patch
1120
1058
cp -a . /tmp/new; cd ../new
1121
1059
sed -i 's/Linux/Penguin/g' README
1122
1060
cd ..
1123
1061
diff -Nurp old new > 90_penguins.patch
1124
1062
popd
1125
1063
mv /tmp/90_penguins.patch debian/patches
1126
1064
rm -rf /tmp/old /tmp/new
1127
1065
</command></screen>
1128
1066
				</sect3>
1129
1067
				<sect3 id="example-2" status="review">
1130
1068
					<title>Example 2.</title>
1131
1069
					<para>What happens if we want to edit an existing patch? We can us a similar procedure as <link linkend="example-1">Example 1</link> but we will apply the patch to be edited first:</para>
1132
1070
					<screen><command>cp -a . /tmp/old 
1133
1071
pushd /tmp/old
1134
1072
cp -a . /tmp/new
1135
1073
cd ../new; patch -p1 &lt; debian/patches/10-selinux-include-udev-h.patch
1136
1074
sed -i '1 s/$/***** HELLO WORLD ****/' udev_selinux.c 
1137
1075
cd .. 
1138
1076
diff -Nurp old new > 10-selinux-include-udev-h.patch 
1139
1077
popd 
1140
1078
mv /tmp/10-selinux-include-udev-h.patch debian/patches 
1141
1079
rm -rf /tmp/old /tmp/new
1142
1080
</command></screen>
1143
1081
					<para>So this way of patching the source, while technically fine, can become very complicated and unmanageable. To make patching easier and more straightforward patch systems were developed. We will take a look at couple popular ones.</para>
1144
1082
				</sect3>
1145
1083
			</sect2>
1146
1084
			<sect2 id="cdbs-with-simple-patchsys" status="review">
1147
1085
				<title>CDBS with Simple Patchsys</title>
1148
1086
				<para>The CDBS build helper system (see the section called “Packaging With CDBS”) has a very simple patch system built in. You simply need to add an include for simple-patchsys.mk in debian/rules. An example is pmount. Its entire rules looks like:</para>
1149
1087
				<programlisting>include /usr/share/cdbs/1/rules/debhelper.mk 
1150
1088
include /usr/share/cdbs/1/class/autotools.mk 
1151
1089
include /usr/share/cdbs/1/rules/simple-patchsys.mk 
1152
1090
1153
1091
common-post-build-arch:: 
1154
1092
        # Generate a POT file 
1155
1093
        cd po; intltool-update -p --verbose 
1156
1094
</programlisting>
1157
1095
				<para>Simple patchsys also has a patch editor built in called cdbs-edit-patch. You can give cdbs-edit-patch either the name of an existing patch to edit or a new patch to create. It will apply the existing patch, if it exists, and put you in a new shell. You can then make any changes you want added to the patch and finally type Ctrl-D to exit the shell and create the new patch. The patches are stored in debian/patches/</para>
1158
1096
			</sect2>
1159
1097
			<sect2 id="cdbs-with-simple-patchsys-example-package-pmount" status="review">
1160
1098
				<title>cdbs with simple-patchsys (example package: pmount)</title>
1161
1099
				<para>cdbs' simple-patchsys.mk module matches its name; it has no bells and whistles whatsoever. However, it is pretty popular since it is sufficient for most tasks, and long ago Martin Pitt wrote a script 'cdbs-edit-patch' which most people can live with pretty well. This script is contained in the normal cdbs package.</para>
1162
1100
				<para>You just supply the name of a patch to the script, and depending on whether it already exists or not, it will create a new patch or edit an existing one.</para>
1163
1101
				<para>Example with pmount:</para>
1164
1102
				<screen><command>  cd /wherever/you/unpacked/the/source/pmount-0.9.11
1165
1103
  cdbs-edit-patch 03-simple-readme.patch
1166
1104
  echo 'This should document pmount' > README
1167
1105
  &lt;press Ctrl+D to end your editing session&gt;
1168
1106
</command></screen>
1169
1107
				<para>Editing an already-existing patch works exactly the same way.</para>
1170
1108
				<para>Since the Ubuntu Edgy version of cdbs, cdbs-edit-patch also works for packages using tarball.mk, and it can edit patches which produce rejections.</para>
1171
1109
			</sect2>
1172
1110
			<sect2 id="dpatch" status="review">
1173
1111
				<title>dpatch</title>
1174
1112
				<para>A popular patch system is dpatch. It has a dpatch-edit-patch script like cdbs has but stores the patches a little differently. It uses a file named debian/patches/00list to find the name and order of patches to apply. This means you can order your patches in whichever way you want and can disable a patch without removing it altogether. However, it also means you need to update 00list if you add a patch. If dpatch-edit-patch is called with two arguments it will edit/create the patch named by the first argument relative to the patch named by the second argument. In other words:</para>
1175
1113
				<screen><command>dpatch-edit-patch new.dpatch old.dpatch</command></screen>
1176
1114
				<para> will apply patches up to old.dpatch and then create new.dpatch. Note that dpatch patches usually have a .dpatch suffix. This is because dpatch stores the patches in a slightly different format than a normal patch that adds a special header.</para>
1177
1115
			</sect2>
1178
1116
			<sect2 id="quilt-example-package-xterm" status="review">
1179
1117
				<title>quilt (example package: xterm)</title>
1180
1118
				<para>quilt is the other non-dumb standard patch system. Like dpatch, it has a list of patches to apply in debian/patches/series. It is non-trivial to set up and has a lot of advanced commands which make it very flexible, but not very easy to use.</para>
1181
1119
				<para>So I will only show a small example here, too. First, set yourself up to use quilt:</para>
1182
1120
				<screen><command>  cd /wherever/you/unpacked/the/source/
1183
1121
  mkdir debian/patches
1184
1122
  export QUILT_PATCHES=debian/patches
1185
1123
  touch debian/patches/series
1186
1124
</command></screen>
1187
1125
				<para>Note that since QUILT_PATCHES is sent, you cannot use "cd" to move around the source tree and expect quilt to still operate sanely. You need to stay in the top level source directory for any quilt operations.</para>
1188
1126
				<para>Now let's edit the already existing patch 901_xterm_manpage.diff:</para>
1189
1127
				<screen><command>  quilt push 901_xterm_manpage.diff
1190
1128
  sed -i 's/Copyright/Copyleft/' xterm.man
1191
1129
  quilt refresh 901_xterm_manpage.diff
1192
1130
  quilt pop -a
1193
1131
</command></screen>
1194
1132
				<para>So unlike the other patch systems, quilt works with patched inline sources, but keeps track of modifications.</para>
1195
1133
				<para>Finally, let's add a new patch to the top of the stack:</para>
1196
1134
				<screen><command>  quilt push -a
1197
1135
  quilt new muhaha.diff
1198
1136
  quilt add README  # you have to do that for all files you modify
1199
1137
  sed -i '1 s/^/MUHAHA/' README
1200
1138
  quilt refresh
1201
1139
  quilt pop -a
1202
1140
</command></screen>
1203
1141
			</sect2>
1204
1142
			<sect2 id="patcihng-other-peoples-packages" status="review">
1205
1143
				<title>Patching other people's packages</title>
1206
1144
				<para>The most important thing to keep in mind when patching packages maintained by other people is to keep the patch system (or lack thereof) that the maintainer has set up. This will ensure consistency and make the package maintainer more likely to accept your patch.</para>
1207
1145
				<para>It is also a good idea to separate patches logically rather than creating one giant patch. If the upstream authors apply one of your changes but not another it is much easier to just drop a patch than edit a monolithic patch to update it.</para>
1208
1146
			</sect2>
1209
1147
		</sect1>
1210
1148
		<sect1 id="kde" status="review">
1211
1149
			<title>KDE</title>
1212
1150
			<para>The <link linkend="basic-packaging">basic packaging</link> section in the <ulink url="https://wiki.ubuntu.com/PackagingGuide">PackagingGuide</ulink> will explain the basic, while this page tries to explain KDE specific bits.</para>
1213
1151
			<para>If it's not already done, you have to install all the software listed in the <ulink url="http://www.nl.debian.org/doc/maint-guide/ch-start.en.html#s-needprogs">Debian New Maintainer's Guide</ulink> and the <ulink url="http://www.debian.org/doc/manuals/developers-reference/">Debian Developer's Reference</ulink>.</para>
1214
1152
			<para>Also recommended are</para>
1215
1153
			<itemizedlist>
1216
1154
				<listitem><para>the kdesdk package which furnish many useful applications and scripts and</para></listitem>
1217
1155
				<listitem><para>docbook2x, because it can be useful to convert docbook into man pages (remember debian policy implies that every single application has a man page!).</para></listitem>
1218
1156
			</itemizedlist>
1219
1157
			<sect2 id="essential-packaging-bits" status="review">
1220
1158
				<title>Essential Packaging Bits</title>
1221
1159
				<para>KDE 3 applications usually use the GNU autoconf/automake build system. There is a CDBS include file designed for KDE.</para>
1222
1160
				<programlisting>include /usr/share/cdbs/1/class/kde.mk</programlisting>
1223
1161
				<para>You will need to build-dep on kdelibs4-dev and, if the package build kcontrol modules, kdebase-dev.</para>
1224
1162
				<screen><command>make -f debian/rules buildprep</command></screen>
1225
1163
				<para>This is also necessary if your upstream has not already run this, e.g. if there is no configure file.</para>
1226
1164
				<para>KDE 4 applications use a new build system, CMake. The way we build KDE 4 packages is still changing so there is no file included in CDBS yet. You can get a suitable kde.mk by downloading the source for kde4libs and copying debian/cdbs.</para>
1227
1165
				<programlisting>include debian/cdbs/kde.mk</programlisting>
1228
1166
				<para>You will need to build-depend on kdelibs5-dev and sometimes also libphonon-dev and kdepimlibs5-dev.</para>
1229
1167
				<para>If there is already a KDE 3 application with the same name in the archive, rename the package to &lt;appname&gt;-kde4.</para>
1230
1168
				<sect3 id="kde-manpages" status="review">
1231
1169
					<title>KDE Manpages</title>
1232
1170
					<para>A template of a KDE manpage can be found here <ulink url="http://people.ubuntu.com/~dholbach/packagingguide/kde/sample.1.docbook">http://people.ubuntu.com/~dholbach/packagingguide/kde/sample.1.docbook</ulink></para>
1233
1171
					<para>This file is a standard file for a basic KDE application. Customize it for your application and check that every important command line option is described in detail. If you don't want to edit the file by hand, install the manedit package and type</para>
1234
1172
					<screen><command>manedit [manpage name or file]</command></screen>
1235
1173
					<para>Add a build-depend on docbook2x in debian/control.</para>
1236
1174
					<para>After that just add this line to the debian/rules file (assuming the name of the binary package is myapp):</para>
1237
1175
					<programlisting>build/myapp::
1238
1176
        docbook2x-man debian/myapp.1.docbook
1239
1177
1240
1178
cleanbuilddir/myapp::
1241
1179
        rm -f myapp.1
1242
1180
1243
1181
DEB_INSTALL_MANPAGES_myapp = myapp.1
1244
1182
</programlisting>
1245
1183
					<para>Of course you have to replace myapp.1.docbook with your manual source file. You also have to add a docbook2x build dependency to the debian/control file. If you have more than one manpage to install (e.g. if your .deb installs a program and its daemon) simply separate their names with a space:</para>
1246
1184
					<programlisting>DEB_INSTALL_MANPAGES_myapp = myapp.1 myappdaemon.8</programlisting>
1247
1185
					<para>As an alternative you can use the kdemangen.pl script to generate a man page based on the command line help of the program.</para>
1248
1186
				</sect3>
1249
1187
			</sect2>
1250
1188
		</sect1>
1251
1189
		<sect1 id="supplementary-files" status="review">
1252
1190
			<title>Supplementary Files</title>
1253
1191
			<sect2 id="desktop-files" status="review">
1254
1192
				<title>.desktop Files</title>
1255
1193
				<para>In order to ensure that the menus are properly populated, and that software is easily installable with Add/Remove Packages, each package should contain a .desktop file. As a matter of policy, .desktop files should only be present for GUI interfaces: software intended to be used from the command-line should not provide such an interface.</para>
1256
1194
				<para>.desktop files may be included in packages in two ways, either as part of the upstream distribution, or as part of the distribution packaging. Including the .desktop file in the upstream distribution is vastly preferred, as this allows for appropriate translation of the .desktop file. If it cannot be included upstream, the .desktop file should be stored in the debian/ directory.</para>
1257
1195
				<para>Criteria for the inclusion of .desktop files:</para>
1258
1196
				<orderedlist>
1259
1197
					<listitem><para>The package must provide a binary with a GUI interface</para></listitem>
1260
1198
					<listitem><para>The binary must be typically executed with constant arguments</para></listitem>
1261
1199
					<listitem><para>Users would expect to launch the program from the menu</para></listitem>
1262
1200
				</orderedlist>
1263
1201
				<para>Packages typically not needing a .desktop file are: Window Managers, programs that do not have sensible defaults, programs that only act on files (rather than having a standard interface), programs that have no GUI, programs that start up invisible.</para>
1264
1202
				<para>Some packaging notes:</para>
1265
1203
				<itemizedlist>
1266
1204
					<listitem><para>In debian/control, if cdbs is not used, Build-Depend on debhelper (&gt;= 4.2.21).</para></listitem>
1267
1205
					<listitem><para>In debian/rules, if cdbs's gnome.mk is not used, call dh_desktop in binary*</para></listitem>
1268
1206
					<listitem><para>ensure that .desktop files are installed or moved to /usr/share/applications/&lt;binary&gt;.desktop</para></listitem>
1269
1207
					<listitem><para>ensure that icon files are installed or moved to /usr/share/pixmaps/</para></listitem>
1270
1208
				</itemizedlist>
1271
1209
				<para>Some ideas about icons:</para>
1272
1210
				<itemizedlist>
1273
1211
					<listitem><para>Provide an 32x32 pixel XPM icon for use by the Debian menus</para></listitem>
1274
1212
					<listitem><para>Optionally provide a 48x48 pixel PNG icon for use by freedesktop.org menus (the Debian icon will be used if this is unavailable)</para></listitem>
1275
1213
					<listitem><para>If neither format is available, many formats can be converted as follows:</para>
1276
1214
					<orderedlist>
1277
1215
						<listitem><para>Get a base icon (clip of package graphic, .ico file, from scratch, etc.)</para></listitem>
1278
1216
						<listitem><para>Crop / resize to 32x32 pixels</para></listitem>
1279
1217
						<listitem><para>run convert editedicon.ico &lt;package&gt;.xpm (requires imagemagick)</para></listitem>
1280
1218
						<listitem><para>if convert generated multiple images, select one (and name correctly)</para></listitem>
1281
1219
					</orderedlist>
1282
1220
					</listitem>
1283
1221
				</itemizedlist>
1284
1222
				<para>About .desktop files generally:</para>
1285
1223
				<itemizedlist>
1286
1224
					<listitem><para>Check the spec at <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">http://standards.freedesktop.org/desktop-entry-spec/latest/</ulink></para></listitem>
1287
1225
					<listitem><para>Avoid Absolute pathnames in .desktop files</para></listitem>
1288
1226
					<listitem><para>Do not include a file type extension in Icon=</para></listitem>
1289
1227
					<listitem><para>Ensure that Categories= includes at least one Registered Category</para></listitem>
1290
1228
					<listitem><para>Add any other applicable Additional Categories</para></listitem>
1291
1229
					<listitem><para>Check with desktop-file-validate to ensure everything is correct</para></listitem>
1292
1230
				</itemizedlist>
1293
1231
				<para>The Workflow:</para>
1294
1232
				<itemizedlist>
1295
1233
					<listitem><para>Find a package without a .desktop file</para></listitem>
1296
1234
					<listitem><para>Verify there is no .desktop file in the latest development version</para></listitem>
1297
1235
					<listitem><para>If no .desktop file is needed, add the package to the list below</para></listitem>
1298
1236
					<listitem><para>If a .desktop is needed:</para>
1299
1237
						<orderedlist>
1300
1238
							<listitem><para>Check to see if there is a .desktop in the upstream or Debian bug tracker</para></listitem>
1301
1239
							<listitem><para>Create the necessary .desktop / icon if necessary</para></listitem>
1302
1240
							<listitem><para>Open a wishlist bug in the package reporting the missing .desktop file</para></listitem>
1303
1241
							<listitem><para>Attach the .desktop file and icon to the bug (optionally a patch for both)</para></listitem>
1304
1242
							<listitem><para>Link the bug to the Debian BTS (create a BTS bug if required)</para></listitem> 
1305
1243
							<listitem><para>Tag the bug with "desktop-file"</para></listitem>
1306
1244
						</orderedlist>
1307
1245
					</listitem>
1308
1246
				</itemizedlist>
1309
1247
				<para>Simple Creation techniques:</para>
1310
1248
				<itemizedlist>
1311
1249
					<listitem><para>In GNOME: use Nautilus' "Create Launcher" to create a template file</para></listitem>
1312
1250
					<listitem><para>Scripted: Some of this can be automated. Please check the results of the automation prior to submission. Most importantly, please ensure that any useful additional categories are included.</para></listitem>
1313
1251
				</itemizedlist>
1314
1252
				<para>Shell sniplets that might prove useful:</para>
1315
1253
				<itemizedlist>
1316
1254
					<listitem><para>Using an absolute path for an icon:</para>
1317
1255
					<screen><command>grep -E "^Icon=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate</command></screen></listitem>
1318
1256
					<listitem><para>Using an absolute path for a binary:</para>
1319
1257
					<screen><command>grep -E "^Exec=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate</command></screen></listitem>
1320
1258
					<listitem><para>.desktop file fails validation:</para>
1321
1259
					<screen><command>for i in /usr/share/applications; do desktop-file-validate $i &gt;&gt; /dev/null || echo $i; done | xargs dlocate</command></screen></listitem>
1322
1260
				</itemizedlist>
1323
1261
				<para>A minimal desktop file for a program to appear in the application menu looks like this:</para>
1324
1262
				<programlisting>[Desktop Entry]
1325
1263
Type=Application
1326
1264
Name=foo
1327
1265
Name[xx]=foo
1328
1266
GenericName=Bar description
1329
1267
Exec=kfoo
1330
1268
Icon=kfoo
1331
1269
Terminal=false
1332
1270
Categories=Qt;KDE;Utility;
1333
1271
</programlisting>
1334
1272
				<para>You should ensure that the icon pointed to by Icon= exists in the hicolor namespace and not in the crystalsvg or oxygen themes, this is so it can be found by Gnome and other desktops.</para>
1335
1273
				<para>Some notes about KDE .desktop files:</para>
1336
1274
				<para>KDE also uses .desktop files to describe many resources such as libraries to be loaded or kcontrol modules.</para>
1337
1275
				<para>.desktop files for applications should be in /usr/share/applications/kde for KDE 3 or /usr/share/applications/kde4 for KDE 4.</para>
1338
1276
				<para>Sometimes packages install the desktop file in the old directory (/usr/share/applnk). You may want to copy the furnished desktop file to the new location (/usr/share/applications/kde). Add these lines to debian/rules:</para>
1339
1277
				<programlisting>install/myapp::
1340
1278
    #other stuff
1341
1279
    dh_install desktop_file usr/share/applications/kde
1342
1280
</programlisting>
1343
1281
			</sect2>
1344
1282
			<sect2 id="man-pages" status="review">
1345
1283
				<title>Man Pages</title>
1346
1284
				<sect3 id="using-pod" status="review">
1347
1285
					<title>Using POD</title>
1348
1286
					<para>POD is a very simple but also elegant format for writing manual pages. It is much easier to learn than writing it directly in groff or using other alternatives like docbook.</para>
1349
1287
				</sect3>
1350
1288
				<sect3 id="basic-template" status="review">
1351
1289
					<title>Basic template</title>
1352
1290
					<para>Below is a sample manpage template in POD format. Customize it for your application and check that every important command line option is described in detail. You can see a real example here.</para>
1353
1291
					<programlisting>=head1 NAME
1354
1292
1355
1293
Command - Short one-line description.
1356
1294
1357
1295
=head1 SYNOPSIS
1358
1296
1359
1297
command [options...]
1360
1298
1361
1299
=head1 DESCRIPTION
1362
1300
1363
1301
Command is a foo that does bar.
1364
1302
1365
1303
=head1 OPTIONS
1366
1304
1367
1305
=over 8
1368
1306
1369
1307
=item B&lt;--key=I&lt;value&gt;&gt;
1370
1308
1371
1309
Uses the given value as key.
1372
1310
1373
1311
=item B&lt;--moo&gt;
1374
1312
1375
1313
Shows an easter egg (don't explain this in real man pages ;)).
1376
1314
1377
1315
=item B&lt;--stupid-example&gt;
1378
1316
1379
1317
Doesn't do anything.
1380
1318
1381
1319
=item B&lt;--version&gt;
1382
1320
1383
1321
Displays information about the currently installed version and exists.
1384
1322
1385
1323
=head1 BUGS
1386
1324
1387
1325
This command has absolutely no bugs, as I have written it. Also, as it has no bugs, there is no need for a bug tracker.
1388
1326
1389
1327
=head1 AUTHORS
1390
1328
1391
1329
B&lt;command&gt; was written by Joe Hacker &lt;joe.hacker@example.com&gt; and John Dough &lt;guy1268@example.net&gt;. This manual page was written by Cool Packager &lt;myself@example.com&gt;.
1392
1330
1393
1331
Both are released under the GNU General Public License, version 3 or later.
1394
1332
1395
1333
=cut
1396
1334
</programlisting>
1397
1335
				</sect3>
1398
1336
				<sect3 id="some-formatting-options" status="review">
1399
1337
					<title>Some formatting options</title>
1400
1338
					<programlisting>B&lt;...text...&gt;  -  "...text..." will be shown in bold.
1401
1339
I&lt;...text...&gt;  -  "...text..." will be shown in italics.
1402
1340
</programlisting>			<para>Usually, the command name is always written in bold (except in the NAME and SYNOPSIS sections), and variables that the user should replace in italics (as in --key=I&lt;value&gt;).</para>
1403
1341
				</sect3>
1404
1342
				<sect3 id="neccessary-packaging-changes" status="review">
1405
1343
					<title>Necessary packaging changes</title>
1406
1344
					<para>- Add a build dependency on 'perl' in debian/control.</para>
1407
1345
					<para>- After that just add this line to the debian/rules file (assuming the name of the binary package is 'myapp' and that it is using cdbs):</para>
1408
1346
					<programlisting>build/myapp::
1409
1347
        pod2man --section=1 --release=$(VERSION) --center "" debian/myapp.pod &gt; myapp.1
1410
1348
1411
1349
cleanbuilddir/myapp::
1412
1350
        rm -f myapp.1
1413
1351
1414
1352
DEB_INSTALL_MANPAGES_myapp = myapp.1
1415
1353
</programlisting>
1416
1354
					<para>Of course you have to replace 'myapp.pod' with the name of your manpage source file, and the section number with that one corresponding to what you are documenting (see 'man man' for a list of all sections). </para>
1417
1355
					<para>If you have more than one manpage to install (e.g. if your .deb installs a program and its daemon) simply separate their names with a space:</para>
1418
1356
					<programlisting>DEB_INSTALL_MANPAGES_myapp = myapp.1 myappdaemon.8</programlisting>
1419
1357
				</sect3>
1420
1358
			</sect2>
1421
1359
		</sect1>
1422
1360
		<sect1 id="recipes" status="review">
1423
1361
			<title>Recipes</title>
1424
1362
			<sect2 id="recipe-updating-an-ubuntu-package" status="review">
1425
1363
				<title>Recipe: Updating An Ubuntu Package</title>
1426
1364
				<sect3 id="introduction2" status="review">
1427
1365
					<title>Introduction</title>
1428
1366
					<para>In this recipe we'll update brasero 0.5.2-0ubuntu1 to 0.6.1-0ubuntu1. This should give you a good introduction to updating packages to a new upstream version.</para>
1429
1367
				</sect3>
1430
1368
				<sect3 id="ingredients" status="review">
1431
1369
					<title>Ingredients</title>
1432
1370
					<orderedlist>
1433
1371
						<listitem><para>To sign the package once it's finished, you'll need a GPG key. See the <ulink url="https://help.ubuntu.com/community/GnuPrivacyGuardHowto">GnuPrivacyGuardHowto</ulink> for a guide.</para></listitem>
1434
1372
						<listitem><para>The debian packaging tools use some environment variables to put your name and e-mail address in the changelog and to find your GPG key ID. To set these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:</para>
1435
1373
						<programlisting>export DEBFULLNAME='Daniel Holbach'
1436
1374
export DEBEMAIL='daniel.holbach@ubuntu.com'</programlisting>
1437
1375
						<para>to make these changes take affect, start a new terminal or type source ~/.bashrc in the terminal.</para></listitem>
1438
1376
						<listitem><para>pbuilder is a very handy command used to test-build packages. See the <ulink url="https://wiki.ubuntu.com/PbuilderHowto">PbuilderHowto</ulink> for a guide to setting it up for the active development release.</para></listitem>
1439
1377
						<listitem><para>Install some necessary tools:</para></listitem>
1440
1378
						<listitem><screen><command>sudo apt-get install devscripts build-essential wget cdbs fakeroot liburi-perl debhelper pbuilder dpatch quilt gnome-pkg-tools</command></screen></listitem>
1441
1379
					</orderedlist>
1442
1380
				</sect3>
1443
1381
				<sect3 id="method" status="review">
1444
1382
					<title>Method</title>
1445
1383
					<orderedlist>
1446
1384
						<listitem><para>Get the source of the old brasero package.</para>
1447
1385
						<para>For that, you'd usually just run apt-get source brasero. As this is just an example, you can run:</para>
1448
1386
						<screen><command>dget -xu http://people.ubuntu.com/~dholbach/motu/brasero_0.5.2-0ubuntu1.dsc</command></screen></listitem>
1449
1387
						<listitem><para>Get the new source.</para>
1450
1388
						<para>Usually, you'd look up from where the old version was downloaded (check debian/copyright) and use the source from there. But as this is a prepared example...:</para>
1451
1389
						<screen><command>wget http://people.ubuntu.com/~dholbach/motu/brasero-0.6.1.tar.gz</command></screen></listitem>
1452
1390
						<listitem><para>Unpack and rename the new source tarball:</para>
1453
1391
						<screen><command>tar xfz brasero-0.6.1.tar.gz
1454
1392
mv brasero-0.6.1.tar.gz brasero_0.6.1.orig.tar.gz
1455
1393
</command></screen>
1456
1394
						<para>(If you use the &lt;package name&gt;_&lt;version&gt;.orig.tar.gz scheme, a .diff.gz file will be created automatically during one of the next steps that contains all your changes regarding the Upstream Tarball.)</para></listitem>
1457
1395
						<listitem><para>Copy the packaging over into the new source tree:</para>
1458
1396
						<screen><command>cp -r brasero-0.5.2/debian brasero-0.6.1/</command></screen></listitem>
1459
1397
						<listitem><para>Add a debian/changelog entry:</para>
1460
1398
						<screen><command>cd brasero-0.6.1
1461
1399
dch -i
1462
1400
</command></screen>
1463
1401
						<para>Here you enter something like "New upstream version" and make sure the version number is 0.6.1-0ubuntu1.</para></listitem>
1464
1402
						<listitem><para>Create the source package from it:</para>
1465
1403
						<screen><command>debuild -S -sa</command></screen></listitem>
1466
1404
						<listitem><para>Try to build it:</para>
1467
1405
						<screen><command>cd ..
1468
1406
sudo pbuilder build brasero_0.6.1-0ubuntu1.dsc
1469
1407
</command></screen></listitem>
1470
1408
						<listitem><para>DONE **Note: This package does not build using pbuilder in Intrepid. It looks like the old brasero package uses an older version of GCC. You should not have this problem when you build other packages.</para></listitem>
1471
1409
					</orderedlist>
1472
1410
				</sect3>
1473
1411
				<sect3 id="for-bonus-points" status="review">
1474
1412
					<title>For Bonus Points...</title>
1475
1413
					<orderedlist>
1476
1414
						<listitem><para>Check configure.in for changes you need to reflect in the packaging:</para>
1477
1415
						<screen><command>diff -u brasero-0.{5.2,6.1}/configure.in</command></screen>
1478
1416
						<para>Sometimes this file might be called configure.ac. Most software programmed in C or C++ has this file which generates checks during the configure run of the build.BR If you look closely, you'll notice that most changes are reformatting and only</para>
1479
1417
						<programlisting>-LIBBURN_REQUIRED=0.2.3
1480
1418
+LIBBURN_REQUIRED=0.3.4
1481
1419
</programlisting>
1482
1420
						<para>might be relevant to us. In debian/control you'll see that we don't use libburn, so we're done here.</para></listitem>
1483
1421
						<listitem><para>Read the NEWS file before:</para>
1484
1422
						<screen><command>less brasero-0.6.1/NEWS</command></screen>
1485
1423
						<para>This file (if the upstream project uses it) contains valuable information about what the package update is about. As a maintainer you want to know what's been going on.</para></listitem>
1486
1424
						<listitem><para>Compare the contents of the old vs. the new package:</para>
1487
1425
						<screen><command>wget http://people.ubuntu.com/~dholbach/motu/brasero_0.5.2-0ubuntu1_i386.deb
1488
1426
debdiff brasero_0.5.2-0ubuntu1_i386.deb /var/cache/pbuilder/result/brasero_0.6.1-0ubuntu1*.deb
1489
1427
</command></screen>
1490
1428
						<orderedlist>
1491
1429
							<listitem><para>The output will show you that some icons have been replaced with others and some translations were added. Nothing to worry about. All looks good.</para></listitem>
1492
1430
							<listitem><para>To download the old package, you would normally run something like</para>
1493
1431
							<screen><command>aptitude download brasero</command></screen></listitem>
1494
1432
						</orderedlist></listitem>
1495
1433
						<listitem><para>Get working on upgrade bugs: <ulink url="https://bugs.launchpad.net/ubuntu/+bugs?field.tag=upgrade">https://bugs.launchpad.net/ubuntu/+bugs?field.tag=upgrade</ulink></para></listitem>
1496
1434
					</orderedlist>
1497
1435
				</sect3>
1498
1436
			</sect2>
1499
1437
			<sect2 id="creating-a-debdiff" status="review">
1500
1438
				<title>Creating a Debdiff</title>
1501
1439
				<sect3 id="introduction3" status="review">
1502
1440
					<title>Introduction</title>
1503
1441
					<para>In this recipe we'll fix a simple problem with a package and create a debdiff which you can send to others or attach to bug reports to fix a package.</para>
1504
1442
				</sect3>
1505
1443
				<sect3 id="ingredients2" status="review">
1506
1444
					<title>Ingredients</title>
1507
1445
					<orderedlist>
1508
1446
						<listitem><para>The debian packaging tools use some environment variables to put your name and e-mail address in the changelog and to find your GPG key ID. To set these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:</para>
1509
1447
						<programlisting>export DEBFULLNAME='Daniel Holbach'
1510
1448
export DEBEMAIL='daniel.holbach@ubuntu.com'
1511
1449
</programlisting>
1512
1450
						<para>to make these changes take effect, start a new terminal or type source ~/.bashrc in the terminal.</para></listitem>
1513
1451
						<listitem><para>pbuilder is a very handy command used to test-build packages. See the <ulink url="https://wiki.ubuntu.com/PbuilderHowto">PbuilderHowto</ulink> for a guide to setting it up for the active development release.</para></listitem>
1514
1452
						<listitem><para>Install some necessary tools:</para>
1515
1453
						<screen><command>sudo apt-get install devscripts build-essential wget fakeroot cdbs patchutils debhelper</command></screen></listitem>
1516
1454
						<listitem><para>To sign the package once it's finished, you'll need a GPG key. See the <ulink url="https://help.ubuntu.com/community/GnuPrivacyGuardHowto">GnuPrivacyGuardHowto</ulink> for a guide. Note that this is only important if you plan to upload the result to a access-restricted archive directly : most of the time it is not important when creating a debdiff.</para></listitem>
1517
1455
					</orderedlist>
1518
1456
				</sect3>
1519
1457
				<sect3 id="method2" status="review">
1520
1458
					<title>Method</title>
1521
1459
					<orderedlist>
1522
1460
						<listitem><para>Let's pretend we got a bug report saying that colour in the description of xicc should be color and we want to fix it. (This is just a bad joke and a bad example.) First verify if that's true:</para>
1523
1461
						<programlisting>$ apt-cache show xicc
1524
1462
Package: xicc
1525
1463
Priority: optional
1526
1464
Section: universe/x11
1527
1465
Installed-Size: 72
1528
1466
Maintainer: Ross Burton &lt;ross@debian.org&gt;
1529
1467
Architecture: amd64
1530
1468
Version: 0.2-2
1531
1469
Depends: libc6 (&gt;= 2.3.4-1), libglib2.0-0 (&gt;= 2.8.0), libice6, libsm6, libx11-6
1532
1470
Filename: pool/universe/x/xicc/xicc_0.2-2_amd64.deb
1533
1471
Size: 8224
1534
1472
MD5sum: a266d60cd721ef91fcb1d3d47ecd6a40
1535
1473
SHA1: b8da21b8dfba7ed9c7ac6fa5c9c3e70b438d7124
1536
1474
SHA256: 635c287a1c43df31670a20194e774561479d70d981bf24c143c3711799bd839a
1537
1475
Description: set the ICC colour profile for an X display
1538
1476
 This utility lets you set an ICC colour profile for an X display, so that
1539
1477
 applications can use it to display colour calibrated images.  Applications have
1540
1478
 to specifically look for this atom but several applications such as Gimp and
1541
1479
 Eye Of Gnome already do.
1542
1480
Bugs: mailto:ubuntu-users@lists.ubuntu.com
1543
1481
Origin: Ubuntu
1544
1482
</programlisting></listitem>
1545
1483
						<listitem><para>Time to act on it... get the source of the package:</para>
1546
1484
						<screen><command>dget -xu http://people.ubuntu.com/~dholbach/motu/xicc_0.2-2.dsc</command></screen>
1547
1485
						<para>(We would typically do this with "apt-get source xicc"; dget is used in this example to grab this specific file)</para></listitem>
1548
1486
						<listitem><para>Edit debian/control and fix colour:</para>
1549
1487
						<screen><command>cd xicc-0.2
1550
1488
sed -i 's/colour/color/g' debian/control
1551
1489
</command></screen>
1552
1490
						<para>Of course patching is not always that easy and you might have to patch bigger parts of the package. Please refer to our <ulink url="https://wiki.ubuntu.com/UbuntuDevelopment/Patches">Patch guidelines</ulink>.</para></listitem>
1553
1491
						<listitem><para>Adhere to <ulink url="https://wiki.ubuntu.com/DebianMaintainerField">DebianMaintainerField</ulink>: Edit debian/control and replace</para>
1554
1492
						<programlisting>Maintainer: Ross Burton &lt;ross@debian.org&gt;</programlisting>
1555
1493
						<para>with</para>
1556
1494
						<programlisting>Maintainer: Ubuntu MOTU Developers &lt;ubuntu-motu@lists.ubuntu.com&gt;
1557
1495
XSBC-Original-Maintainer: Ross Burton &lt;ross@debian.org&gt;
1558
1496
</programlisting>
1559
1497
						<para>You can use the update-maintainer tool (in the ubuntu-dev-tools package) for that.</para></listitem>
1560
1498
						<listitem><para>Update debian/changelog:</para>
1561
1499
						<screen><command>dch -i</command></screen>
1562
1500
						<para>and describe the changes you did.</para></listitem>
1563
1501
						<listitem><para>Generate a new source package:</para>
1564
1502
						<screen><command>debuild -S</command></screen>
1565
1503
						<para>or if you're creating an unsigned package:</para>
1566
1504
						<screen><command>debuild -S -us -uc</command></screen></listitem>
1567
1505
						<listitem><para>Look at the debdiff:</para>
1568
1506
						<screen><command>cd ..
1569
1507
debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc | less
1570
1508
</command></screen></listitem>
1571
1509
						<listitem><para>To create a patch file that you can send to others, run</para>
1572
1510
						<screen><command>debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc &gt; xicc_0.2.2ubuntu1.debdiff</command></screen></listitem>
1573
1511
						<listitem><para>And we're done. You can now attach the debdiff to a bug report or send it to the relevant person. <ulink url="https://wiki.ubuntu.com/SponsorshipProcess">SponsorshipProcess</ulink> explains how to get a package uploaded to Ubuntu.</para></listitem>
1574
1512
					</orderedlist>
1575
1513
				</sect3>
1576
1514
			</sect2>
1577
1515
			<sect2 id="creaitng-and-using-a-debian-watch-file" status="review">
1578
1516
				<title>Creating and Using a debian/watch File</title>
1579
1517
				<sect3 id="introduction4" status="review">
1580
1518
					<title>Introduction</title>
1581
1519
					<para>This should show you why it is important to add a debian/watch file to your package and how easy it is to upload a new upstream version.</para>
1582
1520
					<para>Note: the method is exactly the same for an Ubuntu package, just change revision number in changelog version.</para>
1583
1521
				</sect3>
1584
1522
				<sect3 id="ingredients3" status="review">
1585
1523
					<title>Ingredients</title>
1586
1524
					<orderedlist>
1587
1525
						<listitem><para>To sign the package once it is ready, you will need a GPG key. See <ulink url="https://help.ubuntu.com/community/GnuPrivacyGuardHowto">GnuPrivacyGuardHowto</ulink> for a guide.</para></listitem>
1588
1526
						<listitem><para>Debian packaging tools use some environment variables to put your name and e-mail address in the changelog and to find your GPG key ID. To set these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:</para>
1589
1527
						<programlisting>export DEBFULLNAME='Arthur Loiret'
1590
1528
export DEBEMAIL='arthur.loiret@gmail.com'
1591
1529
</programlisting>
1592
1530
						<para>to make these changes take effect, start a new terminal or type source ~/.bashrc in the terminal.</para></listitem>
1593
1531
						<listitem><para>pbuilder is a very handy command used to test-build packages. See the <ulink url="https://wiki.ubuntu.com/PbuilderHowto">PbuilderHowto</ulink> for a guide on how to set it up for the current development release.</para></listitem>
1594
1532
						<listitem><para>Install some necessary tools:</para>
1595
1533
						<screen><command>sudo apt-get install devscripts build-essential wget fakeroot</command></screen></listitem>
1596
1534
					</orderedlist>
1597
1535
				</sect3>
1598
1536
				<sect3 id="method3" status="review">
1599
1537
					<title>Method</title>
1600
1538
					<para>In this recipe we will update medit 0.8.5-1 to 0.9.4-0ubuntu1 using uscan and uupdate.</para>
1601
1539
					<orderedlist>
1602
1540
						<listitem><para>Get the source of the current medit (0.8.5) package. Run:</para>
1603
1541
						<screen><command>dget -xu http://people.ubuntu.com/~dholbach/motu/medit_0.8.5-1.dsc</command></screen></listitem>
1604
1542
						<listitem><para>Now, instead of getting new upstream sources by hand, we are going to add a debian/watch file, which is going to allow us to check automatically new upstream versions using uscan.
1605
1543
The very first line of the watch file must be the format version, currently 3, and then other lines can contain urls to parse.
1606
1544
For example, we are going to try</para>
1607
1545
						<programlisting>version=3
1608
1546
1609
1547
http://sf.net/mooedit/medit-(\d.*)\.tar\.bz2
1610
1548
</programlisting>
1611
1549
						<para>As you can see the syntax for [<ulink url="http://sourceforge.net/">http://sourceforge.net</ulink> SourceForge] projects is http://sf.net/&lt;project_name&gt;/&lt;tarball_name_with_regex&gt; (Also note that if the project is tar.gz, you must change the bz2 to gz, see the man page of [<ulink url="http://dehs.alioth.debian.org/uscan.html">http://dehs.alioth.debian.org/uscan.html</ulink> uscan] for more information).</para></listitem>
1612
1550
						<listitem><para>Then, we are going to run uscan to ensure the debian/watch works, run in sources directory:</para>
1613
1551
						<programlisting>uscan --verbose
1614
1552
-- Scanning for watchfiles in .
1615
1553
-- Found watchfile in ./debian
1616
1554
-- In debian/watch, processing watchfile line:
1617
1555
   http://sf.net/mooedit/medit-(\d.*)\.tar\.bz2 
1618
1556
-- Found the following matching hrefs:
1619
1557
     medit-0.6.98.tar.bz2
1620
1558
     medit-0.6.99.tar.bz2
1621
1559
     medit-0.7.0.tar.bz2
1622
1560
     medit-0.7.1.tar.bz2
1623
1561
     medit-0.7.9.tar.bz2
1624
1562
     medit-0.7.95.tar.bz2
1625
1563
     medit-0.7.96.tar.bz2
1626
1564
     medit-0.7.97.tar.bz2
1627
1565
     medit-0.8.0.tar.bz2
1628
1566
     medit-0.8.1.tar.bz2
1629
1567
     medit-0.8.10.tar.bz2
1630
1568
     medit-0.8.11.tar.bz2
1631
1569
     medit-0.8.2.tar.bz2
1632
1570
     medit-0.8.3-b20060223.tar.bz2
1633
1571
     medit-0.8.3.tar.bz2
1634
1572
     medit-0.8.4.tar.bz2
1635
1573
     medit-0.8.5.tar.bz2
1636
1574
     medit-0.8.6.tar.bz2
1637
1575
     medit-0.8.7.tar.bz2
1638
1576
     medit-0.8.8.tar.bz2
1639
1577
     medit-0.8.9.tar.bz2
1640
1578
     medit-0.9.0.tar.bz2
1641
1579
     medit-0.9.1.tar.bz2
1642
1580
     medit-0.9.2.tar.bz2
1643
1581
     medit-0.9.3.tar.bz2
1644
1582
     medit-0.9.4.tar.bz2
1645
1583
Newest version on remote site is 0.9.4, local version is 0.8.5
1646
1584
 => Newer version available from
1647
1585
    http://qa.debian.org/watch/sf.php/mooedit/medit-0.9.4.tar.bz2
1648
1586
-- Downloading updated package medit-0.9.4.tar.bz2
1649
1587
-- Successfully downloaded updated package medit-0.9.4.tar.bz2
1650
1588
    and symlinked medit_0.9.4.orig.tar.bz2 to it
1651
1589
-- Scan finished
1652
1590
</programlisting>
1653
1591
						<para>Perfect, we have just got the new upstream version :)</para></listitem>
1654
1592
						<listitem><para>Have a look at the new orig tarball name. Just type:</para>
1655
1593
						<programlisting>ls ..
1656
1594
medit-0.8.5/  medit_0.8.5-1.diff.gz  medit_0.8.5-1.dsc  medit_0.8.5.orig.tar.gz  medit_0.9.4.orig.tar.bz2  medit-0.9.4.tar.bz2</programlisting>
1657
1595
						<para>So, new orig tarball's name is medit_0.9.4.orig.tar.bz2. Don't worry about the archive type, uupdate supports .tar.gz, .tar.bz2, .tar.Z, .tgz, .tar and .zip formats, but if you still have doubts about the new orig tarball format, please read [<ulink url="https://wiki.ubuntu.com/PackagingGuide/Basic#ChangingOrigTarball">https://wiki.ubuntu.com/PackagingGuide/Basic#ChangingOrigTarball</ulink> this]</para></listitem>
1658
1596
						<listitem><para>Run uupdate on new orig tarball:</para>
1659
1597
						<programlisting>uupdate ../medit_0.9.4.orig.tar.bz2
1660
1598
New Release will be 0.9.4-0ubuntu1.
1661
1599
-- Untarring the new sourcecode archive ../medit_0.9.4.orig.tar.bz2
1662
1600
8 out of 11 hunks FAILED -- saving rejects to file config.sub.rej
1663
1601
4 out of 6 hunks FAILED -- saving rejects to file config.guess.rej
1664
1602
uupdate: the diffs from version 0.8.5-1 did not apply cleanly!
1665
1603
Rejected diffs are in ./config.sub.rej
1666
1604
./config.guess.rej
1667
1605
Remember: Your current directory is the OLD sourcearchive!
1668
1606
Do a "cd ../medit-0.9.4" to see the new package
1669
1607
(Did you see the warnings above?)
1670
1608
</programlisting>
1671
1609
						<para>Don't worry about the failure on config.sub, this usually happens very often. Go to the new directory and remove config.sub.rej ;)?BRNow the package is almost ready. You have to update changelog and check it builds fine. For that the easiest and the cleanest way is to type dch -e, here is the result you should get:</para>
1672
1610
						<programlisting>medit (0.9.4-0ubuntu1) intrepid; urgency=low
1673
1611
1674
1612
  * New upstream release
1675
1613
  * Add debian watch
1676
1614
1677
1615
 -- Your Name &lt;your.name@url.com&gt;  Tue, 04 Nov 2008 20:32:22 -0500
1678
1616
</programlisting>
1679
1617
						<para>(You dont have to forget to include the debian/watch on previous upload don't worry ;) )</para></listitem>
1680
1618
						<listitem><para>Let's test the new upstream release, run debuild -S -sa, and finally:</para>
1681
1619
						<screen><command>sudo pbuilder build ../medit_0.9.4-0ubuntu1.dsc</command></screen></listitem>
1682
1620
					</orderedlist>
1683
1621
				</sect3>
1684
1622
				<sect3 id="notes" status="review">
1685
1623
					<title>Notes</title>
1686
1624
					<para>Steps 3 and 5 (of the <link linkend="method3">howto</link>) can be combined by using additional parameters in the URL line of the watch file</para>
1687
1625
					<programlisting>version=3
1688
1626
1689
1627
http://sf.net/medit/mooedit-(.*).tar.bz2 debian uupdate
1690
1628
</programlisting>
1691
1629
					<para>You may want to continue at <ulink url="https://wiki.ubuntu.com/MOTU/Contributing#head-b205c74e27fe15e79e10c9e7f14d3cdfb359d81d">MOTU/Contributing#head-b205c74e27fe15e79e10c9e7f14d3cdfb359d81d</ulink> to create an interdiff for sponsorship.</para>
1692
1630
				</sect3>
1693
1631
			</sect2>
1694
1632
		</sect1>
1695
1633
		<sect1 id="appendix" status="review">
1696
1634
			<title>Appendix</title>
1697
1635
			<sect2 id="additional-resources" status="review">
1698
1636
				<title>Additional Resources</title>
1699
1637
				<para><emphasis role="bold">Debian Resources</emphasis></para>
1700
1638
				<itemizedlist>
1701
1639
					<listitem><para><ulink url="http://www.debian.org/doc/manuals/maint-guide/">Debian New Maintainers Guide</ulink> - Good resource for learning to package</para></listitem>
1702
1640
					<listitem><para><ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink> - The essential Policy manual for Debian and Debian-based distros</para></listitem>
1703
1641
					<listitem><para><ulink url="http://www.debian.org/doc/manuals/developers-reference/">Debian Developer's Reference</ulink> - Specific information for Debian Developers but has some items of interest for packagers.</para></listitem>
1704
1642
					<listitem><para><ulink url="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html">Library Packaging Guide</ulink> - Guide for packaging libraries.</para></listitem>
1705
1643
					<listitem><para><ulink url="http://women.alioth.debian.org/wiki/index.php/English/PackagingTutorial">Debian Women Packaging Tutorial</ulink> - Another good introduction to Debian packaging.</para></listitem>
1706
1644
					<listitem><para><ulink url="http://people.debian.org/~mpalmer/debian-mentors_FAQ.html">Debian Mentors FAQ</ulink></para></listitem>
1707
1645
					<listitem><para><ulink url="http://lists.debian.org/debian-mentors/">debian-mentors mailing list</ulink> - new maintainers can ask questions and find a Debian sponsor here</para></listitem>
1708
1646
					<listitem><para><ulink url="http://wiki.debian.org/PkgSplit">Generating multiple binaries from a single source</ulink></para></listitem>
1709
1647
					<listitem><para><ulink url="http://wiki.debian.org/DebianPython/NewPolicy">Debian New Python Policy</ulink></para></listitem>
1710
1648
					<listitem><para><ulink url="http://pkg-mono.alioth.debian.org/cli-policy/">Debian CLI Policy</ulink></para></listitem>
1711
1649
					<listitem><para><ulink url="http://wiki.debian.org/DebianPackagingHandbook">Debian Packaging Handbook</ulink></para></listitem>
1712
1650
					<listitem><para><ulink url="http://wiki.debian.org/SandroTosi/Svn_get-orig-source">packaging from upstream SVN repository</ulink></para></listitem>
1713
1651
				</itemizedlist>
1714
1652
				<para><emphasis role="bold">Wiki Resources</emphasis></para>
1715
1653
				<itemizedlist>
1716
1654
					<listitem><para><ulink url="https://wiki.ubuntu.com/MOTU/GettingStarted">MOTU/GettingStarted</ulink></para></listitem>
1717
1655
					<listitem><para><ulink url="https://wiki.ubuntu.com/PackagingGuide">PackagingGuide</ulink></para></listitem>
1718
1656
					<listitem><para><ulink url="https://wiki.ubuntu.com/UbuntuDevelopment">UbuntuDevelopment</ulink></para></listitem>
1719
1657
					<listitem><para><ulink url="https://wiki.ubuntu.com/PbuilderHowto">Pbuilder Howto</ulink></para></listitem>
1720
1658
					<listitem><para><ulink url="https://wiki.ubuntu.com/DebootstrapChroot">DebootstrapChroot</ulink></para></listitem>
1721
1659
					<listitem><para><ulink url="https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages">UbuntuDevelopment/NewPackages</ulink></para></listitem>
1722
1660
				</itemizedlist>
1723
1661
				<para><emphasis role="bold">Other Resources</emphasis></para>
1724
1662
				<itemizedlist>
1725
1663
					<listitem><para><ulink url="http://www-106.ibm.com/developerworks/linux/library/l-debpkg.html">IBM Packaging Tutorial</ulink></para></listitem>
1726
1664
					<listitem><para><ulink url="https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml">Duckcorp CDBS Documentation</ulink></para></listitem>
1727
1665
					<listitem><para><ulink url="https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml">Managing packages with Subversion and pbuilder</ulink></para></listitem>
1728
1666
					<listitem><para><ulink url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">Creating .desktop files</ulink> (<ulink url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Categories</ulink>)</para></listitem>
1729
1667
					<listitem><para><ulink url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Debian Library Packaging Guide</ulink></para></listitem>
1730
1668
					<listitem><para><ulink url="http://www.gnu.org/software/make/manual/make.html">Make Manual</ulink> (debian/rules is a Makefile)</para></listitem>
1731
1669
				</itemizedlist>
1732
1670
			</sect2>
1733
1671
			<sect2 id="example-files" status="review">
1734
1672
				<title>example files</title>
1735
1673
				<itemizedlist>
1736
1674
					<listitem><para><emphasis role="bold">Readme.Debian</emphasis> is used to document changes that you have made to the original upstream source that other people might need to know or information specific to Debian or Ubuntu.</para></listitem>
1737
1675
					<listitem><para><emphasis role="bold">conffiles.ex</emphasis>: If the package installs a configuration file, when the package is upgraded dpkg can prompt a user whether to keep his or her version if modified or install the new version. Such configuration files should be listed in conffiles (one per line). Do not list configuration files that are only modified by the package or have to be set up by the user to work.</para></listitem>
1738
1676
					<listitem><para><emphasis role="bold">cron.d.ex</emphasis>: If your package requires regularly scheduled tasks to operate properly, you can use this file to configure it. If you use this file, rename it to cron.d.</para></listitem>
1739
1677
					<listitem><para><emphasis role="bold">dirs</emphasis> specifies the directories that are needed but the normal installation procedure (make installapplication) somehow doesn't create. </para></listitem>
1740
1678
					<listitem><para><emphasis role="bold">docs</emphasis> specifies the filenames of documentation files that dh_installdocs will install into the temporary directory.</para></listitem>
1741
1679
					<listitem><para><emphasis role="bold">emacsen-*.ex</emphasis> specifies Emacs files that will be bytecompiled at install time. They are installed into the temporary directory by dh_installemacsen.</para></listitem>
1742
1680
					<listitem><para><emphasis role="bold">init.d.ex</emphasis>: If your package is a daemon that needs to be run at system startup rename this file to init.d and adjust it to your needs. </para></listitem>
1743
1681
					<listitem><para><emphasis role="bold">manpage.1.ex and manpage.sgml.ex</emphasis> are templates for man pages if the package does not already have one.</para></listitem>
1744
1682
					<listitem><para><emphasis role="bold">menu.ex</emphasis> is used to add your package to the Debian menu. Ubuntu uses the <ulink url="http://www.freedesktop.org/">freedesktop.org</ulink> standard <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">.desktop</ulink> files but remember that packages in Universe/Multiverse are widely used in other (desktop-less) environments. Beside, we strongly want to give-back to Debian (where menu files are required by policy), therefore you are encouraged to include them in your Ubuntu package too.</para></listitem>
1745
1683
					<listitem><para><emphasis role="bold">watch.ex</emphasis>: The package maintainer can use the uscan program and a watch file to check for a new upstream source tarball. (<link linkend="creaitng-and-using-a-debian-watch-file">PackagingGuide/Recipes/DebianWatch</link>)</para></listitem>
1746
1684
					<listitem><para><emphasis role="bold">ex.package.doc-base</emphasis> is used to register your package's documentation (other than man and info pages) with doc-base.</para></listitem>
1747
1685
					<listitem><para><emphasis role="bold">postinst.ex, preinst.ex, postrm.ex, and prerm.ex</emphasis>: These maintainer scripts are run by dpkg when the package is installed, upgraded, or removed.</para></listitem>
1748
1686
				</itemizedlist>
1749
1687
				<para><emphasis role="italics">For more details refer to the Debian New Maintainer's Guide.</emphasis></para>
1750
1688
			</sect2>
1751
1689
			<sect2 id="list-of-debhelper-tools" status="review">
1752
1690
				<title>List of Debhelper Tools</title>
1753
1691
				<itemizedlist>
1754
1692
					<listitem><para><emphasis role="italics">dh_builddeb</emphasis> - build debian packages</para></listitem>
1755
1693
					<listitem><para><emphasis role="italics">dh_clean</emphasis> - clean up package build directories</para></listitem>
1756
1694
					<listitem><para><emphasis role="italics">dh_clideps</emphasis> - calculates CLI (.NET) dependencies</para></listitem>
1757
1695
					<listitem><para><emphasis role="italics">dh_compress</emphasis> - compress files and fix symlinks in package build directories</para></listitem>
1758
1696
					<listitem><para><emphasis role="italics">dh_desktop</emphasis> - Register .desktop files</para></listitem>
1759
1697
					<listitem><para><emphasis role="italics">dh_fixperms</emphasis> - fix permissions of files in package build directories</para></listitem>
1760
1698
					<listitem><para><emphasis role="italics">dh_gconf</emphasis> - generate GConf schema registration scripts</para></listitem>
1761
1699
					<listitem><para><emphasis role="italics">dh_gencontrol</emphasis> - generate and install control file</para></listitem>
1762
1700
					<listitem><para><emphasis role="italics">dh_install</emphasis> - install files into package build directories</para></listitem>
1763
1701
					<listitem><para><emphasis role="italics">dh_installcatalogs</emphasis> - install and register SGML Catalogs</para></listitem>
1764
1702
					<listitem><para><emphasis role="italics">dh_installchangelogs</emphasis> - install changelogs into package build directories</para></listitem>
1765
1703
					<listitem><para><emphasis role="italics">dh_installcligac</emphasis> - register assemblies to be late installed into a GAC</para></listitem>
1766
1704
					<listitem><para><emphasis role="italics">dh_installcron</emphasis> - install cron scripts into etc/cron.*</para></listitem>
1767
1705
					<listitem><para><emphasis role="italics">dh_installdeb</emphasis> - install files into the DEBIAN directory</para></listitem>
1768
1706
					<listitem><para><emphasis role="italics">dh_installdebconf</emphasis> - install files used by debconf in package build directories</para></listitem>
1769
1707
					<listitem><para><emphasis role="italics">dh_installdefoma</emphasis> - install a defoma related scripts</para></listitem>
1770
1708
					<listitem><para><emphasis role="italics">dh_installdirs</emphasis> - create subdirectories in package build directories</para></listitem>
1771
1709
					<listitem><para><emphasis role="italics">dh_installdocs</emphasis> - install documentation into package build directories</para></listitem>
1772
1710
					<listitem><para><emphasis role="italics">dh_installemacsen</emphasis> - register an emacs add on package</para></listitem>
1773
1711
					<listitem><para><emphasis role="italics">dh_installexamples</emphasis> - install example files into package build directories</para></listitem>
1774
1712
					<listitem><para><emphasis role="italics">dh_installinfo</emphasis> - install and register info files</para></listitem>
1775
1713
					<listitem><para><emphasis role="italics">dh_installinit</emphasis> - install init scripts into package build directories</para></listitem>
1776
1714
					<listitem><para><emphasis role="italics">dh_installlogcheck</emphasis> - install logcheck rulefiles into etc/logcheck/</para></listitem>
1777
1715
					<listitem><para><emphasis role="italics">dh_installlogrotate</emphasis> - install logrotate config files</para></listitem>
1778
1716
					<listitem><para><emphasis role="italics">dh_installman</emphasis> - install man pages into package build directories</para></listitem>
1779
1717
					<listitem><para><emphasis role="italics">dh_installmanpages</emphasis> - old-style man page installer</para></listitem>
1780
1718
					<listitem><para><emphasis role="italics">dh_installmenu</emphasis> - install debian menu files into package build directories</para></listitem>
1781
1719
					<listitem><para><emphasis role="italics">dh_installmime</emphasis> - install mime files into package build directories</para></listitem>
1782
1720
					<listitem><para><emphasis role="italics">dh_installmodules</emphasis> - register modules with modutils</para></listitem>
1783
1721
					<listitem><para><emphasis role="italics">dh_installpam</emphasis> - install pam support files</para></listitem>
1784
1722
					<listitem><para><emphasis role="italics">dh_installppp</emphasis> - install ppp ip-up and ip-down files</para></listitem>
1785
1723
					<listitem><para><emphasis role="italics">dh_installtex</emphasis> - register Type 1 fonts, languages, or formats with TeX</para></listitem>
1786
1724
					<listitem><para><emphasis role="italics">dh_installudev</emphasis> - install udev rules files</para></listitem>
1787
1725
					<listitem><para><emphasis role="italics">dh_installwm</emphasis> - register a window manager</para></listitem>
1788
1726
					<listitem><para><emphasis role="italics">dh_installxfonts</emphasis> - register X fonts</para></listitem>
1789
1727
					<listitem><para><emphasis role="italics">dh_installxmlcatalogs</emphasis> - install and register XML catalog files</para></listitem>
1790
1728
					<listitem><para><emphasis role="italics">dh_link</emphasis> - create symlinks in package build directories</para></listitem>
1791
1729
					<listitem><para><emphasis role="italics">dh_listpackages</emphasis> - list binary packages debhelper will act on</para></listitem>
1792
1730
					<listitem><para><emphasis role="italics">dh_make</emphasis> - Debianize a regular source archive</para></listitem>
1793
1731
					<listitem><para><emphasis role="italics">dh_makeclilibs</emphasis> - automatically create clilibs file</para></listitem>
1794
1732
					<listitem><para><emphasis role="italics">dh_makeshlibs</emphasis> - automatically create shlibs file</para></listitem>
1795
1733
					<listitem><para><emphasis role="italics">dh_md5sums</emphasis> - generate DEBIAN/md5sums file</para></listitem>
1796
1734
					<listitem><para><emphasis role="italics">dh_movefiles</emphasis> - move files out of debian/tmp into subpackages</para></listitem>
1797
1735
					<listitem><para><emphasis role="italics">dh_perl</emphasis> - calculates perl dependencies</para></listitem>
1798
1736
					<listitem><para><emphasis role="italics">dh_pycentral</emphasis> - use the python-central framework to handle Python modules and extensions</para></listitem>
1799
1737
					<listitem><para><emphasis role="italics">dh_pysupport</emphasis> - use the python-support framework to handle Python modules</para></listitem>
1800
1738
					<listitem><para><emphasis role="italics">dh_python</emphasis> - calculates python dependencies and adds postinst and prerm python scripts</para></listitem>
1801
1739
					<listitem><para><emphasis role="italics">dh_scrollkeeper</emphasis> - generate ScrollKeeper registration scripts</para></listitem>
1802
1740
					<listitem><para><emphasis role="italics">dh_shlibdeps</emphasis> - calculate shared library dependencies</para></listitem>
1803
1741
					<listitem><para><emphasis role="italics">dh_strip</emphasis> - strip executables, shared libraries, and some static libraries</para></listitem>
1804
1742
					<listitem><para><emphasis role="italics">dh_suidregister</emphasis> - obsolete suid registration program</para></listitem>
1805
1743
					<listitem><para><emphasis role="italics">dh_testdir</emphasis> - test directory before building debian package</para></listitem>
1806
1744
					<listitem><para><emphasis role="italics">dh_testroot</emphasis> - ensure that a package is built as root</para></listitem>
1807
1745
					<listitem><para><emphasis role="italics">dh_testversion</emphasis> - ensure that the correct version of debhelper is installed</para></listitem>
1808
1746
					<listitem><para><emphasis role="italics">dh_undocumented</emphasis> - obsolete undocumented.7 symlink program</para></listitem>
1809
1747
					<listitem><para><emphasis role="italics">dh_usrlocal</emphasis> - migrate usr/local directories to maintainer scripts</para></listitem>
1810
1748
					
1811
1749
				</itemizedlist>
1812
1750
			</sect2>
1813
1751
		</sect1>
1814
1752
</article>
1815
0
1753
1816
=== added directory 'packaging/po'
Status:	Rejected
Rejected by:	Benjamin Kerensa on 2013-04-20
Proposed branch:	lp:~nhandler/ubuntu-docs/packaging-guides
Merge into:	lp:ubuntu-docs/karmic
Diff against target:	None lines
To merge this branch:	bzr merge lp:~nhandler/ubuntu-docs/packaging-guides
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Matthew East (community)		2009-04-19	Disapprove on 2009-10-07
Review via email: mp+5692@code.launchpad.net