[Bug 265476] porters-handbook: add documentation of pkg-{pre,post}-[de]install[.lua]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=265476

--- Comment #2 from Pau Amma <pauamma@FreeBSD.org> ---
Comment on attachment 235522
  --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=235522
0001-en-porters-handbook-Add-pkg-de-install-variants

>From 6d224058b05f25f56b24fa90190b75f1d220aa98 Mon Sep 17 00:00:00 2001
>From: Felix Palmen <felix@palmen-it.de>
>Date: Thu, 28 Jul 2022 11:01:25 +0200
>Subject: [PATCH] en/porters-handbook: Add pkg-[de]install variants
>
>These scripts support "pre" and "post" variants, and these can also be
>written in lua (by adding the ".lua" extension).
>---
> .../porters-handbook/pkg-files/_index.adoc    | 43 ++++++++++++++-----
> 1 file changed, 33 insertions(+), 10 deletions(-)
>
>diff --git a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
>index 969e0b9f43..de5f8038b7 100644
>--- a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
>+++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
>@@ -223,34 +223,45 @@ Most of the time it is by using `maximum_version` to limit its usage to upgrades
> ====
> 
> [[pkg-install]]
>-== pkg-install
>+== pkg-install, pkg-pre-install and pkg-post-install
> 
> If the port needs to execute commands when the binary package is installed with `pkg add` or `pkg install`, use [.filename]#pkg-install#.
>-This script will automatically be added to the package.
> It will be run twice by `pkg`, the first time as `${SH} pkg-install ${PKGNAME} PRE-INSTALL` before the package is installed, and the second time as `${SH} pkg-install ${PKGNAME} POST-INSTALL` after it has been installed.
> `$2` can be tested to determine which mode the script is being run in.
> The `PKG_PREFIX` environmental variable will be set to the package installation directory.
> 
>+If you use [.filename]#pkg-pre-install# or [.filename]#pkg-post-install# instead, the script is only run once, before or after installation of the package.

Command line? Specifically, does it also have a $2?

>+You can also use [.filename]#pkg-pre-install.lua# or [.filename]#pkg-post-install.lua# to run a lua script instead of a shell script.

Invocation command?

>+Lua scripts run by `pkg` provide some extensions and a few restrictions, for these see man:pkg-lua-script[5].

Lua scripts run by `pkg` provide some extensions and a few restrictions, both
explained in man:pkg-lua-script[5].

>+
>+These scripts will automatically be added to the package.

Do you mean the packing list?

>+
> [IMPORTANT]
> ====
>-This script is here to help you set up the package so that it is as ready to use as possible.
>-It _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
>+These scripts are here to help you set up the package so that it is as ready to use as possible.

While here, s/you // for style conformance. (Besides that, it's not you, the
maintainer, it's the user or sysadmin installing the package.)

>+They _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
> ====
> 
> [[pkg-deinstall]]
>-== pkg-deinstall
>+== pkg-deinstall, pkg-pre-deinstall and pkg-post-deinstall
> 
>-This script executes when a package is removed.
>+These scripts execute when a package is removed.
> 
>-This script will be run twice by `pkg delete`.
>+The [.filename]#pkg-deinstall# script will be run twice by `pkg delete`.
> The first time as `${SH} pkg-deinstall ${PKGNAME} DEINSTALL` before the port is de-installed and the second time as `${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL` after the port has been de-installed.
> `$2` can be tested to determine which mode the script is being run in.
>-The `PKG_PREFIX` environmental variable will be set to the package installation directory
>+The `PKG_PREFIX` environmental variable will be set to the package installation directory.
>+
>+If you use [.filename]#pkg-pre-deinstall# or [.filename]#pkg-post-deinstall# instead, the script is only run once, before or after removal of the package.

$2?

>+You can also use [.filename]#pkg-pre-deinstall.lua# or [.filename]#pkg-post-deinstall.lua# to run a lua script instead of a shell script.

Invocation command?

>+Lua scripts run by `pkg` provide some extensions and a few restrictions, for these see man:pkg-lua-script[5].
>+
>+These scripts will automatically be added to the package.

packing list? (as above)

> 
> [IMPORTANT]
> ====
>-This script is here to help you set up the package so that it is as ready to use as possible.
>-It _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
>+These scripts are here to help you set up the package so that it is as ready to use as possible.

s/you // as above.

>+They _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
> ====
> 
> [[pkg-names]]
>@@ -278,9 +289,21 @@ Here is a list of variable names and their default values.
> |`PKGINSTALL`
> |`${PKGDIR}/pkg-install`
> 
>+|`PKGPREINSTALL`
>+|`${PKGDIR}/pkg-pre-install`
>+
>+|`PKGPOSTINSTALL`
>+|`${PKGDIR}/pkg-post-install`
>+
> |`PKGDEINSTALL`
> |`${PKGDIR}/pkg-deinstall`
> 
>+|`PKGPREDEINSTALL`
>+|`${PKGDIR}/pkg-pre-deinstall`
>+
>+|`PKGPOSTDEINSTALL`
>+|`${PKGDIR}/pkg-post-deinstall`
>+
> |`PKGMESSAGE`
> |`${PKGDIR}/pkg-message`
> |===
>-- 
>2.37.1
>

-- 
You are receiving this mail because:
You are the assignee for the bug.