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

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

Parent Directory | Revision Log | View Patch Patch

-revision 8757 by taffit-guest,
Sat Apr 30 05:09:16 2011 UTC
+revision 8771 by osamu,
Sun May  1 04:25:03 2011 UTC
 Line 121 
 important topics.  Some of them may look
  I have also intentionally skipped some corner cases and provided only pointers
  to keep this document simple.
  </para>
- <section id="socialdynamism"><title>Social dynamics of Debian</title>
+ <section id="socialdynamics"><title>Social dynamics of Debian</title>
  <para>
  Here are some observations of Debian's social dynamics, presented in the hope
  that it will prepare you for interactions with Debian.
 Line 226 
 please refer to the following to learn h
  <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
  </itemizedlist>
  </section>
- <section id="needprogs"><title>Programs you need for development</title>
+ <section id="needprogs"><title>Programs needed for development</title>
  <para>
  Before you start anything, you should make sure that you have properly
  installed some additional packages needed for development.  Note that the list
 Line 585 
 documentation</emphasis> for details).
  Let's start by creating a package of your own (or, even better,
  adopting an existing one).
  </para>
- <section id="workflow"><title>Workflow of the Debian package building</title>
+ <section id="workflow"><title>Debian package building workflow</title>
  <para>
- If you are making a Debian package with an upstream program,
+ If you are making a Debian package with an upstream program, the
- typical workflow of the Debian package building involves generating several
+ typical workflow of Debian package building involves generating several
- specifically named files for each step as the following.
+ specifically named files for each step as follows.
  </para>
  <itemizedlist>
  <listitem>
- <para>We obtain an upstream program file usually in a compressed tar format.</para>
+ <para>Get a copy of the upstream software, usually in a compressed tar format.</para>
    <itemizedlist>
    <listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
    </itemizedlist>
  </listitem>
  <listitem>
  <para>
- We create a non-native Debian source package in the <literal>3.0 (quilt)</literal> format, which refers to the set of input files for
+ Add Debian-specific packaging modifications to the upstream program under the
- the Debian package building, by adding Debian package modifications to the upstream program under the <filename>debian</filename> directory.
+ <filename>debian</filename> directory, and create a non-native source package
+ (that is, the set of input files used for Debian package building) in
+ <literal>3.0 (quilt)</literal> format .
  </para>
    <itemizedlist>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
-     <footnote><para>For the older non-native Debian source package in the <literal>1.0</literal> format,
+     <footnote><para>For the older style of non-native Debian source packages in <literal>1.0</literal> format,
      <literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
      is used instead. </para></footnote></listitem>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
-Line 614 
 the Debian package building, by adding D
+Line 616 
 the Debian package building, by adding D
  </listitem>
  <listitem>
  <para>
- We build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer), from the Debian source package.
+ Build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer) from the Debian source package.
  </para>
    <itemizedlist>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
-Line 625 
 We build Debian binary packages, which a
+Line 627 
 We build Debian binary packages, which a
  Please note that the character separating
  <literal><replaceable>package</replaceable></literal> and
  <literal><replaceable>version</replaceable></literal> was changed from
- <literal>-</literal> (hyphen) to <literal>_</literal> (underscore).
+ <literal>-</literal> (hyphen) in the tarball name to
+ <literal>_</literal> (underscore) in the Debian package filenames.
  </para>
  <para>
