Document setting up minimized builds

Closes #1861 #2044

1 files changed, 38 insertions, 1 deletions

diff --git a/doc/building.rst b/doc/building.rst
index cfaf89f4b..0c7608341 100644
--- a/doc/building.rst
+++ b/doc/building.rst
@@ -78,7 +78,7 @@ only the most core modules will be included; you can then explicitly
 enable things that you want to use with ``--enable-modules``. This is
 useful for creating a minimal build targeting to a specific
 application, especially in conjunction with the amalgamation option;
-see :ref:`amalgamation`.
+see :ref:`amalgamation` and :ref:`minimized_builds`.
 
 For instance::
 
@@ -499,6 +499,43 @@ build step is required, just import botan2.py
 See :doc:`Python Bindings <api_ref/python>` for more information about
 the Python bindings.
 
+.. _minimized_builds:
+
+Minimized Builds
+--------------------
+
+Many developers wish to configure a minimized build which contains only the
+specific features their application will use. In general this is straighforward:
+use ``--minimized-build`` plus ``--enable-modules=`` to enable the specific modules
+you wish to use. Any such configurations should build and pass the tests; if you
+encounter a case where it doesn't please file an issue.
+
+The only trick is knowing which features you want to enable. The most common
+difficulty comes with entropy sources. By default, none are enabled, which means
+if you attempt to use ``AutoSeeded_RNG``, it will fail. The easiest resolution
+is to also enable ``system_rng`` which can act as either an entropy source or
+used directly as the RNG.
+
+If you are building for x86, ARM, or POWER, it can be beneficial to enable
+hardware support for the relevant instruction sets with modules such as
+``aes_ni`` and ``clmul`` for x86, or ``aes_armv8``, ``pmull``, and
+``sha2_32_armv8`` on ARMv8. SIMD optimizations such as ``chacha_avx2`` also can
+provide substantial performance improvements.
+
+.. note::
+   In a future release, hardware specific modules will be enabled by default if
+   the underlying "base" module is enabled.
+
+If you are building a TLS application, you may (or may not) want to include
+``tls_cbc`` which enables support for CBC ciphersuites. If ``tls_cbc`` is
+disabled, then it will not be possible to negotiate TLS v1.0/v1.1. In general
+this should be considered a feature; only enable this if you need backward
+compatability with obsolete clients or servers.
+
+For TLS another useful feature which is not enabled by default is the
+ChaCha20Poly1305 ciphersuites. To enable these, add ``chacha20poly1305``.
+
+
 Configure Script Options
 ---------------------------