267 lines
9.1 KiB
XML
267 lines
9.1 KiB
XML
<!-- $NetBSD: plist.xml,v 1.19 2009/08/25 13:19:50 wiz Exp $ -->
|
|
|
|
<chapter id="plist">
|
|
<title>PLIST issues</title>
|
|
|
|
<para>The <filename>PLIST</filename> file contains a package's
|
|
<quote>packing list</quote>, i.e. a list of files that belong to
|
|
the package (relative to the <filename>${PREFIX}</filename>
|
|
directory it's been installed in) plus some additional statements
|
|
- see the &man.pkg.create.1; man page for a full list.
|
|
This chapter addresses some issues that need attention when
|
|
dealing with the <filename>PLIST</filename> file (or files, see
|
|
below!).</para>
|
|
|
|
|
|
<sect1 id="rcs-id">
|
|
<title>RCS ID</title>
|
|
|
|
<para>Be sure to add a RCS ID line as the first thing in any
|
|
<filename>PLIST</filename> file you write:</para>
|
|
|
|
<programlisting>
|
|
@comment $NetBSD$
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="automatic-plist-generation">
|
|
<title>Semi-automatic <filename>PLIST</filename> generation</title>
|
|
|
|
<para>You can use the <command>make print-PLIST</command> command
|
|
to output a PLIST that matches any new files since the package
|
|
was extracted. See <xref linkend="build.helpful-targets"/> for
|
|
more information on this target.</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="print-PLIST">
|
|
<title>Tweaking output of <command>make print-PLIST</command></title>
|
|
|
|
<para>If you have used any of the *-dirs packages, as explained in
|
|
<xref linkend="faq.common-dirs"/>, you may have noticed that
|
|
<command>make print-PLIST</command> outputs a set of
|
|
<varname>@comment</varname>s instead of real
|
|
<varname>@dirrm</varname> lines. You can also do this for
|
|
specific directories and files, so that the results of that
|
|
command are very close to reality. This helps <emphasis>a
|
|
lot</emphasis> during the update of packages.</para>
|
|
|
|
<para>The <varname>PRINT_PLIST_AWK</varname> variable takes a set
|
|
of AWK patterns and actions that are used to filter the output of
|
|
print-PLIST. You can <emphasis>append</emphasis> any chunk of AWK
|
|
scripting you like to it, but be careful with quoting.</para>
|
|
|
|
<para>For example, to get all files inside the
|
|
<filename>libdata/foo</filename> directory removed from the
|
|
resulting PLIST:</para>
|
|
|
|
<programlisting>
|
|
PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
|
|
</programlisting>
|
|
|
|
<para>And to get all the <varname>@dirrm</varname> lines referring
|
|
to a specific (shared) directory converted to
|
|
<varname>@comment</varname>s:</para>
|
|
|
|
<programlisting>
|
|
PRINT_PLIST_AWK+= /^@dirrm share\/specific/ { print "@comment " $$0; next; }
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="plist.misc">
|
|
<title>Variable substitution in PLIST</title>
|
|
|
|
<para>A number of variables are substituted automatically in
|
|
PLISTs when a package is installed on a system. This includes the
|
|
following variables:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><varname>${MACHINE_ARCH}</varname>, <varname>${MACHINE_GNU_ARCH}</varname></term>
|
|
|
|
<listitem>
|
|
<para>Some packages like emacs and perl embed information
|
|
about which architecture they were built on into the
|
|
pathnames where they install their files. To handle this
|
|
case, PLIST will be preprocessed before actually used, and
|
|
the symbol
|
|
<quote><varname>${MACHINE_ARCH}</varname></quote> will be
|
|
replaced by what <command>uname -p</command> gives. The
|
|
same is done if the string
|
|
<varname>${MACHINE_GNU_ARCH}</varname> is embedded in
|
|
PLIST somewhere - use this on packages that have GNU
|
|
autoconf-created configure scripts.</para>
|
|
|
|
<note>
|
|
<title>Legacy note</title>
|
|
|
|
<para>There used to be a symbol
|
|
<quote><varname>$ARCH</varname></quote> that
|
|
was replaced by the output of <command>uname
|
|
-m</command>, but that's no longer supported and has
|
|
been removed.</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>${OPSYS}</varname>, <varname>${LOWER_OPSYS}</varname>, <varname>${OS_VERSION}</varname></term>
|
|
|
|
<listitem>
|
|
<para>Some packages want to embed the OS name and version
|
|
into some paths. To do this, use these variables in the
|
|
<filename>PLIST</filename>:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><varname>${OPSYS}</varname> - output of <quote><command>uname -s</command></quote></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><varname>${LOWER_OPSYS}</varname> - lowercase common name (eg. <quote>solaris</quote>)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><varname>${OS_VERSION}</varname> - <quote><command>uname -r</command></quote></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>For a complete list of values which are replaced by
|
|
default, please look in <filename>bsd.pkg.mk</filename> (and
|
|
search for <varname>PLIST_SUBST</varname>).</para>
|
|
|
|
<para>If you want to change other variables not listed above, you
|
|
can add variables and their expansions to this variable in the
|
|
following way, similar to <varname>MESSAGE_SUBST</varname> (see <xref
|
|
linkend="components.optional"/>):</para>
|
|
|
|
<programlisting>
|
|
PLIST_SUBST+= SOMEVAR="somevalue"
|
|
</programlisting>
|
|
|
|
<para>This replaces all occurrences of <quote>${SOMEVAR}</quote>
|
|
in the <filename>PLIST</filename> with
|
|
<quote>somevalue</quote>.</para>
|
|
|
|
|
|
<para>The <varname>PLIST_VARS</varname> variable can be used to simplify
|
|
the common case of conditionally including some
|
|
<filename>PLIST</filename> entries. It can be done by adding
|
|
<literal><varname>PLIST_VARS</varname>+=foo</literal> and
|
|
setting the corresponding <varname>PLIST.foo</varname> variable
|
|
to <literal>yes</literal> if the entry should be included.
|
|
This will substitute <quote><varname>${PLIST.foo}</varname></quote>
|
|
in the <filename>PLIST</filename> with either
|
|
<quote><literal>""</literal></quote> or
|
|
<quote><literal>"@comment "</literal></quote>.
|
|
For example, in <filename>Makefile</filename>:</para>
|
|
|
|
<programlisting>
|
|
PLIST_VARS+= foo
|
|
.if <replaceable>condition</replaceable>
|
|
PLIST.foo= yes
|
|
.else
|
|
</programlisting>
|
|
|
|
<para>And then in <filename>PLIST</filename>:</para>
|
|
<programlisting>
|
|
@comment $NetBSD$
|
|
bin/bar
|
|
man/man1/bar.1
|
|
${PLIST.foo}bin/foo
|
|
${PLIST.foo}man/man1/foo.1
|
|
${PLIST.foo}share/bar/foo.data
|
|
${PLIST.foo}@dirrm share/bar
|
|
</programlisting>
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="manpage-compression">
|
|
<title>Man page compression</title>
|
|
|
|
<para>Man pages should be installed in compressed form if
|
|
<varname>MANZ</varname> is set (in <filename>bsd.own.mk</filename>),
|
|
and uncompressed otherwise. To handle this in the
|
|
<filename>PLIST</filename> file, the suffix <quote>.gz</quote> is
|
|
appended/removed automatically for man pages according to
|
|
<varname>MANZ</varname> and <varname>MANCOMPRESSED</varname> being set
|
|
or not, see above for details. This modification of the
|
|
<filename>PLIST</filename> file is done on a copy of it, not
|
|
<filename>PLIST</filename> itself.</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="using-PLIST_SRC">
|
|
<title>Changing PLIST source with <varname>PLIST_SRC</varname></title>
|
|
|
|
<para>To use one or more files as source for the <filename>PLIST</filename> used
|
|
in generating the binary package, set the variable
|
|
<varname>PLIST_SRC</varname> to the names of that file(s).
|
|
The files are later concatenated using &man.cat.1;, and the order of things is
|
|
important. The default for <varname>PLIST_SRC</varname> is
|
|
<filename>${PKGDIR}/PLIST</filename>.</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="platform-specific-plist">
|
|
<title>Platform-specific and differing PLISTs</title>
|
|
|
|
<para>Some packages decide to install a different set of files based on
|
|
the operating system being used. These differences can be
|
|
automatically handled by using the following files:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><filename>PLIST.common</filename></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>PLIST.${OPSYS}</filename></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>PLIST.${MACHINE_ARCH}</filename></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>PLIST.${OPSYS}-${MACHINE_ARCH}</filename></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>PLIST.common_end</filename></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="faq.common-dirs">
|
|
<title>Sharing directories between packages</title>
|
|
|
|
<para>A <quote>shared directory</quote> is a directory where
|
|
multiple (and unrelated) packages install files. These
|
|
directories were problematic because you had to add special
|
|
tricks in the PLIST to conditionally remove them, or have some
|
|
centralized package handle them.</para>
|
|
|
|
<para>In pkgsrc, it is now easy: Each package should create
|
|
directories and install files as needed; <command>pkg_delete</command>
|
|
will remove any directories left empty after uninstalling a
|
|
package.</para>
|
|
|
|
<para>If a package needs an empty directory to work, create
|
|
the directory during installation as usual, and also add an
|
|
entry to the PLIST:
|
|
<programlisting>
|
|
@pkgdir path/to/empty/directory
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|