trunk/programmer/programmer.sgml

<!doctype debiandoc system>
<book>
<title> Debian Programmers' Manual (Obsolete Documentation) 
<author> Igor Grobman <email>igor@debian.org
<version> <date>
<abstract>

This manual describes how to construct a debian package from the original 
upstream source distribution.  It is oriented towards a programmer new to 
Debian.  For reference information, try Debian Packaging Manual.

<copyright> Copyright &copy; 1997 Igor Grobman

<p>

This manual is free software; you may redistribute it and/or modify it under 
the terms of the GNU General Public License as published by the Free Software 
Foundation; either version 2, or (at your option) any later version.  
This manual includes parts of documents written by Jaldhar Vyas and Ian Jackson
  
<p>

This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose.  See the GNU
General Public License for more details.
<p>

You should have received a copy of the GNU General Public License with
your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
with the <prgn/debiandoc-sgml/ source package as the file
<tt>COPYING</tt>.  If not, write to the Free Software Foundation,
Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

<toc sect>

<chapt id="Introduction"> Introduction and what you need

<sect>Introduction

<p>
This manual documents the process of making a Debian package.  It is assumed 
that you have at least familiarized yourself with Debian Policy Manual and 
Debian Packaging Manual.  You also need them at your disposal, as they are 
often referenced here.

<sect> Packages you need installed to get started

<p>
The following packages need to be present on your system in order to build a
debian package.
<p>

From the devel section:
<taglist>

<tag><prgn>binutils</prgn>
<item>
The programs in this package are used to assemble and link object files--the 
stuff programs are made of.

<tag><prgn>gcc</prgn>
<item>
This is the GNU C compiler.  Most Linux programs are written in the C 
programming language.

<tag><prgn> cpp </prgn>
<item>
This is the C preprocessor.

<tag><prgn> libc5-dev </prgn>
<item>
These are the C libraries and header files gcc needs to link with to create 
object files.

<tag><prgn> make </prgn>
<item>
Typically creating a program will take several steps.  Rather than having to 
type out the same commands over and over again, you can use the make program 
to automate the process.

<tag><prgn> dpkg-dev </prgn>
<item>
This package contains the tools needed to create Debian archives.  It also 
contains the Debian Programmers and Policy manuals.

<tag><prgn>debmake</prgn> (optional)
<item>
This is a higher level set of tools for creating Debian packages.  It makes the
whole process tremendously easier.
</taglist>

<p>
From the admin section:
<taglist>

<tag><prgn>sudo </prgn> (optional)
<item>
Sudo allows a user to become root temporarily. (In a way controlled by the 
system administrator of course) You need root access during the package 
building process.  If you do have root access you don't really need this 
package but you might want it any way because for security reasons you should 
do only the most essential actvities while logged in as root.

<tag><prgn> cpio </prgn>
<item>
This is an archiver like tar or zip.  Dpkg-dev needs it.
</taglist>
<p>
From the misc section: 
<taglist>

<tag><prgn>file </prgn>
<item>
This handy program can determine what type a file is.  Dpkg-dev needs it.

<tag><prgn> patch </prgn>
<item>
Patch will take a file containing a difference listing produced by the diff 
program and apply it to an original fan, producing a patched version.
<tag><prgn> hello </prgn>
<item>
This is an example package for debian developers.  I will often refer to it in
this document.

</taglist>

<p>
        Also you need the encryption package pgp to digitally
"sign" your package.  This is especially important if you want to
distribute your package to other people.  However due to a rather wacky
U.S. law, you cannot simply download this from your nearest Debian ftp
site.  The ftp site will however have a file called README.non-us in its
root directory which will tell you how to get a copy of pgp.


<chapt id="tools"> Discussion of Debian packaging tools
<p> 
This chapter provides an overview of the tools available for Debian developers.
If this is your first time reading this manual,and you want to see how to make
the debian package first, you may skip this chapter and come back to it later.

