Chapter 10. PLIST issues

Table of Contents

10.1. RCS ID
10.2. Semi-automatic PLIST generation
10.3. Tweaking output of make print-PLIST
10.4. Variable substitution in PLIST
10.5. Man page compression
10.6. Changing PLIST source with PLIST_SRC
10.7. Platform-specific and differing PLISTs
10.8. Sharing directories between packages

The PLIST file contains a package's “packing list”, i.e. a list of files that belong to the package (relative to the ${PREFIX} directory it's been installed in) plus some additional statements - see the pkg_create(1) man page for a full list. This chapter addresses some issues that need attention when dealing with the PLIST file (or files, see below!).

10.1. RCS ID

Be sure to add a RCS ID line as the first thing in any PLIST file you write:

    @comment $NetBSD: plist.html,v 1.68 2006/03/01 17:23:21 rillig Exp $

10.2. Semi-automatic PLIST generation

You can use the make print-PLIST command to output a PLIST that matches any new files since the package was extracted. See Section 14.16, “Other helpful targets” for more information on this target.

10.3. Tweaking output of make print-PLIST

If you have used any of the *-dirs packages, as explained in Section 10.8, “Sharing directories between packages”, you may have noticed that make print-PLIST outputs a set of @comments instead of real @dirrm 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 a lot during the update of packages.

The PRINT_PLIST_AWK variable takes a set of AWK patterns and actions that are used to filter the output of print-PLIST. You can append any chunk of AWK scripting you like to it, but be careful with quoting.

For example, to get all files inside the libdata/foo directory removed from the resulting PLIST:

    PRINT_PLIST_AWK+=       /^libdata\/foo/ { next; }

And to get all the @dirrm lines referring to a specific (shared) directory converted to @comments:

    PRINT_PLIST_AWK+=       /^@dirrm share\/specific/ { print "@comment " $$0; next; }

10.4. Variable substitution in PLIST

A number of variables are substituted automatically in PLISTs when a package is installed on a system. This includes the following variables:

${MACHINE_ARCH}, ${MACHINE_GNU_ARCH}

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 “${MACHINE_ARCH}” will be replaced by what uname -p gives. The same is done if the string ${MACHINE_GNU_ARCH} is embedded in PLIST somewhere - use this on packages that have GNU autoconf-created configure scripts.

Legacy note

There used to be a symbol “$ARCH” that was replaced by the output of uname -m, but that's no longer supported and has been removed.

${OPSYS}, ${LOWER_OPSYS}, ${OS_VERSION}

Some packages want to embed the OS name and version into some paths. To do this, use these variables in the PLIST:

  • ${OPSYS} - output of “uname -s

  • ${LOWER_OPSYS} - lowercase common name (eg. “solaris”)

  • ${OS_VERSION} - “uname -r

${PKGLOCALEDIR}

Packages that install locale files should list them in the PLIST as “${PKGLOCALEDIR}/locale/de/LC_MESSAGES/...” instead of “share/locale/de/LC_MESSAGES/...”. This properly handles the fact that different operating systems expect locale files to be either in share or lib by default.

For a complete list of values which are replaced by default, please look in bsd.pkg.mk (and search for PLIST_SUBST).

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 MESSAGE_SUBST (see Section 8.5, “Optional files”):

    PLIST_SUBST+=   SOMEVAR="somevalue"

This replaces all occurrences of “${SOMEVAR}” in the PLIST with “somevalue”.

10.5. Man page compression

Man pages should be installed in compressed form if MANZ is set (in bsd.own.mk), and uncompressed otherwise. To handle this in the PLIST file, the suffix “.gz” is appended/removed automatically for man pages according to MANZ and MANCOMPRESSED being set or not, see above for details. This modification of the PLIST file is done on a copy of it, not PLIST itself.

10.6. Changing PLIST source with PLIST_SRC

To use one or more files as source for the PLIST used in generating the binary package, set the variable PLIST_SRC to the names of that file(s). The files are later concatenated using cat(1), and order of things is important.

10.7. Platform-specific and differing PLISTs

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:

  • PLIST.common

  • PLIST.${OPSYS}

  • PLIST.${MACHINE_ARCH}

  • PLIST.${OPSYS}-${MACHINE_ARCH}

  • PLIST.common_end

10.8. Sharing directories between packages

A “shared directory” is a directory where multiple (and unrelated) packages install files. These directories are problematic because you have to add special tricks in the PLIST to conditionally remove them, or have some centralized package handle them.

Within pkgsrc, you'll find both approaches. If a directory is shared by a few unrelated packages, it's often not worth to add an extra package to remove it. Therefore, one simply does:

    @unexec ${RMDIR} %D/path/to/shared/directory 2>/dev/null || ${TRUE}

in the PLISTs of all affected packages, instead of the regular "@dirrm" line.

However, if the directory is shared across many packages, two different solutions are available:

  1. If the packages have a common dependency, the directory can be removed in that. For example, see textproc/scrollkeeper, which removes the shared directory share/omf.

  2. If the packages using the directory are not related at all (they have no common dependencies), a *-dirs package is used.

From now on, we'll discuss the second solution. To get an idea of the *-dirs packages available, issue:

    % cd .../pkgsrc
    % ls -d */*-dirs

Their use from other packages is very simple. The USE_DIRS variable takes a list of package names (without the “-dirs” part) together with the required version number (always pick the latest one when writing new packages).

For example, if a package installs files under share/applications, it should have the following line in it:

    USE_DIRS+=      xdg-1.1

After regenerating the PLIST using make print-PLIST, you should get the right (commented out) lines.

Note that even if your package is using $X11BASE, it must not depend on the *-x11-dirs packages. Just specify the name without that part and pkgsrc (in particular, mk/dirs.mk) will take care of it.