Make it possible to have separate install scripts as well as have

an on-delete script.

Submitted by:	Rajesh Vaidheeswarran <rv@fore.com>

1 files changed, 65 insertions, 8 deletions

diff --git a/usr.sbin/pkg_install/delete/pkg_delete.1 b/usr.sbin/pkg_install/delete/pkg_delete.1
index 31888e7..8307525 100644
--- a/usr.sbin/pkg_install/delete/pkg_delete.1
+++ b/usr.sbin/pkg_install/delete/pkg_delete.1
@@ -47,9 +47,9 @@ You are advised to verify the competence and identity of those who
 provide installable package files.  For extra protection, examine all
 the package control files in the package record directory (
 .Pa /var/db/pkg/<pkg-name>/ ).
-Pay particular
-attention to any +INSTALL, +DEINSTALL, +REQUIRE or +MTREE_DIRS files,
-and inspect the +CONTENTS file for
+Pay particular attention to any +INSTALL, +POST-INSTALL, +DEINSTALL,
++POST-DEINSTALL, +REQUIRE or +MTREE_DIRS files, and inspect the +CONTENTS
+file for
 .Cm @cwd ,
 .Cm @mode 
 (check for setuid),
@@ -97,7 +97,7 @@ deinstall or require script fails.
 
 .Pp
 .Sh TECHNICAL DETAILS
-.Nm Pkg_delete
+.Nm pkg_delete
 does pretty much what it says.  It examines installed package records in 
 .Pa /var/db/pkg/<pkg-name> ,
 deletes the package contents, and finally removes the package records.
@@ -140,14 +140,71 @@ The
 .Nm deinstall
 script is called as:
 .Bd -filled -offset indent -compact
-.Cm deinstall
+.Cm script
 .Ar <pkg-name>
 .Ar DEINSTALL
 .Ed
-Passing the keyword
+where
+.Ar pkg-name
+is the name of the package in question and
+.Ar DEINSTALL
+is a keyword denoting this as the pre-deinstallation phase.
+
+.Cm Note:
+The
 .Ar DEINSTALL
-lets you potentially write only one program/script that handles all
-aspects of installation and deletion.
+keyword will not appear if separate scripts for deinstall and post-deinstall
+are given during package creation time (using the
+.Cm Fl k
+and 
+.Cm Fl K
+flags to 
+.Xr pkg_create 1 ).
+.Pp
+If a
+.Cm post-deinstall
+script exists for the package, it is executed
+.Cm after
+all files are removed.  It is this script's responsibility to clean up any
+additional messy details around the package's installation, and leave the
+system (hopefully) in the same state that it was prior to the installation
+of the package.
+
+The
+.Nm post-deinstall
+script is called as:
+.Bd -filled -offset indent -compact
+.Cm script
+.Ar <pkg-name>
+.Ar POST-DEINSTALL
+.Ed
+where
+.Ar pkg-name
+is the name of the package in question and
+.Ar POST-DEINSTALL
+is a keyword denoting this as the post-deinstallation phase.
+
+.Cm Note:
+The
+.Ar POST-DEINSTALL
+keyword will not appear if separate scripts for deinstall and post-deinstall
+are given during package creation time (using the
+.Cm Fl k
+and 
+.Cm Fl K
+flags to 
+.Xr pkg_create 1 ).
+
+Reasoning behind passing keywords such as
+.Ar DEINSTALL
+and
+.Ar POST-DEINSTALL
+is that it lets you potentially write only one program/script that handles
+all aspects of installation and deletion.
+
+But experience has proved that this is a lot more difficult to maintain and
+is not as advantageous as having separate scripts that handle each aspect of
+installation and deinstallation.
 .Pp
 All scripts are called with the environment variable
 .Ev PKG_PREFIX