Sec "Best practices for maintainer scripts" added, special credit here

to Charles Briscoe-Smith for work dating back to 1998; include a POSIX
shell snippet showing how to check if a command is the PATH, closes:
#150384

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1964 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/common.ent b/common.ent
index 341e8753e17d98a8923cdc777782defe35b20ac8..1380d83a49302eaedd9c7926669f622544e83784 100644 (file)
--- a/common.ent
+++ b/common.ent
@@ -240,3 +240,16 @@ pool/non-free/n/
 pool/non-free/n/netscape/
      ...
 </example>">
 pool/non-free/n/netscape/
      ...
 </example>">

+
+<!entity example-pathfind '<example>pathfind() {
+    OLDIFS="$IFS"
+    IFS=:
+    for p in $PATH; do
+        if [ -x "$p/$*" ]; then
+            IFS="$OLDIFS"
+            return 0
+        fi
+    done
+    IFS="$OLDIFS"
+    return 1
+}</example>'>

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 26d0bcb2f0386a5a8a75cc970f3afbd8b04c745f..62ae0f14b24cdc5afd92b125cab087a9f5f97914 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->

-  <!entity cvs-rev "$Revision: 1.147 $">
+  <!entity cvs-rev "$Revision: 1.148 $">

   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--


@@ -2050,7 +2050,7 @@ basis as co-maintainer or backup maintainer
 (see <ref id="collaborative-maint">).
 
 
 (see <ref id="collaborative-maint">).
 
 

-    <sect id="porting">Porting and Being Ported
+    <sect id="porting">Porting and being ported

       <p>
 Debian supports an ever-increasing number of architectures.  Even if
 you are not a porter, and you don't use any architecture but one, it
       <p>
 Debian supports an ever-increasing number of architectures.  Even if
 you are not a porter, and you don't use any architecture but one, it


@@ -2338,8 +2338,8 @@ should subscribe themselves to the appropriate source package.</p>
       </sect>
 
     <sect id="archive-manip">
       </sect>
 
     <sect id="archive-manip">

-      <heading>Moving, Removing, Renaming, Adopting, and Orphaning
-      Packages</heading>
+      <heading>Moving, removing, renaming, adopting, and orphaning
+      packages</heading>

       <p>
 Some archive manipulation operations are not automated in the Debian
 upload process.  These procedures should be manually followed by
       <p>
 Some archive manipulation operations are not automated in the Debian
 upload process.  These procedures should be manually followed by


@@ -2922,7 +2922,7 @@ from Debian developers.  Feel free to pick and choose whatever works
 best for you.
 
     <sect id="bpp-debian-rules">
 best for you.
 
     <sect id="bpp-debian-rules">

-        <heading>Best Practices for <file>debian/rules</file></heading>
+        <heading>Best practices for <file>debian/rules</file></heading>

         <p>
 The following recommendations apply to the <file>debian/rules</file>
 file.  Since <file>debian/rules</file> controls the build process and
         <p>
 The following recommendations apply to the <file>debian/rules</file>
 file.  Since <file>debian/rules</file> controls the build process and


@@ -3027,6 +3027,62 @@ this using an hand-crafted <file>debian/rules</file> file.
         </sect1>
       </sect>
 
         </sect1>
       </sect>
 

+    <sect id="bpp-debian-maint-scripts">
+        <heading>Best practices for maintainer scripts</heading>
+        <p>
+Maintainer scripts include the files <file>debian/postinst</file>,
+<file>debian/preinst</file>, <file>debian/prerm</file> and
+<file>debian/postrm</file>.  These scripts take care of any package
+installation or deinstallation setup which isn't handled merely by the
+creation or removal of files and directories.  The following
+instructions supplement the <url id="&url-debian-policy;" name="Debian
+Policy">.
+        <p>
+Maintainer scripts must be idempotent.  That means that you need to
+make sure nothing bad will happen if the script is called twice where
+it would usually be called once.
+        <p>
+Standard input and output may be redirected (e.g. into pipes) for
+logging purposes, so don't rely on them being a tty.
+        <p>
+All prompting or interactive configuration should be kept to a
+minimum.  When it is necessary, you should use the
+<package>debconf</package> package for the interface.  Remember that
+prompting in any case can only be in the <tt>configure</tt> stage of
+the <file>postinst</file> script.
+        <p>
+Keep the maintainer scripts as simple as possible.  We suggest you use
+pure POSIX shell scripts.  Remember, if you do need any bash features,
+the maintainer script must have a bash shbang line.  Posix shell or
+Bash are preferred to Perl, since they enable
+<package>debhelper</package> to easily add bits to the scripts.
+        <p>
+If you change your maintainer scripts, be sure to test package
+removal, double installation, and purging.  Be sure that a purged
+package is completely gone, that is, it must remove any files created,
+directly or indirectly, in any maintainer script.
+        <p>
+If you need to check for the existance of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hardcode the path of the command in your
+maintainer script, the following POSIX-compliant shell function may
+help:
+
+&example-pathfind;
+
+You can use this function to search <tt>$PATH</tt> for a command name,
+passed as an argument.  It returns true (zero) if the command was
+found, and false if not.  This is really the most portable way, since
+<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
+POSIX.  While <prgn>which</prgn> is an acceptable alternative, since
+it is from the required <package>debianutils</package> package, it's
+not on the root partition, although that is probably not something
+that will cause a problem.
+
+
+

 <!--
        <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
        <p>
 <!--
        <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
        <p>


@@ -3243,7 +3299,7 @@ members in choosing what they want to work on and in choosing
 the most critical thing to spend their time on.
 
     <sect id="submit-bug">
 the most critical thing to spend their time on.
 
     <sect id="submit-bug">

-        <heading>Bug Reporting</heading>
+        <heading>Bug reporting</heading>

         <p>
 We encourage you to file bugs as you find them in Debian packages.  In
 fact, Debian developers are often the first line testers.  Finding and
         <p>
 We encourage you to file bugs as you find them in Debian packages.  In
 fact, Debian developers are often the first line testers.  Finding and


@@ -3305,7 +3361,7 @@ in order to catch up the backlog of bugs that you have (you can ask
 for help on &email-debian-qa; or &email-debian-devel;). At the same
 time, you can look for co-maintainers (see <ref id="collaborative-maint">).
        
 for help on &email-debian-qa; or &email-debian-devel;). At the same
 time, you can look for co-maintainers (see <ref id="collaborative-maint">).
        

-       <sect1 id="qa-bsp">Bug Squashing Parties
+       <sect1 id="qa-bsp">Bug squashing parties

        <p>
 From time to time the QA group organizes bug squashing parties to get rid of
 as many problems as possible. They are announced on &email-debian-devel-announce;
        <p>
 From time to time the QA group organizes bug squashing parties to get rid of
 as many problems as possible. They are announced on &email-debian-devel-announce;