From 0fb39c28400df380179d82fbdd24740340af5172 Mon Sep 17 00:00:00 2001
From: espie <espie@openbsd.org>
Date: Mon, 13 Sep 2010 12:24:33 +0000
Subject: [PATCH] document make-plist

---
 infrastructure/man/man1/make-plist.1 | 127 +++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 infrastructure/man/man1/make-plist.1

diff --git a/infrastructure/man/man1/make-plist.1 b/infrastructure/man/man1/make-plist.1
new file mode 100644
index 00000000000..bc8e702e942
--- /dev/null
+++ b/infrastructure/man/man1/make-plist.1
@@ -0,0 +1,127 @@
+.\"	$OpenBSD: make-plist.1,v 1.1 2010/09/13 12:24:33 espie Exp $
+.\"
+.\" Copyright (c) 2010 Marc Espie <espie@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: September 13 2010 $
+.Dt MAKE-PLIST 1
+.Os
+.Sh NAME
+.Nm make-plist
+.Nd create or update packing-list(s) for a given port.
+.Sh SYNOPSIS
+.Nm make-plist
+.Ar var=value ...
+.Sh DESCRIPTION
+.Nm
+is a helper script for the target
+.Ar update-plist
+in
+.Xr bsd.port.mk 5 .
+.Pp
+.Nm
+looks in
+.Ev MULTI_PACKAGES
+to know which packing-lists to regenerate,
+the corresponding filenames are passed as variable assignments
+.Ar PLIST-sub=filename .
+.Pp
+.Nm
+will scan all files under
+.Ev DESTDIR
+and dispatch them into corresponding subpackages, according to
+.Ev PREFIX-sub=directory .
+.Pp
+.Nm
+is usually run as root to be able to thoroughly scan
+.Ev DESTDIR .
+However, it switches back to
+.Ev OWNER
+and
+.Ev GROUP
+before writing new packing-lists.
+.Pp
+.Nm
+will avoid reporting files in
+.Ev OKAY_FILES
+.Po
+used for storing cookies generated under
+.Pa ${WRKINST}
+by
+.Ar fake
+.Pc .
+.Pp
+By default, files and directories will end up in the main subpackage,
+unless there already exists packing-lists, in which case
+.Nm
+will dispatch them to the most likely packing-list.
+.Pp
+.Nm
+will also scan dependencies for those packages, in order to strip common
+directories.
+Those are passed as
+.Ar DEPPATH-sub=list ,
+a list of
+.Ev FULLPKGPATH
+for each subpackage.
+These may require
+.Bd -literal -indent offset
+make print-list
+.Ed
+.Pp
+to be run to figure out common directories.
+.Pp
+Variables from
+.Ev SUBST_VARS
+should be
+back-substituted into the regenerated packing-lists,
+and so should be passed as
+.Ar var=value
+on the command line.
+.Pp
+Shared libraries versions will also be backsubstituted.
+In addition,
+.Nm
+will complain if it doesn't find the corresponding
+.Ar LIBname_VERSION=value
+assignment.
+.Pp
+.Nm
+will separate shared files fragments unless
+.Ev SHARED_ONLY
+is set.
+.Pp
+.Nm
+also has limited understanding of existing fragments, and will try to
+dispatch entries to the most likely fragment.
+.Pp
+Existing packing-lists are scanned for non-file entries, such as
+.Cm newuser ,
+.Cm mode ,
+or
+.Cm exec
+markers.
+Those will be inserted into the updated packing-lists at the most likely
+position.
+.Sh BUGS
+.Nm
+might be the most complicated piece of the ports infrastructure.
+It tries its best at doing something which is definitely not trivial,
+so it will require manual intervention in specific cases.
+It is especially bad at figuring common directories in inter-dependent
+subpackages.
+.Sh SEE ALSO
+.Xr pkg_add 1 ,
+.Xr pkg_create 1 ,
+.Xr bsd.port.mk 5 .