>From 5950633d23c69cf84200409f2f5354901ecb7933 Mon Sep 17 00:00:00 2001
From: Ken Brown <kbrown@cornell.edu>
Date: Mon, 19 Sep 2016 11:30:34 -0400
Subject: [PATCH] Add information about perpetual postinstall scripts

Also mention ".dash" and ".cmd" suffixes.
---
 packaging-package-files.html | 39 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 34 insertions(+), 5 deletions(-)

diff --git a/packaging-package-files.html b/packaging-package-files.html
index fdf7fdc..e5db8c5 100755
--- a/packaging-package-files.html
+++ b/packaging-package-files.html
@@ -160,13 +160,17 @@ etc...
 <p>
   If your package requires certain commands to be executed after the files in
   the package are installed, include them in a file in the package called
-  /etc/postinstall/<var>package</var>.sh or
-  /etc/postinstall/<var>package</var>.bat.
+  /etc/postinstall/<var>package</var>.sh,
+  /etc/postinstall/<var>package</var>.dash,
+  /etc/postinstall/<var>package</var>.bat, or
+  /etc/postinstall/<var>package</var>.cmd.
 </p>
 <p>
-  If the file's name ends in ".sh", it is executed with the Cygwin shell; if it
-  ends in ".bat", it is executed with the DOS command interpreter. If it doesn't
-  end with either of these suffixes, it is ignored.
+  If the file's name ends in ".sh", it is executed with the Cygwin
+  bash shell; if it ends in ".dash", it is executed with the Cygwin
+  dash shell; if it ends in ".bat" or ".cmd", it is executed with the
+  Windows command interpreter. If it doesn't end with any of these
+  suffixes, it is ignored.
 </p>
 <p>
   After the script has been successfully run it is renamed by appending the
@@ -183,6 +187,31 @@ etc...
   scripts have already been run.
 </p>
 
+<h2>Perpetual postinstall scripts</h2>
+<p>
+  In addition to the ordinary ("run-once") postinstall scripts
+  described above, the setup program supports "perpetual" postinstall
+  scripts.  These are run on every invocation of setup and do not have
+  ".done" appended to their names after they are run.  Perpetual
+  postinstall scripts are distinguished from run-once scripts by
+  having names that start with "0p_" or "zp_".  Those that start with
+  "0p_" are run before the run-once scripts, and those that start with
+  "zp_" are run after the run-once scripts.  Examples include
+  0p_000_autorebase.dash (provided by the _autorebase package) and
+  0p_update-info-dir.dash (provided by the info package).
+</p>
+<p>
+  For those package maintainers wanting to employ perpetual scripts,
+  the first thing to keep in mind is to only use this feature for
+  things that really can't be done with run-once scripting.  Any
+  perpetual script should minimize the resources used (use dash
+  instead of bash for instance) and exit at the earliest possible
+  moment if no action is required.  Scripts of type "0p_" must be able
+  to run with the Base packages installed but the postinstall scripts
+  not yet executed; in practical terms that rules out using bash
+  scripts.  This limitation does not apply to scripts of type "zp_".
+</p>
+
 </div>
 </body>
 </html>
-- 
2.8.3