/[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 8717 by taffit-guest, Sun Apr 24 03:50:22 2011 UTC revision 8719 by osamu, Sun Apr 24 13:31:28 2011 UTC
# Line 421  those made for X11, also use these progr Line 421  those made for X11, also use these progr
421  <para>  <para>
422  The short descriptions that are given above only serve to introduce you to what  The short descriptions that are given above only serve to introduce you to what
423  each package does.  Before continuing please thoroughly read the documentation  each package does.  Before continuing please thoroughly read the documentation
424  of each program including ones installed through the package dependency such as  of each relevant program including ones installed through the package dependency such as
425  <command>make</command>, at least, for the standard usage.  It may seem like heavy  <command>make</command>, at least, for the standard usage.  It may seem like heavy
426  going now, but later on you'll be <emphasis>very</emphasis> glad you read it.  going now, but later on you'll be <emphasis>very</emphasis> glad you read it.
427  </para>  </para>
# Line 825  The program should not be a daemon, or g Line 825  The program should not be a daemon, or g
825  </listitem>  </listitem>
826  <listitem>  <listitem>
827  <para>  <para>
828  The program should be in binary executable form; libraries are harder to handle.  The program should be in the binary executable form; libraries are harder to handle.
829  </para>  </para>
830  </listitem>  </listitem>
831  <listitem>  <listitem>
# Line 990  files requires some knowledge of <comman Line 990  files requires some knowledge of <comman
990  The second step of the Autotools workflow is usually that the user obtains this  The second step of the Autotools workflow is usually that the user obtains this
991  distributed source and runs <literal>./configure &amp;&amp; make</literal> in  distributed source and runs <literal>./configure &amp;&amp; make</literal> in
992  the source directory to compile the program into a  the source directory to compile the program into a
993  <command><replaceable>binary</replaceable></command>.  <command><replaceable>binary</replaceable> executables</command>.
994  </para>  </para>
995  <screen>  <screen>
996  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>
# Line 1021  build system.  You can recognize such so Line 1021  build system.  You can recognize such so
1021  </section>  </section>
1022  <section id="namever"><title>Package name and version</title>  <section id="namever"><title>Package name and version</title>
1023  <para>  <para>
1024  For the upstream source of <filename>gentoo-0.9.12.tar.gz</filename>, you can  If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
1025  intuitively choose  consider
1026  <emphasis role="strong">package name</emphasis> to be <literal>gentoo</literal> and  <emphasis role="strong">package name</emphasis> to be <literal>gentoo</literal> and
1027  <emphasis role="strong">upstream version</emphasis> to be <literal>0.9.12</literal>.  <emphasis role="strong">upstream version</emphasis> to be <literal>0.9.12</literal>.
1028    These are used in the <filename>debian/changelog</filename> file described later in
1029    <xref linkend="changelog"/>, too.
1030    </para>
1031    <para>
1032  Although this simple approach works most of the times, you may need to adjust  Although this simple approach works most of the times, you may need to adjust
1033  <emphasis role="strong">package name</emphasis> and  <emphasis role="strong">package name</emphasis> and
1034  <emphasis role="strong">upstream version</emphasis> to follow the Debian policy  <emphasis role="strong">upstream version</emphasis> by renaming the upstream
1035  and the existing convention.  source to follow the Debian policy and the existing convention.
1036  </para>  </para>
1037  <para>  <para>
1038  You should choose the <emphasis role="strong">package name</emphasis>  You must choose the <emphasis role="strong">package name</emphasis>
1039  which consists only of lower case letters (<literal>a-z</literal>), digits  to consist only of lower case letters (<literal>a-z</literal>), digits
1040  (<literal>0-9</literal>), plus (<literal>+</literal>) and minus  (<literal>0-9</literal>), plus (<literal>+</literal>) and minus
1041  (<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be  (<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be
1042  at least two characters long and must start with an alphanumeric character.  at least two characters long, must start with an alphanumeric character, and
1043  It is good idea to keep its length below 32 characters and should not exceed  must not be the same as existing ones.
1044    It is good idea to keep its length within 30 characters and should not exceed
1045  40 characters.  40 characters.
1046  </para>  </para>
1047  <!--  <!--
# Line 1049  Osamu's archive stat (2011-04-23, sid, k Line 1054  Osamu's archive stat (2011-04-23, sid, k
1054  41 12 99.9%    99.9%  41 12 99.9%    99.9%
1055  52 1 100.0%  52 1 100.0%
1056  Previous 20 chars is becoming too short for 17% of packages  Previous 20 chars is becoming too short for 17% of packages
1057    Default aptitude setting display up to 30 chars (98.3%).
1058  -->  -->
1059  <para>  <para>
1060    If upstream source uses generic words such as <literal>test-suite</literal> as
1061    its name, it is good idea to rename it not to contaminate name space for the
1062    package name and to identify its contents explicitly.
1063    <footnote><para>If you follow the
1064    <ulink url="&devref-newpackage;">Developer's Reference 5.1. 'New packages'</ulink>,
1065    the ITP process will usually catch this kind of issues.</para></footnote>.
1066    </para>
1067    <para>
1068  You should choose the <emphasis role="strong">upstream version</emphasis>  You should choose the <emphasis role="strong">upstream version</emphasis>
1069  which consists only of  to consist only of
1070  alphanumerics (<literal>a-zA-Z0-9</literal>), plus (<literal>+</literal>),  alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),
1071  tilde (<literal>~</literal>), and periods (<literal>.</literal>). It must  tilde (<literal>~</literal>), and periods (<literal>.</literal>). It must
1072  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
1073  rule should help you avoid confusing file names.</para></footnote>  rule should help you avoid confusing file names.</para></footnote>
1074  </para>  It is good idea to keep its length within 8 characters if possible.
 <para>  
 It is good idea to keep its length below 20 characters.  
1075  </para>  </para>
1076  <!--  <!--
1077  === stat for version string length ===  Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
1078  7 8257 53.2%   50% median& mode  === stat for upstream version string length ===
1079  12 976 90.1%   90%  5 9765 60.2%  50% median and mode
1080  20 73 99.0%    99%  6 3765 73.3%
1081  30 3 99.9%     99.9%  7 2789 82.9%
1082  37 6 100.0%  8 1158 86.9%
1083    9 501 88.6%
1084    10 773 91.3%  90%
1085    18 55 99.1%   99%
1086    27 11 99.9%    99.9
1087    35 6 100.0%
1088    === stat for debian revision string length ===
1089    1 22556 83.3%  50% median and mode
1090    2 1106 87.2%
1091    3 1312 91.7%   90%
1092    4 2127 99.1%   99%
1093    7 14 99.9%     99.9%
1094    
1095  20 = 30 -10  aptitude display 10 = 8char for up + 1char (for -) + 1char for deb
1096  appended <emphasis role="strong">Debian revsion</emphasis> is usually few characters.  90chars as max for file name of binary debs (package+up+deb+arch+.deb)
1097  -->  -->
1098  <para>  <para>
1099  If the upstream software does not use version like <literal>2.30.32a</literal>  If the upstream software does not use normal version system like
1100  but use some kind of date such as <literal>09Oct23</literal> or random codename  <literal>2.30.32</literal> but uses some kind of date such as
1101  strings as version, make sure to convert it to the <literal>YYYYMMDD</literal>  <literal>09Oct23</literal>, a random codename string or a VCS hush value as a part
1102  format such as <literal>20110429</literal>.  This ensures that  of version, make sure to remove them from the
1103  <command>dpkg</command> properly sees later versions as  <emphasis role="strong">upstream version</emphasis>.  Such information can be
1104  upgrades.<footnote><para> Version strings can be compared with  recorded in the <filename>debian/changelog</filename> file.  If you need to
1105  <literal>dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable></literal>.  invent a version string, use the <literal>YYYYMMDD</literal> format such as
1106  See <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.</para></footnote>  <literal>20110429</literal> as upstream version.  This ensures that
1107    <command>dpkg</command> properly sees later versions as upgrades.
1108    </para>
1109    <para>
1110    Version strings can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.
1111    </para>
1112    <screen>
1113     $ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
1114    </screen>
1115    <para>
1116    The version comparison rule can be summarized as the folowing.
1117    </para>
1118    <itemizedlist>
1119    <listitem><para>The strings are compared from the head to the tail.</para></listitem>
1120    <listitem><para>Alphabets are larger than numbers.</para></listitem>
1121    <listitem><para>Numbers are compared as the integer.</para></listitem>
1122    <listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>
1123    <listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tilde (<literal>~</literal>) as the followings.</para>
1124      <para>
1125      <literal>0.0</literal> &lt;
1126      <literal>0.5</literal> &lt;
1127      <literal>0.10</literal> &lt;
1128      <literal>0.99</literal> &lt;
1129      <literal>1</literal> &lt;
1130      <literal>1.0~rc1</literal> &lt;
1131      <literal>1.0</literal> &lt;
1132      <literal>1.0+b1</literal> &lt;
1133      <literal>1.0+nmu1</literal> &lt;
1134      <literal>1.1</literal> &lt;
1135      <literal>2.0</literal>
1136      </para>
1137    </listitem>
1138    </itemizedlist>
1139    <para>
1140    One of the tricky case happens when the upstream releases
1141    <filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
1142    pre-release of <filename>gentoo-0.9.12.tar.gz</filename>.  You need to make
1143    sure that the upgrade works properly by renaming the upstream source to
1144    <filename>gentoo-0.9.12~rc99.tar.gz</filename>.
1145  </para>  </para>
1146  </section>  </section>
1147  <section id="dh-make"><title>Initial Debian package</title>  <section id="dh-make"><title>Initial Debian package</title>
# Line 1121  provided by the upstream for your Debian Line 1182  provided by the upstream for your Debian
1182  </para>  </para>
1183  <para>  <para>
1184  You should see some output asking you what sort of package you want  You should see some output asking you what sort of package you want
1185  to create.  Gentoo is a single binary package - it creates only one binary, and  to create.  Gentoo is a single-binary package - it creates only one binary package, i.e,
1186  thus one <filename>.deb</filename> file - so we will select the first option  one <filename>.deb</filename> file - so we will select the first option
1187  (with the <literal>s</literal> key), check the information on the screen, and  (with the <literal>s</literal> key), check the information on the screen, and
1188  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
1189  <footnote><para> There are several choices here: <literal>s</literal> for Single  <footnote><para> There are several choices here: <literal>s</literal> for
1190  binary, <literal>i</literal> for arch-Independent, <literal>m</literal> for  Single-binary package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for
1191  Multiple binary, <literal>l</literal> for Library, <literal>k</literal> for  Multiple-binary packages, <literal>l</literal> for Library package, <literal>k</literal> for
1192  Kernel module, <literal>n</literal> for kernel patch, and <literal>b</literal>  Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>
1193  for <systemitem role="package">cdbs</systemitem>.  This document focuses on the  for <systemitem role="package">cdbs</systemitem> package.  This document focuses on the
1194  use of the <command>dh</command> command (from the package  use of the <command>dh</command> command (from the package
1195  <systemitem role="package">debhelper</systemitem>) to create a single-binary package,  <systemitem role="package">debhelper</systemitem>) to create a single-binary package,
1196  but also touches on how to use it for arch-independent or  but also touches on how to use it for arch-independent or
# Line 1185  packages, e.g.: Line 1246  packages, e.g.:
1246  <itemizedlist>  <itemizedlist>
1247  <listitem>  <listitem>
1248  <para>  <para>
1249  multiple binary packages;  multiple-binary packages;
1250  </para>  </para>
1251  </listitem>  </listitem>
1252  <listitem>  <listitem>
# Line 1414  from the <command>dh_auto_configure</com Line 1475  from the <command>dh_auto_configure</com
1475  options including <literal>--prefix=/usr</literal>.  </para> </footnote>:  options including <literal>--prefix=/usr</literal>.  </para> </footnote>:
1476  </para>  </para>
1477  <screen>  <screen>
1478  # Where to put binary on 'make install'?  # Where to put binary executables on 'make install'?
1479  BIN     = /usr/local/bin  BIN     = /usr/local/bin
1480  # Where to put icons on 'make install'?  # Where to put icons on 'make install'?
1481  ICONS   = /usr/local/share/gentoo  ICONS   = /usr/local/share/gentoo
# Line 1425  As explained above, that directory hiera Line 1486  As explained above, that directory hiera
1486  Debian, so change those paths to:  Debian, so change those paths to:
1487  </para>  </para>
1488  <screen>  <screen>
1489  # Where to put binary on 'make install'?  # Where to put binary executables on 'make install'?
1490  BIN     = $(DESTDIR)/usr/bin  BIN     = $(DESTDIR)/usr/bin
1491  # Where to put icons on 'make install'?  # Where to put icons on 'make install'?
1492  ICONS   = $(DESTDIR)/usr/share/gentoo  ICONS   = $(DESTDIR)/usr/share/gentoo
# Line 1437  documentation, etc. are specified in the Line 1498  documentation, etc. are specified in the
1498  your package.  your package.
1499  </para>  </para>
1500  <para>  <para>
1501  So, we should install the binary in <filename>/usr/bin</filename> instead of  So, we should install binary executables in <filename>/usr/bin</filename> instead of
1502  <filename>/usr/local/bin</filename>, the manual page in  <filename>/usr/local/bin</filename>, the manual page in
1503  <filename>/usr/share/man/man1</filename> instead of  <filename>/usr/share/man/man1</filename> instead of
1504  <filename>/usr/local/man/man1</filename>, and so on.  Notice how there's no manual  <filename>/usr/local/man/man1</filename>, and so on.  Notice how there's no manual
# Line 1726  Build-Conflicts-Indep'</ulink>.</para></ Line 1787  Build-Conflicts-Indep'</ulink>.</para></
1787  <systemitem role="package">build-essential</systemitem> package are implied.  If you need  <systemitem role="package">build-essential</systemitem> package are implied.  If you need
1788  to have other tools to build your package, you should add them to these fields.  to have other tools to build your package, you should add them to these fields.
1789  Multiple entries are separated with commas; read on for the explanation of  Multiple entries are separated with commas; read on for the explanation of
1790  binary dependencies to find out more about the syntax of these lines.  binary package dependencies to find out more about the syntax of these lines.
1791  </para>  </para>
1792  <itemizedlist>  <itemizedlist>
1793  <listitem>  <listitem>
# Line 3245  the <filename>docs</filename> file and n Line 3306  the <filename>docs</filename> file and n
3306  This <filename>install</filename> file has one line per file installed, with  This <filename>install</filename> file has one line per file installed, with
3307  the name of the file (relative to the top build directory) then a space then  the name of the file (relative to the top build directory) then a space then
3308  the installation directory (relative to the install directory).  One example of  the installation directory (relative to the install directory).  One example of
3309  where this is used is where a binary is forgotten to be installed, the  this is when a binary executable is forgotten to be installed, the
3310  <filename>install</filename> file would look like:  <filename>install</filename> file would look like:
3311  </para>  </para>
3312  <screen>  <screen>
3313  src/foo/mybin usr/bin  src/foo/mybin usr/bin
3314  </screen>  </screen>
3315  <para>  <para>
3316  This will mean when this package is installed, there will be a binary file  This will mean when this package is installed, there will be a binary executable
3317  <filename>/usr/bin/mybin</filename>.  <filename>/usr/bin/mybin</filename>.
3318  </para>  </para>
3319  <para>  <para>
# Line 3648  summary information concerning the switc Line 3709  summary information concerning the switc
3709  <filename>debian.tar.gz</filename> archive containing all files under the  <filename>debian.tar.gz</filename> archive containing all files under the
3710  <filename>debian</filename> directory.  This new format supports inclusion of  <filename>debian</filename> directory.  This new format supports inclusion of
3711  binary files such as PNG icons by the package maintainer without requiring  binary files such as PNG icons by the package maintainer without requiring
3712  tricks.  <footnote><para> Actually, this new format also supports multiple  tricks.  <footnote><para>Actually, this new format also supports multiple
3713  upstream tarballs and more compression methods.  These are beyond the scope of  upstream tarballs and more compression methods.  These are beyond the scope of
3714  this document.  </para> </footnote>  this document.</para> </footnote>
3715  </para>  </para>
3716  <para>  <para>
3717  When <command>dpkg-source</command> extracts a source package in <literal>3.0  When <command>dpkg-source</command> extracts a source package in <literal>3.0
Legend:
Removed from v.8717  
changed lines
  Added in v.8719
  ViewVC Help
Powered by ViewVC 1.1.5