- Here,
+ In the file names above, replace
- <literal><replaceable>package</replaceable></literal> part of the file name is substituted by the
+ the <literal><replaceable>package</replaceable></literal> part with the <emphasis role="strong">package name</emphasis>,
- <emphasis role="strong">package name</emphasis>,
+ the <literal><replaceable>version</replaceable></literal> part with the <emphasis role="strong">upstream version</emphasis>,
- <literal><replaceable>version</replaceable></literal> part of it is substituted by the
+ the <literal><replaceable>revision</replaceable></literal> part with the <emphasis role="strong">Debian revision</emphasis>,
- <emphasis role="strong">upstream version</emphasis>,
+ and the <literal><replaceable>arch</replaceable></literal> part with the <emphasis role="strong">package architecture</emphasis>,
- <literal><replaceable>revision</replaceable></literal> part of it is substituted by the
+ as defined in the Debian Policy Manual.
- <emphasis role="strong">Debian revision</emphasis>,
+ <footnote> <para> See
- <literal><replaceable>arch</replaceable></literal> part of it is substituted by the
- <emphasis role="strong">package architecture</emphasis>.
- <footnote><para>
- The <emphasis role="strong">package name</emphasis>, <emphasis
- role="strong">upstream version</emphasis>, and <emphasis role="strong">Debian
- revision</emphasis> must be adjusted to comply with the Debian Policy Manual:
  <ulink url="&policy-source;">5.6.1 Source</ulink>,
  <ulink url="&policy-package;">5.6.7 Package</ulink>, and
  <ulink url="&policy-version;">5.6.12 Version</ulink>.
-Line 649 
 Debian Policy Manual: <ulink url="&polic
+Line 646 
 Debian Policy Manual: <ulink url="&polic
  and is automatically assigned by the package build process.</para></footnote>
  </para>
  <para>
- If you are making a Debian specific package without an upstream program instead,
+ If instead you are making a Debian-specific package with no upstream, the
- typical workflow of the Debian package building is simpler.
+ typical workflow of Debian package building is simpler.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- 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.
+ Create a native Debian source package in the <literal>3.0 (native)</literal>
+ format using a single compressed tar file in which all files are included.
  </para>
    <itemizedlist>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>
-Line 664 
 We create a native Debian source package
+Line 662 
 We create a native Debian source package
  </listitem>
  <listitem>
  <para>
- We build Debian binary packages from the native Debian source package.
+ Build Debian binary packages from the native Debian source package.
  </para>
    <itemizedlist>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
-Line 672 
 We build Debian binary packages from the
+Line 670 
 We build Debian binary packages from the
  </listitem>
  </itemizedlist>
  <para>
- In the following, each step of this is explained with detailed examples.
+ Each step of this outline is explained with detailed examples in later sections.
  </para>
  </section>
  <section id="choose"><title>Choose your program</title>
-Line 817 
 and ask for advice.
+Line 815 
 and ask for advice.
  </para>
  </listitem>
  </itemizedlist>
+ </listitem>
  <listitem>
  <para>
  The program should <emphasis role="strong">not</emphasis> introduce security
  and maintenance concerns to the Debian system.
  </para>
- </listitem>
  <itemizedlist>
  <listitem>
  <para>
-Line 864 
 with easier packages and discouraged fro
+Line 862 
 with easier packages and discouraged fro
  </para>
  <itemizedlist>
  <listitem><para>Simple packages</para>
-   <itemizedlist>
+ <itemizedlist>
    <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
-   <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 an interpreted language such as POSIX shell)</para></listitem>
-   <listitem><para>single binary package, arch = all (executables written in interpreter languages)</para></listitem>
+ </itemizedlist>
-   </itemizedlist>
  </listitem>
  <listitem><para>Intermediate complexity packages</para>
-   <itemizedlist>
+ <itemizedlist>
-   <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 compiled languages such as C and C++)</para></listitem>
    <listitem><para>multiple binary packages, arch = any + all (packages for executables + documentation)</para></listitem>
    <listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
    <listitem><para>upstream source containing undistributable contents</para></listitem>
-   </itemizedlist>
+ </itemizedlist>
  </listitem>
  <listitem><para>High complexity packages</para>
-   <itemizedlist>
+ <itemizedlist>
    <listitem><para>interpreter module package used by other packages</para></listitem>
    <listitem><para>generic library package used by other packages</para></listitem>
-   <listitem><para>multiple binary packages containing a library package</para></listitem>
+   <listitem><para>multiple binary packages including a library package</para></listitem>
    <listitem><para>source package with multiple upstream sources</para></listitem>
    <listitem><para>kernel module packages</para></listitem>
    <listitem><para>kernel patch packages</para></listitem>
    <listitem><para>any package with non-trivial maintainer scripts</para></listitem>
