Created attachment 235522 [details] 0001-en-porters-handbook-Add-pkg-de-install-variants Several variants of the pkg-install and pkg-deinstall scripts are supported by ports and pkg, but aren't documented yet. Attached patch adds the documentation to the english handbook.
at very quick glance, it looks good to me
Comment on attachment 235522 [details] 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 >
Alright, just forget about it.
Tangential question and assumption check: pre and post can be written in LUA, but not install and deinstall? (In reply to Pau Amma from comment #2) "Lua scripts run by `pkg` provide some extensions and a few restrictions, both explained in man:pkg-lua-script[5]." also in deinstall.
(In reply to Pau Amma from comment #4) Yes, indeed, and I thougt that would be obvious. Otherwise, your review was critical about phrases that were there before (just moved around because of the context) and stuff like that ... Well, feel free to improve!
(In reply to Felix Palmen from comment #5) You pointed me to ports/Mk/Scripts/create-manifest.sh line 107 in answer to another question, and looking around that line, I see: for stage in INSTALL DEINSTALL; do for prepost in '' PRE POST; do eval files="\${dp_PKG${prepost}${stage}}" output=${dp_METADIR}/+${prepost:+${prepost}_}${stage} for input in ${files}; do [ -f "${input}" ] && cat ${input} >> ${output} [ -f "${input}.lua" ] && cp ${input}.lua ${dp_METADIR} done done done I don't understand what the inner loop over ${files} is about, but from the outer 2 loops, it looks like 6 sets (INSTALL, PREINSTALL, POSTINSTALL, DEINSTALL, PREDEINSTALL, POSTDEINSTALL) each containing one or more (foo, foo.lua) pairs. So from this, it looks like pkg-install.lua is an option as well. Am I missing something here?
(In reply to Pau Amma from comment #6) > You pointed me to ports/Mk/Scripts/create-manifest.sh Yes, to verify there's indeed no separate make variable for the .lua version. > I don't understand what the inner loop over ${files} is about This seems to support multiple scripts for the same {pre,post,}stage. My *guess* is this could be handy for stuff e.g. added by USES. It's most likely not intended use for a port's Makefile, so better not document it (I tried not to over-complicate docs btw...) > So from this, it looks like pkg-install.lua is an option as well. It looks like it *would* be picked up by the create-manifes.sh script indeed. Still it's not supported by pkg, you can see that in pkg's source: https://github.com/freebsd/pkg/blob/master/libpkg/pkg_create.c#L228
Pau Amma, any news about this?
(In reply to Sergio Carlavilla Delgado from comment #8) Yes. Expect a review (or maybe 2 chained reviews) soon. Maybe even today.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/doc/commit/?id=0265532b9d1257477d98b832937ac5d0c774a27b commit 0265532b9d1257477d98b832937ac5d0c774a27b Author: Felix Palmen <zirias@FreeBSD.org> AuthorDate: 2022-08-04 10:56:04 +0000 Commit: Pau Amma <pauamma@FreeBSD.org> CommitDate: 2022-11-13 21:35:51 +0000 Add documentation of pkg-{pre,post}-[de]install[.lua] PR: 265476 Reported by: Felix Palmen <zirias@FreeBSD.org> Differential Revision: https://reviews.freebsd.org/D36769 Reviewed by: bcr, carlavilla Approved by: carlavilla (mentor) .../books/porters-handbook/pkg-files/_index.adoc | 43 +++++++++++++++++----- 1 file changed, 33 insertions(+), 10 deletions(-)
Committed. Sorry for the delay.