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

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.
 
-# needed: lz4 (>= 1.7.0 / r129)
-prefer_system_liblz4 = not bool(os.environ.get('BORG_USE_BUNDLED_LZ4'))
-
-# needed: zstd (>= 1.3.0)
-prefer_system_libzstd = not bool(os.environ.get('BORG_USE_BUNDLED_ZSTD'))
+# 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'))
+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 += [

setup_compress.py

@@ -69,9 +69,8 @@ zstd_includes_legacy = [
 ]
 
 
-def zstd_ext_kwargs(pc, prefer_system, multithreaded=False, legacy=False):
+def zstd_ext_kwargs(pc, prefer_system, system_prefix, multithreaded=False, legacy=False):
     if prefer_system:
-        system_prefix = os.environ.get('BORG_LIBZSTD_PREFIX')
         if system_prefix:
             print('Detected and preferring libzstd [via BORG_LIBZSTD_PREFIX]')
             return dict(include_dirs=[os.path.join(system_prefix, 'include')],
@@ -114,9 +113,8 @@ lz4_includes = [
 ]
 
 
-def lz4_ext_kwargs(pc, prefer_system):
+def lz4_ext_kwargs(pc, prefer_system, system_prefix):
     if prefer_system:
-        system_prefix = os.environ.get('BORG_LIBLZ4_PREFIX')
         if system_prefix:
             print('Detected and preferring liblz4 [via BORG_LIBLZ4_PREFIX]')
             return dict(include_dirs=[os.path.join(system_prefix, 'include')],

setup_crypto.py

@@ -8,8 +8,7 @@ def multi_join(paths, *path_segments):
     return [os.path.join(*(path_segments + (path,))) for path in paths]
 
 
-def crypto_ext_kwargs(pc):
-    system_prefix = os.environ.get('BORG_OPENSSL_PREFIX')
+def crypto_ext_kwargs(pc, system_prefix):
     if system_prefix:
         print('Detected OpenSSL [via BORG_OPENSSL_PREFIX]')
         return dict(include_dirs=[os.path.join(system_prefix, 'include')],
@@ -37,9 +36,8 @@ b2_includes = [
 ]
 
 
-def b2_ext_kwargs(pc, prefer_system):
+def b2_ext_kwargs(pc, prefer_system, system_prefix):
     if prefer_system:
-        system_prefix = os.environ.get('BORG_LIBB2_PREFIX')
         if system_prefix:
             print('Detected and preferring libb2 [via BORG_LIBB2_PREFIX]')
             return dict(include_dirs=[os.path.join(system_prefix, 'include')],