/[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 8759 by osamu, Sat Apr 30 05:47:20 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 892  with easier packages and discouraged fro Line 892  with easier packages and discouraged fro
892  </itemizedlist>  </itemizedlist>
893  <para>  <para>
894  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
895  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
896    example, some interpreter languages have their policy.
897  </para>  </para>
898  <itemizedlist>  <itemizedlist>
899  <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>  <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
900  <listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>  <listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>
901  <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>  <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
902  </itemizedlist>  </itemizedlist>
903    <para>
904    There is another old Latin saying: <emphasis>Fabricando fit fabe</emphasis>
905    (Practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
906    practice and experiment all the steps of Debian packaging with simple packages
907    while reading this tutorial.  A trivial upstream tarball
908    <filename>hello-sh-1.0.tar.gz</filename> created with the following may offer
909    you a good starting point.<footnote><para>Do not worry about missing
910    <filename>Makefile</filename>.  You can install the <command>hello</command>
911    command by simply using <command>debhelper</command> as in
912    <xref linkend="install"/>, or by modifying the upstream source to add a new
913    <filename>Makefile</filename> with the <literal>install</literal> target as in
914    <xref linkend="modify"/>.</para></footnote>
915    </para>
916    <screen>
917    $ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
918    $ cat &gt; hello &lt;&lt;EOF
919    #!/bin/sh
920    # (C) 2011 Foo Bar, GPL2+
921    echo "Hello!"
922    EOF
923    $ chmod 755 hello
924    $ cd ..
925    $ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0
926    </screen>
927  </section>  </section>
928  <section id="getit"><title>Get the program, and try it out</title>  <section id="getit"><title>Get the program, and try it out</title>
929  <para>  <para>
# Line 930  enough.  </para> </footnote>), you shoul Line 955  enough.  </para> </footnote>), you shoul
955  appropriate tools and repack it.  appropriate tools and repack it.
956  </para>  </para>
957  <para>  <para>
958    If your program's source comes with some contents which do not comply with
959    DFSG, you should also unpack it to remove such contents and repack it with a
960    modified upstream version containg <literal>dfsg</literal>.
961    </para>
962    <para>
963  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+
964  file manager.  file manager.
965  <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 1004  or simply with freshly unpacked sources.
1004  </section>  </section>
1005  <section id="simplemake"><title>Simple build systems</title>  <section id="simplemake"><title>Simple build systems</title>
1006  <para>  <para>
1007  Simple programs come with a <filename>Makefile</filename> and can  Simple programs usually come with a <filename>Makefile</filename> and can
1008  be compiled just by invoking <literal>make</literal>.<footnote><para>  be compiled just by invoking <literal>make</literal>.<footnote><para>
1009  Many modern programs come with a script <filename>configure</filename> which  Many modern programs come with a script <filename>configure</filename> which
1010  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 1123  to consist only of lower case letters (<
1123  at least two characters long, must start with an alphanumeric character, and  at least two characters long, must start with an alphanumeric character, and
1124  must not be the same as existing ones.  must not be the same as existing ones.
1125  It is good idea to keep its length within 30 characters.  It is good idea to keep its length within 30 characters.
1126  <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>
1127  </para>  </para>
1128  <!--  <!--
1129  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 1153  tildes (<literal>~</literal>), and perio
1153  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
1154  rule should help you avoid confusing file names.</para></footnote>  rule should help you avoid confusing file names.</para></footnote>
1155  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.
1156  <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>
1157  </para>  </para>
1158  <!--  <!--
1159  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 1190  invent a version string, use the <litera
1190  </para>  </para>
1191  <para>  <para>
1192  Version strings <footnote><para>Version strings may be  Version strings <footnote><para>Version strings may be
1193  <literal><replaceable>version</replaceable></literal>,  <emphasis role="strong">upstream version</emphasis>
1194  <literal><replaceable>revision</replaceable></literal>, or  (<literal><replaceable>version</replaceable></literal>),
1195  <literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>.  <emphasis role="strong">Debian revision</emphasis>
1196  See <xref linkend="newrevision"/> for how the <emphasis role="strong">Debian  (<literal><replaceable>revision</replaceable></literal>), or
1197  revision</emphasis> <literal><replaceable>revision</replaceable></literal> is incremented.  <emphasis role="strong">version</emphasis>
1198    (<literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>).
1199    See <xref linkend="newrevision"/> for how the
1200    <emphasis role="strong">Debian revision</emphasis> is incremented.
1201  </para></footnote>  </para></footnote>
1202  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.
1203  </para>  </para>
# Line 3975  Debian archives.  See Line 4008  Debian archives.  See
4008  <ulink url="&keycreate;">Creating a new GPG key</ulink> and  <ulink url="&keycreate;">Creating a new GPG key</ulink> and
4009  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
4010  </para></footnote>  </para></footnote>
4011    If you are building Debian packages only for your local use, you can skip
4012    promptings for the GPG signatures on the <filename>.dsc</filename> file and the
4013    <filename>.changes</filename> file as:
4014  </para>  </para>
4015    <screen>
4016    $ dpkg-buildpackage -us -uc
4017    </screen>
4018  <para>  <para>
4019  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.,
4020  (<filename>~/gentoo</filename>):  <systemitem role="package">gentoo</systemitem>, you will see the following
4021    files in the parent directory (<filename>~/gentoo</filename>) after building
4022    packages:
4023  </para>  </para>
4024  <itemizedlist>  <itemizedlist>
4025  <listitem>  <listitem>
# Line 4063  mentioned.  Anyone downloading your file Line 4104  mentioned.  Anyone downloading your file
4104  they'll know the file is corrupt or has been tampered with.  they'll know the file is corrupt or has been tampered with.
4105  </para>  </para>
4106  <para>  <para>
4107  Here, if you are building Debian packages only for your local use, you can skip  For the native Debian package, e.g.,
4108  promptings for the GPG signitures on the <filename>.dsc</filename> file and the  <systemitem role="package">mypackage</systemitem>, you will see the following
4109  <filename>.changes</filename> file as:  files in the parent directory after building packages:
4110  </para>  </para>
4111  <screen>  <itemizedlist>
4112  $ dpkg-buildpackage -us -uc  <listitem>
4113  </screen>  <para>
4114    <filename>mypackage_1.0.tar.gz</filename>
4115    </para>
4116    <para>
4117    This is the source code tarball merely created from the
4118    <filename>mypackage-1.0</filename> directory by the
4119    <command>dpkg-source</command>.  (Its suffix is not <filename>orig.tar.gz</filename>.)
4120    </para>
4121    </listitem>
4122    <listitem>
4123    <para>
4124    <filename>mypackage_1.0.dsc</filename>
4125    </para>
4126    <para>
4127    This is a summary of the contents of the source code as in the non-native
4128    Debian package. (There is no Debian revision.)
4129    </para>
4130    </listitem>
4131    <listitem>
4132    <para>
4133    <filename>mypackage_1.0_i386.deb</filename>
4134    </para>
4135    <para>
4136    This is your completed binary package as in the non-native Debian package.
4137    (There is no Debian revision.)
4138    </para>
4139    </listitem>
4140    <listitem>
4141    <para>
4142    <filename>mypackage_1.0_i386.changes</filename>
4143    </para>
4144    <para>
4145    This file describes all the changes made in the current package version as in
4146    the non-native Debian package. (There is no Debian revision.)
4147    </para>
4148    </listitem>
4149    </itemizedlist>
4150  </section>  </section>
4151  <section id="autobuilder"><title>Autobuilder</title>  <section id="autobuilder"><title>Autobuilder</title>
4152  <para>  <para>
# Line 4186  $ debuild Line 4263  $ debuild
4263  </screen>  </screen>
4264  <para>  <para>
4265  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
4266  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
4267  <filename>.changes</filename> file as:  <filename>.changes</filename> file as:
4268  </para>  </para>
4269  <screen>  <screen>
# Line 4211  under the <literal>sid</literal> auto-bu Line 4288  under the <literal>sid</literal> auto-bu
4288  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
4289  always in the RC (release critical) category.  always in the RC (release critical) category.
4290  <footnote><para>See <ulink url="&buildd-do;"/> for more on  <footnote><para>See <ulink url="&buildd-do;"/> for more on
4291  Debian package auto-building.  Debian package auto-building.</para></footnote>
 .</para></footnote>  
4292  </para>  </para>
4293  <para>  <para>
4294  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 4344  $ sudo pbuilder --update
4344  $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc  $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc
4345  </screen>  </screen>
4346  <para>  <para>
4347  The newly built packages without the GPG signitures will be located in  The newly built packages without the GPG signatures will be located in
4348  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
4349  </para>  </para>
4350  <para>  <para>
4351  The GPG signitures on the <filename>.dsc</filename> file and the  The GPG signatures on the <filename>.dsc</filename> file and the
4352  <filename>.changes</filename> file can be generated as:  <filename>.changes</filename> file can be generated as:
4353  </para>  </para>
4354  <screen>  <screen>
# Line 4291  $ pdebuild Line 4367  $ pdebuild
4367  </screen>  </screen>
4368  <para>  <para>
4369  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
4370  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
4371  <filename>.changes</filename> file as:  <filename>.changes</filename> file as:
4372  </para>  </para>
4373  <screen>  <screen>
# Line 4685  a public archive to share it. Line 4761  a public archive to share it.
4761  <para>  <para>
4762  Once you become an official developer,  Once you become an official developer,
4763  <footnote><para>  <footnote><para>
4764  See <xref linkend="socialdynamism"/>.  See <xref linkend="socialdynamics"/>.
4765  </para></footnote>  </para></footnote>
4766  you can upload the package to the Debian archive.  you can upload the package to the Debian archive.
4767  <footnote><para>  <footnote><para>
# Line 4937  changed and it already exists in the Deb Line 5013  changed and it already exists in the Deb
5013  </listitem>  </listitem>
5014  </itemizedlist>  </itemizedlist>
5015  <para>  <para>
5016  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
5017  uploading the normal version, e.g.,  the packaging before uploading to the official archive with the normal version,
5018    e.g.,
5019  <literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.  <literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.
5020  For such case, you use a version string in the Debian  For the smoother upgrade, it is a good idea to create a
5021  <filename>changelog</filename> file as  <filename>changelog</filename> entry with a version string as
5022  <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>.
5023    You may unclutter <filename>changelog</filename>
5024    by consolidating such local change entries into a single entry for the official package.
5025    See <xref linkend="namever"/> for the order of version strings.
5026  </para>  </para>
5027  <para>  <para>
5028  </para>  </para>
5029  </section>  </section>
5030  <section id="inspectnewupstream"><title>Inspection of the new upstream release</title>  <section id="inspectnewupstream"><title>Inspection of the new upstream release</title>
5031  <para>  <para>
5032  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
5033  must check the new upstream release, first.  must check the new upstream release, first.
5034  </para>  </para>
5035  <para>  <para>
Legend:
Removed from v.8750  
changed lines
  Added in v.8759
  ViewVC Help
Powered by ViewVC 1.1.5