From 6acb9d258a4299228a78db8f04ff6ad2fa79eeee Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 10 Mar 2023 07:48:11 +0200
Subject: Improve bpkg-pkg-bindist documentation, Debian description

---
 bpkg/pkg-bindist.cli | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

(limited to 'bpkg/pkg-bindist.cli')

diff --git a/bpkg/pkg-bindist.cli b/bpkg/pkg-bindist.cli
index dbbf9c3..f3c3899 100644
--- a/bpkg/pkg-bindist.cli
+++ b/bpkg/pkg-bindist.cli
@@ -66,7 +66,10 @@ namespace bpkg
      build packages from source, this implementation \"pretends\" that this is
      what's happening by overriding a number of \cb{dh} targets to invoke the
      \cb{build2} build system on the required packages directly in their
-     \cb{bpkg} configuration locations. Typical invocation:
+     \cb{bpkg} configuration locations.
+
+     The \cb{dpkg-dev} (or \cb{build-essential}) and \cb{debhelper} Debian
+     packages must be installed before invocation. Typical invocation:
 
      \
      bpkg build libhello
@@ -74,8 +77,33 @@ namespace bpkg
      bpkg bindist -o /tmp/output/ libhello
      \
 
-     Note that the \cb{dpkg-dev} (or \cb{build-essential}) and \cb{debhelper}
-     Debian packages must be installed before invocation.
+     Unless the \cb{--recursive} option is specified, dependencies of the
+     specified package are translated to dependencies in the resulting binary
+     package using names and versions that refer to packages that would be
+     generated by the \cb{pkg-bindist} command (called \"non-native\"
+     packages). If instead you would like certain dependencies to refer to
+     binary packages provided by the distribution (called \"native\"
+     packages), then you need to arrange for them to be built as system (see
+     \l{bpkg-pkg-build(1)} for details). For example, if our \cb{libhello} has
+     a dependency on \cb{libsqlite3} and we would like the binary package for
+     \cb{libhello} to refer to \cb{libsqlite3} from Debian (or alike), then
+     the \cb{pkg-build} command would need to be (\cb{--sys-install} is
+     optional):
+
+     \
+     bpkg build --sys-install libhello ?sys:libsqlite3
+     \
+
+     Such a package with native dependencies can then be installed (including
+     any missing native dependencies) using the \cb{apt} or \cb{apt-get}
+     \cb{install} command. Note that the specified \cb{.deb} file must include
+     a directory separator (\c{/}) in order to be recognized as a file rather
+     than a package name. For example:
+
+     \
+     apt-get install ./libhello_1.2.3-0~debian11_amd64.deb \
+                     ./libhello-dev_1.2.3-0~debian11_amd64.deb
+     \
 
      See \l{bpkg#bindist-mapping-debian-produce Debian Package Mapping for
      Production} for details on \cb{bpkg} to Debian package name and version
-- 
cgit v1.1