-   </itemizedlist>
+ </itemizedlist>
  </listitem>
  </itemizedlist>
  <para>
  Packaging high complexity packages is not too hard, but it requires a bit more
- knowledge. You should seek specific guidances for every complexity. For
+ knowledge. You should seek specific guidance for every complex feature. For
- example, some interpreter languages have their policy.
+ example, some languages have their own sub-policy documents:
  </para>
  <itemizedlist>
  <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
-Line 901 
 example, some interpreter languages have
+Line 898 
 example, some interpreter languages have
  <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
  </itemizedlist>
  <para>
- There is another old Latin saying: <emphasis>Fabricando fit fabe</emphasis>
+ There is another old Latin saying: <emphasis>fabricando fit faber</emphasis>
- (Practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
+ (practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
- practice and experiment all the steps of Debian packaging with simple packages
+ practice and experiment with all the steps of Debian packaging with simple packages
  while reading this tutorial.  A trivial upstream tarball
- <filename>hello-sh-1.0.tar.gz</filename> created with the following may offer
+ <filename>hello-sh-1.0.tar.gz</filename> created as followings may offer
- you a good starting point.<footnote><para>Do not worry about missing
+ a good starting point.<footnote><para>Do not worry about the missing
  <filename>Makefile</filename>.  You can install the <command>hello</command>
  command by simply using <command>debhelper</command> as in
  <xref linkend="install"/>, or by modifying the upstream source to add a new
  <filename>Makefile</filename> with the <literal>install</literal> target as in
  <xref linkend="modify"/>.</para></footnote>
-Line 955 
 enough.  </para> </footnote>), you shoul
+Line 952 
 enough.  </para> </footnote>), you shoul
  appropriate tools and repack it.
  </para>
  <para>
+ If your program's source comes with some contents which do not comply with
+ DFSG, you should also unpack it to remove such contents and repack it with a
+ modified upstream version containg <literal>dfsg</literal>.
+ </para>
+ <para>
  As an example, I'll use a program called <command>gentoo</command>, a GTK+
  file manager.
  <footnote><para> This program is already packaged. The
-Line 1098 
 build system.  You can recognize such so
+Line 1100 
 build system.  You can recognize such so
  <section id="namever"><title>Package name and version</title>
  <para>
  If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
- consider
+ take <literal>gentoo</literal> as the (source) <emphasis role="strong">package name</emphasis>
- <emphasis role="strong">package name</emphasis> to be <literal>gentoo</literal> and
+ and <literal>0.9.12</literal> as the <emphasis role="strong">upstream version</emphasis>.
- <emphasis role="strong">upstream version</emphasis> to be <literal>0.9.12</literal>.
  These are used in the <filename>debian/changelog</filename> file described later in
  <xref linkend="changelog"/>, too.
  </para>
-Line 1108 
 These are used in the <filename>debian/c
+Line 1109 
 These are used in the <filename>debian/c
  Although this simple approach works most of the times, you may need to adjust
  <emphasis role="strong">package name</emphasis> and
  <emphasis role="strong">upstream version</emphasis> by renaming the upstream
- source to follow the Debian Policy and the existing convention.
+ source to follow Debian Policy and existing convention.
  </para>
  <para>
  You must choose the <emphasis role="strong">package name</emphasis>
