lib/header locating: add docs, move env vars querying to setup.py

1 files changed, 30 insertions, 11 deletions

diff --git a/setup.py b/setup.py
index 48f5c583f..dc5cb248b 100644
--- a/setup.py
+++ b/setup.py
@@ -24,19 +24,37 @@ import setup_compress
 import setup_crypto
 import setup_docs
 
-# BORG_USE_BUNDLED_XXX=YES  -->  use the bundled code
-# BORG_USE_BUNDLED_XXX undefined  -->  try using system lib
-# Note: do not use =NO, that is not supported!
+# How the build process finds the system libs / uses the bundled code:
+#
+# 1. it will try to use (system) libs (see 1.1. and 1.2.),
+#    except if you use these env vars to force using the bundled code:
+#    BORG_USE_BUNDLED_XXX undefined  -->  try using system lib
+#    BORG_USE_BUNDLED_XXX=YES        -->  use the bundled code
+#    Note: do not use =NO, that is not supported!
+# 1.1. if BORG_LIBXXX_PREFIX is set, it will use headers and libs from there.
+# 1.2. if not and pkg-config can locate the lib, the lib located by
+#      pkg-config will be used. We use the pkg-config tool via the pkgconfig
+#      python package, which must be installed before invoking setup.py.
+#      if pkgconfig is not installed, this step is skipped.
+# 2. if no system lib could be located via 1.1. or 1.2., it will fall back
+#    to using the bundled code.
+
+# OpenSSL is required as a (system) lib in any case as we do not bundle it.
+# Thus, only step 1.1. and 1.2. apply to openssl (but not 1. and 2.).
+# needed: openssl >=1.0.2 or >=1.1.0 (or compatible)
+system_prefix_openssl = os.environ.get('BORG_OPENSSL_PREFIX')
+
+# needed: blake2 (>= 0.98.1)
+prefer_system_libb2 = not bool(os.environ.get('BORG_USE_BUNDLED_B2'))
+system_prefix_libb2 = os.environ.get('BORG_LIBB2_PREFIX')
 
 # needed: lz4 (>= 1.7.0 / r129)
 prefer_system_liblz4 = not bool(os.environ.get('BORG_USE_BUNDLED_LZ4'))
+system_prefix_liblz4 = os.environ.get('BORG_LIBLZ4_PREFIX')
 
 # needed: zstd (>= 1.3.0)
 prefer_system_libzstd = not bool(os.environ.get('BORG_USE_BUNDLED_ZSTD'))
-
-# needed: blake2 (>= 0.98.1)
-prefer_system_libb2 = not bool(os.environ.get('BORG_USE_BUNDLED_B2'))
-
+system_prefix_libzstd = os.environ.get('BORG_LIBZSTD_PREFIX')
 
 cpu_threads = multiprocessing.cpu_count() if multiprocessing else 1
 
@@ -149,14 +167,15 @@ if not on_rtd:
 
     crypto_ext_kwargs = members_appended(
         dict(sources=[crypto_ll_source, crypto_helpers]),
-        setup_crypto.crypto_ext_kwargs(pc),
-        setup_crypto.b2_ext_kwargs(pc, prefer_system_libb2),
+        setup_crypto.crypto_ext_kwargs(pc, system_prefix_openssl),
+        setup_crypto.b2_ext_kwargs(pc, prefer_system_libb2, system_prefix_libb2),
     )
 
     compress_ext_kwargs = members_appended(
         dict(sources=[compress_source]),
-        setup_compress.lz4_ext_kwargs(pc, prefer_system_liblz4),
-        setup_compress.zstd_ext_kwargs(pc, prefer_system_libzstd, multithreaded=False, legacy=False),
+        setup_compress.lz4_ext_kwargs(pc, prefer_system_liblz4, system_prefix_liblz4),
+        setup_compress.zstd_ext_kwargs(pc, prefer_system_libzstd, system_prefix_libzstd,
+                                       multithreaded=False, legacy=False),
     )
 
     ext_modules += [