package kit: Add pre-uninstall scripts feature.

Just like post-install scripts which run shortly after a package is
installed, pre-uninstall scripts are run just before a package is
removed.  Implements enhancement #13427

* Fix script exit code handling vs script launch errors.
* Bump package and repo file version numbers due to new attribute,
  unfortunately makes new .hpkg files not backwards compatible.
* Add pre-uninstall functionality, mostly cloning the post-install
  except in a few places.
* Discover that _RunQueuedScripts() is never called, a future TODO:?
* Update package documentation for pre-uninstall scripts, and use of
  the boot/post-install directory.

Change-Id: I45596255ce74bc102f6e5b606cbf83e4e4347a17
Reviewed-on: https://review.haiku-os.org/c/haiku/+/1504
Reviewed-by: Alexander G. M. Smith <[email protected]>
Reviewed-by: Adrien Destugues <[email protected]>

docs/develop/packages/BuildingPackages.rst

@@ -178,7 +178,11 @@ The supported attributes are:
 - ``groups``: A list of names of Unix groups the packaged software requires.
 - ``post-install-scripts``: A list of paths of files included in the package,
   which shall be executed on package activation. Each path must start with
-  "boot/post-install/".
+  "boot/post-install/". All the files in that directory are also run on first
+  boot after installing or copying the OS to a new disk.
+- ``pre-uninstall-scripts``: A list of paths of files included in the package,
+  which shall be executed on package deactivation. For consistency, each path
+  should start with "boot/pre-uninstall/".
 
 Version Strings
 ---------------

docs/develop/packages/FileFormat.rst

@@ -87,7 +87,7 @@ total_size
 
 minor_version
   The minor version of the HPKG format the file conforms to. The current minor
-  version is 0 (B_HPKG_MINOR_VERSION). Additions of new attributes to the
+  version is 1 (B_HPKG_MINOR_VERSION). Additions of new attributes to the
   attributes or TOC sections should generally only increment the minor version.
   When a file with a greater minor version is encountered, the reader should
   ignore unknown attributes.
@@ -915,7 +915,18 @@ B_HPKG_ATTRIBUTE_ID_PACKAGE_POST_INSTALL_SCRIPT ("package:post-install-script")
   :Value: Relative path of a script that shall be executed after package
     activation.
   :Allowed Values: Installation location relative path of a file included in the
-    package.
+    package.  Must start with "boot/post-install/", so besides being run after
+    package installation, it also gets run on the first boot after the OS is
+    installed.
+  :Child Attributes: none
+
+B_HPKG_ATTRIBUTE_ID_PACKAGE_PRE_UNINSTALL_SCRIPT ("package:pre-uninstall-script")
+  :Type: string
+  :Value: Relative path of a script that shall be executed before package
+    deactivation.
+  :Allowed Values: Installation location relative path of a file included in
+    the package.  For consistency, it is recommended to start with
+    "boot/pre-uninstall/".
   :Child Attributes: none
 
 Haiku Package Repository Format
@@ -994,8 +1005,8 @@ total_size
 
 minor_version
   The minor version of the HPKR format the file conforms to. The current minor
-  version is 0 (B_HPKG_REPO_MINOR_VERSION). Additions of new attributes to the
-  attributes section shouldgenerally only increment the minor version. When a
+  version is 1 (B_HPKG_REPO_MINOR_VERSION). Additions of new attributes to the
+  attributes section should generally only increment the minor version. When a
   file with a greater minor version is encountered, the reader should ignore
   unknown attributes.
 

docs/develop/packages/PackagingPolicy.rst

@@ -127,7 +127,14 @@ Post-Installation Scripts
 =========================
 A package may include one or more post-installation scripts. The scripts are
 executed whenever the package is activated (for the first time, but also after
-package updates). They shall be placed in "boot/post-install" and declared
-explicitly by the package (via POST_INSTALL_SCRIPTS in the build recipe). A
-post-install script should be considered the last resort. It should only be
-used, if there's no reasonable alternative.
+package updates and first boot of a newly installed OS). They shall be placed
+in "boot/post-install" and declared explicitly by the package (via
+POST_INSTALL_SCRIPTS in the build recipe). A post-install script should be
+considered the last resort. It should only be used, if there's no reasonable
+alternative.  A typical use would be to create a desktop icon that the user
+can move around or delete.
+
+Pre-Uninstallation Scripts
+=========================
+These undo the effects of a post-installation script and usually are put
+into "boot/pre-uninstall".  A typical use is to remove desktop icons.