Re: Updated maint-guide contents, question on style
Chapter 3.
A patch-management system is a relatively easy piece of unfamiliar
developer toolchain to learn, but the setup in 3.1 seems strangely
elaborate - why set up a .bashrc alias that calls quilt via a special
config so quilt will check an obscure conditional and put some
variables in its environment... when you could save a couple of steps
with a dquilt function or wrapper script? Or come to that, if I
installed quilt to use it for Debian packages, why not just modify
~/.quiltrc?
3.3 states the rule against installing to /usr/local twice, once in
its first paragraph and again after the example Makefile snippets.
I've trimmed the second one to a reminder.
And I've tweaked the use of grep, and made the sed expression actually
use sed rather than vim emulating sed - that is:
-$ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
+$ grep -nr --include='*.[c|h]' usr/local/lib .
and
-$ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \
+$ sed -i s#usr/local/lib#usr/lib#g \
$(find . -type f -name '*.[c|h]')
3.4 (and footnote): given that readers have no reason to expect
"-lcurses" to cause any particular kind of problem, and given that as
a matter of fact it doesn't, wouldn't it be simplest to say "-lfoo"
and then explicitly state that the problem is that on Debian libfoo is
known as libfoobar?
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- maint-guide.en.dbk.pristine 2011-04-17 14:35:41.052916002 +0100
+++ maint-guide.en.dbk 2011-04-22 10:49:22.289258808 +0100
@@ -1178,12 +1178,13 @@
details of fixing upstream sources, but here are some basic steps and problems
people often run across.
</para>
-<section id="quiltrc"><title>Set up <command>quilt</command></title>
+<section id="quiltrc"><title>Setting up <command>quilt</command></title>
<para>
-The <command>quilt</command> program offers the basic method to record
-modification to the source for the Debian packaging. Since slightly different
-default is desirable, let's create an alias <command>dquilt</command> for
-Debian packaging by adding the following line to <filename>~/.bashrc</filename>.
+The program <command>quilt</command> offers a basic method for recording
+modifications to the upstream source for Debian packaging. It's
+useful to have a slightly customized default, so let's create an alias
+<command>dquilt</command> for Debian packaging by adding the following
+line to <filename>~/.bashrc</filename>.
</para>
<screen>
alias dquilt=quilt --quiltrc=~/.quiltrc-dpkg
@@ -1194,7 +1195,7 @@
<screen>
d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done
if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then
- # Debian packaging case and unset $QUILT_PATCHES
+ # if in Debian packaging tree with unset $QUILT_PATCHES
QUILT_PATCHES="debian/patches"
QUILT_PATCH_OPTS="--reject-format=unified"
QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
@@ -1206,14 +1207,14 @@
<para>
See <citerefentry> <refentrytitle>quilt</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> and
-<ulink url="&quilt-pdf;">quilt.pdf</ulink> for how to use
+<ulink url="&quilt-pdf;">quilt.pdf</ulink> on how to use
<command>quilt</command>.
</para>
</section>
-<section id="fixupstream"><title>Fixing upstream bug</title>
+<section id="fixupstream"><title>Fixing upstream bugs</title>
<para>
Let's assume you find an error in the upstream <filename>Makefile</filename>
-file as follows where <literal>install: gentoo</literal> should have been
+as follows where <literal>install: gentoo</literal> should have been
<literal>install: gentoo-target</literal>.
</para>
<screen>
@@ -1223,11 +1224,11 @@
install gentoorc-example $(HOME)/.gentoorc
</screen>
<para>
-Let's fix this and record this with the <command>dquilt</command> command as
+Let's fix this and record it with the <command>dquilt</command> command as
<filename>fix-gentoo-target.patch</filename>. <footnote><para> The
-<filename>debian/patches</filename> directory should exist now if you run
+<filename>debian/patches</filename> directory should exist now if you ran
<command>dh_make</command> as described before. This example operation creates
-it just in case you are updating the existing package. </para> </footnote>
+it just in case you are updating an existing package. </para> </footnote>
</para>
<screen>
$ mkdir debian/patches
@@ -1244,7 +1245,7 @@
install gentoorc-example $(HOME)/.gentoorc
</screen>
<para>
-Ask <command>dquilt</command> to refresh the patch to create
+Ask <command>dquilt</command> to generate the patch to create
<filename>debian/patches/fix-gentoo-target.patch</filename> and add its
description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.
</para>
@@ -1254,95 +1255,103 @@
... describe patch
</screen>
</section>
-
-<section id="destdir"><title>Installation of files to the destination</title>
+<section id="destdir"><title>Installation of files to their destination</title>
<para>
-Normally, programs install themselves in the <filename>/usr/local</filename>
-subdirectory. Since it is reserved for system administrator's (or user's)
-private use, Debian packages must not use that directory but should use system
-directories such as the <filename>/usr/bin</filename> subdirectory following
-the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).
+Most third-party software installs itself in the <filename>/usr/local</filename>
+directory hierarchy. On Debian this is reserved for private use
+by the system administrator, so packages must not use directories such
+as <filename>/usr/local/bin</filename> but should instead use system
+directories such as <filename>/usr/bin</filename>, obeying the
+<ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).
</para>
<para>
Normally, <citerefentry> <refentrytitle>make</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> is used to automate building the
-program and the execution of <literal>make install</literal> installs programs
-directly to the desired destination by the <literal>install</literal> target of
-the <filename>Makefile</filename> file. In order for Debian to provide binary
-packages, the build system installs programs to the file tree image created
-under a temporary directory instead to the actual destination.
+program, and executing <literal>make install</literal> installs programs
+directly to the desired destination (following the
+<literal>install</literal> target in the
+<filename>Makefile</filename>). In order for Debian to provide
+pre-built installable packages, it modifies the build system to install
+programs into a file tree image created under a temporary directory
+instead of the actual destination.
</para>
<para>
-These 2 differences between (1) the normal program installation and (2) the
-Debian packaging can be transparently addressed by the <systemitem role="package">debhelper</systemitem> package through the
+These two differences between normal program installation on one hand and the
+Debian packaging system on the other can be transparently addressed by the
+<systemitem role="package">debhelper</systemitem> package through the
<command>dh_auto_configure</command> and <command>dh_auto_install</command>
commands if the following conditions are met.
</para>
<itemizedlist>
<listitem>
<para>
-The <filename>Makefile</filename> file follows the GNU conventions to support
-<literal>$(DESTDIR)</literal> variable.
+The <filename>Makefile</filename> must follow GNU conventions and
+support the <literal>$(DESTDIR)</literal> variable.
<footnote><para> See <ulink url="&gnu-destdir;">GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs</ulink>.</para></footnote>
</para>
</listitem>
<listitem>
<para>
-The source follows the Filesystem Hierarchy Standard (FHS).
+The source must follow the Filesystem Hierarchy Standard (FHS).
</para>
</listitem>
</itemizedlist>
<para>
-Programs that use GNU <command>autoconf</command>
-<emphasis>automatically</emphasis> follow the GNU conventions and their
-packaging is almost <emphasis>automatic</emphasis>. With this and other
-heuristics, the <systemitem role="package">debhelper</systemitem> package
-estimates that it works for about 90% of packages without making any intrusive
-changes to their build system. So the packaging is not as complicated as it
-may seem.
-</para>
-<para>
-If you need to make changes in the <filename>Makefile</filename> file, you
-should make sure to support these <literal>$(DESTDIR)</literal> variable. The
-<literal>$(DESTDIR)</literal> variable is unset in it and is prepended to each
-file path used for the program installation. The packaging script will set
-<literal>$(DESTDIR)</literal> to the temporary directory.
-</para>
-<para>
-The temporary directory used by the <command>dh_auto_install</command> command
-is chosen as <filename>debian/<replaceable>package</replaceable></filename> for
-single binary packages. <footnote><para> For multiple binary packages, the
+Programs that use GNU <command>autoconf</command> follow the GNU conventions
+automatically, so they can be trivial to package. On the basis of
+this and other heuristics, it is estimated that the
+<systemitem role="package">debhelper</systemitem> package will work for
+about 90% of packages without making any intrusive changes to their
+build system. So packaging is not as complicated as it may seem.
+</para>
+<para>
+If you need to make changes in the <filename>Makefile</filename>, you
+should be careful to support the <literal>$(DESTDIR)</literal>
+variable. Although it is unset by default, the <literal>$(DESTDIR)</literal>
+variable is prepended to each file path used for the program
+installation. The packaging script will set
+<literal>$(DESTDIR)</literal> to the temporary directory.
+</para>
+<para>
+For packages of the single-binary type, the temporary directory used
+by the <command>dh_auto_install</command> command will be set to
+<filename>debian/<replaceable>package</replaceable></filename>.
+<footnote><para> For packages of the multiple-binary type, the
<command>dh_auto_install</command> command uses <filename>debian/tmp</filename>
as the temporary directory while the <command>dh_install</command> command with
the help of
<filename>debian/<replaceable>package-1</replaceable>.install</filename> and
<filename>debian/<replaceable>package-2</replaceable>.install</filename> files
-will split contents of <filename>debian/tmp</filename> into
+will split the contents of <filename>debian/tmp</filename> into
<filename>debian/<replaceable>package-1</replaceable></filename> and
<filename>debian/<replaceable>package-2</replaceable></filename> temporary
-directories to create multiple binary <filename>*.deb</filename> packages.
+directories, to create
+<filename><replaceable>package-1</replaceable>_*.deb</filename> and
+<filename><replaceable>package-2</replaceable>_*.deb</filename> binary
+packages.
</para> </footnote> Everything that is contained in the temporary directory
-will be installed on a user's system when they install your package, the only
-difference is that <command>dpkg</command> will be installing the files in the
-root directory.
+will be installed on users' systems when they install your package; the only
+difference is that <command>dpkg</command> will be installing the
+files to paths relative to the root directory rather than your working
+directory.
</para>
<para>
Bear in mind that even though your program installs in
<filename>debian/<replaceable>package</replaceable></filename>, it still needs
-to behave correctly when placed in the root directory, i.e. when installed
-from the <filename>.deb</filename> package. So you must not allow the build
+to behave correctly when installed from the <filename>.deb</filename>
+package under the root directory. So you must not allow the build
system to hardcode strings like
<literal>/home/me/deb/<replaceable>package</replaceable>-<replaceable>version</replaceable>/usr/share/<replaceable>package</replaceable></literal>
-into the package file.
+into files in the package.
</para>
<para>
Here's the relevant part of <systemitem role="package">gentoo</systemitem>'s
-<filename>Makefile</filename> file <footnote><para> This is just an example to
-show how the <filename>Makefile</filename> file should look like. If the
-<filename>Makefile</filename> file is created by the
+<filename>Makefile</filename><footnote><para> This is just an example to
+show what a <filename>Makefile</filename> should look like. If the
+<filename>Makefile</filename> is created by the
<command>./configure</command> command, the correct way to fix this kind of
-<filename>Makefile</filename> is to executed the <command>./configure</command>
-command from the <command>dh_auto_configure</command> command with default
+<filename>Makefile</filename> is to execute <command>./configure</command>
+from the <command>dh_auto_configure</command> command with default
options including <literal>--prefix=/usr</literal>. </para> </footnote>:
</para>
<screen>
@@ -1353,7 +1362,8 @@
</screen>
<para>
We see that the files are set to install under <filename>/usr/local</filename>.
-Change those paths to:
+As explained above, that directory hierarchy is reserved for local use on
+Debian, so change those paths to:
</para>
<screen>
# Where to put binary on 'make install'?
@@ -1362,23 +1372,18 @@
ICONS = $(DESTDIR)/usr/share/gentoo
</screen>
<para>
-But why in that directory, and not some other? Because Debian packages never
-install files beneath <filename>/usr/local</filename> -- that tree is reserved
-for the system administrator's use. Such files on Debian systems go under
-<filename>/usr</filename> instead.
-</para>
-<para>
-The more exact locations for binaries, icons, documentation etc. are specified
-in the Filesystem Hierarchy Standard (FHS). I recommend you
-browse it and read the sections that might concern your package.
+The exact locations that should be used for binaries, icons,
+documentation, etc. are specified in the Filesystem Hierarchy Standard
+(FHS). You should browse through it and read the sections relevant to
+your package.
</para>
<para>
So, we should install the binary in <filename>/usr/bin</filename> instead of
<filename>/usr/local/bin</filename>, the manual page in
<filename>/usr/share/man/man1</filename> instead of
-<filename>/usr/local/man/man1</filename> etc. Notice how there's no manual
+<filename>/usr/local/man/man1</filename>, and so on. Notice how there's no manual
page mentioned in <systemitem role="package">gentoo</systemitem>'s
-<filename>Makefile</filename>, but since the Debian Policy requires that every
+<filename>Makefile</filename>, but since Debian Policy requires that every
program has one, we'll make one later and install it in
<filename>/usr/share/man/man1</filename>.
</para>
@@ -1389,7 +1394,7 @@
for? You can find this out by issuing:
</para>
<screen>
-$ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
+$ grep -nr --include='*.[c|h]' usr/local/lib .
</screen>
<para>
<command>grep</command> will run recursively through the source tree and tell
@@ -1400,20 +1405,17 @@
with <literal>usr/lib</literal>. This can be done automatically as follows:
</para>
<screen>
-$ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \
+$ sed -i s#usr/local/lib#usr/lib#g \
$(find . -type f -name '*.[c|h]')
</screen>
<para>
-Be careful that you don't mess up the rest of the code! :-)
-</para>
-<para>
-After that you should find the install target (search for line that starts with
-<literal>install:</literal>, that will usually work) and rename all references
-to directories other than ones defined at the top of the
-<filename>Makefile</filename>.
+Next you should find the <literal>install</literal> target (searching
+for the line that starts with <literal>install:</literal> will usually
+work) and rename all references to directories other than ones defined
+at the top of the <filename>Makefile</filename>.
</para>
<para>
-Before your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s
+Originally, <systemitem role="package">gentoo</systemitem>'s
install target said:
</para>
<screen>
@@ -1423,7 +1425,7 @@
install gentoorc-example $(HOME)/.gentoorc
</screen>
<para>
-Let's fix this and record this with the <command>dquilt</command> command as
+Let's fix this upstream bug and record it with the <command>dquilt</command> command as
<filename>debian/patches/install.patch</filename>.
</para>
<screen>
@@ -1431,7 +1433,7 @@
$ dquilt add Makefile
</screen>
<para>
-Let's change this for Debian package as following using the editor:
+In your editor, change this for the Debian package as follows:
</para>
<screen>
install: gentoo-target
@@ -1441,12 +1443,12 @@
install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
</screen>
<para>
-You've surely noticed that there's now a <literal>install -d</literal> command
+You'll have noticed that there's now an <literal>install -d</literal> command
before the other commands in the rule. The original
-<filename>Makefile</filename> didn't have it because usually the
+<filename>Makefile</filename> didn't have it because usually
<literal>/usr/local/bin</literal> and other directories already exist on the
-system where one runs <literal>make install</literal>. However, since we will
-install into our own empty (or even nonexistent) directory, we will have to
+system where you are running <literal>make install</literal>. However, since we will
+be installing into a newly created private directory tree, we will have to
create each and every one of those directories.
</para>
<para>
@@ -1458,8 +1460,8 @@
cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html
</screen>
<para>
-After careful check, if everything is fine, ask <command>dquilt</command> to
-refresh the patch to create <filename>debian/patches/install.patch</filename>
+Check carefully, and if everything is okay, ask <command>dquilt</command> to
+generate the patch to create <filename>debian/patches/install.patch</filename>
and add its description.
</para>
<screen>
@@ -1487,9 +1489,9 @@
Whenever you make changes that are not specifically related to Debian package
such as <filename>debian/patches/fix-gentoo-target.patch</filename>, be sure to
send them to the upstream maintainer so they can be included in the next
-program revision and be useful to everyone else. Also remember to make your
-fixes not specific to Debian or Linux (or even Unix!) prior to sending them --
-make them portable. This will make your fixes much easier to apply.
+revision of the program and be useful to everyone else. Also remember
+to avoid making your fixes specific to Debian or Linux - or even Unix!
+Make them portable. This will make your fixes much easier to apply.
</para>
<para>
Note that you don't have to send the <filename>debian/*</filename> files
@@ -1516,13 +1518,13 @@
LIBS = -lcurses -lsomething -lsomethingelse
</screen>
<para>
-Let's fix this as <filename>debian/patches/ncurse.patch</filename> by changing
+Let's fix this as <filename>debian/patches/ncurses.patch</filename> by changing
<literal>curses</literal> into <literal>ncurses</literal>.
</para>
<screen>
-$ dquilt new ncurse.patch
+$ dquilt new ncurses.patch
$ dquilt add Makefile
-$ sed -i -e s/-lcurses/-lncurses/g Makefile
+$ sed -i s/-lcurses/-lncurses/g Makefile
$ dquilt refresh
$ dquilt header -e
... describe patch
Reply to: