/[ddp]/manuals/trunk/maint-guide/maint-guide.en.dbk
ViewVC logotype

Diff of /manuals/trunk/maint-guide/maint-guide.en.dbk

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 8611 by osamu, Thu Mar 31 16:47:55 2011 UTC revision 8637 by osamu, Tue Apr 5 17:46:29 2011 UTC
# Line 14  Line 14 
14  <author> <personname> <firstname>Osamu</firstname> <surname>Aoki</surname> </personname> <email>osamu@debian.org</email> <contrib>(updated contents)</contrib> </author>  <author> <personname> <firstname>Osamu</firstname> <surname>Aoki</surname> </personname> <email>osamu@debian.org</email> <contrib>(updated contents)</contrib> </author>
15    
16    
 <!-- BEGIN: Add othercredit for translator via po4a/maint-guide.*.patch -->  
 <!-- END: Add othercredit for translator via po4a/maint-guide.*.patch -->  
17    
18    
19    <!-- BEGIN: Add othercredit for translator via po4a/maint-guide.*.patch -->
20    <!-- END: Add othercredit for translator via po4a/maint-guide.*.patch -->
21    <!-- dummy -->
22    <!-- dummy -->
23  </authorgroup>  </authorgroup>
24  <releaseinfo>version &docversion;</releaseinfo>  <releaseinfo>version &docversion;</releaseinfo>
25  <pubdate>&docisodate;</pubdate>  <pubdate>&docisodate;</pubdate>
# Line 53  exempla!</emphasis> (It's a long way by Line 55  exempla!</emphasis> (It's a long way by
55  examples!).  examples!).
56  </para>  </para>
57  <para>  <para>
58  This document has been updated for the Debian <literal>squeeze</literal>  This document has been updated for the Debian <literal>&base-release;</literal>
59  release.  <footnote><para> The document assumes you are using the  release.
60  <literal>squeeze</literal> system.  If you need to follow this text in the  <footnote><para> The document assumes you are using the
61  <literal>lenny</literal> system, you must install backported <systemitem role="package">dpkg</systemitem> and <systemitem role="package">debhelper</systemitem> packages, at least.  </para> </footnote>  <literal>&base-release;</literal> system or newer.  If you need to follow this
62    text in the older system (including the older Ubuntu system), you must install
63    backported <systemitem role="package">dpkg</systemitem> and <systemitem
64    role="package">debhelper</systemitem> packages, at least.  </para> </footnote>
65  </para>  </para>
66  <para>  <para>
67  One of the things that makes Debian such a top-notch distribution is its  One of the things that makes Debian such a top-notch distribution is its
# Line 78  help you create that first package, and Line 83  help you create that first package, and
83  next releases of that and maybe other packages later on.  next releases of that and maybe other packages later on.
84  </para>  </para>
85  <para>  <para>
86    You must be familiar with <ulink url="&debref;">basic Debian system
87    operations</ulink> before reading this document.
88    </para>
89    <para>
90  If you need some help on packaging, please read <xref linkend="helpme"/> .  If you need some help on packaging, please read <xref linkend="helpme"/> .
91  </para>  </para>
92  <para>  <para>
93  Newer versions of this document should always be available online at <ulink url="http://www.debian.org/doc/maint-guide/">http://www.debian.org/doc/maint-guide/</ulink>  Newer versions of this document should always be available online at
94  and in the <systemitem role="package">maint-guide</systemitem> package.  <ulink url="&maint-guide;"/> and in the
95    <systemitem role="package">maint-guide</systemitem> package.
96    </para>
97    <para>
98    The translations may be available in packages such as <systemitem role="package">maint-guide-es</systemitem>.
99  </para>  </para>
 <!--  
  Translation in [[this language]] is also available in the  
 <systemitem role="package">maint-guide-xy</systemitem> package.  
 -->  
