KDE_BUILD_PLIST: The new plist.* system for KDE/FreeBSD

    Copyright (c) Alan Eldridge (alane@freebsd.org). Covered by BSD License.

    $Id: kde-build-plist.pod,v 1.2 2003/03/23 20:38:41 alane Exp $

    The primary goal of this system is to eliminate PLIST_SUB from the KDE
    ports. This ultimately makes it easier to maintain the plists when
    upgrading or making changes that will affect their content.

  Tools

    You need the have my script "gen-plist", or an equivalent which will do
    an installation in a temporary directory in order to build the plist.

    You can get this script from: http://people.freebsd.org/~alane/gen-plist
    on my FreeBSD web page. (It says "ksh" up top, but should run under BSD
    "sh" just fine. Let me know if it doesn't.)

    Here's the help from gen-plist:

      This is 'gen-plist' v. 1.1.
      Copyright (c) 2002 Alan Eldridge <alane@geeksrus.net>.

      Usage: gen-plist [options] [--] [install-plist [uninstall-plist]] [make opts]
      Options:
              -h,--help       Show this help.
              -V,--version    Show version number.
              -x,--debug      Turn on shell command tracing.
              -m,--man <file> Write Makefile man page entries here.
              -p,--prefix <dir>
                              Installs to here [/usr/local].
              -v.--var        Variable containing top level dir [DESTDIR].
              --              Stop option processing.

      NOTES:
      1. If neither file is specified, writes the plist to stdout.
      2. If only an install-plist file is specified, writes the uninstall part
         of the plist there, too.
      3. If -m/--man is not specified, does not write any info about man pages.

  Overview

    The idea behind this mechanism is that instead of a single "pkg-plist"
    file, the plist file is constructed from fragments, based on what knobs
    the user sets when making the port.

    Every port that uses this feature has a "files/plist.base" file and a
    "files/plist-base.rm" file. These are the basic files that are installed
    if all knobs are set to not build extra features.

  Makefile usage

    The port "Makefile" must contain the line:

      KDE_BUILD_PLIST= yes

    in order to activate the feature.

    Then, for each knob which activates extra installed files, a line:

      PLIST_APPEND+= plist.foo

    is added if the knob is activated. This tells the plist-build system
    that there is a file "file/plist.foo" containing files to install, and
    optionally a file "files/plist.foo.rm" containing instructions to remove
    directories on port uninstall. If this second file is empty, it can be
    omitted.

  Creating the base files

    *   Build the package with knobs set not to create any extra files.

    *   Create the "files" subdirectory if it does not exist.

    *   Run "gen-plist files/plist.base file/plist.base.rm" from the port
        directory. This creates your baseline file list for comparisons.

  Creating the extra plist.* files

    For each knob that can add files or directories to the installation, do:

    *   Build the port with just that one knob set to the value that will
        add the files or directories that correspond to it.

    *   Run "gen-plist p p.rm" from the port dir.

    *   Create "files/plist.foo" by running "comm -13 files/plist.base p >
        files/plist.foo".

    *   Create "files/plist.foo.rm" by running "diff files/plist.base.rm
        p.rm" | "grep" '>' | "cut -c3-" > "files/plist.foo.rm"

    When you are done, be sure to remove the "p" and "p.rm" files.

  Remaking the plist

    There is a target called "kde-plist" in "bsd.kde.mk" which will rebuild
    the "${WRKDIR}/plist" file from the components based on the knobs
    specified.

  Where's the magic hidden?

    Look at the bottom of "bsd.kde.mk" to see how this all happens.

     LocalWords:  var DESTDIR pkg Exp