igor -Ry and some other rewording and fixes.
Differential Revision: https://reviews.freebsd.org/D646 Reviewed by: wblock Sponsored by: Absolight
This commit is contained in:
Mathieu Arnold
parent
50d651dc29
commit
687478c7b6
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=45619
1 changed files with 80 additions and 67 deletions
|
|
@ -19,45 +19,47 @@
|
|||
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
|
||||
ports). To make this easy, any instances in
|
||||
<filename>pkg-plist</filename> of <literal>%%OSREL%%</literal>,
|
||||
<literal>%%PERL_VER%%</literal>, and
|
||||
<literal>%%PERL_VERSION%%</literal> will be substituted for
|
||||
<literal>%%PERL_VERSION%%</literal> will be substituted
|
||||
appropriately. The value of <literal>%%OSREL%%</literal> is the
|
||||
numeric revision of the operating system (e.g.,
|
||||
numeric revision of the operating system (for example,
|
||||
<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>).
|
||||
of <command>perl</command> (for example, <literal>5.8.9</literal>).
|
||||
Several other
|
||||
<literal>%%<replaceable>VARS</replaceable>%%</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
|
||||
<para>To make other substitutions, set
|
||||
<varname>PLIST_SUB</varname> with a list of
|
||||
<literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
|
||||
pairs and instances of
|
||||
<literal>%%<replaceable>VAR</replaceable>%%</literal> will be
|
||||
substituted with <replaceable>VALUE</replaceable> in the
|
||||
substituted with <replaceable>VALUE</replaceable> in
|
||||
<filename>pkg-plist</filename>.</para>
|
||||
|
||||
<para>For instance, if you have a port that installs many files
|
||||
in a version-specific subdirectory, you can put something
|
||||
like</para>
|
||||
<para>For instance, if a port installs many files
|
||||
in a version-specific subdirectory, use a placeholder for the
|
||||
version so that <filename>pkg-plist</filename> does not have to
|
||||
be regenerated every time the port is updated. For
|
||||
example:</para>
|
||||
|
||||
<programlisting>OCTAVE_VERSION= 2.0.13
|
||||
<programlisting>OCTAVE_VERSION= ${PORTREVISION}
|
||||
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
|
||||
up in <filename>pkg-plist</filename>. When
|
||||
the port is upgraded, it will not be necessary to edit dozens (or in some
|
||||
cases, hundreds) of lines in
|
||||
<filename>pkg-plist</filename>.</para>
|
||||
|
||||
<para>If your port installs files conditionally on the options
|
||||
set in the port, the usual way of handling it is prefixing the
|
||||
<para>If files are installed conditionally on the options
|
||||
set in the port, the usual way of handling it is prefixing
|
||||
<filename>pkg-plist</filename> lines with a
|
||||
<literal>%%OPT%%</literal> for lines needed when the option is
|
||||
enabled, or <literal>%%NO_OPT%%</literal> when the option is
|
||||
|
|
@ -66,13 +68,13 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
|
|||
linkend="options_sub"/> for more information.</para>
|
||||
|
||||
<para>For instance, if there are files that are only installed
|
||||
when the <literal>X11</literal> option is enabled, and the
|
||||
when the <literal>X11</literal> option is enabled, and
|
||||
<filename>Makefile</filename> has:</para>
|
||||
|
||||
<programlisting>OPTIONS_DEFINE= X11
|
||||
OPTIONS_SUB= yes</programlisting>
|
||||
|
||||
<para>In the <filename>pkg-plist</filename> file, put
|
||||
<para>In <filename>pkg-plist</filename>, put
|
||||
<literal>%%X11%%</literal> in front of the lines only being
|
||||
installed when the option is enabled, like this :</para>
|
||||
|
||||
|
|
@ -83,9 +85,9 @@ OPTIONS_SUB= yes</programlisting>
|
|||
<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
|
||||
<filename>WRKDIR/.PLIST.mktmp</filename>). So if the port
|
||||
builds <filename>PLIST</filename> on the fly, do so in or before
|
||||
<buildtarget>pre-install</buildtarget>. Also, if your port
|
||||
<buildtarget>pre-install</buildtarget>. Also, if the port
|
||||
needs to edit the resulting file, do so in
|
||||
<buildtarget>post-install</buildtarget> to a file named
|
||||
<filename>TMPPLIST</filename>.</para>
|
||||
|
|
@ -108,13 +110,13 @@ OPTIONS_SUB= yes</programlisting>
|
|||
<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
|
||||
<filename>TMPPLIST</filename> is written, that is, in
|
||||
<buildtarget>pre-install</buildtarget> or earlier.</para>
|
||||
|
||||
<para>From time to time, the <varname>OPTIONS_SUB</varname>
|
||||
construct is not enough, in those cases, adding a specific
|
||||
<literal>TAG</literal> to the <varname>PLIST_SUB</varname>
|
||||
variable inside the <filename>Makefile</filename> with a special
|
||||
<para>From time to time, using <varname>OPTIONS_SUB</varname>
|
||||
is not enough. In those cases, adding a specific
|
||||
<literal><replaceable>TAG</replaceable></literal> to <varname>PLIST_SUB</varname>
|
||||
inside the <filename>Makefile</filename> with a special
|
||||
value of <literal>@comment</literal>, makes package tools to
|
||||
ignore the line. For instance, if some files are only installed
|
||||
when the <literal>X11</literal> option is on and the
|
||||
|
|
@ -139,8 +141,8 @@ PLIST_SUB+= X11I386="@comment "
|
|||
<para>When being de-installed, A port has to remove empty
|
||||
directories it created. 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
|
||||
that are specifically created by the port. Subdirectories
|
||||
must be deleted before deleting parent
|
||||
directories.</para>
|
||||
|
||||
<programlisting> :
|
||||
|
|
@ -152,8 +154,8 @@ 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
|
||||
errors because other ports share the same directory.
|
||||
Use <literal>@dirrmtry</literal> to remove only empty
|
||||
directories without warning.</para>
|
||||
|
||||
<programlisting>@dirrmtry share/doc/gimp</programlisting>
|
||||
|
|
@ -169,33 +171,38 @@ 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 must be present when the package
|
||||
is created. If they are not created by the port code, create
|
||||
them in the <filename>Makefile</filename>:</para>
|
||||
|
||||
<programlisting>@exec mkdir -p %D/share/foo/templates</programlisting>
|
||||
<programlisting>post-stage:
|
||||
@${MKDIR} ${STAGEDIR}${PREFIX}/some/directory</programlisting>
|
||||
|
||||
<para>Add the directory to <filename>pkg-plist</filename>
|
||||
like any other. For example, if the directory has files
|
||||
created when the port is used:</para>
|
||||
|
||||
<programlisting>@dirrmtry some/directory</programlisting>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="plist-config">
|
||||
<title>Configuration Files</title>
|
||||
|
||||
<para>If your port installs configuration files to
|
||||
<para>If the port installs configuration files to
|
||||
<filename>PREFIX/etc</filename> (or elsewhere) do
|
||||
<emphasis>not</emphasis> simply list them in the
|
||||
<emphasis>not</emphasis> list them in
|
||||
<filename>pkg-plist</filename>. That will cause
|
||||
<command>pkg delete</command> to remove the files carefully
|
||||
<command>pkg delete</command> to remove files that have been carefully
|
||||
edited by the user, and a re-installation will wipe them
|
||||
out.</para>
|
||||
|
||||
<para>Instead, install sample file(s) as
|
||||
<filename><replaceable>filename</replaceable>.sample</filename>,
|
||||
and for each sample file, add this line to your
|
||||
<filename>pkg-plist</filename>.</para>
|
||||
<para>Instead, install sample files with a
|
||||
<filename><replaceable>filename</replaceable>.sample</filename>
|
||||
extension. The <literal>@sample</literal> macro automates this,
|
||||
see <xref linkend="plist-keywords-sample"/> for what it does
|
||||
exactly. For each sample file, add a line to
|
||||
<filename>pkg-plist</filename>:</para>
|
||||
|
||||
<programlisting>@sample etc/orbit.conf.sample</programlisting>
|
||||
|
||||
|
|
@ -209,19 +216,19 @@ lib/X11/oneko/sounds/cat.au
|
|||
|
||||
<tip>
|
||||
<para>When a port installs its configuration in a subdirectory
|
||||
of <filename>${PREFIX}/etc</filename>, it should be in
|
||||
of <filename>${PREFIX}/etc</filename>, use
|
||||
<varname>ETCDIR</varname>, which defaults to
|
||||
<literal>${PREFIX}/etc/${PORTNAME}</literal>, it can be
|
||||
overridden in the ports <filename>Makefile</filename> if there
|
||||
is a convention for the port to use some other directory. The
|
||||
<literal>%%ETCDIR%%</literal> macro should be used in its
|
||||
stead in the <filename>pkg-plist</filename> file.</para>
|
||||
<literal>%%ETCDIR%%</literal> macro will be used in its
|
||||
stead in <filename>pkg-plist</filename>.</para>
|
||||
</tip>
|
||||
|
||||
<note>
|
||||
<para>The sample configuration files should always have the
|
||||
<filename>.sample</filename> 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:</para>
|
||||
|
||||
<programlisting>@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 @@ etc/orbit.conf-dist
|
|||
<title>Dynamic Versus Static Package List</title>
|
||||
|
||||
<para>A <emphasis>static package list</emphasis> is a package
|
||||
list which is available in the Ports Collection either as a
|
||||
<filename>pkg-plist</filename> file (with or without variable
|
||||
list which is available in the Ports Collection either as
|
||||
<filename>pkg-plist</filename> (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
|
||||
auto-generated by a tool or a target in the Makefile
|
||||
<emphasis>before</emphasis> the inclusion into the Ports
|
||||
Collection by a committer (e.g., using <command>make
|
||||
Collection by a committer (for example, using <command>make
|
||||
makeplist></command>), this is still considered a static list,
|
||||
since it is possible to examine it without having to download or
|
||||
compile the distfile.</para>
|
||||
|
|
@ -281,8 +288,8 @@ etc/orbit.conf-dist
|
|||
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>
|
||||
upon the version of dependent software used. For example, ports which
|
||||
generate docs with <application>Javadoc</application>.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="plist-autoplist">
|
||||
|
|
@ -290,7 +297,7 @@ etc/orbit.conf-dist
|
|||
|
||||
<para>First, make sure the port is almost complete, with only
|
||||
<filename>pkg-plist</filename> missing. Running <command>make
|
||||
makeplist</command> will show what should be put in
|
||||
makeplist</command> will show an example for
|
||||
<filename>pkg-plist</filename>. The output of
|
||||
<buildtarget>makeplist</buildtarget> must be double checked for
|
||||
correctness as it tries to automatically guess a few things, and
|
||||
|
|
@ -298,12 +305,12 @@ etc/orbit.conf-dist
|
|||
|
||||
<para>User configuration files should be installed as
|
||||
<filename><replaceable>filename</replaceable>.sample</filename>,
|
||||
as it is described in <xref linkend="plist-config"/>. The
|
||||
<filename>info/dir</filename> file should not be listed and
|
||||
appropriate <filename>install-info</filename> lines should be
|
||||
as it is described in <xref linkend="plist-config"/>.
|
||||
<filename>info/dir</filename> must not be listed and
|
||||
appropriate <filename>install-info</filename> lines must 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
|
||||
must be listed as specified in the <link
|
||||
linkend="porting-shlibs">shared libraries</link>
|
||||
section.</para>
|
||||
</sect1>
|
||||
|
|
@ -412,9 +419,9 @@ etc/orbit.conf-dist
|
|||
<replaceable>command</replaceable></title>
|
||||
|
||||
<para>Execute <replaceable>command</replaceable> 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
|
||||
<literal>@cwd</literal> is set to <filename
|
||||
class="directory">/usr/local</filename> and the last
|
||||
extracted file was <filename>bin/emacs</filename>.</para>
|
||||
|
|
@ -527,7 +534,7 @@ etc/orbit.conf-dist
|
|||
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.</para>
|
||||
</sect3>
|
||||
|
|
@ -542,8 +549,8 @@ etc/orbit.conf-dist
|
|||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2 xml:id="plist-keywords-your-own">
|
||||
<title>Creating Your Own Keyword</title>
|
||||
<sect2 xml:id="plist-keywords-creating-new">
|
||||
<title>Creating New Keywords</title>
|
||||
|
||||
<para>Package list files can be extended by keywords that are
|
||||
defined in the <filename
|
||||
|
|
@ -551,7 +558,7 @@ etc/orbit.conf-dist
|
|||
The settings for each keyword lives in a
|
||||
<acronym>YAML</acronym> file named
|
||||
<filename><replaceable>keyword</replaceable>.yaml</filename>.
|
||||
The file must contain at least one of the following
|
||||
The file must contain at least one of the next
|
||||
sections:</para>
|
||||
|
||||
<variablelist>
|
||||
|
|
@ -713,13 +720,19 @@ post-deinstall: |
|
|||
|
||||
<programlisting>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}"
|
||||
|
|
|
|||
Loading…
Reference in a new issue