<p>
There are 2 classes of debian packaging tools.  Those that come with dpkg and 
dpkg-dev are mandatory for building packages.  Debmake provides a set of tools
which are not mandatory and are there to help you in your development.  They 
have a number of drawbacks, especially debstd, but they make creating a debian 
package that much easier at first.  
<p>
All dpkg-dev tools are described in section 3.1 of Debian Packaging Manual.  
Please look it over before proceeding.

<sect> debmake tools
<p>
Below you will find a list of debmake tools with simple descriptions.  Every 
tool has its own manpage.  Please refer to them for more information. 

<taglist>
<tag><prgn>deb-make</prgn>
<item> 
Should be run from the directory where the upstream source is unpacked.  
Renames that directory to package-version.orig and sets up debian directory 
structure and files. 

<tag><prgn>debchange, debch</prgn>
<item>
Manages debian/changelog file

<tag><prgn>todo, done</prgn>
<item>
Manage todo list for a debian package

<tag><prgn>build</prgn>
<item>
Invokes dpkg-buildpackage if given no arguments, runs <tt>debian/rules argument</tt> when an argument is given.

<tag<prgn>debstd</prgn>
<item>
usually executed from debian/rules. Has numerous functions, including putting 
the documentation in proper place and compressing it if necessary, running on
dpkg-shlibdeps on all binaries found, checking for and fixing dangling 
symlinks and multi-binary packages support.  Some of these features will be 
discussed further in this manual, others won't be.  Please refer to <manref
name="debstd" section="1"> for the complete description of debstd.

<tag><prgn>debc</prgn>
<item>
lists the contents of debian package

<tag><prgn>debi</prgn>
<item>
Installs the package produced from the source tree it was invoked from.

<tag><prgn>deblint</prgn>
<item>
unpacks the package and performs various checks on the contents.

<tag><prgn>release</prgn>
<item>
uploads the package using dupload, if it is installed or using ssh, if dupload
isn't installed.  Posts the announcement to appropriate mailing lists.

<tag><prgn>uupdate</prgn>
<item>
updates the source package using new upstream source of patch file.

</taglist>

<sect>Execution trees
<p>
In order to see how debian packaging process works, the following execution 
trees might be helpful.  They show which tools should be executed by maintainer
and which are only called internally by other tools.
<p>
Here is how the process looks like without debmake:

<example>

(maintainer creates the debian structure)
dpkg-buildpackage
     dpkg-parsechangelog
     dpkg-source
     rules clean
     rules binary
          dpkg-shlibdeps
          dpkg-gencontrol
          dpkg-deb --build
     dpkg-genchanges
(maintainer checks and tests the package)
</example>

<p>
And here is how it looks like with debmake tools:

<example>

deb-make or uupdate 
debchange
dpkg-buildpackage or build
    dpkg-parsechangelog
    dpkg-source
    rules clean
    rules binary
         debstd
              dpkg-shlibdeps
         dpkg-gencontrol
         dpkg-deb --build     
    dpkg-genchanges
debc
deblint
debi
release
</example>

<chapt id="preparation"> Getting the Source and creating debian structure.

<sect>Getting the source 
<p>

You should get the source from a site that is listed as official distribution 
site in the documentation of the program you are debianizing. This way, you 
make sure you have the latest version, and that the program has not been 
modifieed by anyone.  Unfortunately, the hello program did not have the 
official site mentioned in its documentation, but since it is a GNU program, I
assumed its home site must be ftp.gnu.ai.mit.edu.  If you don't see such 
indications, you might want to contact the author of the program, and ask him.
<p>  
Usually, you should contact the upstream author anyway to let him know what you
are doing.  You  should also remember the name of the site you downloaded the 
program from, because you will need it later, when you will be creating the 
copyright file, and when checking for a new upstream version.

