From nobody Sun Nov 13 21:54:01 2022 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4N9R6K5WXDz4hF6C for ; Sun, 13 Nov 2022 21:54:01 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4N9R6K57M6z3JQm; Sun, 13 Nov 2022 21:54:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1668376441; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=vK7dTux7Y4NOLSN0jZS4Z6BY3Yl8jOoBWf2CxuhCNA8=; b=QK6NcsACFCwmo81HQYKh7g3pmRaTvNCkbL0K4bWz09LpqnBhfaWnIo0lFj7XUiGG0MMYcy BmG35fnUjHMasFuANwRln7WSKoZpVm7T+kn3+97RPwrSGM38v/to/iXE1xqYRO/H49S6cS tuQ2EYrxASrx4XRdZdSAdGoXmzpgt4Ls3sQypyp+jjfa6l49gJ5yS/jY1TmL4EO2dRMJyO djRjZuQYpY1kmNo69g2ovYWHkK/qpZEYxQB4DcLkGNBYBc35lUXLuC21lGH1v+WPkjlSPm S2jcDMB/zVQsat7A08U3YiI5B/kEBFIn5iy1x8rXkjr5ZPmzZ2D/RyE2AzCVGQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1668376441; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=vK7dTux7Y4NOLSN0jZS4Z6BY3Yl8jOoBWf2CxuhCNA8=; b=Okdx8snok8ngKjIluqUIGJ9jgN03nAspn9lzpgUYboS/pVA1NFsguUiQedUWWNHXM4/0M1 FixRFmN3WgvLfU85yRkKsfWlSoBKnUQ5fhZbEjUFr/R9ZWKVQXanU6nJ7uGcK/wS8TLvrp CyiR/xqtCm/7bQhoZ8eDCgjJdhc/vvM2fpjWqFpcl5nXNeT1qLjqAYX60HwUe0WwZREFT0 1lcFc+bUGNeytAjf/Mzvbeu1iJENkEGHjZ7fK2PwpkVYoe0lnPBHfYAbIF2Ma9fA+REcKU xxwEW4a25JEDefRirOeO/A3mok8i4ORiTYUy6hbfO+g+iQd6OCfEmJs7/x841A== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1668376441; a=rsa-sha256; cv=none; b=dd2Ppn2FzcP0U4wymUQFkXo2LOn8MJQl6YRaa1MHaSem8426eKXZFLryzc/ldZzuUNDAQu tQ73mTAw4jleRhWplahjpig4D0T6iPSsEQcheNcOMLFU1j5zvQU2T4Kq0tYA+sYco8J2yc biBFhs1dz03FKLervB0ghB2cxjmDQBWif+PByKR6bDowH/IjeQkCYy51/zkbUvjlTsEzUR +bRpBPYO+PSp8Z+Eem+T2FhqWUI1ICkNJbPQeG2LtbEv+7IzGmVVXMRgRiQUbEIzRp5gKX htc+geQeVusZ2ctrBbZcc3WcvaN+WrFSs+980KzYxdohebNrALv3UbBo28YwbQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4N9R6K3mYZzJ8H; Sun, 13 Nov 2022 21:54:01 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 2ADLs15L088237; Sun, 13 Nov 2022 21:54:01 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 2ADLs1Im088236; Sun, 13 Nov 2022 21:54:01 GMT (envelope-from git) Date: Sun, 13 Nov 2022 21:54:01 GMT Message-Id: <202211132154.2ADLs1Im088236@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Pau Amma Subject: git: aa2e780d4e - main - Copyedit zirias' pre*/post* update. List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: pauamma X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: aa2e780d4e90c2be648323ff4cf56fc2a2aec79c Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by pauamma: URL: https://cgit.FreeBSD.org/doc/commit/?id=aa2e780d4e90c2be648323ff4cf56fc2a2aec79c commit aa2e780d4e90c2be648323ff4cf56fc2a2aec79c Author: Pau Amma AuthorDate: 2022-09-27 21:12:11 +0000 Commit: Pau Amma CommitDate: 2022-11-13 21:43:24 +0000 Copyedit zirias' pre*/post* update. While there, wordsmith a bit more of those sections. Differential Revision: https://reviews.freebsd.org/D36770 Reviewed by: bapt (previous version), bcr, carlavilla Approved by: carlavilla (mentor) --- .../books/porters-handbook/pkg-files/_index.adoc | 42 +++++++++++++--------- 1 file changed, 26 insertions(+), 16 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 d56bc79d9c..413637c4af 100644 --- a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc +++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc @@ -223,44 +223,54 @@ Most of the time it is by using `maximum_version` to limit its usage to upgrades ==== [[pkg-install]] -== pkg-install, pkg-pre-install and pkg-post-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#. -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. +It is 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. +The `PKG_PREFIX` environment variable is 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. -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. -Lua scripts run by `pkg` provide some extensions and a few restrictions, for these see man:pkg-lua-script[5]. +If using [.filename]#pkg-pre-install# or [.filename]#pkg-post-install# instead, the script is run only once (before or after installing the package), with the single argument `${PKGNAME}`. +Using [.filename]#pkg-pre-install.lua# or [.filename]#pkg-post-install.lua# will run a lua script instead of a shell script. +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. +[NOTE] +==== +Using [.filename]#pkg-pre-install# (or [.filename]#pkg-pre-install.lua#) and [.filename]#pkg-post-install# (or [.filename]#pkg-post-install.lua#) is preferred to using [.filename]#pkg-install#. +==== + +These scripts are automatically added to the packing list. [IMPORTANT] ==== -These scripts are here to help you set up the package so that it is as ready to use as possible. +These scripts are here to simplify package configuration after installation. 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-pre-deinstall and pkg-post-deinstall +== pkg-deinstall, pkg-pre-deinstall, and pkg-post-deinstall These scripts execute when a package is removed. -The [.filename]#pkg-deinstall# script will be run twice by `pkg delete`. +The [.filename]#pkg-deinstall# script is 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` environment variable is 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. -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. -Lua scripts run by `pkg` provide some extensions and a few restrictions, for these see man:pkg-lua-script[5]. +If using [.filename]#pkg-pre-deinstall# or [.filename]#pkg-post-deinstall# instead, the script is run only once (before or after deinstalling the package), with the single argument `${PKGNAME}`. +Using [.filename]#pkg-pre-deinstall.lua# or [.filename]#pkg-post-deinstall.lua# will run a lua script instead of a shell script. +Lua scripts run by `pkg` provide some extensions and a few restrictions, both explained in man:pkg-lua-script[5]. + +[NOTE] +==== +Using [.filename]#pkg-pre-deinstall# (or [.filename]#pkg-pre-deinstall.lua#) and [.filename]#pkg-post-deinstall# (or [.filename]#pkg-post-deinstall.lua#) is preferred to using [.filename]#pkg-deinstall#. +==== -These scripts will automatically be added to the package. +These scripts are automatically added to the packing list. [IMPORTANT] ==== -These scripts are here to help you set up the package so that it is as ready to use as possible. +These scripts are here to simplify cleanup after package deinstallation. They _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system. ====