move msgpack hints to helpers.py

also remove msgpack from install_requires - by default we use the
bundled code now.

setup.py

@@ -25,6 +25,8 @@ prefer_system_libzstd = True
 # True: use the shared libb2 from the system, False: use the bundled blake2 code
 prefer_system_libb2 = True
 
+# prefer_system_msgpack is another option, but you need to set it in src/borg/helpers.py.
+
 min_python = (3, 4)
 my_python = sys.version_info
 
@@ -35,19 +37,7 @@ if my_python < min_python:
 # Are we building on ReadTheDocs?
 on_rtd = os.environ.get('READTHEDOCS')
 
-install_requires = [
+install_requires = []
-    # we are rather picky about msgpack versions, because a good working msgpack is
-    # very important for borg, see https://github.com/borgbackup/borg/issues/3753
-    # best versions seem to be 0.4.6, 0.4.7, 0.4.8 and 0.5.6:
-    #'msgpack-python >=0.4.6, <=0.5.6, !=0.5.0, !=0.5.1, !=0.5.2, !=0.5.3, !=0.5.4, !=0.5.5',
-    # if you can't satisfy the above requirement, these are versions that might
-    # also work ok, IF you make sure to use the COMPILED version of msgpack-python,
-    # NOT the PURE PYTHON fallback implementation: ==0.5.1, ==0.5.4
-    #
-    # Please note:
-    # using any other version is not supported by borg development and
-    # any feedback related to issues caused by this will be ignored.
-]
 
 # note for package maintainers: if you package borgbackup for distribution,
 # please add llfuse as a *requirement* on all platforms that have a working

src/borg/helpers.py

@@ -31,6 +31,30 @@ from operator import attrgetter
 from string import Formatter
 from shutil import get_terminal_size
 
+# MSGPACK =====================================================================
+# we are rather picky about msgpack versions, because a good working msgpack is
+# very important for borg, see https://github.com/borgbackup/borg/issues/3753
+#
+# because some linux distributions didn't get their dependency management right
+# and broke borgbackup by upgrading msgpack to incompatible versions, we now
+# bundle msgpack-python 0.5.6, which is the latest and best msgpack that is
+# still compatible with borg 1.1.x and we use the bundled version by default.
+#
+# if you are a package maintainer and don't like bundled library code, feel
+# free to not use the bundled code:
+# - set prefer_system_msgpack = True
+# - make sure that an external msgpack-python gets installed
+# - make sure the external msgpack-python always stays at supported versions.
+# - best versions seem to be 0.4.6, 0.4.7, 0.4.8 and 0.5.6.
+# - if you can't satisfy the above requirement, these are versions that might
+#   also work ok, IF you make sure to use the COMPILED version of
+#   msgpack-python NOT the PURE PYTHON fallback implementation: 0.5.1 and 0.5.4
+#
+# Please note:
+# - using any other version is not supported by borg development and
+#   any feedback related to issues caused by this will be ignored.
+# - especially, it is known that msgpack 0.6.x does NOT work for borg 1.1.x.
+
 prefer_system_msgpack = False
 
 try:
@@ -40,8 +64,7 @@ try:
     import borg.algorithms.msgpack as msgpack
     from borg.algorithms.msgpack import fallback as msgpack_fallback
 except ImportError:
-    # when using a system msgpack, make sure it satisfies the requirements, see setup.py.
+    # use an external msgpack version
-    # also, you must make sure it actually gets installed as a dependency.
     import msgpack
     from msgpack import fallback as msgpack_fallback