<sect> Creating debian structure
<p>
If you have debmake installed on your system, and would like to use it, then
all you have to do to create debian dirs and files is do the following:

<enumlist>

<item>
unpack the source file to a directory whose name is in the
package-version format, removing any  capital letters, if present.  
It looks like this: <example>hello-1.3</example>

<item>
Cd to that directory and type <tt>deb-make</tt>.  You will see your e-mail
address, date, your name, the name of the package and version on your
screen.  Make sure all are correct, then you'll see a list of options like
the following:
<p>
<example>Type of Package: (S=Single binary, M=multi-binary, L=Library, X=abort?
s/m/l/x</example>
<p>
You are most likely to be packaging a single binary package, so choose "S". 
Note that Multi-binary package implies that it will produce more than one .deb
file, not that it will have more than one binary executable.

<item>
You will see that debian directory has been created, and that the
original directory has been renamed to package-version.orig.  Edit the
necessary files in debian directory.  You will need to edit at least
control, rules, changelog and copyright files.  See below for more information.
For discussion on the structure of the rules file, see  
<ref id="rules">

</enumlist>

<p>
Without debmake the process is slightly more complicated.
<p>
Unpack the original upstream source into package-version.orig,directory 
and another copy in package-version.  It is best not to touch the sources in 
the .orig directory, but if the upstream source requires modification in order
to debianise it, you may do so, but make sure to document your changes in the 
copyright file.  Create debian directory and the following files inside it:
<list>
<item>control      
<item>rules
<item>changelog 
<item>copyright
</list>

<sect> Debian files
<p>
<em>control</em> file consists of a number of required fields:  The information
from these fields is used in several other control files automatically created 
by dpkg in the build stage.  The following fields are required in the control 
file, please refer to Packaging Manual for detailed descriptions.
<list>
<item>Source
<item>Section
<item>Priority
<item>Maintainer
<item>Standards-Version
<item>Package
<item>Architecture
<item>Description
</list>

<p>
Pre-depends, Depends, Recommends and Suggests fields describe the 
interrelationships between packages.  They are not required, but most packages 
do need them.  These fields should not be hard coded. Instead, the variable 
<tt>${shlibs:Relationship}</tt> should be used.  For example, 
<tt>Depends:${shlibs:Depends</tt> and <tt>Suggests: ${shlibs:Suggests}</tt>
are properly formatted fields.  The variables are filled by dpkg-shlibdeps 
program which will be covered in <ref id="rules">
<p>
<em>rules</em> is covered in <ref id="rules">
<p>
<em>changelog</em>  file has a special format described in section 3.2.3 of 
Debian Packaging Manual.  This format is used by dpkg to obtain the version 
number of debian package and other information.  If you used <prgn>deb-make
</prgn> to create your source package, the file is already in the correct 
format, and the only thing you need to do is record your changes.
<p>
<em>copyright</em>  file does not have any special format, but it must contain 
the following: 
<list>
<item> Name of the person who debianised the package,
<item> the site where the upstream source was downloaded from,  
<item> the list of modifications made to the original source in the process of
debianising it.  
</list>

<chapt id="rules"> Rules File Structure

</book>
1	<!doctype debiandoc system>
2	<book>
3	<title> Debian Programmers' Manual (Obsolete Documentation)
4	<author> Igor Grobman <email>igor@debian.org
5	<version> <date>
6	<abstract>
7
8	This manual describes how to construct a debian package from the original
9	upstream source distribution. It is oriented towards a programmer new to
10	Debian. For reference information, try Debian Packaging Manual.
11
12	<copyright> Copyright © 1997 Igor Grobman
13
14	<p>
15
16	This manual is free software; you may redistribute it and/or modify it under
17	the terms of the GNU General Public License as published by the Free Software
18	Foundation; either version 2, or (at your option) any later version.
19	This manual includes parts of documents written by Jaldhar Vyas and Ian Jackson
20
21	<p>
22
23	This is distributed in the hope that it will be useful, but
24	<em>without any warranty</em>; without even the implied warranty of
25	merchantability or fitness for a particular purpose. See the GNU
26	General Public License for more details.
27	<p>
28
29	You should have received a copy of the GNU General Public License with
30	your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
31	with the <prgn/debiandoc-sgml/ source package as the file
32	<tt>COPYING</tt>. If not, write to the Free Software Foundation,
33	Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
34
35	<toc sect>
36
37	<chapt id="Introduction"> Introduction and what you need
38
39	<sect>Introduction
40
41	<p>
42	This manual documents the process of making a Debian package. It is assumed
43	that you have at least familiarized yourself with Debian Policy Manual and
44	Debian Packaging Manual. You also need them at your disposal, as they are
45	often referenced here.
46
47	<sect> Packages you need installed to get started
48
49	<p>
50	The following packages need to be present on your system in order to build a
51	debian package.
52	<p>
53
54	From the devel section:
55	<taglist>
56
57	<tag><prgn>binutils</prgn>
58	<item>
59	The programs in this package are used to assemble and link object files--the
60	stuff programs are made of.
61
62	<tag><prgn>gcc</prgn>
63	<item>
64	This is the GNU C compiler. Most Linux programs are written in the C
65	programming language.
66
67	<tag><prgn> cpp </prgn>
68	<item>
69	This is the C preprocessor.
70
71	<tag><prgn> libc5-dev </prgn>
72	<item>
73	These are the C libraries and header files gcc needs to link with to create
74	object files.
75
76	<tag><prgn> make </prgn>
77	<item>
78	Typically creating a program will take several steps. Rather than having to
79	type out the same commands over and over again, you can use the make program
80	to automate the process.
81
82	<tag><prgn> dpkg-dev </prgn>
83	<item>
84	This package contains the tools needed to create Debian archives. It also
85	contains the Debian Programmers and Policy manuals.
86
87	<tag><prgn>debmake</prgn> (optional)
88	<item>
89	This is a higher level set of tools for creating Debian packages. It makes the
90	whole process tremendously easier.
91	</taglist>
92
93	<p>
94	From the admin section:
95	<taglist>
96
97	<tag><prgn>sudo </prgn> (optional)
98	<item>
99	Sudo allows a user to become root temporarily. (In a way controlled by the
100	system administrator of course) You need root access during the package
101	building process. If you do have root access you don't really need this
102	package but you might want it any way because for security reasons you should
103	do only the most essential actvities while logged in as root.
104
105	<tag><prgn> cpio </prgn>
106	<item>
107	This is an archiver like tar or zip. Dpkg-dev needs it.
108	</taglist>
109	<p>
110	From the misc section:
111	<taglist>
112
113	<tag><prgn>file </prgn>
114	<item>
115	This handy program can determine what type a file is. Dpkg-dev needs it.
116
117	<tag><prgn> patch </prgn>
118	<item>
119	Patch will take a file containing a difference listing produced by the diff
120	program and apply it to an original fan, producing a patched version.
121	<tag><prgn> hello </prgn>
122	<item>
123	This is an example package for debian developers. I will often refer to it in
124	this document.
125
126	</taglist>
127
128	<p>
129	Also you need the encryption package pgp to digitally
130	"sign" your package. This is especially important if you want to
131	distribute your package to other people. However due to a rather wacky
132	U.S. law, you cannot simply download this from your nearest Debian ftp
133	site. The ftp site will however have a file called README.non-us in its
134	root directory which will tell you how to get a copy of pgp.
135
136
137	<chapt id="tools"> Discussion of Debian packaging tools
138	<p>
139	This chapter provides an overview of the tools available for Debian developers.
140	If this is your first time reading this manual,and you want to see how to make
141	the debian package first, you may skip this chapter and come back to it later.
142
143	<p>
144	There are 2 classes of debian packaging tools. Those that come with dpkg and
145	dpkg-dev are mandatory for building packages. Debmake provides a set of tools
146	which are not mandatory and are there to help you in your development. They
147	have a number of drawbacks, especially debstd, but they make creating a debian
148	package that much easier at first.
149	<p>
150	All dpkg-dev tools are described in section 3.1 of Debian Packaging Manual.
151	Please look it over before proceeding.
152
153	<sect> debmake tools
154	<p>
155	Below you will find a list of debmake tools with simple descriptions. Every
156	tool has its own manpage. Please refer to them for more information.
157
158	<taglist>
159	<tag><prgn>deb-make</prgn>
160	<item>
161	Should be run from the directory where the upstream source is unpacked.
162	Renames that directory to package-version.orig and sets up debian directory
163	structure and files.
164
165	<tag><prgn>debchange, debch</prgn>
166	<item>
167	Manages debian/changelog file
168
169	<tag><prgn>todo, done</prgn>
170	<item>
171	Manage todo list for a debian package
172
173	<tag><prgn>build</prgn>
174	<item>
175	Invokes dpkg-buildpackage if given no arguments, runs <tt>debian/rules argument</tt> when an argument is given.
176
177	<tag<prgn>debstd</prgn>
178	<item>
179	usually executed from debian/rules. Has numerous functions, including putting
180	the documentation in proper place and compressing it if necessary, running on
181	dpkg-shlibdeps on all binaries found, checking for and fixing dangling
182	symlinks and multi-binary packages support. Some of these features will be
183	discussed further in this manual, others won't be. Please refer to <manref
184	name="debstd" section="1"> for the complete description of debstd.
185
186	<tag><prgn>debc</prgn>
187	<item>
188	lists the contents of debian package
189
190	<tag><prgn>debi</prgn>
191	<item>
192	Installs the package produced from the source tree it was invoked from.
193
194	<tag><prgn>deblint</prgn>
195	<item>
196	unpacks the package and performs various checks on the contents.
197
198	<tag><prgn>release</prgn>
199	<item>
200	uploads the package using dupload, if it is installed or using ssh, if dupload
201	isn't installed. Posts the announcement to appropriate mailing lists.
202
203	<tag><prgn>uupdate</prgn>
204	<item>
205	updates the source package using new upstream source of patch file.
206
207	</taglist>
208
209	<sect>Execution trees
210	<p>
211	In order to see how debian packaging process works, the following execution
212	trees might be helpful. They show which tools should be executed by maintainer
213	and which are only called internally by other tools.
214	<p>
215	Here is how the process looks like without debmake:
216
217	<example>
218
219	(maintainer creates the debian structure)
220	dpkg-buildpackage
221	dpkg-parsechangelog
222	dpkg-source
223	rules clean
224	rules binary
225	dpkg-shlibdeps
226	dpkg-gencontrol
227	dpkg-deb --build
228	dpkg-genchanges
229	(maintainer checks and tests the package)
230	</example>
231
232	<p>
233	And here is how it looks like with debmake tools:
234
235	<example>
236
237	deb-make or uupdate
238	debchange
239	dpkg-buildpackage or build
240	dpkg-parsechangelog
241	dpkg-source
242	rules clean
243	rules binary
244	debstd
245	dpkg-shlibdeps
246	dpkg-gencontrol
247	dpkg-deb --build
248	dpkg-genchanges
249	debc
250	deblint
251	debi
252	release
253	</example>
254
255	<chapt id="preparation"> Getting the Source and creating debian structure.
256
257	<sect>Getting the source
258	<p>
259
260	You should get the source from a site that is listed as official distribution
261	site in the documentation of the program you are debianizing. This way, you
262	make sure you have the latest version, and that the program has not been
263	modifieed by anyone. Unfortunately, the hello program did not have the
264	official site mentioned in its documentation, but since it is a GNU program, I
265	assumed its home site must be ftp.gnu.ai.mit.edu. If you don't see such
266	indications, you might want to contact the author of the program, and ask him.
267	<p>
268	Usually, you should contact the upstream author anyway to let him know what you
269	are doing. You should also remember the name of the site you downloaded the
270	program from, because you will need it later, when you will be creating the
271	copyright file, and when checking for a new upstream version.
272
273	<sect> Creating debian structure
274	<p>
275	If you have debmake installed on your system, and would like to use it, then
276	all you have to do to create debian dirs and files is do the following:
277
278	<enumlist>
279
280	<item>
281	unpack the source file to a directory whose name is in the
282	package-version format, removing any capital letters, if present.
283	It looks like this: <example>hello-1.3</example>
284
285	<item>
286	Cd to that directory and type <tt>deb-make</tt>. You will see your e-mail
287	address, date, your name, the name of the package and version on your
288	screen. Make sure all are correct, then you'll see a list of options like
289	the following:
290	<p>
291	<example>Type of Package: (S=Single binary, M=multi-binary, L=Library, X=abort?
292	s/m/l/x</example>
293	<p>
294	You are most likely to be packaging a single binary package, so choose "S".
295	Note that Multi-binary package implies that it will produce more than one .deb
296	file, not that it will have more than one binary executable.
297
298	<item>
299	You will see that debian directory has been created, and that the
300	original directory has been renamed to package-version.orig. Edit the
301	necessary files in debian directory. You will need to edit at least
302	control, rules, changelog and copyright files. See below for more information.
303	For discussion on the structure of the rules file, see
304	<ref id="rules">
305
306	</enumlist>
307
308	<p>
309	Without debmake the process is slightly more complicated.
310	<p>
311	Unpack the original upstream source into package-version.orig,directory
312	and another copy in package-version. It is best not to touch the sources in
313	the .orig directory, but if the upstream source requires modification in order
314	to debianise it, you may do so, but make sure to document your changes in the
315	copyright file. Create debian directory and the following files inside it:
316	<list>
317	<item>control
318	<item>rules
319	<item>changelog
320	<item>copyright
321	</list>
322
323	<sect> Debian files
324	<p>
325	<em>control</em> file consists of a number of required fields: The information
326	from these fields is used in several other control files automatically created
327	by dpkg in the build stage. The following fields are required in the control
328	file, please refer to Packaging Manual for detailed descriptions.
329	<list>
330	<item>Source
331	<item>Section
332	<item>Priority
333	<item>Maintainer
334	<item>Standards-Version
335	<item>Package
336	<item>Architecture
337	<item>Description
338	</list>
339
340	<p>
341	Pre-depends, Depends, Recommends and Suggests fields describe the
342	interrelationships between packages. They are not required, but most packages
343	do need them. These fields should not be hard coded. Instead, the variable
344	<tt>${shlibs:Relationship}</tt> should be used. For example,
345	<tt>Depends:${shlibs:Depends</tt> and <tt>Suggests: ${shlibs:Suggests}</tt>
346	are properly formatted fields. The variables are filled by dpkg-shlibdeps
347	program which will be covered in <ref id="rules">
348	<p>
349	<em>rules</em> is covered in <ref id="rules">
350	<p>
351	<em>changelog</em> file has a special format described in section 3.2.3 of
352	Debian Packaging Manual. This format is used by dpkg to obtain the version
353	number of debian package and other information. If you used <prgn>deb-make
354	</prgn> to create your source package, the file is already in the correct
355	format, and the only thing you need to do is record your changes.
356	<p>
357	<em>copyright</em> file does not have any special format, but it must contain
358	the following:
359	<list>
360	<item> Name of the person who debianised the package,
361	<item> the site where the upstream source was downloaded from,
362	<item> the list of modifications made to the original source in the process of
363	debianising it.
364	</list>
365
366	<chapt id="rules"> Rules File Structure
367
368	</book>