-Line 1117 
 to consist only of lower case letters (<
+Line 1118 
 to consist only of lower case letters (<
  (<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be
  at least two characters long, must start with an alphanumeric character, and
  must not be the same as existing ones.
- It is good idea to keep its length within 30 characters.
+ It is a good idea to keep its length within 30 characters.
  <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>
  </para>
  <!--
-Line 1133 
 Previous 20 chars is becoming too short
+Line 1134 
 Previous 20 chars is becoming too short
  Default aptitude setting display up to 30 chars (98.3%).
  -->
  <para>
- If upstream source uses generic words such as <literal>test-suite</literal> as
+ If upstream uses some generic term such as <literal>test-suite</literal> for
- its name, it is good idea to rename it not to contaminate name space for the
+ its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
- package name and to identify its contents explicitly.
  <footnote><para>If you follow the
  <ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
  the ITP process will usually catch this kind of issues.</para></footnote>
 Line 1173 
 aptitude display 10 = 8char for up + 1ch
 chars as max for file name of binary debs (package+up+deb+arch+.deb)
  -->
  <para>
- If the upstream software does not use normal version system like
+ If upstream does not use a normal versioning scheme such as
  <literal>2.30.32</literal> but uses some kind of date such as
- <literal>09Oct23</literal>, a random codename string or a VCS hash value as a part
+ <literal>09Oct23</literal>, a random codename string, or a VCS hash value as part
- of version, make sure to remove them from the
+ of the version, make sure to remove them from the
  <emphasis role="strong">upstream version</emphasis>.  Such information can be
  recorded in the <filename>debian/changelog</filename> file.  If you need to
  invent a version string, use the <literal>YYYYMMDD</literal> format such as
  <literal>20110429</literal> as upstream version.  This ensures that
- <command>dpkg</command> properly sees later versions as upgrades.
+ <command>dpkg</command> interprets later versions correctly as upgrades.
  </para>
  <para>
  Version strings <footnote><para>Version strings may be
 Line 1194 
 Version strings <footnote><para>Version
  See <xref linkend="newrevision"/> for how the
  <emphasis role="strong">Debian revision</emphasis> is incremented.
  </para></footnote>
- can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.
+ can be compared using <citerefentry>
+ <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as follows.
  </para>
  <screen>
   $ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
  </screen>
  <para>
- The version comparison rule can be summarized as the following.
+ The version comparison rule can be summarized as:
  </para>
  <itemizedlist>
- <listitem><para>The strings are compared from the head to the tail.</para></listitem>
+ <listitem><para>Strings are compared from the head to the tail.</para></listitem>
- <listitem><para>Alphabets are larger than numbers.</para></listitem>
+ <listitem><para>Letters are larger than digits.</para></listitem>
- <listitem><para>Numbers are compared as the integer.</para></listitem>
+ <listitem><para>Numbers are compared as integers.</para></listitem>
- <listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>
+ <listitem><para>Letters are compared in ASCII code order.</para></listitem>
- <listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tildes (<literal>~</literal>) as the followings.</para>
+ <listitem><para>There are special rules for period
+ (<literal>.</literal>), plus (<literal>+</literal>), and tilde
+ (<literal>~</literal>) characters, as follows.</para>
    <para>
    <literal>0.0</literal> &lt;
    <literal>0.5</literal> &lt;
-Line 1224 
 The version comparison rule can be summa
+Line 1227 
 The version comparison rule can be summa
  </listitem>
  </itemizedlist>
  <para>
- One of the tricky case happens when the upstream releases
+ One tricky case occurs when upstream releases
  <filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
  pre-release of <filename>gentoo-0.9.12.tar.gz</filename>.  You need to make
  sure that the upgrade works properly by renaming the upstream source to
-Line 1347 
 package; further explanations are given
+Line 1350 
 package; further explanations are given
  <para>
  Please note that the source file does not need to contain any build system
  discussed in <xref linkend="simplemake"/> and <xref linkend="portable"/>.  It
- could be just a collection of graphics data etc.  Installation of files may be
+ could be just a collection of graphical data etc.  Installation of files may be
- enabled by <systemitem role="package">debhelper</systemitem> configuration
+ carried out using only <systemitem role="package">debhelper</systemitem> configuration
  files such as <filename>debian/install</filename> (see
- <xref linkend="install"/>) only.
+ <xref linkend="install"/>).
  </para>
  </section>
  <section id="native-dh-make"><title>Initial native Debian package</title>
  <para>
- Debian native packages are simpler to manage if they contain source files you
+ If a package contains source files you are only maintaining for Debian,
- manage only for Debian, possibly only for local uses.  If you have source
+ possibly only for local use, it may be simpler to create it as a Debian
+ native package. If you have source
  files in <filename>~/mypackage-1.0</filename>, you can create an initial native
  Debian package for it by issuing the <command>dh_make</command> command as
  follows.
-Line 4003 
 Debian archives.  See
+Line 4007 
 Debian archives.  See
  <ulink url="&keycreate;">Creating a new GPG key</ulink> and
  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
  </para></footnote>
- If you are building Debian packages only for your local use, you can skip
+ If you are building Debian packages only for your own local use, you can skip
  promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- <filename>.changes</filename> file as:
+ <filename>.changes</filename> file like this:
  </para>
  <screen>
  $ dpkg-buildpackage -us -uc
  </screen>
  <para>
- For the non-native Debian package, e.g.,
+ For a non-native Debian package, e.g.,
  <systemitem role="package">gentoo</systemitem>, you will see the following
  files in the parent directory (<filename>~/gentoo</filename>) after building
  packages:
-Line 4099 
 mentioned.  Anyone downloading your file
+Line 4103 
 mentioned.  Anyone downloading your file
  they'll know the file is corrupt or has been tampered with.
  </para>
  <para>
- For the native Debian package, e.g.,
+ For a native Debian package, e.g.,
  <systemitem role="package">mypackage</systemitem>, you will see the following
  files in the parent directory after building packages:
  </para>
-Line 4109 
 files in the parent directory after buil
+Line 4113 
 files in the parent directory after buil
  <filename>mypackage_1.0.tar.gz</filename>
  </para>
  <para>
- This is the source code tarball merely created from the
+ This is the source code tarball created from the
  <filename>mypackage-1.0</filename> directory by the
  <command>dpkg-source</command>.  (Its suffix is not <filename>orig.tar.gz</filename>.)
  </para>
-Line 4257 
 Cleaning the source and rebuilding the p
+Line 4261 
 Cleaning the source and rebuilding the p
  $ debuild
  </screen>
  <para>
- 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 own local use, you can skip
  promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- <filename>.changes</filename> file as:
+ <filename>.changes</filename> file like this:
  </para>
  <screen>
  $ debuild -us -uc
-Line 4756 
 a public archive to share it.
+Line 4760 
 a public archive to share it.
  <para>
  Once you become an official developer,
  <footnote><para>
- See <xref linkend="socialdynamism"/>.
+ See <xref linkend="socialdynamics"/>.
  </para></footnote>
  you can upload the package to the Debian archive.
  <footnote><para>
-Line 4853 
 For the <command>debuild</command> comma
+Line 4857 
 For the <command>debuild</command> comma
  $ debuild -sa
  </screen>
  <para>
- For the <command>debuild</command> command:
+ For the <command>pdebuild</command> command:
  </para>
  <screen>
  $ pdebuild --debbuildopts -sa
-Line 4885 
 For the <command>debuild</command> comma
+Line 4889 
 For the <command>debuild</command> comma
  $ debuild -v<replaceable>1.2</replaceable>
  </screen>
  <para>
- For the <command>debuild</command> command:
+ For the <command>pdebuild</command> command:
  </para>
  <screen>
  $ pdebuild --debbuildopts "-v<replaceable>1.2</replaceable>"
-Line 5008 
 changed and it already exists in the Deb
+Line 5012 
 changed and it already exists in the Deb
  </listitem>
  </itemizedlist>
  <para>
- One of the tricky case happens when you make an experimental package before
+ One tricky case can occur when you make a local package to experiment with
- uploading the normal version, e.g.,
+ the packaging before uploading  the normal version to the official archive,
+ e.g.,
  <literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.
- For such case, you use a version string in the Debian
+ For smoother upgrades, it is a good idea to create a
- <filename>changelog</filename> file as
+ <filename>changelog</filename> entry with a version string as
- <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>.
+ You may unclutter <filename>changelog</filename>
+ by consolidating such local change entries into a single entry for the official package.
+ See <xref linkend="namever"/> for the order of version strings.
  </para>
  <para>
  </para>

 Legend:



Removed from v.8757
 


changed lines


 
Added in v.8771
 Legend:



Removed from v.8757
 


changed lines


 
Added in v.8771
-Removed from v.8757
+Added in v.8771

	ViewVC Help
Powered by ViewVC 1.1.5