Whitespace-only fixes, translators please ignore.
This commit is contained in:
Warren Block
parent
c943775a5b
commit
ab87e4711c
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43850
1 changed files with 212 additions and 223 deletions
|
|
@ -5,7 +5,9 @@
|
|||
$FreeBSD$
|
||||
-->
|
||||
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="plist">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="plist">
|
||||
|
||||
<title>Advanced <filename>pkg-plist</filename> Practices</title>
|
||||
|
||||
|
|
@ -14,30 +16,28 @@
|
|||
Variables</title>
|
||||
|
||||
<para>Some ports, particularly the <literal>p5-</literal> ports,
|
||||
need to change their <filename>pkg-plist</filename> depending
|
||||
on what options they are configured with (or version of
|
||||
need to change their <filename>pkg-plist</filename> depending on
|
||||
what options they are configured with (or version of
|
||||
<literal>perl</literal>, in the case of <literal>p5-</literal>
|
||||
ports). To make this easy, any instances in the
|
||||
<filename>pkg-plist</filename> of
|
||||
<literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>,
|
||||
and <literal>%%PERL_VERSION%%</literal> will be substituted
|
||||
for appropriately. The value of <literal>%%OSREL%%</literal>
|
||||
is the numeric revision of the operating system (e.g.,
|
||||
<filename>pkg-plist</filename> of <literal>%%OSREL%%</literal>,
|
||||
<literal>%%PERL_VER%%</literal>, and
|
||||
<literal>%%PERL_VERSION%%</literal> will be substituted for
|
||||
appropriately. The value of <literal>%%OSREL%%</literal> is the
|
||||
numeric revision of the operating system (e.g.,
|
||||
<literal>4.9</literal>). <literal>%%PERL_VERSION%%</literal>
|
||||
and <literal>%%PERL_VER%%</literal> is the full version number
|
||||
of <command>perl</command> (e.g., <literal>5.8.9</literal>).
|
||||
Several other
|
||||
<literal>%%VARS%%</literal> related
|
||||
to port's documentation files are described in
|
||||
Several other <literal>%%VARS%%</literal> related to port's
|
||||
documentation files are described in
|
||||
<link linkend="install-documentation">the relevant
|
||||
section</link>.</para>
|
||||
|
||||
<para>If you need to make other substitutions, you can set the
|
||||
<varname>PLIST_SUB</varname> variable with a list of
|
||||
<literal>VAR=VALUE</literal>
|
||||
pairs and instances of
|
||||
<literal>%%VAR%%</literal> will be
|
||||
substituted with <replaceable>VALUE</replaceable> in the
|
||||
<literal>VAR=VALUE</literal> pairs and instances of
|
||||
<literal>%%VAR%%</literal> will be substituted with
|
||||
<replaceable>VALUE</replaceable> in the
|
||||
<filename>pkg-plist</filename>.</para>
|
||||
|
||||
<para>For instance, if you have a port that installs many files
|
||||
|
|
@ -48,10 +48,10 @@
|
|||
PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
|
||||
|
||||
<para>in the <filename>Makefile</filename> and use
|
||||
<literal>%%OCTAVE_VERSION%%</literal> wherever the version
|
||||
shows up in <filename>pkg-plist</filename>. That way, when
|
||||
you upgrade the port, you will not have to change dozens (or
|
||||
in some cases, hundreds) of lines in the
|
||||
<literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
|
||||
up in <filename>pkg-plist</filename>. That way, when you
|
||||
upgrade the port, you will not have to change dozens (or in some
|
||||
cases, hundreds) of lines in the
|
||||
<filename>pkg-plist</filename>.</para>
|
||||
|
||||
<para>If your port installs files conditionally on the options
|
||||
|
|
@ -59,9 +59,9 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
|
|||
<filename>pkg-plist</filename> lines with a
|
||||
<literal>%%TAG%%</literal> and adding that
|
||||
<literal>TAG</literal> to the <varname>PLIST_SUB</varname>
|
||||
variable inside the <filename>Makefile</filename> with a
|
||||
special value of <literal>@comment</literal>, which makes
|
||||
package tools to ignore the line:</para>
|
||||
variable inside the <filename>Makefile</filename> with a special
|
||||
value of <literal>@comment</literal>, which makes package tools
|
||||
to ignore the line:</para>
|
||||
|
||||
<programlisting>.if defined(WITH_X11)
|
||||
PLIST_SUB+= X11=""
|
||||
|
|
@ -73,43 +73,37 @@ PLIST_SUB+= X11="@comment "
|
|||
|
||||
<programlisting>%%X11%%bin/foo-gui</programlisting>
|
||||
|
||||
<para>This substitution
|
||||
will be
|
||||
done between the <buildtarget>pre-install</buildtarget> and
|
||||
<para>This substitution will be done between the
|
||||
<buildtarget>pre-install</buildtarget> and
|
||||
<buildtarget>do-install</buildtarget> targets, by reading from
|
||||
<filename>PLIST</filename> and writing to
|
||||
<filename>TMPPLIST</filename> (default:
|
||||
<filename>WRKDIR/.PLIST.mktmp</filename>).
|
||||
So if your port builds
|
||||
<filename>PLIST</filename> on the fly, do
|
||||
so in or before <buildtarget>pre-install</buildtarget>. Also,
|
||||
if your port needs to edit the resulting file, do so in
|
||||
<filename>WRKDIR/.PLIST.mktmp</filename>). So if your port
|
||||
builds <filename>PLIST</filename> on the fly, do so in or before
|
||||
<buildtarget>pre-install</buildtarget>. Also, if your port
|
||||
needs to edit the resulting file, do so in
|
||||
<buildtarget>post-install</buildtarget> to a file named
|
||||
<filename>TMPPLIST</filename>.</para>
|
||||
|
||||
<para>Another way of modifying a port's packing list is based
|
||||
on setting the variables <varname>PLIST_FILES</varname>,
|
||||
<para>Another way of modifying a port's packing list is based on
|
||||
setting the variables <varname>PLIST_FILES</varname>,
|
||||
<varname>PLIST_DIRS</varname>, and
|
||||
<varname>PLIST_DIRSTRY</varname>. The value of each variable
|
||||
is regarded as a list of pathnames to write to
|
||||
<varname>PLIST_DIRSTRY</varname>. The value of each variable is
|
||||
regarded as a list of pathnames to write to
|
||||
<filename>TMPPLIST</filename> along with
|
||||
<filename>PLIST</filename> contents. Names
|
||||
listed in <varname>PLIST_FILES</varname>,
|
||||
<varname>PLIST_DIRS</varname>, and
|
||||
<varname>PLIST_DIRSTRY</varname> are subject to
|
||||
<literal>%%VAR%%</literal>
|
||||
substitution as described above. Except for that, names from
|
||||
<varname>PLIST_FILES</varname> will appear in the final
|
||||
packing list unchanged, while <literal>@dirrm</literal> and
|
||||
<literal>@dirrmtry</literal> will
|
||||
be prepended to names from <varname>PLIST_DIRS</varname>
|
||||
and <varname>PLIST_DIRSTRY</varname>, respectively. To
|
||||
take effect, <varname>PLIST_FILES</varname>,
|
||||
<varname>PLIST_DIRS</varname>, and
|
||||
<varname>PLIST_DIRSTRY</varname> must be set before
|
||||
<filename>TMPPLIST</filename> is written,
|
||||
i.e., in <buildtarget>pre-install</buildtarget> or
|
||||
earlier.</para>
|
||||
<filename>PLIST</filename> contents. Names listed in
|
||||
<varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
|
||||
and <varname>PLIST_DIRSTRY</varname> are subject to
|
||||
<literal>%%VAR%%</literal> substitution as described above.
|
||||
Except for that, names from <varname>PLIST_FILES</varname> will
|
||||
appear in the final packing list unchanged, while
|
||||
<literal>@dirrm</literal> and <literal>@dirrmtry</literal> will
|
||||
be prepended to names from <varname>PLIST_DIRS</varname> and
|
||||
<varname>PLIST_DIRSTRY</varname>, respectively. To take effect,
|
||||
<varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
|
||||
and <varname>PLIST_DIRSTRY</varname> must be set before
|
||||
<filename>TMPPLIST</filename> is written, i.e., in
|
||||
<buildtarget>pre-install</buildtarget> or earlier.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="plist-cleaning">
|
||||
|
|
@ -118,8 +112,8 @@ PLIST_SUB+= X11="@comment "
|
|||
<sect2 xml:id="plist-dir-cleaning">
|
||||
<title>Cleaning Up Empty Directories</title>
|
||||
|
||||
<para>Do make your ports remove empty directories when they
|
||||
are de-installed. This is usually accomplished by adding
|
||||
<para>Do make your ports remove empty directories when they are
|
||||
de-installed. This is usually accomplished by adding
|
||||
<literal>@dirrm</literal> lines for all directories that are
|
||||
specifically created by the port. You need to delete
|
||||
subdirectories before you can delete parent
|
||||
|
|
@ -134,9 +128,9 @@ lib/X11/oneko/sounds/cat.au
|
|||
@dirrm lib/X11/oneko</programlisting>
|
||||
|
||||
<para>However, sometimes <literal>@dirrm</literal> will give
|
||||
you errors because other ports share the same directory.
|
||||
You can use <literal>@dirrmtry</literal> to remove only
|
||||
empty directories without warning.</para>
|
||||
you errors because other ports share the same directory. You
|
||||
can use <literal>@dirrmtry</literal> to remove only empty
|
||||
directories without warning.</para>
|
||||
|
||||
<programlisting>@dirrmtry share/doc/gimp</programlisting>
|
||||
|
||||
|
|
@ -151,14 +145,13 @@ lib/X11/oneko/sounds/cat.au
|
|||
<title>Creating Empty Directories</title>
|
||||
|
||||
<para>Empty 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 <command>pkg add</command> and <command>pkg
|
||||
install</command> creates directories for them as needed.
|
||||
To make sure the empty directory is created when installing
|
||||
the package, add this line to <filename>pkg-plist</filename>
|
||||
above the corresponding <literal>@dirrm</literal>
|
||||
line:</para>
|
||||
special attention. They will not get created when installing
|
||||
the package, because packages only store the files, and both
|
||||
<command>pkg add</command> and <command>pkg install</command>
|
||||
creates directories for them as needed. To make sure the
|
||||
empty directory is created when installing the package, add
|
||||
this line to <filename>pkg-plist</filename> above the
|
||||
corresponding <literal>@dirrm</literal> line:</para>
|
||||
|
||||
<programlisting>@exec mkdir -p %D/share/foo/templates</programlisting>
|
||||
</sect2>
|
||||
|
|
@ -168,19 +161,19 @@ lib/X11/oneko/sounds/cat.au
|
|||
<title>Configuration Files</title>
|
||||
|
||||
<para>If your port installs configuration files to
|
||||
<filename>PREFIX/etc</filename> (or
|
||||
elsewhere) do <emphasis>not</emphasis> simply list them in the
|
||||
<filename>pkg-plist</filename>. That will cause <command>pkg
|
||||
delete</command> to remove the files carefully edited by the
|
||||
user, and a re-installation will wipe them out.</para>
|
||||
<filename>PREFIX/etc</filename> (or elsewhere) do
|
||||
<emphasis>not</emphasis> simply list them in the
|
||||
<filename>pkg-plist</filename>. That will cause
|
||||
<command>pkg delete</command> to remove the files carefully
|
||||
edited by the user, and a re-installation will wipe them
|
||||
out.</para>
|
||||
|
||||
<para>Instead, install sample file(s) with a
|
||||
<filename>filename.sample</filename>
|
||||
suffix. Then copy the sample file to the real configuration
|
||||
file name, if it does not already exist. On deinstall
|
||||
delete the configuration file, but only if it is identical
|
||||
to the <filename>.sample</filename> file.
|
||||
You need to handle this both in the port
|
||||
<filename>filename.sample</filename> suffix. Then copy the
|
||||
sample file to the real configuration file name, if it does not
|
||||
already exist. On deinstall delete the configuration file, but
|
||||
only if it is identical to the <filename>.sample</filename>
|
||||
file. You need to handle this both in the port
|
||||
<filename>Makefile</filename>, and in the
|
||||
<filename>pkg-plist</filename> (for installation from the
|
||||
package).</para>
|
||||
|
|
@ -222,9 +215,9 @@ etc/orbit.conf.sample
|
|||
configuration file by default, leave the
|
||||
<literal>@exec</literal> line out of
|
||||
<filename>pkg-plist</filename> and add a
|
||||
<link linkend="porting-message">message</link> pointing out
|
||||
that the user must copy and edit the file before the software
|
||||
will work.</para>
|
||||
<link linkend="porting-message">message</link> pointing out that
|
||||
the user must copy and edit the file before the software will
|
||||
work.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="plist-dynamic">
|
||||
|
|
@ -235,9 +228,8 @@ etc/orbit.conf.sample
|
|||
<filename>pkg-plist</filename> file (with or without variable
|
||||
substitution), or embedded into the
|
||||
<filename>Makefile</filename> via
|
||||
<varname>PLIST_FILES</varname>,
|
||||
<varname>PLIST_DIRS</varname>, and
|
||||
<varname>PLIST_DIRSTRY</varname>. Even if the contents are
|
||||
<varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
|
||||
and <varname>PLIST_DIRSTRY</varname>. Even if the contents are
|
||||
auto-generated by a tool or a target in the Makefile
|
||||
<emphasis>before</emphasis> the inclusion into the Ports
|
||||
Collection by a committer, this is still considered a static
|
||||
|
|
@ -257,11 +249,10 @@ etc/orbit.conf.sample
|
|||
discover, for example, which port installs a certain file.
|
||||
Dynamic lists should be primarily used for complex ports where
|
||||
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
|
||||
<application>Javadoc</application>).</para>
|
||||
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 <application>Javadoc</application>).</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="plist-autoplist">
|
||||
|
|
@ -269,20 +260,18 @@ etc/orbit.conf.sample
|
|||
|
||||
<para>First, make sure your port is almost complete, with only
|
||||
<filename>pkg-plist</filename> missing. You may then run
|
||||
<command>make makeplist</command> to
|
||||
generate a <filename>pkg-plist</filename> automatically. This
|
||||
file must be double checked for correctness.</para>
|
||||
<command>make makeplist</command> to generate a
|
||||
<filename>pkg-plist</filename> automatically. This file must be
|
||||
double checked for correctness.</para>
|
||||
|
||||
<para>User configuration files should be
|
||||
removed, or installed as
|
||||
<filename>filename.sample</filename>.
|
||||
The <filename>info/dir</filename> file should not be listed
|
||||
and appropriate <filename>install-info</filename> lines should
|
||||
be added as noted in the
|
||||
<para>User configuration files should be removed, or installed as
|
||||
<filename>filename.sample</filename>. The
|
||||
<filename>info/dir</filename> file should not be listed and
|
||||
appropriate <filename>install-info</filename> lines should be
|
||||
added as noted in the
|
||||
<link linkend="makefile-info">info files</link> section. Any
|
||||
libraries installed by the port should be listed as specified
|
||||
in the <link linkend="porting-shlibs">shared libraries</link>
|
||||
libraries installed by the port should be listed as specified in
|
||||
the <link linkend="porting-shlibs">shared libraries</link>
|
||||
section.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue