document new helper

2 files changed, 88 insertions, 2 deletions

diff --git a/share/man/man1/Makefile b/share/man/man1/Makefile
index ff11619c9a6..f54494417a9 100644
--- a/share/man/man1/Makefile
+++ b/share/man/man1/Makefile
@@ -1,10 +1,11 @@
-#	$OpenBSD: Makefile,v 1.16 2019/09/08 17:20:51 daniel Exp $
+#	$OpenBSD: Makefile,v 1.17 2019/11/12 16:39:10 espie Exp $
 #	$NetBSD: Makefile,v 1.4 1994/12/22 10:48:04 cgd Exp $
 
 MAN=	clang-local.1 help.1 intro.1 gcc-local.1
 
 # ports tools doc
-MAN+=	check-lib-depends.1 clean-old-distfiles.1 dpb-replay.1 dpb.1 \
+MAN+=	build-debug-info.1 check-lib-depends.1 clean-old-distfiles.1 \
+	dpb-replay.1 dpb.1 \
 	outdated-perl-ports.1 \
 	pkg_check-problems.1 pkg_check-manpages.1 pkg_outdated.1 \
 	pkg_subst.1 \
diff --git a/share/man/man1/build-debug-info.1 b/share/man/man1/build-debug-info.1
new file mode 100644
index 00000000000..c066ca80f2e
--- /dev/null
+++ b/share/man/man1/build-debug-info.1
@@ -0,0 +1,85 @@
+.\"	$OpenBSD: build-debug-info.1,v 1.1 2019/11/12 16:39:10 espie Exp $
+.\"
+.\" Copyright (c) 2019 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: November 12 2019 $
+.Dt BUILD-DEBUG-INFO 1
+.Os
+.Sh NAME
+.Nm build-debug-info
+.Nd generate packing-lists and Makefiles for debug packages
+.Sh SYNOPSIS
+.Nm
+.Op Fl Fmnqvx
+.Op Fl P Ar pkgdir
+.Op Fl W Ar wrkinst
+.Fl -
+.Ar pkg_create_args ...
+.Sh DESCRIPTION
+.Nm
+is a helper script for generating debug package information in
+.Xr bsd.port.mk 5 ,
+with similar calling conventions to
+.Xr update-plist 1 .
+.Pp
+Along with options and environment variables,
+.Nm
+uses the exact same options and arguments that would be passed to
+.Xr pkg_create 1 .
+Since
+.Xr pkg_create 1
+normally takes one single actual
+.Ar pkgname ,
+there is no ambiguity in
+.Ev MULTI_PACKAGES
+situations.
+.Pp
+The first set of arguments correspond to the
+.Sq default package .
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl P Ar pkgdir
+directory used  for generating output (mandatory).
+.It Fl q
+Quiet mode.
+Do not display status progress messages.
+Note that this is not the opposite of verbose mode.
+.It Fl v
+Verbose mode.
+Explain about directories stripped from dependencies.
+Note that this is not the opposite of quiet mode.
+.It Fl W Ar wrkinst
+directory with actual files from the fake staging area,
+needed for figuring out what to do with hard links.
+.El
+.Pp
+.Nm
+will read each packing-list
+.Ar list
+and generate a corresponding
+.Ar debug-list
+under
+.Ar pkgdir .
+.Pp
+The full list of Makefile rules needed to generate those files and
+directories will be written as
+.Ar pkgdir/Makefile .
+.Pp
+.Sh SEE ALSO
+.Xr pkg_add 1 ,
+.Xr pkg_create 1 ,
+.Xr update-plist 1 ,
+.Xr bsd.port.mk 5