100  <section id="needprogs"><title>Programs you need for development</title>  <section id="needprogs"><title>Programs you need for development</title>
101  <para>  <para>
102  Before you start anything, you should make sure that you have properly  Before you start anything, you should make sure that you have properly
# Line 99  doesn't contain any packages marked <lit Line 108  doesn't contain any packages marked <lit
108  The following packages come with the standard Debian installation, so you  The following packages come with the standard Debian installation, so you
109  probably have them already (along with any additional packages they depend on).  probably have them already (along with any additional packages they depend on).
110  Still, you should check it with <literal>aptitude show  Still, you should check it with <literal>aptitude show
111  <replaceable>package</replaceable></literal>.  <replaceable>package</replaceable></literal>
112    or with <literal>dpkg -s <replaceable>package</replaceable></literal>.
113  </para>  </para>
114  <para>  <para>
115  The most important package to install on your development system is the  The most important package to install on your development system is the
# Line 281  you should read along with this document Line 291  you should read along with this document
291  <itemizedlist>  <itemizedlist>
292  <listitem>  <listitem>
293  <para>  <para>
294  <systemitem role="package">debian-policy</systemitem> - the <ulink url="http://www.debian.org/doc/devel-manuals#policy">Debian Policy  <systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy
295  Manual</ulink> includes explanations of the structure and contents of the  Manual</ulink> includes explanations of the structure and contents of the
296  Debian archive, several OS design issues, the Filesystem Hierarchy Standard  Debian archive, several OS design issues, the Filesystem Hierarchy Standard
297  (which says where each file and directory should be) etc.  For you, the most  (which says where each file and directory should be) etc.  For you, the most
298  important thing is that it describes requirements that each package must  important thing is that it describes requirements that each package must
299  satisfy to be included in the distribution (see  satisfy to be included in the distribution (see
300  <filename>&debian-policy;</filename>).  <ulink url="&policy-pdf;">local PDF copy</ulink>).
301  </para>  </para>
302  </listitem>  </listitem>
303  <listitem>  <listitem>
304  <para>  <para>
305  <systemitem role="package">developers-reference</systemitem> - the <ulink url="http://www.debian.org/doc/devel-manuals#devref">Debian Developer's  <systemitem role="package">developers-reference</systemitem> - the <ulink url="&developers-reference;">Debian Developer's
306  Reference</ulink> describes all matters not specifically about the technical  Reference</ulink> describes all matters not specifically about the technical
307  details of packaging, like the structure of the archive, how to rename, orphan,  details of packaging, like the structure of the archive, how to rename, orphan,
308  pick up packages, how to do NMUs, how to manage bugs, best packaging practices,  pick up packages, how to do NMUs, how to manage bugs, best packaging practices,
309  when and where to upload etc.  (see  when and where to upload etc.  (see
310  <filename>&developers-reference;</filename>).  <ulink url="&developers-reference-pdf;">local PDF copy</ulink>).
311  </para>  </para>
312  </listitem>  </listitem>
313  <listitem>  <listitem>
314  <para>  <para>
315  <ulink url="http://www.lrde.epita.fr/~adl/autotools.html">Autotools  <ulink url="&autotools-tutorial;">Autotools
316  Tutorial</ulink> provides very good tutorial for <ulink url="http://en.wikipedia.org/wiki/GNU_build_system">the GNU Build System known  Tutorial</ulink> provides very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
317  as the GNU Autotools</ulink> whose most important components are Autoconf,  as the GNU Autotools</ulink> whose most important components are Autoconf,
318  Automake, Libtool, and gettext.  Automake, Libtool, and gettext.
319  </para>  </para>
# Line 311  Automake, Libtool, and gettext. Line 321  Automake, Libtool, and gettext.
321  <listitem>  <listitem>
322  <para>  <para>
323  <systemitem role="package">gnu-standards</systemitem> - this package contains  <systemitem role="package">gnu-standards</systemitem> - this package contains
324  two pieces of documentation from the GNU project: <ulink url="http://www.gnu.org/prep/standards/html_node/index.html">GNU Coding  two pieces of documentation from the GNU project: <ulink url="&gnu-standard;">GNU Coding
325  Standards</ulink>, and <ulink url="http://www.gnu.org/prep/maintain/html_node/index.html">Information for  Standards</ulink>, and <ulink url="&gnu-maintainer;">Information for
326  Maintainers of GNU Software</ulink>.  Although Debian does not require these to  Maintainers of GNU Software</ulink>.  Although Debian does not require these to
327  be followed, these are still helpful as guidelines and common sense.  (see  be followed, these are still helpful as guidelines and common sense.  (see
328  <filename>/usr/share/doc/gnu-standards/standards.html</filename> and  <filename>/usr/share/doc/gnu-standards/standards.html</filename> and
# Line 410  limited upload right to the official Deb Line 420  limited upload right to the official Deb
420  </listitem>  </listitem>
421  </itemizedlist>  </itemizedlist>
422  <para>  <para>
423  There are several version names used around Debian.  There are several version names<footnote><para>see <ulink url="&policy-control;#s-f-Version">Debian Policy  Manual: 5.6.12 Version</ulink>.</para></footnote> used around Debian.
424  </para>  </para>
425  <itemizedlist>  <itemizedlist>
426  <listitem>  <listitem>
# Line 452  Please read the other manuals if you nee Line 462  Please read the other manuals if you nee
462  </section>  </section>
463  <section id="debiandeveloper"><title>Official Debian Developer</title>  <section id="debiandeveloper"><title>Official Debian Developer</title>
464  <para>  <para>
465  You can not become an official <emphasis role="strong">Debian  You can not become an official
466  Developer</emphasis> (DD) over night because it takes more than technical  <emphasis role="strong">Debian Developer</emphasis> (DD) over night because it
467  skill.  Please do not be discouraged by this.  If it is useful to others, you  takes more than technical skill.  Please do not be discouraged by this.  If it
468  can still upload your package either as a <emphasis role="strong">maintainer</emphasis> through a <emphasis role="strong">sponsor</emphasis> or as a <emphasis role="strong">Debian  is useful to others, you can still upload your package either as a
469  Maintainer</emphasis>.  See <ulink url="&newmaint;">Debian New  <emphasis role="strong">maintainer</emphasis> through a
470  Maintainers</ulink> for more.  <emphasis role="strong">sponsor</emphasis> or as a
471    <emphasis role="strong">Debian Maintainer</emphasis>.
472    </para>
473    <para>
474    See
475    <ulink url="&nm-do;">Debian New Maintainer site</ulink> and
476    <ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> for more.
477  </para>  </para>
478  <para>  <para>
479  Please note that you do not need to create any new package to become an  Please note that you do not need to create any new package to become an
# Line 467  waiting for good maintainers (see <xref Line 483  waiting for good maintainers (see <xref
483  </para>  </para>
484  </section>  </section>
485  <section id="helpme"><title>Where to ask for help</title>  <section id="helpme"><title>Where to ask for help</title>
 <!--  
  /usr/share/doc/debian is used be doc-debian and debian-faq  
 -->  
486  <para>  <para>
487  Before you decide to ask your question in some public place, please just RTFM.  Before you decide to ask your question in some public place, please read the fine documentation.
488  That includes documentation in <filename>/usr/share/doc/dpkg</filename>,  </para>
489  <filename>/usr/share/doc/debian</filename>,  <itemizedlist>
490  <filename>&autotools-dev;</filename>,  <listitem>
491  <filename>/usr/share/doc/<replaceable>package</replaceable>/*</filename> files  <para>
492  and the <command>man</command>/<command>info</command> pages for all the  files in <filename>/usr/share/doc/dpkg</filename>
493  programs mentioned in this document.  See all the information at <ulink url="&nm-home;">&nm-home;</ulink>.  </para>
494    </listitem>
495    <listitem>
496    <para>
497    files in <filename>/usr/share/doc/debian</filename>
498    <!-- /usr/share/doc/debian is used be doc-debian and debian-faq -->
499    </para>
500    </listitem>
501    <listitem>
502    <para>
503    files in <filename>/usr/share/doc/autotools-dev</filename>
504    </para>
505    </listitem>
506    <listitem>
507    <para>
508    files in <filename>/usr/share/doc/<replaceable>package</replaceable></filename> for all pertinent packages.
509    </para>
510    </listitem>
511    <listitem>
512    <para>
513    contents of "<literal><command>man</command> <replaceable>command</replaceable></literal>" for all pertinent commands
514    </para>
515    </listitem>
516    <listitem>
517    <para>
518    contents of "<literal><command>info</command> <replaceable>command</replaceable></literal>" for all pertinent commands
519    </para>
520    </listitem>
521    <listitem>
522    <para>
523    contents of <ulink url="&nm-do;">Debian New Maintainer site</ulink>
524    </para>
525    </listitem>
526    <listitem>
527    <para>
528    contents of <ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink>
529    </para>
530    </listitem>
531    <listitem>
532    <para>
533    contents of <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list archive</ulink>
534    </para>
535    </listitem>
536    <listitem>
537    <para>
538    contents of <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list archive</ulink>
539    </para>
540    </listitem>
541    </itemizedlist>
542    <para>
543    Please consider to use web search engine effectively by including search string
544    such as "<literal>site:lists.debian.org</literal>" to limit the domain.
545  </para>  </para>
546  <para>  <para>
547  Making a small test package is good way to learn details of packaging.  Making a small test package is good way to learn details of packaging.
# Line 486  people make packages. Line 550  people make packages.
550  </para>  </para>
551  <para>  <para>
552  If you still have questions about packaging that you couldn't find answers to  If you still have questions about packaging that you couldn't find answers to
553  in the available documentation and web resources, you can ask them on the  in the available documentation and web resources, you can ask them interactively.
554  Debian Mentors' mailing list at <ulink url="http://lists.debian.org/debian-mentors/">debian-mentors@lists.debian.org</ulink>.  </para>
555  The more experienced Debian developers will gladly help you, but do read at  <itemizedlist>
556  least some of the documentation before asking a question!  <listitem>
557    <para>
558    <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list</ulink>. (This mailing list is for the novice.)
559  </para>  </para>
560    </listitem>
561    <listitem>
562  <para>  <para>
563  See <ulink url="http://lists.debian.org/debian-mentors/">http://lists.debian.org/debian-mentors/</ulink>  <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list</ulink>. (This mailing list is for the expert.)
 for more information about this mailing list.  
564  </para>  </para>
565    </listitem>
566    <listitem>
567  <para>  <para>
568  When you receive a bug report (yes, actual bug reports!), you will know that it  <ulink url="&irc-debian;">IRC</ulink> such as <literal>#debian-mentors</literal>.
569  is time for you to dig into the <ulink url="http://www.debian.org/Bugs/">Debian  </para>
570  Bug Tracking System</ulink> and read the documentation there, to be able to  </listitem>
571  deal with the reports efficiently.  I highly recommend reading the <ulink url="http://www.debian.org/doc/manuals/developers-reference/pkgs.html#bug-handling">Developer's  </itemizedlist>
572  Reference, 5.8.  'Handling bugs'</ulink>.  <para>
573    The more experienced Debian developers will gladly help you, but do read at
574    least some of the documentation before asking a question!
575  </para>  </para>
576  <para>  <para>
577  If you still have questions, ask on the Debian Developers' mailing list at  When you receive a bug report (yes, actual bug reports!), you will know that it
578  <ulink url="http://lists.debian.org/debian-devel/">debian-devel@lists.debian.org</ulink>.  is time for you to dig into the
579  See <ulink url="http://lists.debian.org/debian-devel/">http://lists.debian.org/debian-devel/</ulink>  <ulink url="&bts;">Debian Bug Tracking System</ulink>
580  for more information about this mailing list.  and read the documentation there, to be able to
581    deal with the reports efficiently.  I highly recommend reading the
582    <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8.  'Handling bugs'</ulink>.
583  </para>  </para>
584  <para>  <para>
585  Even if it all worked well, it's time to start praying.  Why?  Because in just  Even if it all worked well, it's time to start praying.  Why?  Because in just
# Line 530  Let's try to make your own package (or, Line 603  Let's try to make your own package (or,
603  <para>  <para>
604  You have probably chosen the package you want to create.  The first thing you  You have probably chosen the package you want to create.  The first thing you
605  need to do is check if the package is in the distribution archive already by  need to do is check if the package is in the distribution archive already by
606  using <command>aptitude</command>.  using the following.
 </para>  
 <para>  
 You can also check package information through <ulink url="http://www.debian.org/distrib/packages">package search page</ulink> and  
 <ulink url="http://packages.qa.debian.org/common/index.html">Debian Package  
 Tracking System</ulink>.  
607  </para>  </para>
608    <itemizedlist>
609    <listitem>
610    <para>the <command>aptitude</command> command</para>
611    </listitem>
612    <listitem>
613    <para><ulink url="&packages-do;">Debian packages</ulink> web page</para>
614    </listitem>
615    <listitem>
616    <para><ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
617    </listitem>
618    </itemizedlist>
619  <para>  <para>
620  If the package already exists, well, install it!  :-) If it happens to be  If the package already exists, well, install it!  :-) If it happens to be
621  <emphasis role="strong">orphaned</emphasis> -- if its maintainer is set to  <emphasis role="strong">orphaned</emphasis> -- if its maintainer is set to
622  <ulink url="http://qa.debian.org/">Debian QA Group</ulink>, you may be able to  <ulink url="&qa-do;">Debian QA Group</ulink>, you may be able to pick it up if
623  pick it up if it's still available (check the ownership status at <ulink url="http://bugs.debian.org/wnpp">Debian Bug report logs: Bugs in package wnpp  it's still available.  You may also adopt a package for which the corresponding
624  in unstable</ulink>).  You may also adopt a package for which the corresponding  maintainer has filed a Request for Adoption
625  maintainer has filed a Request for Adoption (<emphasis role="strong">RFA</emphasis>).  (<emphasis role="strong">RFA</emphasis>).
626  </para>  </para>
627  <para>  <para>
628  Several different views of orphaned or RFA'ed packages are available at:  There are several package ownership status resorces.
629  </para>  </para>
630  <itemizedlist>  <itemizedlist>
631  <listitem>  <listitem>
632  <para>  <para> <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> </para>
 <ulink url="http://www.debian.org/devel/wnpp/">Work-Needing and Prospective  
 Packages</ulink>  
 </para>  
633  </listitem>  </listitem>
634  <listitem>  <listitem>
635  <para>  <para> <ulink url="&wnpp-bts;">Debian Bug report logs: Bugs in package wnpp in unstable</ulink> </para>
 <ulink url="http://wnpp.debian.net/">Debian Packages that Need Lovin'</ulink>  
 </para>  
636  </listitem>  </listitem>
637  <listitem>  <listitem>
638  <para>  <para> <ulink url="&wnpp-dn;">Debian Packages that Need Lovin'</ulink> </para>
639  <ulink url="http://members.hellug.gr/serzan/wnpp/">Browse WNPP bugs based on  </listitem>
640  debtags</ulink>  <listitem>
641  </para>  <para> <ulink url="&wnpp-debtags;">Browse WNPP bugs based on debtags</ulink> </para>
642  </listitem>  </listitem>
643  </itemizedlist>  </itemizedlist>
644  <para>  <para>
# Line 584  taking over orphaned, yet actively used, Line 658  taking over orphaned, yet actively used,
658  </listitem>  </listitem>
659  <listitem>  <listitem>
660  <para>  <para>
661  joining <ulink url="http://wiki.debian.org/Teams">packaging teams</ulink>  joining <ulink url="&teams;">packaging teams</ulink>
662  </para>  </para>
663  </listitem>  </listitem>
664  <listitem>  <listitem>
# Line 594  triaging bugs of very popular packages Line 668  triaging bugs of very popular packages
668  </listitem>  </listitem>
669  <listitem>  <listitem>
670  <para>  <para>
671  preparing <ulink url="http://www.debian.org/doc/developers-reference/pkgs.html#nmu-qa-upload">QA  preparing <ulink url="&devref-nmu;">QA or NMU uploads</ulink>
 or NMU uploads</ulink>  
672  </para>  </para>
673  </listitem>  </listitem>
674  </itemizedlist>  </itemizedlist>
# Line 621  confirm its usefulness. Line 694  confirm its usefulness.
694  </listitem>  </listitem>
695  <listitem>  <listitem>
696  <para>  <para>
697  You must check if no one else is working on the package already at <ulink url="http://www.de.debian.org/devel/wnpp/being_packaged">the list of packages  You must check if no one else is working on the package already at the
698  being worked on</ulink>.  If no one else is working on it, file an ITP (Intent  <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> site.
699    If no one else is working on it, file an ITP (Intent
700  To Package) bug report to the <systemitem role="package">wnpp</systemitem>  To Package) bug report to the <systemitem role="package">wnpp</systemitem>
701  pseudo-package using <command>reportbug</command>.  If someone's already on it,  pseudo-package using <command>reportbug</command>.  If someone's already on it,
702  contact them if you feel you need to.  If not - find another interesting  contact them if you feel you need to.  If not - find another interesting
# Line 637  That program <emphasis role="strong">mus Line 711  That program <emphasis role="strong">mus
711  <listitem>  <listitem>
712  <para>  <para>
713  For the <literal>main</literal> section, it <emphasis role="strong">must be  For the <literal>main</literal> section, it <emphasis role="strong">must be
714  compliant to all the Debian Free Software Guidelines (DFSG)</emphasis> (see  compliant to all the Debian Free Software Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
 <ulink url="http://www.debian.org/social_contract#guidelines">http://www.debian.org/social_contract#guidelines</ulink>)  
715  and <emphasis role="strong">that program must not require a package outside of  and <emphasis role="strong">that program must not require a package outside of
716  <literal>main</literal></emphasis> for compilation or execution as required by  <literal>main</literal></emphasis> for compilation or execution as required by
717  the Debian Policy.  This is desired case.  the Debian Policy.  This is desired case.
# Line 659  the DFSG but it <emphasis role="strong"> Line 732  the DFSG but it <emphasis role="strong">
732  </listitem>  </listitem>
733  </itemizedlist>  </itemizedlist>
734  <para>  <para>
735  If you are unsure about where it should go, post the license text on <ulink url="http://lists.debian.org/debian-legal/">debian-legal@lists.debian.org</ulink>  If you are unsure about where it should go, post the license text on <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>
736  and ask for advice.  and ask for advice.
737  </para>  </para>
738  </listitem>  </listitem>
# Line 699  package unmaintained pieces of software. Line 772  package unmaintained pieces of software.
772  <para>  <para>
773  Of course, these things are just safety measures, and intended to save you from  Of course, these things are just safety measures, and intended to save you from
774  raging users if you do something wrong in some setuid daemon...  When you gain  raging users if you do something wrong in some setuid daemon...  When you gain
775  some more experience in packaging, you'll be able to do such packages, but even  some more experience in packaging, you'll be able to package such packages.
 the experienced developers consult the <ulink url="http://lists.debian.org/debian-mentors/">debian-mentors@lists.debian.org</ulink>  
 mailing list when they are in doubt.  And people there will gladly help.  
 </para>  
 <para>  
 For more help about these, check in <ulink url="http://www.debian.org/doc/devel-manuals#devref">Debian Developer's  
 Reference</ulink>.  
776  </para>  </para>
777  </section>  </section>
778  <section id="getit"><title>Get the program, and try it out</title>  <section id="getit"><title>Get the program, and try it out</title>
# Line 723  in them and all the sources under it. Line 790  in them and all the sources under it.
790  <para>  <para>
791  If the latest version of such sources are available through VCS such as Git,  If the latest version of such sources are available through VCS such as Git,
792  Subversion, or CVS repository, you need to get it with <literal>git  Subversion, or CVS repository, you need to get it with <literal>git
793  clone</literal>, <literal>cvs co</literal>, or <literal>svn co</literal> and  clone</literal>, <literal>svn co</literal>, or <literal>cvs co</literal> and
794  repack it into <command>tar</command>+<command>gzip</command> format by  repack it into <command>tar</command>+<command>gzip</command> format by
795  yourself using the <literal>--exclude-vcs</literal> option.  yourself using the <literal>--exclude-vcs</literal> option.
796  </para>  </para>
# Line 737  too. Line 804  too.
804  </para>  </para>
805  <para>  <para>
806  As an example, I'll use a program called <command>gentoo</command>, an X GTK+  As an example, I'll use a program called <command>gentoo</command>, an X GTK+
807  file manager.<footnote><para> This program is already packaged.  Current  file manager.<footnote><para> This program is already packaged.
808  version 0.15.3 has changed substantially from the version 0.9.12 in the  <ulink url="&gentoo-package;">Current
809  following examples.  </para> </footnote>  version</ulink> has changed substantially from the version 0.9.12 in the
810    following examples.</para> </footnote>
811  </para>  </para>
812  <para>  <para>
813  Create a subdirectory under your home directory named  Create a subdirectory under your home directory named
# Line 772  that, but more on that later in <xref li Line 840  that, but more on that later in <xref li
840  </para>  </para>
841  <para>  <para>
842  Simple programs come with a <filename>Makefile</filename> file in them and can  Simple programs come with a <filename>Makefile</filename> file in them and can
843  be compiled simply with <literal>make</literal>.  Some of them support  be compiled simply with <literal>make</literal>.<footnote><para>
844    Many modern programs come with a script <filename>configure</filename> which
845    creates a <filename>Makefile</filename> file customized for your system upon
846    its execution.</para></footnote> Some of them support
847  <literal>make check</literal>, which runs included self-checks.  Installation  <literal>make check</literal>, which runs included self-checks.  Installation
848  to the destination directories is usually done with <literal>make  to the destination directories is usually done with <literal>make
849  install</literal>.  install</literal>.
# Line 790  all the installed files. Line 861  all the installed files.
861  </section>  </section>
862  <section id="portable"><title>Free portable programs</title>  <section id="portable"><title>Free portable programs</title>
863  <para>  <para>
864  A lot of Free programs are written in the <ulink url="http://en.wikipedia.org/wiki/C_(programming_language)">C</ulink> and  A lot of Free programs are written in the <ulink url="&c-program;">C</ulink> and
865  <ulink url="http://en.wikipedia.org/wiki/C++">C++</ulink> languages.  Many of  <ulink url="&cxx;">C++</ulink> languages.  Many of
866  these use Autotools or CMake to make them portable across different platforms.  these use Autotools or CMake to make them portable across different platforms.
867  These tools are used to generate <filename>Makefile</filename> and other  These tools are used to generate <filename>Makefile</filename> and other
868  required source files.  Then, such programs are built with usual <literal>make;  required source files.  Then, such programs are built with usual <literal>make;
869  make install</literal>.  make install</literal>.
870  </para>  </para>
871  <para>  <para>
872  <ulink url="http://en.wikipedia.org/wiki/GNU_build_system">Autotools</ulink>  <ulink url="&gnu-build-system;">Autotools</ulink>
873  are the GNU build system comprising <ulink url="http://en.wikipedia.org/wiki/Autoconf">Autoconf</ulink>, <ulink url="http://en.wikipedia.org/wiki/Automake">Automake</ulink>, <ulink url="http://en.wikipedia.org/wiki/GNU_Libtool">Libtool</ulink>, and <ulink url="http://en.wikipedia.org/wiki/GNU_gettext">gettext</ulink>.  You can notice  are the GNU build system comprising <ulink url="&autoconf;">Autoconf</ulink>, <ulink url="&automake;">Automake</ulink>, <ulink url="&libtool;">Libtool</ulink>, and <ulink url="&gettext;">gettext</ulink>.  You can notice
874  such sources by the <filename>configure.ac</filename>,  such sources by the <filename>configure.ac</filename>,
875  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
876  <footnote><para> See <ulink url="http://www.lrde.epita.fr/~adl/autotools.html">Autotools Tutorial</ulink>  <footnote><para> See <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>
877  and <filename>&autotools-dev;</filename>.  </para> </footnote>  and <filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename>.  </para> </footnote>
878  </para>  </para>
879  <para>  <para>
880  The first step of Autotools work flow is usually that the upstream runs  The first step of Autotools work flow is usually that the upstream runs
# Line 851  other files with <literal>autoreconf -i Line 922  other files with <literal>autoreconf -i
922  the compatibility of the source.  the compatibility of the source.
923  </para>  </para>
924  <para>  <para>
925  <ulink url="http://en.wikipedia.org/wiki/CMake">CMake</ulink> is an alternative  <ulink url="&cmake;">CMake</ulink> is an alternative
926  build system.  You can notice such sources by the  build system.  You can notice such sources by the
927  <filename>CMakeLists.txt</filename> file.  <filename>CMakeLists.txt</filename> file.
928  </para>  </para>
# Line 1059  d=. ; while [ ! -d $d/debian -a `readlin Line 1130  d=. ; while [ ! -d $d/debian -a `readlin
1130  if [ -d $d/debian ] &amp;&amp; [ -z $QUILT_PATCHES ]; then  if [ -d $d/debian ] &amp;&amp; [ -z $QUILT_PATCHES ]; then
1131      # Debian packaging case and unset $QUILT_PATCHES      # Debian packaging case and unset $QUILT_PATCHES
1132      QUILT_PATCHES=debian/patches      QUILT_PATCHES=debian/patches
1133      QUILT_PATCH_OPTS=--unified-reject-files      QUILT_PATCH_OPTS=--reject-format=unified
1134      QUILT_DIFF_ARGS=-p ab --no-timestamps --no-index --color=auto      QUILT_DIFF_ARGS=-p ab --no-timestamps --no-index --color=auto
1135      QUILT_REFRESH_ARGS=-p ab --no-timestamps --no-index      QUILT_REFRESH_ARGS=-p ab --no-timestamps --no-index
1136      QUILT_COLORS=diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33      QUILT_COLORS=diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33
# Line 1109  install: gentoo-target Line 1180  install: gentoo-target
1180  <para>  <para>
1181  Ask <command>quilt</command> to refresh the patch to create  Ask <command>quilt</command> to refresh the patch to create
1182  <filename>debian/patches/fix-gentoo-target.patch</filename> and add its  <filename>debian/patches/fix-gentoo-target.patch</filename> and add its
1183  description.  description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.
1184  </para>  </para>
1185  <screen>  <screen>
1186  $ quilt refresh  $ quilt refresh
# Line 1117  $ quilt header -e Line 1188  $ quilt header -e
1188  ... describe patch  ... describe patch
1189  </screen>  </screen>
1190  </section>  </section>
1191    
1192  <section id="destdir"><title>Installation of files to the destination</title>  <section id="destdir"><title>Installation of files to the destination</title>
1193  <para>  <para>
1194  Normally, programs install themselves in the <filename>/usr/local</filename>  Normally, programs install themselves in the <filename>/usr/local</filename>
1195  subdirectory.  Since it is reserved for system administrator's (or user's)  subdirectory.  Since it is reserved for system administrator's (or user's)
1196  private use, Debian packages must not use that directory but should use system  private use, Debian packages must not use that directory but should use system
1197  directories such as the <filename>/usr/bin</filename> subdirectory following  directories such as the <filename>/usr/bin</filename> subdirectory following
1198  the Filesystem Hierarchy Standard (<ulink url="http://www.debian.org/doc/packaging-manuals/fhs/fhs-2.3.html">FHS</ulink>,  the Filesystem Hierarchy Standard (<ulink url="&fhs;">FHS</ulink>,
1199  <filename>/usr/share/doc/debian-policy/fhs/fhs-2.3.html</filename>).  <filename>/usr/share/doc/debian-policy/fhs/fhs-2.3.html</filename>).
1200  </para>  </para>
1201  <para>  <para>
# Line 1145  commands if the following conditions are Line 1217  commands if the following conditions are
1217  <listitem>  <listitem>
1218  <para>  <para>
1219  The <filename>Makefile</filename> file follows the GNU conventions to support  The <filename>Makefile</filename> file follows the GNU conventions to support
1220  <literal>$(DESTDIR)</literal> variable  <literal>$(DESTDIR)</literal> variable.
1221  (<filename>/usr/share/doc/gnu-standards/standards.html#Makefile-Conventions</filename>).  <footnote><para> See <ulink url="&gnu-destdir;">GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs</ulink>.</para></footnote>
1222  </para>  </para>
1223  </listitem>  </listitem>
1224  <listitem>  <listitem>
# Line 1261  you the filename and the line number for Line 1333  you the filename and the line number for
1333  </para>  </para>
1334  <para>  <para>
1335  Edit those files and in those lines replace <literal>usr/local/lib</literal>  Edit those files and in those lines replace <literal>usr/local/lib</literal>
1336  with <literal>usr/lib</literal>.  with <literal>usr/lib</literal>.  This can be done automatically as follows:
1337  </para>  </para>
1338  <screen>  <screen>
1339  $ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \  $ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \
# Line 1277  to directories other than ones defined a Line 1349  to directories other than ones defined a
1349  <filename>Makefile</filename>.  <filename>Makefile</filename>.
1350  </para>  </para>
1351  <para>  <para>
1352  After your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s  Before your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s
1353  install target said:  install target said:
1354  </para>  </para>
1355  <screen>  <screen>
# Line 1407  most important of them are <filename>con Line 1479  most important of them are <filename>con
1479  This file contains various values which <command>dpkg</command>,  This file contains various values which <command>dpkg</command>,
1480  <command>dselect</command>, <command>apt-get</command>,  <command>dselect</command>, <command>apt-get</command>,
1481  <command>apt-cache</command>, <command>aptitude</command>, and other package  <command>apt-cache</command>, <command>aptitude</command>, and other package
1482  management tools will use to manage the package.  It is defined by the <ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html">Debian  management tools will use to manage the package.  It is defined by the <ulink url="&policy-control;">Debian
1483  Policy Manual, 5 'Control files and their fields'</ulink>.  Policy Manual, 5 'Control files and their fields'</ulink>.
1484  </para>  </para>
1485  <para>  <para>
# Line 1433  created for us: Line 1505  created for us:
1505  (I've added the line numbers.)  (I've added the line numbers.)
1506  </para>  </para>
1507  <para>  <para>
1508  Lines 1-6 are the control information for the source package.  Lines 1-7 are the control information for the source package.
1509    Lines 9-13 are the control information for the binary package.
1510  </para>  </para>
1511  <para>  <para>
1512  Line 1 is the name of the source package.  Line 1 is the name of the source package.
# Line 1452  for administrator-only programs, <litera Line 1525  for administrator-only programs, <litera
1525  documentation, <literal>libs</literal> for libraries, <literal>mail</literal>  documentation, <literal>libs</literal> for libraries, <literal>mail</literal>
1526  for e-mail readers and daemons, <literal>net</literal> for network apps and  for e-mail readers and daemons, <literal>net</literal> for network apps and
1527  daemons, <literal>x11</literal> for X11 programs that don't fit anywhere else,  daemons, <literal>x11</literal> for X11 programs that don't fit anywhere else,
1528  and many more.  See the <ulink url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections">Debian  and many more.  See the <ulink url="&policy-subsections;">Debian
1529  Policy Manual, 2.4 'Sections'</ulink> and <ulink url="http://packages.debian.org/unstable/">List of sections in 'sid'</ulink>  Policy Manual, 2.4 'Sections'</ulink> and <ulink url="&sections-unstable;">List of sections in 'sid'</ulink>
1530  for the guidance.  for the guidance.
1531  </para>  </para>
1532  <para>  <para>
# Line 1462  we can omit it.) Line 1535  we can omit it.)
1535  </para>  </para>
1536  <para>  <para>
1537  Line 3 describes how important it is that the user installs this package.  See  Line 3 describes how important it is that the user installs this package.  See
1538  the <ulink url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities">Debian  the <ulink url="&policy-priorities;">Debian
1539  Policy Manual, 2.5 'Priorities'</ulink> for the guidance.  Policy Manual, 2.5 'Priorities'</ulink> for the guidance.
1540  </para>  </para>
1541  <itemizedlist>  <itemizedlist>
# Line 1499  you.  Avoid using commas, ampersands and Line 1572  you.  Avoid using commas, ampersands and
1572  <para>  <para>
1573  The 5th line includes the list of packages required to build your package as  The 5th line includes the list of packages required to build your package as
1574  the <literal>Build-Depends</literal> field.  You can also have the  the <literal>Build-Depends</literal> field.  You can also have the
1575  <literal>Build-Depends-Indep</literal> field as an additional line, here.  (see  <literal>Build-Depends-Indep</literal> field as an additional line, here (see
1576  the <ulink url="http://www.debian.org/doc/debian-policy/ch-relationships.html#s-sourcebinarydeps">Debian  the <ulink url="&policy-relationships;#s-sourcebinarydeps">Debian
1577  Policy Manual, 7.7 'Relationships between source and binary packages -  Policy Manual, 7.7 'Relationships between source and binary packages -
1578  Build-Depends, Build-Depends-Indep, Build-Conflicts,  Build-Depends, Build-Depends-Indep, Build-Conflicts,
1579  Build-Conflicts-Indep'</ulink>).  Some packages like <systemitem role="package">gcc</systemitem> and <systemitem role="package">make</systemitem> which are required by the <systemitem role="package">build-essential</systemitem> package are implied.  If you need  Build-Conflicts-Indep'</ulink>).  Some packages like <systemitem role="package">gcc</systemitem> and <systemitem role="package">make</systemitem> which are required by the <systemitem role="package">build-essential</systemitem> package are implied.  If you need
# Line 1541  for the <literal>clean</literal> target. Line 1614  for the <literal>clean</literal> target.
1614  If you are not sure which one should be used, use the  If you are not sure which one should be used, use the
1615  <literal>Build-Depends</literal> field to be on the safe side.  <literal>Build-Depends</literal> field to be on the safe side.
1616  <footnote><para> This somewhat strange situation is a feature well documented  <footnote><para> This somewhat strange situation is a feature well documented
1617  in the <ulink url="http://www.debian.org/doc/debian-policy/footnotes.html#f48">Debian Policy  in the <ulink url="&policy-build-depends-indep;">Debian Policy
1618  Manual, Footnotes 48</ulink>.  This is not due to the use of the  Manual, Footnotes 48</ulink>.  This is not due to the use of the
1619  <command>dh</command> command in the <filename>debian/rules</filename> file but  <command>dh</command> command in the <filename>debian/rules</filename> file but
1620  due to how the <command>dpkg-buildpackage</command> works.  The same situation  due to how the <command>dpkg-buildpackage</command> works.  The same situation
# Line 1579  the problem of excessive build dependenc Line 1652  the problem of excessive build dependenc
1652  next to <systemitem role="package">debhelper</systemitem>.  next to <systemitem role="package">debhelper</systemitem>.
1653  </para>  </para>
1654  <para>  <para>
1655  Line 6 is the version of the <ulink url="http://www.debian.org/doc/devel-manuals#policy">Debian Policy  Line 6 is the version of the <ulink url="&debian-policy;">Debian Policy
1656  Manual</ulink> standards this package follows, the one you read while making  Manual</ulink> standards this package follows, the one you read while making
1657  your package.  your package.
1658  </para>  </para>
# Line 1623  these relations; if not, it will be expl Line 1696  these relations; if not, it will be expl
1696  </citerefentry> etc.)  </citerefentry> etc.)
1697  </para>  </para>
1698  <para>  <para>
1699  This is what the dependencies mean:  Here is a simplified description of package relationships.
1700    <footnote><para>See
1701    <ulink url="&policy-relationships;">Debian Policy Manual, 7 'Declaring relationships between packages'</ulink>
1702    </para></footnote>:
1703  </para>  </para>
1704  <itemizedlist>  <itemizedlist>
1705  <listitem>  <listitem>
# Line 1670  ignore this field. Line 1746  ignore this field.
1746  This is stronger than <literal>Depends</literal>.  The package will not be  This is stronger than <literal>Depends</literal>.  The package will not be
1747  installed unless the packages it pre-depends on are installed and  installed unless the packages it pre-depends on are installed and
1748  <emphasis>correctly configured</emphasis>.  Use this <emphasis>very</emphasis>  <emphasis>correctly configured</emphasis>.  Use this <emphasis>very</emphasis>
1749  sparingly and only after discussing it on the <ulink url="http://lists.debian.org/debian-devel/">debian-devel@lists.debian.org</ulink>  sparingly and only after discussing it on the <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org</ulink>
1750  mailing list.  Read: don't use it at all.  :-)  mailing list.  Read: don't use it at all.  :-)
1751  </para>  </para>
1752  </listitem>  </listitem>
# Line 1755  components when the <citerefentry> <refe Line 1831  components when the <citerefentry> <refe
1831  libraries determine their shared library dependencies and detect which packages  libraries determine their shared library dependencies and detect which packages
1832  they are in, such as <systemitem role="package">libc6</systemitem> or  they are in, such as <systemitem role="package">libc6</systemitem> or
1833  <systemitem role="package">xlib6g</systemitem>, after your package has been  <systemitem role="package">xlib6g</systemitem>, after your package has been
1834  built and installed into the temporary directory.  This list of shared library  built and installed into the temporary directory.  This package list is used
1835  dependencies is used for <literal>${shlibs:Depends}</literal>.  for substituting <literal>${shlibs:Depends}</literal>.
1836  </para>  </para>
1837  <para>  <para>
1838  The package list generated by the <citerefentry>  The package list generated by <citerefentry>
1839  <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>  <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
1840  is used for <literal>${perl:Depends}</literal>.  is used for substituting <literal>${perl:Depends}</literal>.
1841  </para>  </para>
1842  <para>  <para>
1843  Some <systemitem role="package">debhelper</systemitem> commands may make the  Some <systemitem role="package">debhelper</systemitem> commands may make the
1844  generated package need to depend on some other packages.  This list of required  generated package need to depend on some other packages.  This list of required
1845  packages is used for <literal>${misc:Depends}</literal>.  packages is used for substituting <literal>${misc:Depends}</literal>.
1846  </para>  </para>
1847  <para>  <para>
1848  Having said all that, we can leave the <literal>Depends</literal> field exactly  Having said all that, we can leave the <literal>Depends</literal> field exactly
# Line 1775  file</literal>, because <systemitem role Line 1851  file</literal>, because <systemitem role
1851  some features provided by that <systemitem role="package">file</systemitem>  some features provided by that <systemitem role="package">file</systemitem>
1852  package.  package.
1853  </para>  </para>
1854    <para> Line 9 is the Homepage URL.  Let's assume this to be at
1855    <ulink url="&gentoo;"/>.
1856    </para>
1857  <para>  <para>
1858  Line 12 is the short description.  Most people screens are 80 columns wide so  Line 12 is the short description.  Most people screens are 80 columns wide so
1859  this shouldn't be longer than about 60 characters.  I'll change it to  this shouldn't be longer than about 60 characters.  I'll change it to
# Line 1785  Line 13 is where the long description go Line 1864  Line 13 is where the long description go
1864  gives more details about the package.  Column 1 of each line should be empty.  gives more details about the package.  Column 1 of each line should be empty.
1865  There must be no blank lines, but you can put a single <literal>.</literal>  There must be no blank lines, but you can put a single <literal>.</literal>
1866  (dot) in a column to simulate that.  Also, there must be no more than one blank  (dot) in a column to simulate that.  Also, there must be no more than one blank
1867  line after the long description.  line after the long description. <footnote><para>These descriptions are in
1868    English.  Translations of these descriptions are provided by
1869    <ulink url="&ddtp;">The Debian Description Translation Project - DDTP</ulink>.</para></footnote>
1870  </para>  </para>
1871  <para>  <para>
1872  Let's insert <literal>Vcs-*</literal> fields documented in <ulink url="http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#bpp-vcs">Developer's  Let's insert <literal>Vcs-*</literal> fields documented in <ulink url="&devref-bpp-vcs;">Developer's
1873  Reference, 6.2.5.  'Version Control System location'</ulink> between line 6 and  Reference, 6.2.5.  'Version Control System location'</ulink> between line 6 and
1874  7.  Let's assume that the <systemitem role="package">gentoo</systemitem>  7.  Let's assume that the <systemitem role="package">gentoo</systemitem>
1875  package is located in Debian Alioth Git Service at  package is located in Debian Alioth Git Service at
# Line 1806  Finally, here is the updated <filename>c Line 1887  Finally, here is the updated <filename>c
1887   6 Standards-Version: 3.8.4   6 Standards-Version: 3.8.4
1888   7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git   7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
1889   8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git   8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
1890   9 Homepage: http://www.obsession.se/gentoo/   9 Homepage: &gentoo;
1891  10  10
1892  11 Package: gentoo  11 Package: gentoo
1893  12 Architecture: any  12 Architecture: any
# Line 1835  Finally, here is the updated <filename>c Line 1916  Finally, here is the updated <filename>c
1916  <para>  <para>
1917  This file contains the information about package upstream resources, copyright  This file contains the information about package upstream resources, copyright
1918  and license information.  Its format is not dictated by the Debian Policy  and license information.  Its format is not dictated by the Debian Policy
1919  Manual, but the content is (<ulink url="http://www.debian.org/doc/debian-policy/ch-docs.html#s-copyrightfile">Debian  Manual, but the content is (<ulink url="&policy-copyright;">Debian
1920  Policy Manual, 12.5 'Copyright information'</ulink>).  You may also consult  Policy Manual, 12.5 'Copyright information'</ulink>).  You may also consult
1921  <ulink url="http://dep.debian.net/deps/dep5/">DEP-5: Machine-parseable  <ulink url="&dep5;">DEP-5: Machine-parseable
1922  debian/copyright</ulink>.  debian/copyright</ulink>.
1923  </para>  </para>
1924  <para>  <para>
# Line 1899  In short, here's how <systemitem role="p Line 1980  In short, here's how <systemitem role="p
1980  </para>  </para>
1981  <para>  <para>
1982  Please follow the HOWTO provided by ftpmasters and sent to  Please follow the HOWTO provided by ftpmasters and sent to
1983  debian-devel-announce: <ulink url="&copyright-howto;">&copyright-howto;</ulink>.  debian-devel-announce: <ulink url="&howto-copyright;"/>.
1984  </para>  </para>
1985  </section>  </section>
1986  <section id="changelog"><title><filename>changelog</filename> file</title>  <section id="changelog"><title><filename>changelog</filename> file</title>
1987  <para>  <para>
1988  This is a required file, which has a special format described in the <ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog">Debian  This is a required file, which has a special format described in the <ulink url="&policy-dpkgchangelog;">Debian
1989  Policy Manual, 4.4 'debian/changelog'</ulink>.  This format is used by  Policy Manual, 4.4 'debian/changelog'</ulink>.  This format is used by
1990  <command>dpkg</command> and other programs to obtain the version number,  <command>dpkg</command> and other programs to obtain the version number,
1991  revision, distribution and urgency of your package.  revision, distribution and urgency of your package.
# Line 1985  is marked as executable. Line 2066  is marked as executable.
2066  <para>  <para>
2067  Every <filename>rules</filename> file, as any other  Every <filename>rules</filename> file, as any other
2068  <filename>Makefile</filename>, consists of several targets and their rules  <filename>Makefile</filename>, consists of several targets and their rules
2069  specifying how to handle the source.  <ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules">Debian  specifying how to handle the source.  <ulink url="&policy-debianrules;">Debian
2070  Policy Manual, 4.9 'Main building script: debian/rules'</ulink> explains its  Policy Manual, 4.9 'Main building script: debian/rules'</ulink> explains its
2071  details.  details.
2072  </para>  </para>
# Line 2106  anything from you. Line 2187  anything from you.
2187  Lines 12 and 13 are where all the work is done.  The percent sign means any  Lines 12 and 13 are where all the work is done.  The percent sign means any
2188  targets which then call a single program, <command>dh</command> with the target  targets which then call a single program, <command>dh</command> with the target
2189  name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> V7 features.  Its design concepts are  name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> V7 features.  Its design concepts are
2190  explained in <ulink url="http://joey.kitenet.net/talks/debhelper/debhelper-slides.pdf">Not Your  explained in <ulink url="&debhelper-slides;">Not Your
2191  Grandpa's Debhelper</ulink> presented at Debconf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under  Grandpa's Debhelper</ulink> presented at Debconf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under
2192  <literal>lenny</literal>, <command>dh_make</command> created a much more  <literal>lenny</literal>, <command>dh_make</command> created a much more
2193  complicated <filename>rules</filename> file with many <command>dh_*</command>  complicated <filename>rules</filename> file with many <command>dh_*</command>
# Line 2564  If you want to store the system configur Line 2645  If you want to store the system configur
2645  <literal>--sysconfig=/etc</literal> argument given by the  <literal>--sysconfig=/etc</literal> argument given by the
2646  <command>dh_auto_configure</command> command to the  <command>dh_auto_configure</command> command to the
2647  <command>./configure</command> command by the following.  <footnote><para> The  <command>./configure</command> command by the following.  <footnote><para> The
2648  <systemitem role="package">gentoo</systemitem> package uses the GNU build  <systemitem role="package">gentoo</systemitem> package uses the <ulink url="&gnu-build-system;">GNU build
2649  system, also known as the Autotools.  See <ulink url="http://en.wikipedia.org/wiki/GNU_build_system">http://en.wikipedia.org/wiki/GNU_build_system</ulink>.  system</ulink>, also known as the Autotools.
2650  </para> </footnote>  </para> </footnote>
2651  </para>  </para>
2652  <screen>  <screen>
# Line 2647  possible. Line 2728  possible.
2728  To control most of what <systemitem role="package">debhelper</systemitem> does  To control most of what <systemitem role="package">debhelper</systemitem> does
2729  while building the package, you put optional configuration files under the  while building the package, you put optional configuration files under the
2730  <filename>debian</filename> directory.  This chapter will make an overview of  <filename>debian</filename> directory.  This chapter will make an overview of
2731  what each of these does and its format.  Please read <ulink url="http://www.debian.org/doc/devel-manuals#policy">Debian Policy  what each of these does and its format.  Please read <ulink url="&debian-policy;">Debian Policy
2732  Manual</ulink> and <ulink url="http://www.debian.org/doc/devel-manuals#devref">Debian Developer's  Manual</ulink> and <ulink url="&developers-reference;">Debian Developer's
2733  Reference</ulink> for guidelines for the packaging.  Reference</ulink> for guidelines for the packaging.
2734  </para>  </para>
2735  <para>  <para>
# Line 2746  $ echo 7 &gt; debian/compat Line 2827  $ echo 7 &gt; debian/compat
2827  <para>  <para>
2828  One of the most annoying things about software is when you spend a great deal  One of the most annoying things about software is when you spend a great deal
2829  of time and effort customizing a program, only to have an upgrade stomp all  of time and effort customizing a program, only to have an upgrade stomp all
2830  over your changes.  Debian solves this problem by marking configuration files  over your changes.  Debian solves this problem by marking such configuration files as conffiles.
2831  so that when you upgrade a package, you'll be prompted whether you want to keep  <footnote><para>See <citerefentry> <refentrytitle>dpkg</refentrytitle>
2832  your old configuration or not.  <manvolnum>1</manvolnum> </citerefentry> and
2833    <ulink url="&policy-conffiles;">Debian Policy Manual 'D.2.5 Conffiles'</ulink>.
2834    </para></footnote>
2835    When you upgrade a package, you'll be prompted whether you want to keep
2836    your old configuration files or not.
2837  </para>  </para>
2838  <para>  <para>
2839  Since <systemitem role="package">debhelper</systemitem> V3, <citerefentry>  Since <systemitem role="package">debhelper</systemitem> V3, <citerefentry>
# Line 2858  directories created first.  See <xref li Line 2943  directories created first.  See <xref li
2943  </para>  </para>
2944  <para>  <para>
2945  It is best to first try to run the installation first and only use this if you  It is best to first try to run the installation first and only use this if you
2946  run into trouble.  There is no preceding slash on the directory names.  run into trouble.  There is no preceding slash on the directory names listed in
2947    the <filename>dirs</filename> file.
2948  </para>  </para>
2949  </section>  </section>
2950  <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename> file</title>  <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename> file</title>
# Line 3085  as the first suffix, which means it's a Line 3171  as the first suffix, which means it's a
3171  sure to verify that this section is indeed the correct one.  Here's a short  sure to verify that this section is indeed the correct one.  Here's a short
3172  list of manual page sections:  list of manual page sections:
3173  </para>  </para>
3174  <screen>  <table id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
3175  Section |     Description     |     Notes  <title>manual page sections</title>
3176     1     User commands          Executable commands or scripts.  <tgroup cols="3">
3177     2     System calls           Functions provided by the kernel.    <colspec colwidth="8*" align="left"/> <colspec colwidth="24*" align="left"/> <colspec colwidth="40*" align="left"/>
3178     3     Library calls          Functions within system libraries.    <thead>
3179     4     Special files          Usually found in /dev      <row> <entry>Section</entry> <entry>Description</entry> <entry>Notes</entry> </row>
3180     5     File formats           E.g. /etc/passwd's format    </thead>
3181     6     Games                  Or other frivolous programs    <tbody>
3182     7     Macro packages         Such as man macros.      <row> <entry>1</entry> <entry>User command</entry> <entry>Executable commands or scripts</entry> </row>
3183     8     System administration  Programs typically only run by root.      <row> <entry>2</entry> <entry>System calls</entry> <entry>Functions provided by the kernel</entry> </row>
3184     9     Kernel routines        Non-standard calls and internals.      <row> <entry>3</entry> <entry>Library calls</entry> <entry>Functions within system libraries</entry> </row>
3185  </screen>      <row> <entry>4</entry> <entry>Special files</entry> <entry>Usually found in /dev</entry> </row>
3186        <row> <entry>5</entry> <entry>File formats</entry> <entry>E.g. <filename>/etc/passwd</filename>'s format</entry> </row>
3187        <row> <entry>6</entry> <entry>Games</entry> <entry>Games or other frivolous programs</entry> </row>
3188        <row> <entry>7</entry> <entry>Macro packages</entry> <entry>Such as man macros</entry> </row>
3189        <row> <entry>8</entry> <entry>System administration</entry> <entry>Programs typically only run by root</entry> </row>
3190        <row> <entry>9</entry> <entry>Kernel routines</entry> <entry>Non-standard calls and internals</entry> </row>
3191      </tbody>
3192    </tgroup>
3193    </table>
3194  <para>  <para>
3195  So <systemitem role="package">gentoo</systemitem>'s man page should be called  So <systemitem role="package">gentoo</systemitem>'s man page should be called
3196  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>
# Line 3203  If your package has manual pages, you sh Line 3297  If your package has manual pages, you sh
3297  <filename><replaceable>package</replaceable>.manpages</filename> files.  <filename><replaceable>package</replaceable>.manpages</filename> files.
3298  </para>  </para>
3299  <para>  <para>
3300  To install <filename>doc/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a  To install <filename>docs/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a
3301  <filename>gentoo.manpages</filename> file as:  <filename>gentoo.manpages</filename> file as:
3302  </para>  </para>
3303  <screen>  <screen>
# Line 3287  package is installed, upgraded or remove Line 3381  package is installed, upgraded or remove
3381  <para>  <para>
3382  As a novice maintainer, you should avoid any manual editing of  As a novice maintainer, you should avoid any manual editing of
3383  <emphasis>maintainer scripts</emphasis> because they are problematic.  For more  <emphasis>maintainer scripts</emphasis> because they are problematic.  For more
3384  information look in the <ulink url="http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html">Debian  information look in the <ulink url="&policy-mantainerscripts;">Debian
3385  Policy Manual, 6 'Package maintainer scripts and installation  Policy Manual, 6 'Package maintainer scripts and installation
3386  procedure'</ulink>, and take a look at these example files provided by  procedure'</ulink>, and take a look at these example files provided by
3387  <command>dh_make</command>.  <command>dh_make</command>.
# Line 3336  The <filename>watch</filename> file form Line 3430  The <filename>watch</filename> file form
3430  <refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>  <refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
3431  manpage.  The <filename>watch</filename> file configures the  manpage.  The <filename>watch</filename> file configures the
3432  <command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you  <command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you
3433  originally got the source from.  This is also used by <ulink url="http://wiki.debian.org/DEHS">Debian External Health Status (DEHS)</ulink>.  originally got the source from.  This is also used by <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink>.
3434  </para>  </para>
3435  <para>  <para>
3436  Here's what I put in it:  Here's what I put in it:
# Line 3344  Here's what I put in it: Line 3438  Here's what I put in it:
3438  <screen>  <screen>
3439  # watch control file for uscan  # watch control file for uscan
3440  version=3  version=3
3441  http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate  &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
3442  </screen>  </screen>
3443  <para>  <para>
3444  Normally with this <filename>watch</filename> file, the URL at  Normally with this <filename>watch</filename> file, the URL at
3445  <literal>http://sf.net/gentoo</literal> is downloaded and searched for links of  <literal>&sf-net;/gentoo</literal> is downloaded and searched for links of
3446  the form <literal>&lt;a href=...&gt;</literal>.  The base name (just the part  the form <literal>&lt;a href=...&gt;</literal>.  The base name (just the part
3447  after the final <literal>/</literal>) of these linked URLs are matched against  after the final <literal>/</literal>) of these linked URLs are matched against
3448  Perl regexp (see <citerefentry> <refentrytitle>perlre</refentrytitle>  Perl regexp (see <citerefentry> <refentrytitle>perlre</refentrytitle>
# Line 3359  program is run to create the updated sou Line 3453  program is run to create the updated sou
3453  </para>  </para>
3454  <para>  <para>
3455  Although this is true for other sites, the SourceForge download service at  Although this is true for other sites, the SourceForge download service at
3456  <ulink url="http://sf.net">http://sf.net</ulink> is an exception.  When the  <ulink url="&sf-net;">&sf-net;</ulink> is an exception.  When the
3457  <filename>watch</filename> file has an URL matching with the Perl regexp  <filename>watch</filename> file has an URL matching with the Perl regexp
3458  <literal>^http://sf\.net/</literal>, the <command>uscan</command> program  <literal>^http://sf\.net/</literal>, the <command>uscan</command> program
3459  substitutes it with <literal>http://qa.debian.org/watch/sf.php/</literal> and  substitutes it with <literal>&qa-do;watch/sf.php/</literal> and
3460  then applies this rule.  The URL redirector service at this <ulink url="http://qa.debian.org/">http://qa.debian.org/</ulink> is designed to offer  then applies this rule.  The URL redirector service at this <ulink url="&qa-do;"/> is designed to offer
3461  a stable redirect service to the desired file for the  a stable redirect service to the desired file for the
3462  <filename>watch</filename> file having  <filename>watch</filename> file having
3463  <literal>http://sf.net/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.  <literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.
3464  This solves issues related to the periodically changing URL there.  This solves issues related to the periodically changing URL there.
3465  </para>  </para>
3466  </section>  </section>
# Line 3394  should say either: Line 3488  should say either:
3488  The newer <literal>3.0 (quilt)</literal> source format records modifications in  The newer <literal>3.0 (quilt)</literal> source format records modifications in
3489  a <command>quilt</command> patch series within  a <command>quilt</command> patch series within
3490  <filename>debian/patches</filename>.  Those changes are then automatically  <filename>debian/patches</filename>.  Those changes are then automatically
3491  applied during extraction of the source package.  <footnote><para> See <ulink url="http://wiki.debian.org/Projects/DebSrc3.0">DebSrc3.0</ulink> for the  applied during extraction of the source package.  <footnote><para> See <ulink url="&debsrc3;">DebSrc3.0</ulink> for the
3492  summary information concerning the switch to the new <literal>3.0  summary information concerning the switch to the new <literal>3.0
3493  (quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>  (quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>
3494  </footnote> The Debian modifications are simply stored in a  </footnote> The Debian modifications are simply stored in a
# Line 3432  file may contain <literal>abort-on-upstr Line 3526  file may contain <literal>abort-on-upstr
3526  <citerefentry> <refentrytitle>dpkg-source</refentrytitle>  <citerefentry> <refentrytitle>dpkg-source</refentrytitle>
3527  <manvolnum>1</manvolnum> </citerefentry>).  <manvolnum>1</manvolnum> </citerefentry>).
3528  </para>  </para>
3529    <screen>
3530    unapply-patches
3531    abort-on-upstream-changes
3532    </screen>
3533    </section>
3534    <section id="sourceopt"><title><filename>source/options</filename> file</title>
3535    <para>
3536    The autogenerated files in the source tree can be quite annoying for packaging
3537    since they generate meaningless large patch files.  There are custom modules
3538    such as <command>dh_autoreconf</command> to ease this problem as described in
3539    <xref linkend="customrules"/>.
3540    </para>
3541    <para>
3542    You can provide a Perl regular expression argument to the
3543    <literal>--extend-diff-ignore</literal> option of <citerefentry>
3544    <refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum>
3545    </citerefentry> to ignore changes made to the autogenerated files while
3546    creating the source package.
3547    </para>
3548    <para>
3549    You can store such <command>dpkg-source</command> option argument in the
3550    <filename>source/options</filename> file of the source package as the generic
3551    solution to address this problem of the autogenerated files.  The following
3552    will skip creating patch files for <filename>config.sub</filename>
3553    <filename>config.guess</filename> and <filename>Makefile</filename>.
3554    </para>
3555    <screen>
3556    extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
3557    </screen>
3558  </section>  </section>
3559  <section id="patches"><title><filename>patches/*</filename> files</title>  <section id="patches"><title><filename>patches/*</filename> files</title>
3560  <para>  <para>
# Line 3573  create and sign the upload <filename>.ch Line 3696  create and sign the upload <filename>.ch
3696  <para>  <para>
3697  The only input that will be required of you is your GPG secret pass phrase,  The only input that will be required of you is your GPG secret pass phrase,
3698  twice.  twice.
3699    <footnote><para>
3700    This GPG key must be signed by the Debian developer to get connected to the web
3701    of trust.  This enables your uploaded packages to be accepted to the Debian
3702    archives.  See
3703    <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
3704    </para></footnote>
3705  </para>  </para>
3706  <para>  <para>
3707  After all this is done, you will see the following files in the directory above  After all this is done, you will see the following files in the directory above
# Line 3646  This file is GPG signed, so that people Line 3775  This file is GPG signed, so that people
3775  As you keep working on the package, behavior will change and new features will  As you keep working on the package, behavior will change and new features will
3776  be added.  People downloading your package can look at this file and quickly  be added.  People downloading your package can look at this file and quickly
3777  see what has changed.  Debian archive maintenance programs will also post the  see what has changed.  Debian archive maintenance programs will also post the
3778  contents of this file to the <ulink url="http://lists.debian.org/debian-devel-announce/">debian-devel-announce@lists.debian.org</ulink>  contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>
3779  mailing list.  mailing list.
3780  </para>  </para>
3781  </listitem>  </listitem>
# Line 3664  they'll know the file is corrupt or has Line 3793  they'll know the file is corrupt or has
3793  </section>  </section>
3794  <section id="autobuilder"><title>Autobuilder</title>  <section id="autobuilder"><title>Autobuilder</title>
3795  <para>  <para>
3796  Debian supports many <ulink url="http://www.debian.org/ports/">ports</ulink>  Debian supports many <ulink url="&ports;">ports</ulink>
3797  with the <ulink url="http://www.debian.org/devel/buildd/">autobuilder  with the <ulink url="&buildd;">autobuilder
3798  network</ulink> running <command>buildd</command> daemons on many different  network</ulink> running <command>buildd</command> daemons on many different
3799  architecture computers.  Although you do not need to do this by yourself, you  architecture computers.  Although you do not need to do this by yourself, you
3800  should be aware of what will happen on your packages.  Let's look into roughly  should be aware of what will happen on your packages.  Let's look into roughly
# Line 3749  packages in the <literal>Build-Depends</ Line 3878  packages in the <literal>Build-Depends</
3878  <section id="option-sa"><title>Including <filename>orig.tar.gz</filename> for upload</title>  <section id="option-sa"><title>Including <filename>orig.tar.gz</filename> for upload</title>
3879  <para>  <para>
3880  When you first upload the package to the archive, you need to include the  When you first upload the package to the archive, you need to include the
3881  original <filename>orig.tar.gz</filename> source.  If the last changelog entry  original <filename>orig.tar.gz</filename> source, too.  If the Debian revision
3882  is not the first one for the given upstream version, you must provide  number of such package is neither <literal>1</literal> nor
3883  <command>dpkg-buildpackage</command> command with the <literal>-sa</literal>  <literal>0</literal>, you must provide <command>dpkg-buildpackage</command>
3884  option.  On the other hand, the <literal>-sd</literal> option will force to  command with the <literal>-sa</literal> option.  On the other hand, the
3885  exclude the original <filename>orig.tar.gz</filename> source.  <literal>-sd</literal> option will force to exclude the original
3886    <filename>orig.tar.gz</filename> source.
3887  </para>  </para>
3888  </section>  </section>
3889  <section id="debuild"><title><command>debuild</command> command</title>  <section id="debuild"><title><command>debuild</command> command</title>
# Line 3809  check the actual configuration situation Line 3939  check the actual configuration situation
3939  documentation.  </para> </footnote> This ensures a clean build from the source  documentation.  </para> </footnote> This ensures a clean build from the source
3940  under the <literal>sid</literal> auto-builder for different architectures and  under the <literal>sid</literal> auto-builder for different architectures and
3941  avoids the severity serious FTBFS (Fails To Build From Source) bug which is  avoids the severity serious FTBFS (Fails To Build From Source) bug which is
3942  always in the RC (release critical) category.  See <ulink url="&buildd-home;">&buildd-home;</ulink> for more on the Debian  always in the RC (release critical) category.  See <ulink url="&buildd-do;"/> for more on the Debian
3943  package auto-builder.  package <systemitem role="package">auto-builder</systemitem>.
3944  </para>  </para>
3945  <para>  <para>
3946  Let's customize the <systemitem role="package">pbuilder</systemitem> package by  Let's customize the <systemitem role="package">pbuilder</systemitem> package by
# Line 3941  environments of almost any Debian deriva Line 4071  environments of almost any Debian deriva
4071  architecture.  architecture.
4072  </para>  </para>
4073  <para>  <para>
4074  See <ulink url="&pbuilder-home;">&pbuilder-home;</ulink>,  See <ulink url="&pbuilder;"/>,
4075  <citerefentry> <refentrytitle>pdebuild</refentrytitle> <manvolnum>1</manvolnum>  <citerefentry> <refentrytitle>pdebuild</refentrytitle> <manvolnum>1</manvolnum>
4076  </citerefentry>, <citerefentry> <refentrytitle>pbuilderrc</refentrytitle>  </citerefentry>, <citerefentry> <refentrytitle>pbuilderrc</refentrytitle>
4077  <manvolnum>5</manvolnum> </citerefentry>, and <citerefentry>  <manvolnum>5</manvolnum> </citerefentry>, and <citerefentry>
# Line 3951  See <ulink url="&pbuilder-home;">&pbuild Line 4081  See <ulink url="&pbuilder-home;">&pbuild
4081  </section>  </section>
4082  <section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>  <section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>
4083  <para>  <para>
4084  If your upstream uses the source code management system (<ulink url="http://www.debian.org/doc/manuals/debian-reference/ch10.en.html#_version_control_systems">VCS</ulink>)  If your upstream uses the source code management system (<ulink url="&debref-vcs;">VCS</ulink>)
4085  to maintain their code, you should consider to use them.  That makes merging  to maintain their code, you should consider to use them.  That makes merging
4086  and cherry-picking upstream patches much easier.  There are several specialized  and cherry-picking upstream patches much easier.  There are several specialized
4087  wrapper script packages for the Debian package building for each VCS.  wrapper script packages for the Debian package building for each VCS.
# Line 3989  this tutorial.  <footnote><para> Here ar Line 4119  this tutorial.  <footnote><para> Here ar
4119  advanced audiences.  </para> <itemizedlist> <listitem> <para> Building Debian  advanced audiences.  </para> <itemizedlist> <listitem> <para> Building Debian
4120  Packages with git-buildpackage at  Packages with git-buildpackage at
4121  <filename>/usr/share/doc/git-buildpackage/manual-html/gbp.html</filename>  <filename>/usr/share/doc/git-buildpackage/manual-html/gbp.html</filename>
4122  </para> </listitem> <listitem> <para> <ulink url="https://honk.sigxcpu.org/piki/development/debian_packages_in_git/">debian  </para> </listitem> <listitem> <para> <ulink url="&debian-packages-git;">debian
4123  packages in git</ulink> </para> </listitem> <listitem> <para> <ulink url="http://www.eyrie.org/~eagle/notes/debian/git.html">Using Git for Debian  packages in git</ulink> </para> </listitem> <listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian
4124  Packaging</ulink> </para> </listitem> <listitem> <para> <ulink url="http://git.debian.org/?p=collab-maint/topgit.git;a=blob_plain;f=debian/HOWTO-tg2quilt;hb=HEAD">Using  Packaging</ulink> </para> </listitem> <listitem> <para> <ulink url="http://git.debian.org/?p=collab-maint/topgit.git;a=blob_plain;f=debian/HOWTO-tg2quilt;hb=HEAD">Using
4125  TopGit to generate quilt series for Debian packaging</ulink> </para>  TopGit to generate quilt series for Debian packaging</ulink> </para>
4126  </listitem> <listitem> <para> <ulink url="http://git-dpm.alioth.debian.org/">git-dpm: Debian packages in Git  </listitem> <listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git
4127  manager</ulink> </para> </listitem> </itemizedlist> </footnote>  manager</ulink> </para> </listitem> </itemizedlist> </footnote>
4128  </para>  </para>
4129  </section>  </section>
# Line 4236  You can compare two <filename>diff.gz</f Line 4366  You can compare two <filename>diff.gz</f
4366  </citerefentry> command.  This is useful for verifying that no inadvertent  </citerefentry> command.  This is useful for verifying that no inadvertent
4367  changes were made to the source by the maintainer when updating packages in the  changes were made to the source by the maintainer when updating packages in the
4368  old <literal>1.0</literal> source format.  old <literal>1.0</literal> source format.
4369    <footnote><para>The new <literal>3.0</literal> source format stores changes
4370    made by the maintainer to the source in the
4371    <filename><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.tar.gz</filename>
4372    file.</para></footnote>
4373  </para>  </para>
4374  <screen>  <screen>
4375  $ interdiff -z <replaceable>old-package</replaceable>.diff.gz <replaceable>new-package</replaceable>.diff.gz  $ interdiff -z <replaceable>old-package</replaceable>.diff.gz <replaceable>new-package</replaceable>.diff.gz
# Line 4261  your <filename>rules</filename> file to Line 4395  your <filename>rules</filename> file to
4395  <para>  <para>
4396  Now that you have tested your new package thoroughly, you will be technically  Now that you have tested your new package thoroughly, you will be technically
4397  ready to start the Debian new maintainer application process, as described at  ready to start the Debian new maintainer application process, as described at
4398  <ulink url="http://www.debian.org/devel/join/newmaint">http://www.debian.org/devel/join/newmaint</ulink>  <ulink url="&nm-join;"/>
4399  </para>  </para>
4400  <section id="upload-debian"><title>Uploading to the Debian archive</title>  <section id="upload-debian"><title>Uploading to the Debian archive</title>
4401  <para>  <para>
# Line 4292  these options means. Line 4426  these options means.
4426  The <literal>$default_host</literal> option determines which of the upload  The <literal>$default_host</literal> option determines which of the upload
4427  queues will be used by default.  <literal>anonymous-ftp-master</literal> is the  queues will be used by default.  <literal>anonymous-ftp-master</literal> is the
4428  primary one, but it's possible that you will want to use another one.  primary one, but it's possible that you will want to use another one.
4429    <footnote><para>See <ulink url="&devref-upload;">Debian Developer's Reference 5.6. 'Uploading a package'</ulink>.</para></footnote>
4430  </para>  </para>
4431  <para>  <para>
4432  While connected to the Internet, you can upload your package by the following:  While connected to the Internet, you can upload your package by the following:
# Line 4310  useful these days.  If you upload to ftp Line 4445  useful these days.  If you upload to ftp
4445  will ask for your password on Debian machines, and then upload the packages.  will ask for your password on Debian machines, and then upload the packages.
4446  -->  -->
4447  <para>  <para>
4448  If you encounter an upload problem at <ulink url="&ftp-uploadqueue;">&ftp-uploadqueue;</ulink>, you can fix this  If you encounter an upload problem at <ulink url="&uploadqueue;"/>, you can fix this
4449  by manually uploading GPG signed <filename>*.commands</filename> file to there  by manually uploading GPG signed <filename>*.commands</filename> file to there
4450  with <command>ftp</command>.  <footnote><para> See <ulink url="&ftp-command;">&ftp-command;</ulink>.  Alternatively, you may  with <command>ftp</command>.  <footnote><para> See <ulink url="&uploadqueue-readme;"/>.  Alternatively, you may
4451  use <command>dcut</command> command from the <systemitem role="package">dput</systemitem> package.  </para> </footnote> For example, use  use <command>dcut</command> command from the <systemitem role="package">dput</systemitem> package.  </para> </footnote> For example, use
4452  <filename>hello.commands</filename>:  <filename>hello.commands</filename>:
4453  </para>  </para>
# Line 4332  Z4jxNrgh7Bc= Line 4467  Z4jxNrgh7Bc=
4467  -----END PGP SIGNATURE-----  -----END PGP SIGNATURE-----
4468  </screen>  </screen>
4469  <para>  <para>
4470  See <ulink url="http://mentors.debian.net/cgi-bin/welcome">mentors.debian.net</ulink> for  See <ulink url="&mentors-dn;"/> for
4471  publically accessible upload area for non-DD.  publically accessible upload area for non-DD.
4472  </para>  </para>
4473  <para>  <para>
4474  See <ulink url="http://www.debian.org/doc/manuals/debian-reference/ch02.en.html#_small_public_package_archive">Debian  See <ulink url="&debref-archive;">Debian
4475  Reference, 2.7.12.  'Small public package archive'</ulink> for an example for  Reference, 2.7.12.  'Small public package archive'</ulink> for an example for
4476  creating a small public package archive compatible with the modern secure APT  creating a small public package archive compatible with the modern secure APT
4477  system.  system.
# Line 4528  Update the Debian <filename>changelog</f Line 4663  Update the Debian <filename>changelog</f
4663  <itemizedlist>  <itemizedlist>
4664  <listitem>  <listitem>
4665  <para>  <para>
4666  Add an entry with New upstream release.  Add an entry with "<literal>New upstream release</literal>".
4667  </para>  </para>
4668  </listitem>  </listitem>
4669  <listitem>  <listitem>
4670  <para>  <para>
4671  Describe concisely the changes <emphasis>in the new upstream release</emphasis>  Describe concisely the changes <emphasis>in the new upstream release</emphasis>
4672  that fix reported bugs and close those bugs.  that fix reported bugs and close those bugs by adding "<literal>Closes: #<replaceable>bug_number</replaceable></literal>".
4673  </para>  </para>
4674  </listitem>  </listitem>
4675  <listitem>  <listitem>
4676  <para>  <para>
4677  Describe concisely the changes <emphasis>to the new upstream release</emphasis>  Describe concisely the changes <emphasis>to the new upstream release</emphasis>
4678  by the maintainer that fix reported bugs and close those bugs.  by the maintainer that fix reported bugs and close those bugs by adding "<literal>Closes: #<replaceable>bug_number</replaceable></literal>".
4679  </para>  </para>
4680  </listitem>  </listitem>
4681  </itemizedlist>  </itemizedlist>
# Line 4710  using the <command>splitdiff</command> c Line 4845  using the <command>splitdiff</command> c
4845  If it was packaged with another patch system such as <systemitem role="package">dpatch</systemitem>, <systemitem role="package">dbs</systemitem>, or <systemitem role="package">cdbs</systemitem> with <literal>-p0</literal>,  If it was packaged with another patch system such as <systemitem role="package">dpatch</systemitem>, <systemitem role="package">dbs</systemitem>, or <systemitem role="package">cdbs</systemitem> with <literal>-p0</literal>,
4846  <literal>-p1</literal>, or <literal>-p2</literal>, convert it to the  <literal>-p1</literal>, or <literal>-p2</literal>, convert it to the
4847  <systemitem role="package">quilt</systemitem> command using  <systemitem role="package">quilt</systemitem> command using
4848  <filename>deb3</filename> at <ulink url="http://bugs.debian.org/581186">http://bugs.debian.org/581186</ulink>.  <filename>deb3</filename> at <ulink url="&deb3;"/>.
4849  </para>  </para>
4850  </listitem>  </listitem>
4851  <listitem>  <listitem>
# Line 4756  and <filename>debian/control</filename> Line 4891  and <filename>debian/control</filename>
4891  </listitem>  </listitem>
4892  <listitem>  <listitem>
4893  <para>  <para>
4894  Check to see <ulink url="http://www.debian.org/Bugs/">Debian Bug Tracking  Check to see <ulink url="&bts;">Debian Bug Tracking
4895  System (BTS)</ulink> if someone have provided patches to bugs that are  System (BTS)</ulink> if someone have provided patches to bugs that are
4896  currently open in it.  currently open in it.
4897  </para>  </para>
Legend:
Removed from v.8611  
changed lines
  Added in v.8637
  ViewVC Help
Powered by ViewVC 1.1.5