1 files changed, 59 insertions, 0 deletions
diff --git a/comm/third_party/botan/doc/packaging.rst b/comm/third_party/botan/doc/packaging.rst
new file mode 100644
index 0000000000..f77000b89b
--- /dev/null
+++ b/comm/third_party/botan/doc/packaging.rst
@@ -0,0 +1,59 @@
+Notes for Distributors
+========================
+
+This document has information for anyone who is packaging copies of Botan for
+use by downstream developers, such as through a Linux distribution or other
+package management system.
+
+Recommended Options
+------------------------
+
+In most environments, zlib, bzip2, and sqlite are already installed, so there is
+no reason to not include support for them in Botan as well. Build with options
+``--with-zlib --with-bzip2 --with-sqlite3`` to enable these features.
+
+Even though OpenSSL is also typically already installed, using
+``--with-openssl`` by default is *not recommended*. OpenSSL is sometimes faster
+and sometimes slower than Botan, and the relative speeds vary depending on the
+algorithm and CPU.
+
+Set Path to the System CA bundle
+---------------------------------
+
+Most Unix/Linux systems maintain a list of trusted CA certificates at some well
+known path like ``/etc/ssl/certs/ca-certificates.crt`` or
+``/etc/ssl/cert.pem``. Unfortunately the exact path varies between systems. Use
+``--system-cert-bundle=PATH`` to set this path. If the option is not used,
+``configure.py`` tries a list of known locations.
+
+Set Distribution Info
+------------------------
+
+If your distribution of Botan involves creating library binaries, use the
+configure.py flag ``--distribution-info=`` to set the version of your
+packaging. For example Foonix OS might distribute its 4th revision of the
+package for Botan 2.1.3 using ``--distribution-info='Foonix 2.1.3-4'``. The
+string is completely free-form, since it depends on how the distribution numbers
+releases and packages.
+
+Any value set with ``--distribution-info`` flag will be included in the version
+string, and can read through the ``BOTAN_DISTRIBUTION_INFO`` macro.
+
+Minimize Distribution Patches
+------------------------------
+
+We (Botan upstream) *strongly* prefer that downstream distributions maintain no
+long-term patches against Botan. Even if it is a build problem which probably
+only affects your environment, please open an issue on github and include the
+patch you are using. Perhaps the issue does affect other users, and even if not
+it would be better for everyone if the library were improved so it were not
+necessary for the patch to be created in the first place. For example, having to
+modify or remove a build data file, or edit the makefile after generation,
+suggests an area where the build system is insufficiently flexible.
+
+Obviously nothing in the BSD-2 license prevents you from distributing patches or
+modified versions of Botan however you please. But long term patches by
+downstream distributors have a tendency to bitrot and sometimes even result in
+security problems (such as in the Debian OpenSSL RNG fiasco) because the patches
+are never reviewed by the library developers. So we try to discourage them, and
+work to ensure they are never necessary.