Chapter 19. PLIST issues
Prev | Part II. The pkgsrc developer's guide | Next

## Chapter 19. PLIST issues

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!).

## 19.1. RCS ID

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

    @comment $NetBSD $

An artificial space has been added between NetBSD and $, this is a workaround here to prevent CVS expanding to the filename of the guide. When adding the RCS ID the space should be omitted.

## 19.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 13.17, “Other helpful targets” for more information on this target.

## 19.3. Tweaking output of make print-PLIST

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; }

The `PRINT_PLIST_AWK` transformations are evaluated after the file list and directory list are sorted. `EARLY_PRINT_PLIST_AWK` is like `PRINT_PLIST_AWK` except it operates before the file list and directory list are sorted.

## 19.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”

For a list of values which are replaced by default, the output of make help topic=PLIST_SUBST as well as searching the `pkgsrc/mk` directory with grep for `PLIST_SUBST` should help.

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 12.5, “Optional files”):

    PLIST_SUBST+=   SOMEVAR="somevalue"

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

The `PLIST_VARS` variable can be used to simplify the common case of conditionally including some `PLIST` entries. It can be done by adding ``PLIST_VARS`+=foo` and setting the corresponding `PLIST.foo` variable to `yes` if the entry should be included. This will substitute “`${PLIST.foo}`” in the `PLIST` with either “`""`” or “`"@comment "`”. For example, in `Makefile`:

    PLIST_VARS+=    foo
    .if condition
    PLIST.foo=      yes
    .else

And then in `PLIST`:

    @comment $NetBSD $
    bin/bar
    man/man1/bar.1
    ${PLIST.foo}bin/foo
    ${PLIST.foo}man/man1/foo.1
    ${PLIST.foo}share/bar/foo.data

An artificial space has been added between NetBSD and $, this is a workaround here to prevent CVS expanding to the filename of the guide. When adding the RCS ID the space should be omitted.

## 19.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.

## 19.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 the order of things is important. The default for `PLIST_SRC` is `${PKGDIR}/PLIST`.

## 19.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`

## 19.8. Build-specific PLISTs

Some packages decide to generate hard-to-guess file names during installation that are hard to wire down.

In such cases, you can set the `GENERATE_PLIST` variable to shell code terminated (with a semicolon) that will output PLIST entries which will be appended to the PLIST

You can find one example in editors/xemacs:

    GENERATE_PLIST+=        ${ECHO} bin/${DISTNAME}-`${WRKSRC}/src/xemacs -sd`.dmp ;

which will append something like `bin/xemacs-21.4.23-54e8ea71.dmp` to the `PLIST`.

## 19.9. Sharing directories between packages

A “shared directory” 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.

In pkgsrc, it is now easy: Each package should create directories and install files as needed; pkg_delete will remove any directories left empty after uninstalling a package.

If a package needs an empty directory to work, create the directory during installation as usual, and also add an entry to the PLIST:

    @pkgdir path/to/empty/directory

or take a look at `MAKE_DIRS` and `OWN_DIRS`.

Prev | Up | Next
Chapter 18. Buildlink methodology | Home | Chapter 20. The pkginstall framework