/[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 8750 by osamu, Fri Apr 29 09:04:04 2011 UTC revision 8769 by taffit-guest, Sun May 1 02:09:52 2011 UTC
# Line 121  important topics.  Some of them may look Line 121  important topics.  Some of them may look
121  I have also intentionally skipped some corner cases and provided only pointers  I have also intentionally skipped some corner cases and provided only pointers
122  to keep this document simple.  to keep this document simple.
123  </para>  </para>
124  <section id="socialdynamism"><title>Social dynamics of Debian</title>  <section id="socialdynamics"><title>Social dynamics of Debian</title>
125  <para>  <para>
126  Here are some observations of Debian's social dynamics, presented in the hope  Here are some observations of Debian's social dynamics, presented in the hope
127  that it will prepare you for interactions with Debian.  that it will prepare you for interactions with Debian.
# Line 226  please refer to the following to learn h Line 226  please refer to the following to learn h
226  <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>  <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
227  </itemizedlist>  </itemizedlist>
228  </section>  </section>
229  <section id="needprogs"><title>Programs you need for development</title>  <section id="needprogs"><title>Programs needed for development</title>
230  <para>  <para>
231  Before you start anything, you should make sure that you have properly  Before you start anything, you should make sure that you have properly
232  installed some additional packages needed for development.  Note that the list  installed some additional packages needed for development.  Note that the list
# Line 655  typical workflow of the Debian package b Line 655  typical workflow of the Debian package b
655  <itemizedlist>  <itemizedlist>
656  <listitem>  <listitem>
657  <para>  <para>
658  We create a native Debian source package in the <literal>3.0 (quilt)</literal> format using a compressed tar format in which required files under the <filename>debian</filename> directory are also included.  We create a native Debian source package in the <literal>3.0 (native)</literal>
659    format using a single compressed tar file in which all files are included.
660  </para>  </para>
661    <itemizedlist>    <itemizedlist>
662    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>
# Line 817  and ask for advice. Line 818  and ask for advice.
818  </para>  </para>
819  </listitem>  </listitem>
820  </itemizedlist>  </itemizedlist>
821    </listitem>
822  <listitem>  <listitem>
823  <para>  <para>
824  The program should <emphasis role="strong">not</emphasis> introduce security  The program should <emphasis role="strong">not</emphasis> introduce security
825  and maintenance concerns to the Debian system.  and maintenance concerns to the Debian system.
826  </para>  </para>
 </listitem>  
827  <itemizedlist>  <itemizedlist>
828  <listitem>  <listitem>
829  <para>  <para>
# Line 864  with easier packages and discouraged fro Line 865  with easier packages and discouraged fro
865  </para>  </para>
866  <itemizedlist>  <itemizedlist>
867  <listitem><para>Simple packages</para>  <listitem><para>Simple packages</para>
868    <itemizedlist>  <itemizedlist>
869    <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>    <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
870    <listitem><para>single binary package, arch = all (executables written in the POSIX shell language)</para></listitem>    <listitem><para>single binary package, arch = all (executables written in the POSIX shell language)</para></listitem>
871    <listitem><para>single binary package, arch = all (executables written in interpreter languages)</para></listitem>    <listitem><para>single binary package, arch = all (executables written in interpreter languages)</para></listitem>
872    </itemizedlist>  </itemizedlist>
873  </listitem>  </listitem>
874  <listitem><para>Intermediate complexity packages</para>  <listitem><para>Intermediate complexity packages</para>
875    <itemizedlist>  <itemizedlist>
876    <listitem><para>single binary package, arch = any (executables written in compiler languages such as C and C++)</para></listitem>    <listitem><para>single binary package, arch = any (executables written in compiler languages such as C and C++)</para></listitem>
877    <listitem><para>multiple binary packages, arch = any + all (packages for executables + documentation)</para></listitem>    <listitem><para>multiple binary packages, arch = any + all (packages for executables + documentation)</para></listitem>
878    <listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>    <listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
879    <listitem><para>upstream source containing undistributable contents</para></listitem>    <listitem><para>upstream source containing undistributable contents</para></listitem>
880    </itemizedlist>  </itemizedlist>
881  </listitem>  </listitem>
882  <listitem><para>High complexity packages</para>  <listitem><para>High complexity packages</para>
883    <itemizedlist>  <itemizedlist>
884    <listitem><para>interpreter module package used by other packages</para></listitem>    <listitem><para>interpreter module package used by other packages</para></listitem>
885    <listitem><para>generic library package used by other packages</para></listitem>    <listitem><para>generic library package used by other packages</para></listitem>
886    <listitem><para>multiple binary packages containing a library package</para></listitem>    <listitem><para>multiple binary packages containing a library package</para></listitem>
# Line 887  with easier packages and discouraged fro Line 888  with easier packages and discouraged fro
888    <listitem><para>kernel module packages</para></listitem>    <listitem><para>kernel module packages</para></listitem>
889    <listitem><para>kernel patch packages</para></listitem>    <listitem><para>kernel patch packages</para></listitem>
890    <listitem><para>any package with non-trivial maintainer scripts</para></listitem>    <listitem><para>any package with non-trivial maintainer scripts</para></listitem>
891    </itemizedlist>  </itemizedlist>
892  </listitem>  </listitem>
893  </itemizedlist>  </itemizedlist>
894  <para>  <para>
895  Packaging high complexity packages is not too hard, but it requires a bit more  Packaging high complexity packages is not too hard, but it requires a bit more
896  knowledge. You should seek specific guidances for every complexity. For example, some interpreter languages have their policy.  knowledge. You should seek specific guidances for every complexity. For
897    example, some interpreter languages have their policy.
898  </para>  </para>
899  <itemizedlist>  <itemizedlist>
900  <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>  <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
901  <listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>  <listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>
902  <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>  <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
903  </itemizedlist>  </itemizedlist>
904    <para>
905    There is another old Latin saying: <emphasis>Fabricando fit faber</emphasis>
906    (Practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
907    practice and experiment all the steps of Debian packaging with simple packages
908    while reading this tutorial.  A trivial upstream tarball
909    <filename>hello-sh-1.0.tar.gz</filename> created with the following may offer
910    you a good starting point.<footnote><para>Do not worry about missing
911    <filename>Makefile</filename>.  You can install the <command>hello</command>
912    command by simply using <command>debhelper</command> as in
913    <xref linkend="install"/>, or by modifying the upstream source to add a new
914    <filename>Makefile</filename> with the <literal>install</literal> target as in
915    <xref linkend="modify"/>.</para></footnote>
916    </para>
917    <screen>
918    $ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
919    $ cat &gt; hello &lt;&lt;EOF
920    #!/bin/sh
921    # (C) 2011 Foo Bar, GPL2+
922    echo "Hello!"
923    EOF
924    $ chmod 755 hello
925    $ cd ..
926    $ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0
927    </screen>
928  </section>  </section>
929  <section id="getit"><title>Get the program, and try it out</title>  <section id="getit"><title>Get the program, and try it out</title>
930  <para>  <para>
# Line 930  enough.  </para> </footnote>), you shoul Line 956  enough.  </para> </footnote>), you shoul
956  appropriate tools and repack it.  appropriate tools and repack it.
957  </para>  </para>
958  <para>  <para>
959    If your program's source comes with some contents which do not comply with
960    DFSG, you should also unpack it to remove such contents and repack it with a
961    modified upstream version containg <literal>dfsg</literal>.
962    </para>
963    <para>
964  As an example, I'll use a program called <command>gentoo</command>, a GTK+  As an example, I'll use a program called <command>gentoo</command>, a GTK+
965  file manager.  file manager.
966  <footnote><para> This program is already packaged. The  <footnote><para> This program is already packaged. The
# Line 974  or simply with freshly unpacked sources. Line 1005  or simply with freshly unpacked sources.
1005  </section>  </section>
1006  <section id="simplemake"><title>Simple build systems</title>  <section id="simplemake"><title>Simple build systems</title>
1007  <para>  <para>
1008  Simple programs come with a <filename>Makefile</filename> and can  Simple programs usually come with a <filename>Makefile</filename> and can
1009  be compiled just by invoking <literal>make</literal>.<footnote><para>  be compiled just by invoking <literal>make</literal>.<footnote><para>
1010  Many modern programs come with a script <filename>configure</filename> which  Many modern programs come with a script <filename>configure</filename> which
1011  when executed creates a <filename>Makefile</filename> customized for  when executed creates a <filename>Makefile</filename> customized for
# Line 1093  to consist only of lower case letters (< Line 1124  to consist only of lower case letters (<
1124  at least two characters long, must start with an alphanumeric character, and  at least two characters long, must start with an alphanumeric character, and
1125  must not be the same as existing ones.  must not be the same as existing ones.
1126  It is good idea to keep its length within 30 characters.  It is good idea to keep its length within 30 characters.
1127  <footnote><para>The package name field length of <command>aptitude</command> is 30.  For more than 90% of packages, the package name is less than 24 characters.</para></footnote>  <footnote><para>The default package name field length of <command>aptitude</command> is 30.  For more than 90% of packages, the package name is less than 24 characters.</para></footnote>
1128  </para>  </para>
1129  <!--  <!--
1130  Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):  Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
# Line 1123  tildes (<literal>~</literal>), and perio Line 1154  tildes (<literal>~</literal>), and perio
1154  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
1155  rule should help you avoid confusing file names.</para></footnote>  rule should help you avoid confusing file names.</para></footnote>
1156  It is good idea to keep its length within 8 characters if possible.  It is good idea to keep its length within 8 characters if possible.
1157  <footnote><para>The version field length of <command>aptitude</command> is 10.  The Debian revision with preceding hyphen usually consumes 2.  For more than 80% of packages, the upstream version is less than 8 charactes and the Debian revision is less than 2 characters.  For more than 90% of packages, the upstream version is less than 10 charactes and the Debian revision is less than 3 characters.</para></footnote>  <footnote><para>The default version field length of <command>aptitude</command> is 10.  The Debian revision with preceding hyphen usually consumes 2.  For more than 80% of packages, the upstream version is less than 8 characters and the Debian revision is less than 2 characters.  For more than 90% of packages, the upstream version is less than 10 characters and the Debian revision is less than 3 characters.</para></footnote>
1158  </para>  </para>
1159  <!--  <!--
1160  Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):  Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
# Line 1160  invent a version string, use the <litera Line 1191  invent a version string, use the <litera
1191  </para>  </para>
1192  <para>  <para>
1193  Version strings <footnote><para>Version strings may be  Version strings <footnote><para>Version strings may be
1194  <literal><replaceable>version</replaceable></literal>,  <emphasis role="strong">upstream version</emphasis>
1195  <literal><replaceable>revision</replaceable></literal>, or  (<literal><replaceable>version</replaceable></literal>),
1196  <literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>.  <emphasis role="strong">Debian revision</emphasis>
1197  See <xref linkend="newrevision"/> for how the <emphasis role="strong">Debian  (<literal><replaceable>revision</replaceable></literal>), or
1198  revision</emphasis> <literal><replaceable>revision</replaceable></literal> is incremented.  <emphasis role="strong">version</emphasis>
1199    (<literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>).
1200    See <xref linkend="newrevision"/> for how the
1201    <emphasis role="strong">Debian revision</emphasis> is incremented.
1202  </para></footnote>  </para></footnote>
1203  can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.  can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.
1204  </para>  </para>
# Line 3975  Debian archives.  See Line 4009  Debian archives.  See
4009  <ulink url="&keycreate;">Creating a new GPG key</ulink> and  <ulink url="&keycreate;">Creating a new GPG key</ulink> and
4010  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
4011  </para></footnote>  </para></footnote>
4012    If you are building Debian packages only for your local use, you can skip
4013    promptings for the GPG signatures on the <filename>.dsc</filename> file and the
4014    <filename>.changes</filename> file as:
4015  </para>  </para>
4016    <screen>
4017    $ dpkg-buildpackage -us -uc
4018    </screen>
4019  <para>  <para>
4020  After all this is done for the non-native Debian package, you will see the following files in the directory above  For the non-native Debian package, e.g.,
4021  (<filename>~/gentoo</filename>):  <systemitem role="package">gentoo</systemitem>, you will see the following
4022    files in the parent directory (<filename>~/gentoo</filename>) after building
4023    packages:
4024  </para>  </para>
4025  <itemizedlist>  <itemizedlist>
4026  <listitem>  <listitem>
# Line 4063  mentioned.  Anyone downloading your file Line 4105  mentioned.  Anyone downloading your file
4105  they'll know the file is corrupt or has been tampered with.  they'll know the file is corrupt or has been tampered with.
4106  </para>  </para>
4107  <para>  <para>
4108  Here, if you are building Debian packages only for your local use, you can skip  For the native Debian package, e.g.,
4109  promptings for the GPG signitures on the <filename>.dsc</filename> file and the  <systemitem role="package">mypackage</systemitem>, you will see the following
4110  <filename>.changes</filename> file as:  files in the parent directory after building packages:
4111  </para>  </para>
4112  <screen>  <itemizedlist>
4113  $ dpkg-buildpackage -us -uc  <listitem>
4114  </screen>  <para>
4115    <filename>mypackage_1.0.tar.gz</filename>
4116    </para>
4117    <para>
4118    This is the source code tarball merely created from the
4119    <filename>mypackage-1.0</filename> directory by the
4120    <command>dpkg-source</command>.  (Its suffix is not <filename>orig.tar.gz</filename>.)
4121    </para>
4122    </listitem>
4123    <listitem>
4124    <para>
4125    <filename>mypackage_1.0.dsc</filename>
4126    </para>
4127    <para>
4128    This is a summary of the contents of the source code as in the non-native
4129    Debian package. (There is no Debian revision.)
4130    </para>
4131    </listitem>
4132    <listitem>
4133    <para>
4134    <filename>mypackage_1.0_i386.deb</filename>
4135    </para>
4136    <para>
4137    This is your completed binary package as in the non-native Debian package.
4138    (There is no Debian revision.)
4139    </para>
4140    </listitem>
4141    <listitem>
4142    <para>
4143    <filename>mypackage_1.0_i386.changes</filename>
4144    </para>
4145    <para>
4146    This file describes all the changes made in the current package version as in
4147    the non-native Debian package. (There is no Debian revision.)
4148    </para>
4149    </listitem>
4150    </itemizedlist>
4151  </section>  </section>
4152  <section id="autobuilder"><title>Autobuilder</title>  <section id="autobuilder"><title>Autobuilder</title>
4153  <para>  <para>
# Line 4186  $ debuild Line 4264  $ debuild
4264  </screen>  </screen>
4265  <para>  <para>
4266  Here, if you are building Debian packages only for your local use, you can skip  Here, if you are building Debian packages only for your local use, you can skip
4267  promptings for the GPG signitures on the <filename>.dsc</filename> file and the  promptings for the GPG signatures on the <filename>.dsc</filename> file and the
4268  <filename>.changes</filename> file as:  <filename>.changes</filename> file as:
4269  </para>  </para>
4270  <screen>  <screen>
# Line 4211  under the <literal>sid</literal> auto-bu Line 4289  under the <literal>sid</literal> auto-bu
4289  avoids a severity serious FTBFS (Fails To Build From Source) bug which is  avoids a severity serious FTBFS (Fails To Build From Source) bug which is
4290  always in the RC (release critical) category.  always in the RC (release critical) category.
4291  <footnote><para>See <ulink url="&buildd-do;"/> for more on  <footnote><para>See <ulink url="&buildd-do;"/> for more on
4292  Debian package auto-building.  Debian package auto-building.</para></footnote>
 .</para></footnote>  
