Index: en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml @@ -211,31 +211,19 @@ The sample configuration files should always have the .sample suffix. If for some historical - reason using the standard suffix is not possible, use + reason using the standard suffix is not possible, or if the + sample files come from some other directory, use this construct: - @unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi -etc/orbit.conf-dist -@exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi - - The order of these lines is important. On deinstallation, - the sample file is compared to the actual configuration file. - If these files are identical, no changes have been made by the - user and the actual file can be safely deleted. Because the - sample file must still exist for the comparison, the - @unexec line comes before the sample - configuration file name. On installation, if an actual - configuration file is not already present, the sample file is - copied to the actual file. The sample file must be present - before it can be copied, so the @exec line - comes after the sample configuration file name. - - To debug any issues, temporarily remove the - -s flag to &man.cmp.1; for more - output. - - See &man.pkg-create.8; for more information on - %D and related substitution markers. + @sample etc/orbit.conf-dist etc/orbit.conf + + or + + @sample %%EXAMPLESDIR%%/orbit.conf etc/orbit.conf + + The format is @sample + sample-file + actual-config-file. @@ -408,15 +396,17 @@ <literal>@sample</literal> - <replaceable>file</replaceable> + file + [file] - Add the file passed as argument to the plist. + Add the first file passed as argument to the plist. - On installation, check for a real file with - just the base name (the name without the - .sample extension). If the real file is - not found, copy the sample file to the base file name. On - deinstallation, remove the configuration file if it has not + The actual file is either the second + filename, if present, or the first filename without the + .sample extension. On installation, if + the actual file is + not found, copy the sample file to the actual file. On + deinstallation, remove the actual file if it has not been modified. See for more information. @@ -461,21 +451,67 @@ @(,games,2755) sbin/daemon - - <literal>@cwd</literal> - [<replaceable>directory</replaceable>] (Deprecated) - - Set the internal directory pointer to point to - directory. All subsequent filenames are assumed relative to - this directory. - - - <literal>@exec</literal> + <title><literal>@preexec</literal> + <replaceable>command</replaceable>, + <literal>@postexec</literal> + <replaceable>command</replaceable>, + <literal>@preunexec</literal> + <replaceable>command</replaceable>, + <literal>@postunexec</literal> <replaceable>command</replaceable> Execute command as part of - the unpacking process. If command contains any of these + the package installation or deinstallation process. + + + + @preexec + command + + + Execute command as part + of the pre-install + scripts. + + + + + @postexec + command + + + Execute command as part + of the post-install + scripts. + + + + + @preunexec + command + + + Execute command as part + of the pre-deinstall + scripts. + + + + + @postunexec + command + + + Execute command as part + of the post-deinstall + scripts. + + + + + If command contains + any of these sequences somewhere in it, they are expanded inline. For these examples, assume that @cwd is set to @@ -527,22 +563,6 @@ - - <literal>@unexec</literal> - <replaceable>command</replaceable> - - Execute command as part of - the deinstallation process. Expansion of special - % sequences is the same as for - @exec. This command is not executed - during the package add, as @exec is, but - rather when the package is deleted. This is useful for - deleting links and other ancillary files that were created - as a result of adding the package, but not directly known to - the package's table of contents (and hence not automatically - removable). - - <literal>@mode</literal> <replaceable>mode</replaceable> @@ -606,6 +626,17 @@ mode. + + <literal>@exec</literal> + <replaceable>command</replaceable>, + <literal>@unexec</literal> + <replaceable>command</replaceable> (Deprecated) + + Execute command as part of + the installation or deinstallation process. Please use instead. + + <literal>@dirrm</literal> <replaceable>directory</replaceable> (Deprecated) @@ -634,14 +665,45 @@ directory. The settings for each keyword are stored in a UCL file named keyword.ucl. - The file must contain at least one of the next - sections: + The file must contain at least one of these sections: - - - attributes + + + attributes + + + + action + + + + pre-install + + + + post-install + + + + pre-deinstall + + + + post-deinstall + + + + pre-upgrade + + + + post-upgrade + + + + + <literal>attributes</literal> - Changes the owner, group, or mode used by the keyword. Contains an associative array where the possible keys are owner, @@ -650,13 +712,11 @@ and a file mode. For example: attributes: { owner: "games", group: "games", mode: 0555 } - - + - - action + + <literal>action</literal> - Defines what happens to the keyword's parameter. Contains an array where the possible values are: @@ -750,18 +810,41 @@ - - - - - pre-install - post-install - pre-deinstall - post-deinstall - pre-upgrade - post-upgrade - - + + + + <literal>arguments</literal> + + If set to true, adds argument + handling, splitting the whole line, %@, + into numbered arguments, %1, + %2... For example, if enabled, for the + @foo some.content + other.content line, + %@, %1, and + %2 will contain + some.content + other.content, + some.content, and + other.content, + respectively. + + It also affects how the action + entry works. When there is more than one argument, the + argument number must be specified. For example: + + actions: [file(1)] + + + + <literal>pre-install</literal>, + <literal>post-install</literal>, + <literal>pre-deinstall</literal>, + <literal>post-deinstall</literal>, + <literal>pre-upgrade</literal>, + <literal>post-upgrade</literal> + These keywords contains a &man.sh.1; script to be executed before or after installation, deinstallation, or upgrade of the package. In addition to the usual @@ -771,9 +854,10 @@ linkend="plist-keywords-base-exec"/>, there is a new one, %@, which represents the argument of the keyword. - - - + + + + Custom Keyword Examples Example of a <literal>@dirrmtryecho</literal> @@ -795,7 +879,7 @@ <title>Real Life Example, How <literal>@sample</literal> is Implemented - This keyword does three things, it adds the + This keyword does three things. It adds the first filename passed as an argument to @sample to the packing list, it adds to the post-install script instructions to @@ -804,30 +888,50 @@ post-deinstall instructions to remove the configuration file if it has not been modified. - actions: [file] + actions: [file(1)] +arguments: true post-install: <<EOD - case "%@" in - /*) sample_file="%@" ;; - *) sample_file="%D/%@" ;; + case "%1" in + /*) sample_file="%1" ;; + *) sample_file="%D/%1" ;; esac target_file="${sample_file%.sample}" + set -- %@ + if [ $# -eq 2 ]; then + target_file=${2} + fi + case "${target_file}" in + /*) target_file="${target_file}" ;; + *) target_file="%D/${target_file}" ;; + esac if ! [ -f "${target_file}" ]; then - /bin/cp -p "${sample_file}" "${target_file}" + /bin/cp -p "${sample_file}" "${target_file}" && \ + /bin/chmod u+w "${target_file}" fi EOD pre-deinstall: <<EOD - case "%@" in - /*) sample_file="%@" ;; - *) sample_file="%D/%@" ;; + case "%1" in + /*) sample_file="%1" ;; + *) sample_file="%D/%1" ;; esac target_file="${sample_file%.sample}" + set -- %@ + if [ $# -eq 2 ]; then + set -- %@ + target_file=${2} + fi + case "${target_file}" in + /*) target_file="${target_file}" ;; + *) target_file="%D/${target_file}" ;; + esac if cmp -s "${target_file}" "${sample_file}"; then rm -f "${target_file}" else - echo "You may need to manually remove ${target_file} if it's no longer needed." + echo "You may need to manually remove ${target_file} if it is no longer needed." fi EOD +