File: maint-guide.sgml

package info (click to toggle)
maint-guide 1.0.2
  • links: PTS
  • area: main
  • in suites: woody
  • size: 652 kB
  • ctags: 12
  • sloc: makefile: 104; sh: 8
file content (1459 lines) | stat: -rw-r--r-- 64,357 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
<!doctype debiandoc system>

<debiandoc>

 <book>

  <titlepag>

   <title>Debian New Maintainers' Guide</title>

   <author>Josip Rodin <email/jrodin@jagor.srce.hr/
   </author>
<!--
   <author>Translated by: [put your name here] <email/[put your e-mail here]/
   </author>
  -->

   <version>version 1.0.2, 10 June 2001.</version>

   <copyright>
   <copyrightsummary>Copyright &copy; 1998-2001 Josip Rodin.</copyrightsummary>

   <p>This document may used under the terms the GNU General Public License
   version 2 or higher.

   <p>This document was made using with these two documents as examples:

   <p>Making a Debian Package (AKA the Debmake Manual), copyright &copy;
   1997 Jaldhar Vyas <email/jaldhar@debian.org/.

   <p>The New-Maintainer's Debian Packaging Howto, copyright &copy; 1997
   Will Lowe <email/lowe@debian.org/.
   </copyright>

  </titlepag>

  <toc sect>

  <chapt id="start">Getting started "The Right Way"

  <p>This document will try to describe building of a Debian GNU/Linux package
  to the common Debian user (and wannabe developer) in common language, and
  well covered with working examples. There is an old Roman saying, <em>Longum
  iter est per preaecepta, breve et efficax per exempla!</em> (It's a long way
  by the rules, but short and efficient with examples!).

  <p>One of the things that makes Debian such a top-notch Linux distribution
  is its package system. While there is a vast quantity of software already
  in the Debian format, sometimes you need to install software that isn't.
  You may be wondering how you can make your own packages and perhaps you
  think it is a very difficult task. Well, if you are a real novice on Linux,
  it is hard, but if you were rookie, you wouldn't be reading this doc now. :-)
  You do need to know a little about Unix programming but you certainly
  don't need to be a wizard.

  <p>Newer versions of this document should always be available online at
  <url name="http://www.debian.org/doc/maint-guide" id="http://www.debian.org/doc/maint-guide">
  and in the `maint-guide' package.

  <sect id="needprogs">Programs you need for development

  <p>Before you start anything, you should make sure that you have properly
  installed some additional packages needed for development. Note that the
  list doesn't contain any packages marked `essential' or `required' - we
  expect that you have those installed already.

  <p>This document has been written while the 2.1 `slink' distribution
  was the officially stable release of Debian, and the 2.2 `potato' was
  being created, thus the packages named here are mostly those from
  `potato'.

  <p>The following packages come with standard installation of Debian 2.1,
  so you probably have them (and additional packages they depend on) already.
  Still, you should check with `dpkg -s &lt;package&gt;`.

  <list>
  <item><em>binutils</em> - these programs used to assemble and link
  object files - the stuff programs are made of. (see `info binutils`)

  <item><em>cpp</em> - the C preprocessor. (see <manref name="cpp" section="1">)

  <item><em>cpio</em> - this is an archiver like tar or zip. (see
  <manref name="cpio" section="1">)

  <item><em>dpkg-dev</em> - this package contains the tools needed to unpack,
  build and upload Debian source packages. (see
  <manref name="dpkg-source" section="1">)

  <item><em>file</em> - this handy program can determine what type a file is.
  (see <manref name="file" section="1">)

  <item><em>gcc</em> - the GNU C compiler. Most Linux programs are written
  in C. However, if your program is written in some other programming
  language, like C++, Fortran, Pascal, you should get g++, g77, or gpc,
  respectively. (see <manref name="gcc" section="1">,
  <manref name="g++" section="1">, <manref name="g77" section="1">,
  <manref name="gpc" section="1">)

  <item><em>libc6-dev</em> - the C libraries and header files gcc needs to
  link with to create object files. Although some programs still recommend
  and/or use libc5, you are encouraged to use the newer version (libc6).
  (see `info libc`)

  <item><em>make</em> - usually creation of a program takes several steps.
  Rather than having to type out the same commands over and over again, you
  can use this program to automate the process, creating `Makefile's. Some
  programs also use imake and xmkmf, programs used to generate Makefiles
  from sets of macro functions. Many newer programs use configure scripts
  and Makefiles with help of programs like autoconf and automake, so you
  might need these, too. (see `info make`, <manref name="imake" section="1">,
  <manref name="xmkmf" section="1">, <manref name="autoconf" section="1">,
  <manref name="automake" section="1">)

  <item><em>patch</em> - this very useful utility will take file containing
  a difference listing (produced by the diff program) and apply it to the
  original file, producing a patched version. (see <manref name="patch" section="1">)

  <item><em>perl5</em> - Perl is one of the most used interpreted scripting
  languages on today's un*x systems, often referred to as "Unix's Swiss Army
  Chainsaw". (see <manref name="perl" section="1">)
  </list>

  <p>From the `devel' section of the distribution you'll probably need to
  install these yourself:

  <list>
  <item><em>dh-make</em> and <em>debhelper</em> - dh-make is necessary to
  create the skeleton of our example package, and it will use some the
  debhelper tools for creating packages. They are not essential for creation
  of packages, but it is <strong>highly</strong> recommended for new
  maintainers. It makes the whole process very much easier to start, and
  control afterwards. (see <manref name="dh_make" section="1">,
  <manref name="debhelper" section="1">, /usr/share/doc/debhelper/README)

  <item><em>devscripts</em> - this package contain some nice and useful
  scripts that can be helpful to the maintainers, but they are also not
  necessary for building packages. (see /usr/share/doc/devscripts/README.gz)

  <item><em>fakeroot</em> - this utility lets you emulate being root which
  is necessary for some parts of the build process. (see
  <manref name="fakeroot" section="1">)

  <item><em>lintian</em> - this is the Debian package checker that can let
  you know of any common mistakes after you build the package, and explain
  the errors found. (see <manref name="lintian" section="1">,
  /usr/share/doc/lintian/lintian.html/index.html)
  </list>

  <p>Finally, these <em>very important</em> packages are in the doc section
  of the distribution:

  <list>
  <item><em>debian-policy</em> - includes the structure and contents of the
  archive, several OS design issues, the Filesystem Hierarchy Standard, and
  the most important thing (for you) is that it describes requirements that
  each package must satisfy to be included in the distribution.
  (see /usr/share/doc/debian-policy/policy.html/index.html)

  <item><em>developers-reference</em> - for all matters not specifically
  about the technical details of packaging, like the structure of the
  archive, how to rename, orphan, pick up packages, how to do NMUs, how to
  manage bugs, when and where to upload etc.
  (see /usr/share/doc/developers-reference/developers-reference.html/index.html)
  </list>

  <p>You will also need the encryption package, either PGP (the pgp-*
  packages) or GPG (the gnupg package), to digitally <em>sign</em> your
  package. This is especially important if you want to distribute it to
  other people (and you will certainly be doing that when your work gets
  included in the Debian distribution).  However, due to a rather wacky U.S. 
  export law, you cannot simply download this from your nearest Debian FTP
  site. But Debian does provide these packages through a site that is not
  physically located in the US, called non-US.debian.org
  (ftp://non-us.debian.org/debian-non-US/). Your FTP site will have a file
  called README.non-US, which will tell you how to find a closer mirror of
  that site.

  <p>The short descriptions that are given above only serve to introduce
  you to what each package does. Before continuing please thoroughly read
  how to the documentation of each program, at least the standard usage.
  It may seem like heavy going now, but later on you'll be <em>very</em>
  glad you read it.

  Note: <em>debmake</em> is a package that contains some programs that
  function similar to dh-make, but its specific use is <strong>not</strong>
  covered in this document. Refer to <url name="the Debmake manual"
  id="http://www.debian.org/~jaldhar/"> for more information.

  <sect id="otherinfo">Other information

  <p>There are two types of packages you can make, source and binary.
  A source package contains code which you can compile into a program.
  A binary package contains just the finished program. Don't mix terms
  like source of the program and the source package of the program!
  Please read the other manuals if you need more details on terminology.

  <p>In Debian, the term `maintainer' is used for the person who makes
  packages, `upstream author' for the person that made the program, and
  `upstream maintainer' for the person who currently maintains that program,
  outside of Debian. Usually author and the upstream maintainer are the
  same person - and sometimes even the maintainer is the same person.
  If you made a program, and want it to get in Debian, feel free to submit
  your application to become a maintainer.

  <p>After you build your package (or while doing that), you will have
  to become an official Debian maintainer if you wish your program to get
  into the next distribution (if the program is useful, why not?).
  That process is explained in Developer's Reference. Please read it.

  <chapt id="first">First steps

  <p>While the documentation at the <url name="Developers corner" id="http://www.debian.org/devel/">
  is not so clear about where and how new maintainers should start their
  work, this document will explain every little (at first maybe irrelevant)
  step, and help you create that first package, and to gain some experience
  in building next releases of that and maybe other packages later on.

  <sect id="choose">Choose your program.

  <p>You have probably chosen the package you want to build, but here are
  some pointers for you as the uninitiated:

  <list>
  <item>check if the package is in the distribution already. If you use the
  `stable' distribution, maybe it's best that you go to the
  <url name="package search page" id="http://www.debian.org/distrib/packages.html">.
  If you use <strong>current</strong> `unstable' distribution, check it out
  with these commands:
  <example>
  dpkg -s program
  dpkg -l '*program*'
  </example>

  <item>consult the <url name="WNPP page" id="http://www.debian.org/devel/wnpp/">
  and debian-devel mailing list archives to see if anyone else is building
  that same package. If so, contact the current maintainer if you feel you
  need to. If not - find another interesting program that nobody maintains.
  </item>

  <item>program <strong>must</strong> have a license, if possible free as
  according to the <url name="Debian Free Software Guidelines" id="http://www.debian.org/social_contract.html#guidelines">.
  If it doesn't conform to some of these rules, it still can be included in
  `contrib' or `non-free' sections of Debian. If you are unsure about where
  should it go, ask on <email/debian-legal@lists.debian.org/.
  </item>

  <item>program certainly should <strong>not</strong> run setuid root, or
  even better - it shouldn't need to be setuid or setgid to anything.</item>

  <item>program should not be a daemon, or something that goes in */sbin
  directories.</item>

  <item>program should result in binary executable form, don't try
  libraries yet.</item>

  <item>it should be well documented, or at least understandable
  (to anyone).</item>

  <item>you should contact program's author(s) to check if they agree
  with packaging it. It is important to be able to consult with author(s)
  about the program in case of any program specific problems, so don't
  try to package unmaintained pieces of software.</item>

  <item>and last but not the least, you must know that it works, and
  have it tried for some time.</item>
  </list>

  <p>Of course, these things are just safety measures, and intended to save
  you from raging users if you do something wrong in some setuid daemon...
  When you gain some more experience in packaging, you'll be able to do such
  packages, but even the most experienced developers consult debian-devel
  mailing list when they are in doubt. And people there will gladly help.

  <p>For more help about these, check in Developer's Reference.

  <sect id="getit">Get the program, and try it out.

  <p>So the first thing to do is to find and download the original package.
  I presume that you already have the source file that you picked up at
  the author's homepage. Sources for free Linux programs usually come in
  tar/gzip format, with extension .tar.gz, and usually contain the
  subdirectory called program-version and all the sources in it. If your
  program's source comes as some other sort of archive (for instance, the
  filename ends in ".Z" or ".zip"), unpack it with appropriate
  tools, or ask on debian-mentors if you're not sure how to unpack it
  correctly (hint: issue `file archive.extension`).

  <p>As an example, I'll use program called `gentoo', an X11 GTK+ file
  manager. Note that the program is already packaged, and has changed
  substantially from the version while this text was first written.

  <p>Create a subdirectory under your home directory named 'debian' or 'deb'
  or anything you find appropriate (e.g. just ~/gentoo/ would do fine in
  this case). Place the downloaded archive in it, and uncompress it (with
  `tar xzf gentoo-0.9.12.tar.gz`). Make sure there are no errors, even some
  "irrelevant" ones, because there will most probably be problems unpacking
  on other people's systems, whose unpacking tools may or may not ignore
  those anomalies.

  <p>Now you have another subdirectory, called 'gentoo-0.9.12'. Change to
  that directory and <strong>thoroughly</strong> read the provided
  documentation. Usually there exist files named README*, INSTALL*, *.lsm
  or *.html. You must find instructions on how to correctly compile and
  install the program (most probably they'll assume you want to install to
  /usr/local/bin directory; you won't be doing that, but more on that later
  in <ref id="destdir">).

  <p>The process varies from program to program, but a lot of modern
  programs come with a `configure' script that configures the source under
  your system and makes sure that your system is in condition to compile it.
  After configuring (with `./configure`), programs are usually compiled
  with `make`. Some of them support `make check`, to run included
  self-checks. Installation in destination directories is usually done with
  `make install`.
  
  <p>Now try to compile and run your program, to make sure it works properly
  and doesn't break something else while it's installing or running.

  <p>Also, you can usually type `make uninstall` to remove all the
  installed files, and `make clean` (or better `make distclean`) to
  clean up the build directory.

  <sect id="namever">Stuff prior to `dh_make'

  <p>You should start packaging with a completely clean (pristine) source
  directory, or simply with freshly unpacked sources.
  
  <p>For the package to be built correctly, you must make the program's
  original name lowercase (if it isn't already), and you should move the
  source directory to &lt;packagename&gt;-&lt;version&gt;.
  
  <p>If the program name consists of more than one word, contract them to one
  word, or make an abbreviation. For example, program "John's little editor
  for X" package would be named johnledx, or jle4x, or whatever you decide,
  as long as it's under some reasonable limit, e.g. 20 characters.

  <p>Also check for the exact version of the program (to be included in the
  package version). If that piece of software is not numbered with versions
  like X.Y.Z, but with some kind of date, feel free to use that date as the
  version number, prepended with a "0.0." (just in case upstream people one
  day decide to release a nice version like 1.0). So, if the release or
  snapshot date was 19th of December, 1998, you can use the version string
  of 0.0.19981219. Some programs won't be numbered at all, in which case you
  should contact the upstream maintainer to see if they've got some other
  revision-tracking method.

  <sect id="dh_make">Running `dh_make'

  <p>Make sure you're in the program source directory, and issue this:

  <p><example>
  dh_make -e your.maintainer@address -f ../gentoo-0.9.12.tar.gz
  </example>

  <p>Of course, replace the string "your.maintainer@address" with your
  e-mail address for inclusion in the changelog entry and other files,
  and the filename with the name of your original source archive. See
  <manref name="dh_make" section="1"> for details.
 
  <p>Some information will come up. It will ask you what sort of package you
  want to create. Gentoo is a single binary package - it creates only one
  binary, and thus one .deb file - so we will select the first option, with
  the `s' key, check the information on the screen and confirm with pressing
  &lt;enter&gt;. As a new maintainer you are discouraged from creating
  packages with multiple binary packages, or libraries, as explained earlier.
  It's not that hard, really, but it does require a bit more knowledge,
  so we won't describe all of it here.

  <p>Please note that you should run dh_make <strong>only once</strong>,
  and that it won't behave correctly if you run it again in the same,
  already "debianized", directory. That also means that you will use a
  different method to release a new revision or a new version of your
  package in the future. Read more about that later in <ref id="update">

  <chapt id="modify">Modifying the source

  <p>Normally, programs install themselves in the /usr/local subdirectories. 
  But, Debian packages must not use that directory, since it is reserved for
  system administrator's (or user's) private use. This means that you have
  to take a look at your program's build system, usually starting with the
  Makefile. This is the script <manref name="make" section="1"> will use to
  automate building this program. For more details on Makefiles, look in
  <ref id="rules">.

  <p>Note that if your program uses GNU <manref name="automake" section="1">
  and/or <manref name="autoconf" section="1">, meaning the source includes
  Makefile.am and/or Makefile.in files, respectively, you will need to
  modify those files. This is because each automake invocation will rewrite
  Makefile.in's with information generated from Makefile.am's, and each
  ./configure invocation will do the same with Makefile's, with data from
  Makefile.in's. Editing Makefile.am files requires some knowledge of
  automake, which you can read about in the automake info entry, whereas editing
  Makefile.in files is pretty much the same as editing Makefile files, just
  pay attention on the variables, i.e. any strings surrounded with `@'s, for
  example @CFLAGS@ or @LN_S@, which are replaced with actual stuff on each
  ./configure invocation.

  <p>Also note that there isn't space here to go into <em>all</em> the
  details of fixing upstream sources, but here are a few problems people
  often run across.

  <sect id="destdir">Installation in a subdirectory

  <p>Most of the programs have some way of installing themselves in the
  existing directory structure of your system, so that their binaries get
  included in your $PATH, and that you find their documentation and manual
  pages in common places. You have to make sure that they do it correctly,
  but you have to make them install themselves in a temporary subdirectory
  that will be created under your debian/ directory, usually called
  <tt>debian/tmp</tt>, from which the maintainer tools will build a working
  .deb package. Everything that is contained in this directory will be
  installed on user's system when he installs your package, the only
  difference is that dpkg will be installing the files in the root
  directory.

  <p>Basically, you need to make the program install in debian/tmp, but
  behave correctly when placed in the root directory, i.e. when installed
  from the .deb package. With programs using GNU autoconf, this will be
  quite easy, because dh_make will set up commands for doing that
  automatically, so you might as well skip reading this section. But with
  other programs, you will most probably have to examine and edit the
  Makefiles.

  <p>Here's the relevant part of gentoo's Makefile:

  <p><example>
  # Where to put binary on 'make install'?
  BIN     = /usr/local/bin
  # Where to put icons on 'make install'? Note: if you change this,
  # gentoo will not find the icons as it starts up. You're going to
  # have to alter gentoo's icon path (in the config window, "Paths"
  # tab) to get it work.
  ICONS   = /usr/local/lib/gentoo/
  </example>

  <p>Before all that, you should insert a new two lines that say:

  <p><example>
  # Edited for Debian GNU/Linux.
  DESTDIR =
  </example>
  because the build process requires it (will be explained later, in
  <ref id="rules">).

  <p>Then the Makefile mentions the location of the final binary. Just
  change that to this:
  <p><example>
  # Where to put binary on 'make install'?
  BIN     = $(DESTDIR)/usr/X11R6/bin
  </example>

  <p>But why in that directory, and not some other? Because Debian has
  defined some rules on where programs are to be installed. That is specified
  in the Filesystem Hierarchy Standard (see /usr/share/doc/debian-policy/fhs/).
  So, we should install the binary in /usr/X11R6/bin instead of /usr/local/bin,
  and the man page (it doesn't exist here, but almost every program has one,
  so we'll make one later) in /usr/share/man/man1 instead of /usr/local/man/man1.

  <p>After that we have a bit harder situation. If you change one line to:

  <p><example>
  ICONS   = $(DESTDIR)/usr/share/gentoo/
  </example>
  which conforms to the policy, you will have to edit some real C sources.
  But where and what to search? You can find this out by issuing:
  <p><example>
  grep -n usr/local/lib *.[ch]
  </example>
  (in every subdirectory that contains .c and .h files). Grep will tell
  you the name of the file and the line in it, when it finds an occurrence.
  Now edit those files and in those lines replace usr/local/lib with
  usr/share - and that is it. Just replace usr/local/lib with your location,
  and be very careful that you don't mess up the rest of the code, if you
  don't know much about programming in C. :-)

  <p>After that you should find the install target (search for line that
  starts with `install:') and rename all references to directories other
  than ones defined at the top of the Makefile. Previously, gentoo's
  install target said:

  <p><example>
  # ----------------------------------------- Installation

  # You're going to have to be root to do this!
  install:        gentoo
                  install ./gentoo $(BIN)
                  install icons $(ICONS)
                  install gentoorc-example $(HOME)/.gentoorc
  </example>

  <p>After our change it says:
  <example>
  # ----------------------------------------- Installation

  # You're going to have to be root to do this!
  install:        gentoo-target
                  install -d $(BIN) $(ICONS) $(DESTDIR)/etc
                  install ./gentoo $(BIN)
                  install -m644 icons/* $(ICONS)
                  install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
                  install -d $(DESTDIR)/usr/share/doc/gentoo/html
                  cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html
  </example>

  <p>A careful reader will notice that I changed `gentoo' to `gentoo-target'
  in the `install:' line. That is called bug fix :-)

  <p>Whenever you make changes that are not specifically related to Debian
  package, be sure to send them to the upstream maintainer so they can be
  included in the next program revision. Note that you don't have to send
  the debian/* files upstream, but you should do so with any other patches.
  And try to be nice to upstream, by making your fixes not specific to
  Debian or Linux (or even Unix!) prior to sending them.

  <sect id="difflibs">Differing libraries

  <p>There is one other common problem: libraries are often different from
  platform to platform. For example, Makefile can contain a reference to a
  library which doesn't exist on Debian, or even Linux. In that case, we
  need to change it to a library which does exist in Debian, and serves the
  same purpose. The best way is to comment out those lines because there may
  be others who will try to compile on different platforms, so that they can
  have some hints about what could be the problem.

  <p>So, if there is a line in your program's Makefile (or Makefile.in) that
  says something like this (and your program doesn't compile):

  <p><example>
  LIBS = -lcurses -lsomething -lsomethingelse
  </example>

  <p>Change it to this, and it will most probably work:
  <p><example>
  LIBS = -lncurses -lsomething -lsomethingelse
  #LIBS = -lcurses -lsomething -lsomethingelse
  </example>

  <chapt id="dreq">Required stuff under debian/

  <p>There is a new subdirectory under the program's main directory
  (`gentoo-0.9.12'), it is called `debian'. There are a number of files
  in this directory. We will be editing these in order to customize
  the behavior of the package. The most important of them are `control',
  `changelog', `copyright' and 'rules', which are required for all packages.

  <sect id="control">`control' file

  <p>This file contains various values which dpkg and dselect will use to
  manage the package. Here is the control file dh_make creates for us.

  <p><example>
  1  Source: gentoo
  2  Section: unknown
  3  Priority: optional
  4  Maintainer: Josip Rodin &lt;jrodin@jagor.srce.hr&gt;
  5  Standards-Version: 3.0.1
  6
  7  Package: gentoo
  8  Architecture: any
  9  Depends: ${shlibs:Depends}
  10 Description: &lt;insert up to 60 chars description&gt;
  11  &lt;insert long description, indented with spaces&gt;
  </example>
  (I've added the line numbers.)

  <p>Lines 1-5 are the control information for the source package. Line 1
  is the name of the source package.

  <p>Line 2 is the section of the distribution this package goes into. 
  As you may have noticed, Debian is divided in sections: main (the free
  software), non-free (the not really free software) and contrib (free
  software that depends on non-free software). Under those, there are
  logical subsections that describe in short what packages are in.
  So we have `admin' for administrator-only programs, `base' for the
  basic tools, `devel' for programmer tools, `doc' for documentation,
  `libs' for libraries, `mail' for e-mail readers and daemons, `net' for
  network apps and daemons, `x11' for X11 specific programs, and many more.

  <p>Let's change it then to x11.

  <p>Line 3 describes how important it is that the user install this package.
  Section and priority are actually only used by dselect when it sorts
  packages and selects defaults, and they can (and most probably will be)
  overridden by our FTP maintainers. See the Policy manual for guidance on
  what to set these fields to.
  
  <p>As it is a normal priority package, we'll leave it as optional.

  <p>Line 4 is the name and email address of the maintainer.

  <p>Line 5 is the version of the Debian Policy standards this package follows
  (two major versions of the installed debian-policy package).

  <p>If some non-standard compiler or other tool is needed to build your
  package, you should add here a `Build-Depends' line and list the
  required packages. For more information on this, read the Packaging Manual
  (section 8.7) and documentation of the `build-essential' package.

  <p>Line 7 is the name of the binary package.

  <p>Line 8 describes the CPU architecture the binary package can be compiled
  for. We can leave this as "any" because <manref name="dpkg-gencontrol"
  section="1"> will fill in the appropriate value for any machine this
  package gets compiled on (see the Developer's Reference for explanation on
  what porting packages is). If your package is architecture independent
  (for example, a shell or Perl script, or a document), change this to
  "all", and read later in <ref id="rules"> about using `binary-indep'
  rule instead of `binary-arch' for building the package.

  <p>Line 9 shows one of the most powerful features of the Debian packaging
  system. Packages can relate to each other in various ways. Apart from
  Depends:, other relationship fields are Recommends:, Suggests:,
  Pre-Depends:, Conflicts:, Provides:, and Replaces: .

  <p>The package management tools such as dpkg, dselect or APT (and its
  front-ends) usually behave the same way when dealing with these relations;
  if not, it will be explained.
  (see <manref name="dpkg" section="8">, <manref name="dselect" section="8">,
  <manref name="apt" section="8">, <manref name="console-apt" section="8">,
  <manref name="gnome-apt" section="8">)

  <p>This is what they usually mean:

  <p><list>
  <item>Depends:
  <p>The package will not be installed unless the packages it depends on
  are installed. Use this if your program absolutely will not run (or will
  cause severe breakage) unless a particular package is present.</item>

  <item>Recommends:
  <p>Dselect will not install your package unless the packages it recommends
  are installed. Dpkg and APT should let you do it, though. Use this for
  packages that are not strictly necessary but are typically used with your
  program.</item>

  <item>Suggests:
  <p>When a user installs your program, dselect will prompt him to install
  any package it suggests. Dpkg and APT shouldn't care much. Use this for
  packages which will work nicely with your program but are not at all
  necessary.</item>

  <item>Pre-Depends:
  <p>This is stronger than Depends:. The package will not be installed
  unless the packages it pre-depends on are installed <em>and correctly
  configured</em>. Use this <strong>very</strong> sparingly and only after
  discussing it on the debian-devel mailing list. Read: don't use it at
  all. :-)</item>

  <item>Conflicts:
  <p>The package will not be installed until all the packages it conflicts
  with have been removed. Use this if your program absolutely will not run
  (or will cause severe breakage) if a particular package is present.</item>

  <item>Provides:
  <p>For some types of packages where there are multiple alternatives
  virtual names have been defined. You can get the full list in
  /usr/share/doc/debian-policy/virtual-package-names-list.text.gz file.
  Use this if your program provides a function of an existing virtual
  package.</item>

  <item>Replaces:
  <p>Use this when your program replaces files from another package, or
  completely replaces another package (used in conjunction with Conflicts:).
  Files from the named packages will be removed before installing yours.
  </item>
  </list>

  <p>All these fields have uniform syntax. They are a list of package names
  separated by commas. These package names may also be lists of alternative
  package names, separated by vertical bar symbols <tt>|</tt> (pipe symbols).
  The fields may restrict their applicability to particular versions of each
  named package. These versions are listed in parentheses after each
  individual package name, and they should contain a relation from the list
  below followed by the version number. The relations allowed are:
  <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>, <tt>=</tt>, <tt>&gt;=</tt> and
  <tt>&gt;&gt;</tt> for strictly earlier, earlier or equal, exactly equal,
  later or equal and strictly later, respectively.
  
  <p>The last feature you need to know about is $(shlibs:Depends). This will
  be automatically generated by <manref name="dh_shlibdeps" section="1"> and
  filled in by <manref name="dh_gencontrol" section="1"> with the names of
  any shared libraries your program uses, such as libc6 or xlib6g, so you
  don't have to specify them yourself. Having said all that, we can leave
  line 9 exactly as it is now.

  <p>Line 10 is where the list of suggestions go. Here it's only `file',
  because gentoo can use some features provided by that program/package.

  <p>Line 11 is the short description. Most people screens are 80 columns
  wide so this shouldn't be longer than about 60 characters. I'll change
  it to "A fully GUI configurable GTK+ file manager".

  <p>Line 12 is where the long description goes. This should be a paragraph
  which gives more detail about the package. Column 1 of each line should
  be empty. There must be no blank lines, but you can put a . (dot) in a
  column to simulate that. Also, there must be no more that one blank line
  after the long description.

  <p>Here is the updated control file:

  <p><example>
  1  Source: gentoo
  2  Section: x11
  3  Priority: optional
  4  Maintainer: Josip Rodin &lt;jrodin@jagor.srce.hr&gt;
  5  Standards-Version: 3.0.1
  6
  7  Package: gentoo
  8  Architecture: any
  9  Depends: ${shlibs:Depends}
  10 Suggests: file
  11 Description: A fully GUI configurable GTK+ file manager
  12  gentoo is a file manager for Linux written from scratch in pure C. It
  13  uses the GTK+ toolkit for all of its interface needs. gentoo provides
  14  100% GUI configurability; no need to edit config files by hand and re-
  15  start the program. gentoo supports identifying the type of various
  16  files (using extension, regular expressions, or the 'file' command),
  17  and can display files of different types with different colors and icons.
  18  .
  19  gentoo borrows some of its look and feel from the classic Amiga file
  20  manager "Directory OPUS" (written by Jonathan Potter).
  </example>
  (I've added the line numbers.)

  <sect id="copyright">`copyright' file

  <p>This file contains the information about package upstream resources,
  copyright and license information. Its format is not dictated by the
  Policy, but the contents is (section 6.5). Dh_make created a default
  one, this is what it looks like:

  <p><example>
  1  This package was debianized by Josip Rodin &lt;jrodin@jagor.srce.hr&gt; on
  2  Wed, 11 Nov 1998 21:02:14 +0100.
  3
  4  It was downloaded from &lt;fill in ftp site&gt;
  5
  6  Upstream Author(s): &lt;put author(s) name and email here&gt;
  7
  8  Copyright:
  9
  10 &lt;Must follow here&gt;
  </example>
  (I've added the line numbers.)

  <p>The important things to add to this file are the place you got the
  package from and the actual copyright notice and license. You must
  include the complete license, unless it's one of the common free software
  licenses such as GNU GPL or LGPL, BSD or the Artistic license, when you
  can just refer to the appropriate file in /usr/share/common-licenses/
  directory that exists on every Debian system. Gentoo is licensed under
  the GNU General Public License, so we'll change the file to this:

  <p><example>
  1  This package was debianized by Josip Rodin &lt;jrodin@jagor.srce.hr&gt; on
  2  Wed, 11 Nov 1998 21:02:14 +0100.
  3
  4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
  5
  6  Upstream author: Emil Brink &lt;emil@obsession.se&gt;
  7
  8  This software is copyright (c) 1998-99 by Emil Brink, Obsession
  9  Development.
  10
  11 You are free to distribute this software under the terms of
  12 the GNU General Public License.
  13 On Debian systems, the complete text of the GNU General Public
  14 License can be found in /usr/share/common-licenses/GPL file.
  </example>
  (I've added the line numbers.)

  <sect id="changelog">`changelog' file

  <p>This is a required file, which has a special format described in
  the Packaging Manual (section 3.2.3). This format is used by dpkg and
  other programs to obtain the version number, revision, distribution and
  urgency of your package.

  <p>For you, it is also important, since it is good to have documented
  all changes you have done. It will help people downloading your package
  to see whether there are there any unresolved issues with the package
  that they should know about instantly. It will be saved as
  `/usr/share/doc/gentoo/changelog.Debian.gz' in the binary package.

  <p>Dh_make creates a default one, this is what it looks like:

  <p><example>
  1  gentoo (0.9.12-1) unstable; urgency=low
  2
  3   * Initial Release.
  4
  5  -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 21:02:14 +0100
  6
  7  Local variables:
  8  mode: debian-changelog
  9  End:
  </example>
  (I've added the line numbers.)

  <p>Line 1 is the package name, version, distribution, and urgency.
  The name must match the source package name, distribution should be
  either `unstable' or `experimental' (for now), and urgency shouldn't
  be changed to anything higher than `low'. :-)
  
  <p>Lines 3-5 are a log entry, where you document changes made in this
  package revision (not the upstream changes - there is special file for
  that purpose, created by upstream authors, installed as
  /usr/share/doc/gentoo/changelog.gz). New lines must be inserted just
  before the uppermost line that begins with asterisk (`*'). You can do
  it with <manref name="dch" section="1">, <manref name="emacs" section="1">
  (lines 7-9 contain mode information for the Emacs editor), or any other
  text editor. You will end up with something like this:

  <p><example>
  1  gentoo (0.9.12-1) unstable; urgency=low
  2
  3   * Initial Release.
  4   * This is my first Debian package.
  5   * Adjusted the Makefile to fix $DESTDIR problems.
  6
  7  -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 21:02:14 +0100
  8
  9  Local variables:
  10  mode: debian-changelog
  11 End:
  </example>
  (I've added the line numbers.)

  <p>When you release a new revision, you must increment the version number.
  You can do that with just `dch -i` or explicitly with `dch -v
  &lt;version&gt;-&lt;revision&gt;` and then insert the comments using your
  preferred editor. Tip: how to easily get the date in required format?
  Use `822-date`, or `date -R`.

  <p>New version information is added at the top of the changelog file.
  This is what the changelog looks like afterwards:

  <p><example>
  1  gentoo (0.9.12-2) unstable; urgency=low
  2
  3   * Fixed a glitch in the menu file.
  4
  5  -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 22:15:39 +0100
  6
  7  gentoo (0.9.12-1) unstable; urgency=low
  8
  9   * Initial Release.
  10  * This is my first Debian package.
  11  * Adjusted the Makefile to fix $DESTDIR problems.
  12
  13 -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 21:02:14 +0100
  14
  15 Local variables:
  16 mode: debian-changelog
  17 End:
  </example>
  (I've added the line numbers.)

  <p>You can read more about new package versions/revisions later in
  <ref id="update">.

  <sect id="rules">`rules' file

  <p>Now we need to take a look at the exact rules which
  <manref name="dpkg-buildpackage" section="1"> will use to actually create
  the package. This file is actually another Makefile, since it is executed
  with `make -f`, but different than the one in the upstream source.

  <p>Every `rules' file, as any other Makefile, consists of several rules
  specifying how to handle the source. Each rule consists of targets,
  filenames or names of actions that should be carried out (e.g. `build:'
  or `install:'). Rules that you want to execute are invoked as command
  line arguments (for example, `./debian/rules build` or `make -f rules
  install`). After the target name, you can name the dependency, program
  or file that that rule depends on. After that, there can be any number
  of commands (indented with &lt;tab&gt;!), until an empty line is found.
  There begins another rule. Multiple empty lines, and lines beginning
  with `#' (hash) are treated as comments and ignored.

  <p>You are probably confused now, but it will all be clear upon examination
  of the `rules' file that dh_make gives us as a default. You should also
  read the `make' entry in info for more information.

  <p>The important part to know about the rules file created by dh_make, is
  that it is just a suggestion. It will work for simple packages but for
  more complicated ones, don't be afraid to add and subtract from it to fit
  your needs. Only thing that you must not change are the names of the
  rules, because all the tools use these names, as mandated by the Packaging
  Manual.

  <p><example>
  1  #!/usr/bin/make -f
  2  # Made with the aid of dh_make, by Craig Small
  3  # Sample debian/rules that uses debhelper. GNU copyright 1997 by Joey Hess.
  4  # Some lines taken from debmake, by Christoph Lameter.
  5
  6  # Uncomment this to turn on verbose mode.
  7  #export DH_VERBOSE=1
  8
  9  # This is the debhelper compatibility version to use.
  10 export DH_COMPAT=1
  11
  12 build: build-stamp
  13 build-stamp:
  14	dh_testdir
  15
  16	# Add here commands to compile the package.
  17	$(MAKE)
  18
  19	touch build-stamp
  20
  21 clean:
  22	dh_testdir
  23	dh_testroot
  24	rm -f build-stamp
  25
  26	# Add here commands to clean up after the build process.
  27	-$(MAKE) clean
  28
  29	dh_clean
  30
  31 install: build-stamp
  32	dh_testdir
  33	dh_testroot
  34	dh_clean -k
  35	dh_installdirs
  36
  37	# Add here commands to install the package into debian/tmp.
  38	$(MAKE) install DESTDIR=`pwd`/debian/tmp
  39
  40 # Build architecture-independent files here.
  41 binary-indep: build install
  42 # We have nothing to do by default.
  43
  44 # Build architecture-dependent files here.
  45 binary-arch: build install
  46 #	dh_testversion
  47	dh_testdir
  48	dh_testroot
  49 #	dh_installdebconf
  50	dh_installdocs
  51	dh_installexamples
  52	dh_installmenu
  53 #	dh_installemacsen
  54 #	dh_installpam
  55 #	dh_installinit
  56	dh_installcron
  57	dh_installmanpages
  58	dh_installinfo
  59 #	dh_undocumented
  60	dh_installchangelogs
  61	dh_link
  62	dh_strip
  63	dh_compress
  64	dh_fixperms
  65	# You may want to make some executables suid here.
  66	dh_suidregister
  67 #	dh_makeshlibs
  68	dh_installdeb
  69 #	dh_perl
  70	dh_shlibdeps
  71	dh_gencontrol
  72	dh_md5sums
  73	dh_builddeb
  74
  75 binary: binary-indep binary-arch
  76 .PHONY: build clean binary-indep binary-arch binary install
  </example>
  (I've added the line numbers.)

  <p>You are probably familiar with lines like line 1 from shell and Perl
  scripts. It tells the operating system that this file is to be processed
  with /usr/bin/make.

  <p>Lines 12 through 19 describe the `build' (and its child `build-stamp')
  rule, which runs the application's own Makefile to compile the program.

  <p>The `clean' rule, as specified in lines 21-29, cleans up any unneeded
  binary or auto-generated stuff, left over from building the package.
  This rule must be working at all times (even when the source tree <em/is/
  cleaned up!), so please use the forcing options (e.g. for rm, that is
  `-f'), or ignore return values (with a `-' in front of a command name).

  <p>The installation process, the `install' rule, starts with line 31.
  It basically runs the `install' rule from the program's own Makefile,
  but installs in `pwd`/debian/tmp directory - this is why we specified
  $(DESTDIR) as the root installation directory in gentoo's Makefile.

  <p>As the comments suggest, the `binary-indep' rule, on the line 41, is
  used to build architecture independent packages. As we don't have any,
  nothing will be done there. If your package is `Architecture: all' one,
  you need to include all the commands for building the package under this
  rule, and leave the next rule (`binary-arch') empty instead.

  <p>On to the next rule - `binary-arch', on lines 45 through 73, in which
  we run several small utilities from the debhelper package that do various
  operations on your package files to make the package Policy conforming.
  
  <p>The names start with dh_, and the rest is the description of what the
  particular utility really does. It is all quite self-explanatory, but
  here are some additional explanations:

  <list>
  <item><manref name="dh_testdir" section="1"> checks that you are in the
        right directory (i.e. the top-level source directory),
  <item><manref name="dh_testroot" section="1"> checks that you have root
        permissions which is needed for binary* targets, and clean,
  <item><manref name="dh_installmanpages" section="1"> copies all the
        manpages it can find in the source tree to package (beware, this is
        DWIM),
  <item><manref name="dh_strip" section="1"> strips debugging headers from
        executable files and libraries, to make them smaller,
  <item><manref name="dh_compress" section="1"> gzips man pages and
        documentation larger than 4 kB,
  <item><manref name="dh_installdeb" section="1"> copies package related
        files (e.g. the maintainer scripts) under debian/tmp/DEBIAN directory,
  <item><manref name="dh_shlibdeps" section="1"> calculates shared libraries
        dependencies of the libraries and executables,
  <item><manref name="dh_gencontrol" section="1"> adds stuff to, and
        installs, the control file,
  <item><manref name="dh_md5sums" section="1"> generates MD5 checksums for
        all the files in the package.
  </list>

  <p>For more complete information on what do all these dh_* scripts do, and
  what are their other options, please read respective manual pages. There
  are some other, possibly very useful, dh_* scripts, which were not
  mentioned here. If you need them, read the debhelper documentation.

  <p>The binary-arch section is the one where you really should comment
  out any lines that call features you don't need. For gentoo, I'll comment
  out lines about testversion, emacsen, pam, init, cron, manpages, info,
  undocumented, suidregister, makeshlibs, and perl, simply because gentoo
  doesn't need them. Also, on the line 60, I'll need to add ` FIXES',
  because that is the name of the upstream changelog file.

  <p>The last two lines (along with any other not explained ones) are just
  some more-or-less necessary things, regarding which you can read in the
  make manual, and the Packaging Manual. For now, they're not important to
  know about.

  <chapt id="dother">Other files under debian/

  <p>You will see that there exist several other files in the debian/
  subdirectory, most of them with the `.ex' suffix, meaning that they are
  examples. If you wish or need to use any of those features, examine them
  and the related documentation (hint: the Policy Manual), rename them to
  remove the `.ex' suffix, and modify them and the rules file if necessary. 
  Some of those files, those commonly used ones, are explained in the
  following sections.

  <sect id="readme">README.Debian

  <p>Any extra details or discrepancies between the original package and
  your debianized version should be documented here. Dh_make created
  a default one, this is what it looks like:

  <example>
  gentoo for Debian
  ----------------------

  &lt;possible notes regarding this package - if none, delete this file&gt;

  Josip Rodin &lt;jrodin@jagor.srce.hr&gt;, Wed, 11 Nov 1998 21:02:14 +0100
  </example>

  <p>Since we don't have anything to put there - it is allowed to delete
  the file.


  <sect id="conffiles">conffiles

  <p>One of the most annoying things about software is when you spend a
  great deal of time and effort customizing a program only to have an
  upgrade stomp all over your changes. Debian solves this problem by
  marking configuration files so that when you upgrade a package you will
  be prompted whether you want to keep your old configuration or not. You
  do this by entering the full path to each configuration file (they are
  usually in /etc,) one per line, in a file called conffiles.

  <p>Gentoo has one conffile, /etc/gentoorc, and we'll enter that in the
  `conffiles' file. It is not actually necessary to have that file, if
  your program has no configuration files.

  <sect id="dirs">dirs

  <p>This file specifies the directories which we need but the normal
  installation procedure (make install) somehow doesn't create.

  By default, it looks like this:
  <p><example>
  usr/bin
  usr/sbin
  </example>

  <p>Note that the preceding slash is not included. We would have normally
  changed it to look like this:
  <p><example>
  usr/X11R6/bin
  usr/X11R6/man/man1
  </example>
  
  but those directories are already created in the Makefile, so we won't
  need this file, and we may delete it.

  <sect id="manpage">manpage.1.ex

  <p>The files ending in *.ex are examples of how to add that kind of
  support into the package. To use one of them, edit it and remove
  the .ex extension. If you don't want to use it, just delete it.

  <p>Your program should have a man page. If it doesn't, this is a skeleton
  you can fill out. See the man pages for <manref name="man" section="7">
  for a brief description of how to create a man page. Be sure to rename
  this file to the name of the program and make the extension the manual
  section it should go into. Here's a short list:

  <p><example>
  Section |     Description     |     Notes
     1     User commands          Executable commands or scripts.
     2     System calls           Functions provided by the kernel.
     3     Library calls          Functions within system libraries.
     4     Special files          Usually found in /dev
     5     File formats           E.g. /etc/passwd's format
     6     Games                  Or other frivolous programs
     7     Macro packages         Such as man macros.
     8     System administration  Programs typically only run by root.
     9     Kernel routines        Non-standard calls and internals.
  </example>
  
  <p>So gentoo's manpage should be called gentoo.1, or gentoo.1x because it
  is an X11 program. There was no gentoo.1 man page in the original source
  so I wrote it using information from the example and from upstream docs.

  <sect id="menu">menu.ex

  <p>X Window System users usually have a window manager with a menu that
  can be customized to launch programs. If they have installed the Debian
  "menu" package, a set of menus for every program on the system will be
  created for them. It isn't required by the Debian Policy, but users will
  surely appreciate it. We can add Gentoo to the menus by editing this
  file. Here's the default that dh_make creates:
  
  <p><example>
  ?package(gentoo):needs=X11|text|vc|wm section=Apps/see-menu-manual\
    title="gentoo" command="/usr/bin/gentoo"
  </example>

  <p>The first field specifies what kind of interface the program needs
  (e.g. text or X11). The next is the menu and submenu the entry should
  appear in. The current list of sections is at:
  /usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1
  The third field is the name of the program. The fourth is the icon for
  the program or none if there isn't one. The fifth is the actual text
  which will appear in the menu. Finally, the sixth field is the command
  that runs the program.

  <p>Now we'll change the menu entry to this:
  <p><example>
  ?package(gentoo):needs=X11 section=Apps/Misc \
    title="Gentoo" command="/usr/X11R6/bin/gentoo"
  </example>

  <p>See <manref name="menufile" section="5">, <manref name="update-menus" section="1">
  and /usr/share/doc/debian-policy/menu-policy.html/ for more information.

  <sect id="watch">watch.ex

  <p>You can use this file in addition to the <manref name="uscan" section="1">
  and <manref name="uupdate" section="1"> programs (in the devscripts package)
  to watch the site you got the original source from. Here's what I put in
  it:

  <p><example>
  # watch control file for uscan
  # Site		Directory	Pattern			Version	Script
  ftp.obsession.se	/gentoo		gentoo-(.*)\.tar\.gz	debian	uupdate
  </example>

  <p>Hint: connect to the Internet, and try running "uscan" in the program
  directory once you create the file. And read the manual pages.

  <sect id="doc-base">ex.doc-base

  <p>If your package has HTML or any other documentation (except manual
  pages and info docs), you should use the `doc-base' file to register it,
  so the user can find it with e.g. <manref name="dhelp" section="1"> or
  <manref name="dwww" section="1">.

  <p>This is how gentoo's doc-base file looks like:

  <p><example>
  Document: gentoo
  Title: Gentoo Manual
  Author: Emil Brink
  Abstract: This manual describes what Gentoo is, and how it can be used.
  Section: Apps/Tools

  Format: HTML
  Index: /usr/share/doc/gentoo/html/index.html
  Files: /usr/share/doc/gentoo/html/*.html
  </example>

  <p>For information on the file format, see <manref name="install-docs" section="8">
  and the doc-base manual, in /usr/doc/doc-base/doc-base.html/index.html.

  <sect id="maintscripts">postinst.ex, preinst.ex, postrm.ex, prerm.ex

  <p>These files are called maintainer scripts, scripts which are put in the
  control area of the package and run by dpkg when your package is installed,
  upgraded or removed.

  <p>For now, you should try to avoid any manual editing of maintainer
  scripts if you possibly can because they tend to get complex. For more
  information look in the Packaging Manual, section 6, and take a look at
  these example files provided by dh_make.

  <p>We should now be ready to build the package.

  <chapt id="final">Final steps

  <sect id="build">Building the package

  <p>Enter the program's main directory and then issue this command:

  <p><example>
  dpkg-buildpackage -rfakeroot
  </example>

  <p>This will do everything for you, you'll just have to enter your
  PGP secret key, twice. After it's done, you will see four new files
  in the directory above (~/debian/):

  <p><list>
  <item><em>gentoo_0.9.12-1_i386.deb</em>
  <p>This is the completed binary package. You can use dpkg or dselect to
  install and remove this just like any other package.

  <item><em>gentoo_0.9.12.orig.tar.gz</em>
  <p>This is the original source code gathered up so that if someone else
  wants to recreate your package from scratch they can. Or if they aren't
  using the Debian packaging system, but need to manually download the
  source and compile.

  <item><em>gentoo_0.9.12-1.dsc</em>
  <p>This is a summary of the contents of the source code. The file is
  generated from the gentoo-0.9.12/debian/control file, and is used when
  unpacking the source with <manref name="dpkg-source" section="1">. This
  file is PGP signed, so that people can be sure that it's really yours.

  <item><em>gentoo_0.9.12-1.diff.gz</em>
  <p>This compressed file contains each and every addition you made to the
  original source code, in the form known as "unified diff". It is made
  and used by <manref name="dpkg-source" section="1">.

  <item><em>gentoo_0.9.12-1_i386.changes</em>
  <p>This file describes all the changes made in the current package
  revision, and it is used by the Debian FTP archive maintenance programs
  to install the binary and source packages in it. It is partly generated
  from the gentoo-0.9.12/debian/changelog file and the .dsc file.

  <p>As you keep working on the package, behavior will change and new
  features will be added. People downloading your package can look at this
  file and quickly see what has changed. The long strings of numbers are MD5
  checksums for the files mentioned. Person downloading your files can test
  them with <manref name="md5sum" section="1"> and if the numbers don't
  match, they'll know the file is corrupt or has been hacked. This file is
  PGP signed, so that people can be even more sure that it's really yours. 
  </list>

  <p>With a large package, you may not want to rebuild from scratch every
  time while you tune a detail in debian/rules. For testing purposes, you
  can make a .deb file without rebuilding the upstream sources like this:

  <p><example>
  fakeroot debian/rules binary
  </example>

  <p>Just make sure that your `install' rule does <strong/not/ have
  `install-stamp' child (that's the default nowadays), to make sure
  `dh_clean -k` is run each time. And once you are finished with cleanups,
  remember to rebuild following the right procedure, to be able to
  upload correctly.

  <sect id="checkit">Checking the package for errors

  <p>Run <manref name="lintian" section="1"> on your .changes file; this
  program will check for many common packaging errors. The command is:
  
  <p><example>
  lintian -i gentoo_0.9.12-1_i386.changes
  </example>
  
  <p>Of course, replace the filename with the name of the changes file
  generated for your package. If it appears that there are some errors
  (lines beginning with E:), read the explanation (the N: lines), correct
  mistakes, and rebuild as described in <ref id="build">. If there are
  lines that begin with W:, those are only warnings, so you can be pretty
  much sure that your package is okay (but it most probably needs some tuning).

  <p>Note that you can build the package with dpkg-buildpackage and run
  lintian all in one command with <manref name="debuild" section="1">.

  <p>Look inside the package using a file manager like <manref name="mc" section="1">,
  or unpack it in a temporary place using <manref name="dpkg-deb" section="1">.
  Be on the lookout for extra unneeded files both in the binary and source
  package, in case something went wrong and some cruft didn't get cleaned
  up. Tips: `zgrep ^+++ ../gentoo_0.9.12-1.diff.gz` will give you a list of
  your changes/additions to the source files, and `dpkg-deb -c gentoo_0.9.12-1_i386.deb`
  will list the files in the package.

  <p>Install the package to test it yourself, e.g. using the
  <manref name="debi" section="1"> command as root. Try to install and run
  it on machines other than your own and watch closely for any warnings
  or errors both on installation and running the program.

  <p>Later, when you build a new version, you should do the following to
  ensure basic upgradability of the package:

  <list>
  <item>upgrade from the previous version (and from the version in last Debian release),
  <item>downgrade back again,
  <item>install the package as a new package (i.e., with no previous version installed),
  <item>uninstall it, reinstall it again, and then purge it.
  </list>

  <sect id="upload">Uploading the package

  <p>Now that you have tested your new package thoroughly, you'll need to
  upload these files to master.debian.org, using <manref name="dupload" section="1">.
  First you have to set up dupload's config file, ~/.dupload.conf . Put
  something like this in it:

  <p><example>
  package config;
  $default_host = "master";
  
  $cfg{"master"}{"method"} = "scpb";
  $cfg{"master"}{"login"} = "joy";
  $cfg{"master"}{"visibleuser"} = "jrodin";
  $cfg{"master"}{"visiblename"} = "jagor.srce.hr";
  $cfg{"master"}{"fullname"} = "Josip Rodin";
  
  $cfg{"non-us"}{"method"} = "scpb";
  $cfg{"non-us"}{"login"} = "joy";
  $cfg{"non-us"}{"visibleuser"} = "jrodin";
  $cfg{"non-us"}{"visiblename"} = "jagor.srce.hr";
  $cfg{"non-us"}{"fullname"} = "Josip Rodin";
  
  1;
  </example>

  <p>Of course, change my personal settings to yours, and read the
  <manref name="dupload.conf" section="5"> manual page to understand
  what each of these options means.

  <p>Then connect to your Internet provider, and issue this command:
  
  <p><example>
  dupload --to master gentoo_0.9.12-1_i386.changes
  </example>

  <p>Dupload checks that the files' md5 checksums match those from the
  .changes file, so it will warn you to rebuild it as described in
  <ref id="build"> so it can properly upload.

  <p>Dupload will ask for your password on master.debian.org, upload the
  packages, and give a short announcement about your upload on
  <email/debian-devel-changes@lists.debian.org/ if necessary.

  <p>If you live in Europe, you can use some other upload queues instead
  of master. For details look in <manref name="dupload" section="1">,
  <manref name="dupload.conf" section="5"> and the Developer's Reference.

  <sect id="update">Updating the package

  <p>Let's say that a bug report was filed against your package, #54321,
  and it describes a problem that you can solve. To create a new Debian
  revision of the package, you need to:

  <list>
  <item>Correct the problem in the package source, of course.

  <item>Add a new revision in the Debian changelog file, with
  `dch -i`, and include a short description of the bug and the solution,
  followed by this: "Closes: #54321". That way, the bug report will be
  automagically closed by the archive maintenance software the moment your
  package gets accepted in the Debian archive.

  <item>Repeat what you did in <ref id="build">, <ref id="checkit">,
  and <ref id="upload">. The difference is that this time, original source
  archive won't be included, as it hasn't been changed and it already
  exists in the Debian archive.
  </list>

  <p>Now let's consider a different, a wee bit more complicated situation
  - a new upstream version was released, and of course you want it packaged.
  You need to do the following:

  <list>
  <item>Download the new sources and put the tarball (e.g. named
  `gentoo-0.9.13.tar.gz') in the directory above the old source tree
  (e.g. ~/debian/).

  <item>Enter the old source directory, and run:

  <example>
  uupdate -u gentoo-0.9.13.tar.gz
  </example>

  Of course, replace this filename with the name of your program's source
  archive. <manref name="uupdate" section="1"> will properly rename that
  tarball, try to apply all the changes from your previous .diff.gz file,
  and update the new debian/changelog file.

  <item>Change directory to `../gentoo-0.9.13', the new package source tree,
  and repeat what you did in <ref id="build">, <ref id="checkit">, and
  <ref id="upload">.
  </list>

  <p>Note that if you set up `debian/watch' file as described in
  <ref id="watch">, you can run <manref name="uscan" section="1"> to
  automagically look for revised sources, download them, and run uupdate.

  <sect id="helpme">Where to ask for help

  <p>Before you decide to ask your question in some public place, please
  just RTFM. That includes documentation in /usr/share/doc/dpkg,
  /usr/share/doc/debian, /usr/share/doc/package/* files and the man/info
  pages for all the programs mentioned in this article. When you receive
  a bug report (yes, actual bug reports!), you will know that it is time
  that you dig in the <url name="Debian Bug Tracking System" id="http://www.debian.org/Bugs/">
  and read the documentation there, to be able to deal with the reports
  efficiently.

  <p>By joining the Debian Mentors' mailing list at <email/debian-mentors@lists.debian.org/
  you can team up with experienced Debian developers who will help you with
  questions you might have. You can subscribe to it by sending e-mail
  to <email/debian-mentors-request@lists.debian.org/ with the word
  `subscribe' in the message subject.

  <p>If you still have questions, ask on the Debian Developers' mailing list
  at <email/debian-devel@lists.debian.org/. You can subscribe to it by
  sending e-mail to <email/debian-devel-request@lists.debian.org/ with the
  word `subscribe' in the message subject. If you are already a Debian
  developer, you should be subscribed to it anyway.

  <p>Even if it all worked well, it's time to start praying. Why? Because
  in just a few hours (or days) users from all around the world will start
  to use your package, and if you made some critical error you'll get
  mailbombed by numerous angry Debian users... Just kidding. :-)

  <p>Relax and be ready for bug reports, because there is a lot more work
  to be done before it will be fully in line with Debian policies (once again,
  read the <em>real documentation</em> for details). Good luck!

 </book>

</debiandoc>