document how DEBUG_PACKAGES works

1 files changed, 74 insertions, 2 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index a62ed0349fc..e3d48870b07 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.516 2019/07/14 12:41:33 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.517 2019/11/12 16:38:44 espie Exp $
 .\"
 .\" Copyright (c) 2000-2008 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 14 2019 $
+.Dd $Mdocdate: November 12 2019 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -716,6 +716,9 @@ show the contents of ${name1} ${name2} ...,
 one variable value per line.
 Mostly used from recursive makes, or to know the contents of another
 port's variables without guessing wrongly.
+.It Cm show-debug-info
+Displays the information that was generated by
+.Xr build-debug-info 1 .
 .It Cm show-fake-size
 Print the size of ${WRKINST}.
 Used by some options of
@@ -1489,6 +1492,23 @@ Many ports ignore it.
 .It Ev CXXOPTS
 User settings.
 Supplementary options appended to ${CXXFLAGS} for building.
+.It Ev DEBUG_CONFIGURE_ARGS
+Supplementary ${CONFIGURE_ARGS}
+for enabling the generation of debugging information.
+.It Ev DEBUG_PACKAGES
+List of ${SUBPACKAGES} for which debug packages should be built "on the side".
+Usually set as
+.Li DEBUG_PACKAGES=${BUILD_PACKAGES}
+for packages where debug information is desireable.
+Note the subpackages with
+.Li PKG_ARCH=*
+will automatically be stripped from that list.
+See
+.Sx THE DEBUG_PACKAGES INFRASTRUCTURE
+below for details.
+.It Ev DEBUGINFO_ARCHS
+List of archs for which debug information may be provided as extra packages.
+Normally only amd64 for performance reasons.
 .It Ev DESTDIR
 See
 .Ev DESTDIRNAME .
@@ -3602,6 +3622,58 @@ during
 (see the
 .Sx FILES
 section above for details).
+.Sh THE DEBUG_PACKAGES INFRASTRUCTURE
+If
+.Ev DEBUG_PACKAGES
+is not empty, debug packages will be built "on the side".
+Since debug information is usually large, this is controlled on a per-arch
+basis with
+.Ev DEBUGINFO_ARCHS
+controlling the behavior (set to amd64 by default).
+.Pp
+During the normal
+.Cm package
+target ,
+.Xr build-debug-info 1
+will be invoked to deduce debug packing-lists from the normal packing-lists,
+and some extra makefile rules will be invoked to set aside the debug 
+information.
+.Pp
+Then each normal package will have a "shadow" debug-* package built alongside
+it, with the exact same package signature, except it will also be tied closely
+with the normal package.
+.Pp
+Figuring out what files contain debug information is entirely achieved through
+.Cm @bin ,
+.Cm @lib ,
+.Cm @so
+and
+.Cm @static-lib
+annotations in the base packing-lists.
+.Pp
+The actual debug packages are not registered through
+.Xr register-plist 1
+since the information was automatically generated.
+.Pp
+debug package names and debug package filenames are added to
+.Ev PKGNAMES
+and
+.Ev PKGFILES
+respectively for introspection purpose.
+.Pp
+.Xr egdb 1
+from ports can read debug information from a separate file, as long as
+the original ELF file was annotated with a debuginfo link.
+.Pp
+That feature is used to set debug information on the side, in
+.Pa .debug/
+subdirectories alongside the normal binaries, shared objects and shared 
+libraries.
+.Pp
+For static libraries, the information can't be separated, instead the full
+static library with debug information is provided in the
+.Pa .debug/
+subdirectory, while the normal static library gets stripped.
 .Sh FLAVORS AND MULTI_PACKAGES
 Starting with
 .Ox 2.7 ,