Path: blob/main/documentation/content/en/books/porters-handbook/pkg-files/_index.po
18099 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-05-01 19:56-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:1 #, no-wrap msgid "Tricks about the pkg-* files" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:1 #, no-wrap msgid "Chapter 9. pkg-*" msgstr "" #. type: Title = #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:14 #, no-wrap msgid "pkg-*" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:52 msgid "" "There are some tricks we have not mentioned yet about the [.filename]#pkg-*# " "files that come in handy sometimes." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:54 #, no-wrap msgid "pkg-message" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:58 msgid "" "To display a message when the package is installed, place the message in " "[.filename]#pkg-message#. This capability is often useful to display " "additional installation steps to be taken after a `pkg install` or `pkg " "upgrade`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:62 msgid "" "[.filename]#pkg-message# must contain only information that is _vital_ to " "setup and operation on FreeBSD, and that is unique to the port in question." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:63 msgid "" "Setup information should only be shown on initial install. Upgrade " "instructions should be shown only when upgrading from the relevant version." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:64 msgid "" "Do not surround the messages with either whitespace or lines of symbols " "(like `----------`, `**********`, or `==========`). Leave the formatting to " "man:pkg[8]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:65 msgid "" "Committers have blanket approval to constrain existing messages to install " "or upgrade ranges using the UCL format specifications." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:66 msgid "Please be sure to refer to the proper tools for handling services." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:67 msgid "" "Use `service name start` to start a service rather than using `/usr/local/" "etc/rc.d/name start`" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:68 msgid "Use `sysrc name_enable=YES` to change options in rc.conf" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:72 msgid "pkg-message supports two formats:" msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:73 #, no-wrap msgid "raw" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:76 msgid "A regular plain text file. Its message is only displayed on install." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:77 #, no-wrap msgid "UCL" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:80 msgid "" "If the file starts with \"`[`\" then it is considered to be a UCL file. The " "UCL format is described on https://github.com/vstakhov/libucl[libucl's " "GitHub page]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:84 msgid "" "Do not add an entry for [.filename]#pkg-message# in [.filename]#pkg-plist#." msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:87 #, no-wrap msgid "UCL in pkg-message" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:92 msgid "" "The format is the following. It should be an array of objects. The objects " "themselves can have these keywords:" msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:93 #, no-wrap msgid "`message`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:96 msgid "The actual message to be displayed. This keyword is mandatory." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:97 #, no-wrap msgid "`type`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:99 msgid "When the message should be displayed." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:100 #, no-wrap msgid "`maximum_version`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:103 msgid "" "Only if `type` is `upgrade`. Display if upgrading from a version strictly " "lower than the version specified." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:104 #, no-wrap msgid "`minimum_version`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:107 msgid "" "Only if `type` is `upgrade`. Display if upgrading from a version strictly " "greater than the version specified." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:109 msgid "The `maximum_version` and `minimum_version` keywords can be combined." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:111 msgid "The `type` keyword can have three values:" msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:112 #, no-wrap msgid "`install`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:114 msgid "The message should only be displayed when the package is installed." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:115 #, no-wrap msgid "`remove`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:117 msgid "The message should only be displayed when the package is removed." msgstr "" #. type: Labeled list #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:118 #, no-wrap msgid "`upgrade`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:120 msgid "the message should only be displayed during an upgrade of the package.." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:125 msgid "" "To preserve the compatibility with non UCL [.filename]#pkg-message# files, " "the first line of a UCL [.filename]#pkg-message# _MUST be_ a single \"`[`\", " "and the last line _MUST be_ a single \"`]`\"." msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:128 #, no-wrap msgid "UCL Short Strings" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:133 msgid "" "The message is delimited by double quotes `\"`, this is used for simple " "single line strings:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:141 #, no-wrap msgid "" "[\n" "{ type: install\n" " message: \"Simple message\"\n" "}\n" "]\n" msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:146 #, no-wrap msgid "UCL Multiline Strings" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:154 msgid "" "Multiline strings use the standard here document notation. The multiline " "delimiter _must_ start just after `<<` symbols without any whitespace and it " "_must_ consist of capital letters only. To finish a multiline string, add " "the delimiter string on a line of its own without any whitespace. The " "message from crossref:pkg-files[porting-message-ucl-short-ex,UCL Short " "Strings] can be written as:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:164 #, no-wrap msgid "" "[\n" "{ type: install\n" " message: <<EOM\n" "Simple message\n" "EOM\n" "}\n" "]\n" msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:169 #, no-wrap msgid "Display a Message on Install/Deinstall" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:174 msgid "" "When a message only needs to be displayed on installation or uninstallation, " "set the type:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:184 #, no-wrap msgid "" "[\n" "{\n" " type: remove\n" " message: \"package being removed.\"\n" "}\n" "{ type: install, message: \"package being installed.\"}\n" "]\n" msgstr "" #. type: Block title #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:189 #, no-wrap msgid "Display a Message on Upgrade" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:194 msgid "" "When a port is upgraded, the message displayed can be even more tailored to " "the port's needs." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:219 #, no-wrap msgid "" "[\n" "{\n" " type: upgrade\n" " message: \"Package is being upgraded.\"\n" "}\n" "{\n" " type: upgrade\n" " maximum_version: \"1.0\"\n" " message: \"Upgrading from before 1.0 need to do this.\"\n" "}\n" "{\n" " type: upgrade\n" " minimum_version: \"1.0\"\n" " message: \"Upgrading from after 1.0 should do that.\"\n" "}\n" "{\n" " type: upgrade\n" " maximum_version: \"3.0\"\n" " minimum_version: \"1.0\"\n" " message: \"Upgrading from > 1.0 and < 3.0 remove that file.\"\n" "}\n" "]\n" msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:225 msgid "" "When displaying a message on upgrade, it is important to limit when it is " "being shown to the user. Most of the time it is by using `maximum_version` " "to limit its usage to upgrades from before a certain version when something " "specific needs to be done." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:230 #, no-wrap msgid "pkg-install, pkg-pre-install, and pkg-post-install" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:236 msgid "" "If the port needs to execute commands when the binary package is installed " "with `pkg add` or `pkg install`, use [.filename]#pkg-install#. 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` " "environment variable is set to the package installation directory." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:240 msgid "" "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]." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:244 msgid "" "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#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:247 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:274 msgid "These scripts are automatically added to the packing list." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:252 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:255 #, no-wrap msgid "pkg-deinstall, pkg-pre-deinstall, and pkg-post-deinstall" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:258 msgid "These scripts execute when a package is removed." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:263 msgid "" "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` " "environment variable is set to the package installation directory." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:267 msgid "" "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]." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:271 msgid "" "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#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:279 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:282 #, no-wrap msgid "Changing the Names of pkg-*" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:287 msgid "" "All the names of [.filename]#pkg-\\*# are defined using variables that can " "be changed in the [.filename]#Makefile# if needed. This is especially " "useful when sharing the same [.filename]#pkg-*# files among several ports or " "when it is necessary to write to one of these files. See crossref:porting-" "dads[porting-wrkdir,writing to places other than `WRKDIR`] for why it is a " "bad idea to write directly into the directory containing the [.filename]#pkg-" "*# files." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:290 msgid "" "Here is a list of variable names and their default values. (`PKGDIR` " "defaults to `${MASTERDIR}`.)" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:295 #, no-wrap msgid "Variable" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:297 #, no-wrap msgid "Default value" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:298 #, no-wrap msgid "`DESCR`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:300 #, no-wrap msgid "`${PKGDIR}/pkg-descr`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:301 #, no-wrap msgid "`PLIST`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:303 #, no-wrap msgid "`${PKGDIR}/pkg-plist`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:304 #, no-wrap msgid "`PKGINSTALL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:306 #, no-wrap msgid "`${PKGDIR}/pkg-install`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:307 #, no-wrap msgid "`PKGPREINSTALL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:309 #, no-wrap msgid "`${PKGDIR}/pkg-pre-install`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:310 #, no-wrap msgid "`PKGPOSTINSTALL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:312 #, no-wrap msgid "`${PKGDIR}/pkg-post-install`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:313 #, no-wrap msgid "`PKGDEINSTALL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:315 #, no-wrap msgid "`${PKGDIR}/pkg-deinstall`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:316 #, no-wrap msgid "`PKGPREDEINSTALL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:318 #, no-wrap msgid "`${PKGDIR}/pkg-pre-deinstall`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:319 #, no-wrap msgid "`PKGPOSTDEINSTALL`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:321 #, no-wrap msgid "`${PKGDIR}/pkg-post-deinstall`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:322 #, no-wrap msgid "`PKGMESSAGE`" msgstr "" #. type: Table #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:323 #, no-wrap msgid "`${PKGDIR}/pkg-message`" msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:326 #, no-wrap msgid "Making Use of `SUB_FILES` and `SUB_LIST`" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:329 msgid "" "`SUB_FILES` and `SUB_LIST` are useful for dynamic values in port files, such " "as the installation `PREFIX` in [.filename]#pkg-message#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:335 msgid "" "`SUB_FILES` specifies a list of files to be automatically modified. Each " "[.filename]#file# in the `SUB_FILES` list must have a corresponding " "[.filename]#file.in# present in `FILESDIR`. A modified version will be " "created as [.filename]#${WRKDIR}/file#. Files defined as a value of " "`USE_RC_SUBR` are automatically added to `SUB_FILES`. For the files " "[.filename]#pkg-message#, [.filename]#pkg-install#, and [.filename]#pkg-" "deinstall#, the corresponding Makefile variable is automatically set to " "point to the processed version." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:340 msgid "" "`SUB_LIST` is a list of `VAR=VALUE` pairs. For each pair, `%%VAR%%` will be " "replaced with `VALUE` in each file listed in `SUB_FILES`. Several common " "pairs are automatically defined: `PREFIX`, `LOCALBASE`, `DATADIR`, " "`DOCSDIR`, `EXAMPLESDIR`, `WWWDIR`, and `ETCDIR`. Any line beginning with " "`@comment` followed by a space, will be deleted from resulting files after a " "variable substitution." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:342 msgid "" "This example replaces `%%ARCH%%` with the system architecture in a " "[.filename]#pkg-message#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:347 #, no-wrap msgid "" "SUB_FILES=\tpkg-message\n" "SUB_LIST=\tARCH=${ARCH}\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:350 msgid "" "Note that for this example, [.filename]#pkg-message.in# must exist in " "`FILESDIR`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:352 msgid "Example of a good [.filename]#pkg-message.in#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:358 #, no-wrap msgid "" "Now it is time to configure this package.\n" "Copy %%PREFIX%%/shared/examples/putsy/%%ARCH%%.conf into your home directory\n" "as .putsy.conf and edit it.\n" msgstr ""