Index: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
@@ -19,45 +19,47 @@
need to change their pkg-plist depending on
what options they are configured with (or version of
perl, in the case of p5-
- ports). To make this easy, any instances in the
+ ports). To make this easy, any instances in
pkg-plist of %%OSREL%%,
%%PERL_VER%%, and
- %%PERL_VERSION%% will be substituted for
+ %%PERL_VERSION%% will be substituted
appropriately. The value of %%OSREL%% is the
- numeric revision of the operating system (e.g.,
+ numeric revision of the operating system (for example,
4.9). %%PERL_VERSION%%
and %%PERL_VER%% is the full version number
- of perl (e.g., 5.8.9).
+ of perl (for example, 5.8.9).
Several other
%%VARS%% related
to port's documentation files are described in the relevant
section.
- If you need to make other substitutions, you can set the
- PLIST_SUB variable with a list of
+ To make other substitutions, set
+ PLIST_SUB with a list of
VAR=VALUE
pairs and instances of
%%VAR%% will be
- substituted with VALUE in the
+ substituted with VALUE in
pkg-plist.
- For instance, if you have a port that installs many files
- in a version-specific subdirectory, you can put something
- like
+ For instance, if a port installs many files
+ in a version-specific subdirectory, use a placeholder for the
+ version so that pkg-plist does not have to
+ be regenerated every time the port is updated. For
+ example:
- OCTAVE_VERSION= 2.0.13
+ OCTAVE_VERSION= ${PORTREVISION}
PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}in the Makefile and use
%%OCTAVE_VERSION%% wherever the version shows
- up in pkg-plist. That way, when you
- upgrade the port, you will not have to change dozens (or in some
- cases, hundreds) of lines in the
+ up in pkg-plist. When
+ the port is upgraded, it will not be necessary to edit dozens (or in some
+ cases, hundreds) of lines in
pkg-plist.
- If your port installs files conditionally on the options
- set in the port, the usual way of handling it is prefixing the
+ If files are installed conditionally on the options
+ set in the port, the usual way of handling it is prefixing
pkg-plist lines with a
%%OPT%% for lines needed when the option is
enabled, or %%NO_OPT%% when the option is
@@ -66,13 +68,13 @@
linkend="options_sub"/> for more information.For instance, if there are files that are only installed
- when the X11 option is enabled, and the
+ when the X11 option is enabled, and
Makefile has:OPTIONS_DEFINE= X11
OPTIONS_SUB= yes
- In the pkg-plist file, put
+ In pkg-plist, put
%%X11%% in front of the lines only being
installed when the option is enabled, like this :
@@ -83,9 +85,9 @@
do-install targets, by reading from
PLIST and writing to
TMPPLIST (default:
- WRKDIR/.PLIST.mktmp). So if your port
+ WRKDIR/.PLIST.mktmp). So if the port
builds PLIST on the fly, do so in or before
- pre-install. Also, if your port
+ pre-install. Also, if the port
needs to edit the resulting file, do so in
post-install to a file named
TMPPLIST.
@@ -108,13 +110,13 @@
PLIST_DIRSTRY, respectively. To take effect,
PLIST_FILES, PLIST_DIRS,
and PLIST_DIRSTRY must be set before
- TMPPLIST is written, i.e., in
+ TMPPLIST is written, that is, in
pre-install or earlier.
- From time to time, the OPTIONS_SUB
- construct is not enough, in those cases, adding a specific
- TAG to the PLIST_SUB
- variable inside the Makefile with a special
+ From time to time, using OPTIONS_SUB
+ is not enough. In those cases, adding a specific
+ TAG to PLIST_SUB
+ inside the Makefile with a special
value of @comment, makes package tools to
ignore the line. For instance, if some files are only installed
when the X11 option is on and the
@@ -139,8 +141,8 @@
When being de-installed, A port has to remove empty
directories it created. This is usually accomplished by
adding @dirrm lines for all directories
- that are specifically created by the port. You need to delete
- subdirectories before you can delete parent
+ that are specifically created by the port. Subdirectories
+ must be deleted before deleting parent
directories. :
@@ -152,8 +154,8 @@
@dirrm lib/X11/onekoHowever, sometimes @dirrm will give
- you errors because other ports share the same directory. You
- can use @dirrmtry to remove only empty
+ errors because other ports share the same directory.
+ Use @dirrmtry to remove only empty
directories without warning.@dirrmtry share/doc/gimp
@@ -169,33 +171,38 @@
Creating Empty DirectoriesEmpty directories created during port installation need
- special attention. They will not get created when installing
- the package, because packages only store the files, and both
- pkg add and pkg install
- creates directories for them as needed. To make sure the
- empty directory is created when installing the package, add
- this line to pkg-plist above the
- corresponding @dirrm line:
+ special attention. They must be present when the package
+ is created. If they are not created by the port code, create
+ them in the Makefile:
+
+ post-stage:
+ @${MKDIR} ${STAGEDIR}${PREFIX}/some/directory
+
+ Add the directory to pkg-plist
+ like any other. For example, if the directory has files
+ created when the port is used:
- @exec mkdir -p %D/share/foo/templates
+ @dirrmtry some/directoryConfiguration Files
- If your port installs configuration files to
+ If the port installs configuration files to
PREFIX/etc (or elsewhere) do
- not simply list them in the
+ not list them in
pkg-plist. That will cause
- pkg delete to remove the files carefully
+ pkg delete to remove files that have been carefully
edited by the user, and a re-installation will wipe them
out.
- Instead, install sample file(s) as
- filename.sample,
- and for each sample file, add this line to your
- pkg-plist.
+ Instead, install sample files with a
+ filename.sample
+ extension. The @sample macro automates this,
+ see for what it does
+ exactly. For each sample file, add a line to
+ pkg-plist:@sample etc/orbit.conf.sample
@@ -209,19 +216,19 @@
When a port installs its configuration in a subdirectory
- of ${PREFIX}/etc, it should be in
+ of ${PREFIX}/etc, use
ETCDIR, which defaults to
${PREFIX}/etc/${PORTNAME}, it can be
overridden in the ports Makefile if there
is a convention for the port to use some other directory. The
- %%ETCDIR%% macro should be used in its
- stead in the pkg-plist file.
+ %%ETCDIR%% macro will be used in its
+ stead in pkg-plist.The sample configuration files should always have the
.sample suffix. If for some historical
- reason you cannot use the standard suffix, you can still use
+ reason using the standard suffix is not possible, use
this construct:@unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
@@ -253,15 +260,15 @@
Dynamic Versus Static Package ListA static package list is a package
- list which is available in the Ports Collection either as a
- pkg-plist file (with or without variable
+ list which is available in the Ports Collection either as
+ pkg-plist (with or without variable
substitution), or embedded into the
Makefile via
PLIST_FILES, PLIST_DIRS,
and PLIST_DIRSTRY. Even if the contents are
auto-generated by a tool or a target in the Makefile
before the inclusion into the Ports
- Collection by a committer (e.g., using make
+ Collection by a committer (for example, using make
makeplist>), this is still considered a static list,
since it is possible to examine it without having to download or
compile the distfile.
@@ -281,8 +288,8 @@
the package list changes drastically based upon optional
features of the port (and thus maintaining a static package list
is infeasible), or ports which change the package list based
- upon the version of dependent software used (e.g., ports which
- generate docs with Javadoc).
+ upon the version of dependent software used. For example, ports which
+ generate docs with Javadoc.
@@ -290,7 +297,7 @@
First, make sure the port is almost complete, with only
pkg-plist missing. Running make
- makeplist will show what should be put in
+ makeplist will show an example for
pkg-plist. The output of
makeplist must be double checked for
correctness as it tries to automatically guess a few things, and
@@ -298,12 +305,12 @@
User configuration files should be installed as
filename.sample,
- as it is described in . The
- info/dir file should not be listed and
- appropriate install-info lines should be
+ as it is described in .
+ info/dir must not be listed and
+ appropriate install-info lines must be
added as noted in the info
files section. Any libraries installed by the port
- should be listed as specified in the shared libraries
section.
@@ -412,9 +419,9 @@
commandExecute command as part of
- the unpacking process. If command contains any of the
- following sequences somewhere in it, they are expanded
- inline. For the following examples, assume that
+ the unpacking process. If command contains any of these
+ sequences somewhere in it, they are expanded
+ inline. For these examples, assume that
@cwd is set to /usr/local and the last
extracted file was bin/emacs.
@@ -527,7 +534,7 @@
By default, directories created by a package installation
are not deleted when the package is deinstalled. This
provides an explicit directory cleanup method. These
- directives should appear at the end of the package list. If
+ directives must appear at the end of the package list. If
the directory is not empty a warning is printed, and the
directory is not removed.
@@ -542,8 +549,8 @@
-
- Creating Your Own Keyword
+
+ Creating New KeywordsPackage list files can be extended by keywords that are
defined in the YAML file named
keyword.yaml.
- The file must contain at least one of the following
+ The file must contain at least one of the next
sections:
@@ -713,13 +720,19 @@
actions: [file]
post-install: |
- sample_file="%D/%@"
+ case "%@" in
+ /*) sample_file="%@" ;;
+ *) sample_file="%D/%@" ;;
+ esac
target_file="${sample_file%.sample}"
if ! [ -f "${target_file}" ]; then
/bin/cp -p "${sample_file}" "${target_file}"
fi
pre-deinstall: |
- sample_file="%D/%@"
+ case "%@" in
+ /*) sample_file="%@" ;;
+ *) sample_file="%D/%@" ;;
+ esac
target_file="${sample_file%.sample}"
if cmp -s "${target_file}" "${sample_file}"; then
rm -f "${target_file}"