4293  </para>  </para>
4294  <para>  <para>
4295  Let's customize the <systemitem role="package">pbuilder</systemitem> package as  Let's customize the <systemitem role="package">pbuilder</systemitem> package as
# Line 4268  $ sudo pbuilder --update Line 4345  $ sudo pbuilder --update
4345  $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc  $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc
4346  </screen>  </screen>
4347  <para>  <para>
4348  The newly built packages without the GPG signitures will be located in  The newly built packages without the GPG signatures will be located in
4349  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
4350  </para>  </para>
4351  <para>  <para>
4352  The GPG signitures on the <filename>.dsc</filename> file and the  The GPG signatures on the <filename>.dsc</filename> file and the
4353  <filename>.changes</filename> file can be generated as:  <filename>.changes</filename> file can be generated as:
4354  </para>  </para>
4355  <screen>  <screen>
# Line 4291  $ pdebuild Line 4368  $ pdebuild
4368  </screen>  </screen>
4369  <para>  <para>
4370  Here, if you are building Debian packages only for your local use, you can skip  Here, if you are building Debian packages only for your local use, you can skip
4371  promptings for the GPG signitures on the <filename>.dsc</filename> file and the  promptings for the GPG signatures on the <filename>.dsc</filename> file and the
4372  <filename>.changes</filename> file as:  <filename>.changes</filename> file as:
4373  </para>  </para>
4374  <screen>  <screen>
# Line 4685  a public archive to share it. Line 4762  a public archive to share it.
4762  <para>  <para>
4763  Once you become an official developer,  Once you become an official developer,
4764  <footnote><para>  <footnote><para>
4765  See <xref linkend="socialdynamism"/>.  See <xref linkend="socialdynamics"/>.
4766  </para></footnote>  </para></footnote>
4767  you can upload the package to the Debian archive.  you can upload the package to the Debian archive.
4768  <footnote><para>  <footnote><para>
# Line 4937  changed and it already exists in the Deb Line 5014  changed and it already exists in the Deb
5014  </listitem>  </listitem>
5015  </itemizedlist>  </itemizedlist>
5016  <para>  <para>
5017  One of the tricky case happens when you make an experimental package before  One of the tricky case happens when you make a local package to experiment with
5018  uploading the normal version, e.g.,  the packaging before uploading to the official archive with the normal version,
5019    e.g.,
5020  <literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.  <literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.
5021  For such case, you use a version string in the Debian  For the smoother upgrade, it is a good idea to create a
5022  <filename>changelog</filename> file as  <filename>changelog</filename> entry with a version string as
5023  <literal><replaceable>1.0.1</replaceable>-<replaceable>1~rc1</replaceable></literal>. See <xref linkend="namever"/> for the order of version strings.  <literal><replaceable>1.0.1</replaceable>-<replaceable>1~rc1</replaceable></literal>.
5024    You may unclutter <filename>changelog</filename>
5025    by consolidating such local change entries into a single entry for the official package.
5026    See <xref linkend="namever"/> for the order of version strings.
5027  </para>  </para>
5028  <para>  <para>
5029  </para>  </para>
5030  </section>  </section>
5031  <section id="inspectnewupstream"><title>Inspection of the new upstream release</title>  <section id="inspectnewupstream"><title>Inspection of the new upstream release</title>
5032  <para>  <para>
5033  When preparing packages of the a upstream release for the Debian archive, you  When preparing packages of a new upstream release for the Debian archive, you
5034  must check the new upstream release, first.  must check the new upstream release, first.
5035  </para>  </para>
5036  <para>  <para>
Legend:
Removed from v.8750  
changed lines
  Added in v.8769
  ViewVC Help
Powered by ViewVC 1.1.5