Update build-related documentation and comments

1 files changed, 560 insertions, 179 deletions

diff --git a/manual/installation.rst b/manual/installation.rst
index e8773a65..28d4ccd9 100644
--- a/manual/installation.rst
+++ b/manual/installation.rst
@@ -3,125 +3,440 @@
 Building and Installing QPDF
 ============================
 
-This chapter describes how to build and install qpdf. Please see also
-the :file:`README.md` and
-:file:`INSTALL` files in the source distribution.
+This chapter describes how to build and install qpdf.
 
 .. _prerequisites:
 
-System Requirements
--------------------
+Dependencies
+------------
+
+qpdf has few external dependencies. This section describes what you
+need to build qpdf in various circumstances.
+
+Basic Dependencies
+~~~~~~~~~~~~~~~~~~
+
+- A C++ compiler that supports C++-14
+
+- `CMake <https://www.cmake.org>`__ version 3.16 or later
+
+- `zlib <https://www.zlib.net/>`__ or a compatible zlib implementation
+
+- A libjpeg-compatible library such as `jpeg <https://ijg.org/>`__ or
+  `libjpeg-turbo <https://libjpeg-turbo.org/>`__
+
+- *Recommended but not required:* `gnutls <https://www.gnutls.org/>`__
+  to be able to use the gnutls crypto provider and/or `openssl
+  <https://openssl.org/>`__ to be able to use the openssl crypto
+  provider
+
+The qpdf source tree includes a few automatically generated files. The
+code generator uses Python 3. Automatic code generation is off by
+default. For a discussion, refer to :ref:`build-options`.
+
+Test Dependencies
+~~~~~~~~~~~~~~~~~
+
+qpdf's test suite is run by ``ctest``, which is part of CMake, but
+the tests themselves are implemented using an embedded copy of `qtest
+<https://qtest.sourceforge.io>`__, which is implemented in perl. On
+Windows, MSYS2's perl is known to work.
+
+qtest requires `GNU diffutils
+<http://www.gnu.org/software/diffutils/>`__ or any other diff that
+supports :command:`diff -u`. The default ``diff`` command works on
+GNU/Linux and MacOS.
+
+Part of qpdf's test suite does comparisons of the contents PDF files
+by converting them to images and comparing the images. The image
+comparison tests are disabled by default. Those tests are not required
+for determining correctness of a qpdf build since the test suite also
+contains expected output files that are compared literally. The image
+comparison tests provide an extra check to make sure that any content
+transformations don't break the rendering of pages. Transformations
+that affect the content streams themselves are off by default and are
+only provided to help developers look into the contents of PDF files.
+If you are making deep changes to the library that cause changes in
+the contents of the files that qpdf generates, then you should enable
+the image comparison tests. Enable them by setting the
+``QPDF_TEST_COMPARE_IMAGES`` environment variable to ``1`` before
+running tests. Image comparison tests add these additional
+requirements:
+
+- `libtiff <http://www.simplesystems.org/libtiff/>`__ command-line
+  utilities
+
+- `GhostScript <https://www.ghostscript.com/>`__ version 8.60 or newer
+
+Note: prior to qpdf 11, image comparison tests were enabled within
+:file:`qpdf.test`, and you had to *disable* them by setting
+``QPDF_SKIP_TEST_COMPARE_IMAGES`` to ``1``. This was done
+automatically by ``./configure``. Now you have to *enable* image
+comparison tests by setting an environment variable. This change was
+made because developers have to set the environment variable
+themselves now rather than setting it through the build. Either way,
+they are off by default.
+
+Additional Requirements on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The qpdf package has few external dependencies. In order to build qpdf,
-the following packages are required:
+- To build qpdf with Visual Studio, there are no additional
+  requirements when the default cmake options are used. You can build
+  qpdf from a Visual C++ command-line shell.
 
-- A C++ compiler that supports C++-14.
+- To build with mingw, MSYS2 is recommended with the mingw32 and/or
+  mingw64 tool chains. You can also build with MSVC from an MSYS2
+  environment.
 
-- zlib: http://www.zlib.net/
+- qpdf's test suite can run within the MSYS2 environment for both
+  mingw and MSVC-based builds.
 
-- jpeg: http://www.ijg.org/files/ or https://libjpeg-turbo.org/
+For additional notes, see :file:`README-windows.md` in the source
+distribution.
 
-- *Recommended but not required:* gnutls: https://www.gnutls.org/ to be
-  able to use the gnutls crypto provider, and/or openssl:
-  https://openssl.org/ to be able to use the openssl crypto provider.
+Requirements for Building Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- gnu make 3.81 or newer: http://www.gnu.org/software/make
+The qpdf manual is written in reStructured Text and built with `Sphinx
+<https://www.sphinx-doc.org>`__ using the `Read the Docs Sphinx Theme
+<https://sphinx-rtd-theme.readthedocs.io>`__. Versions of sphinx prior
+to version 4.3.2 probably won't work. Sphinx requires Python 3. In
+order to build the HTML documentation from source, you need to install
+sphinx and the theme, which you can typically do with ``pip install
+sphinx sphinx_rtd_theme``. To build the PDF version of the
+documentation, you need ``pdflatex``, ``latexmk``, and a fairly
+complete LaTeX installation. Detailed requirements can be found in the
+Sphinx documentation. To see how the documentation is built for the
+qpdf distribution, refer to the :file:`build-scripts/build-doc` file
+in the qpdf source distribution.
 
-- perl version 5.8 or newer: http://www.perl.org/; required for running
-  the test suite. Starting with qpdf version 9.1.1, perl is no longer
-  required at runtime.
+.. _building:
 
-- GNU diffutils (any version): http://www.gnu.org/software/diffutils/
-  is required to run the test suite. Note that this is the version of
-  diff present on virtually all GNU/Linux systems. This is required
-  because the test suite uses :command:`diff -u`.
+Build Instructions
+------------------
 
-Part of qpdf's test suite does comparisons of the contents PDF files by
-converting them images and comparing the images. The image comparison
-tests are disabled by default. Those tests are not required for
-determining correctness of a qpdf build if you have not modified the
-code since the test suite also contains expected output files that are
-compared literally. The image comparison tests provide an extra check to
-make sure that any content transformations don't break the rendering of
-pages. Transformations that affect the content streams themselves are
-off by default and are only provided to help developers look into the
-contents of PDF files. If you are making deep changes to the library
-that cause changes in the contents of the files that qpdf generate,
-then you should enable the image comparison tests. Enable them by
-running :command:`configure` with the
-:samp:`--enable-test-compare-images` flag. If you enable
-this, the following additional requirements are required by the test
-suite. Note that in no case are these items required to use qpdf.
+Starting with qpdf 11, qpdf is built with `CMake
+<https://www.cmake.org>`__.
 
-- libtiff: http://www.remotesensing.org/libtiff/
+Basic Build Invocation
+~~~~~~~~~~~~~~~~~~~~~~
 
-- GhostScript version 8.60 or newer: http://www.ghostscript.com
+qpdf uses cmake in an ordinary way, so refer to the CMake
+documentation for details about how to run ``cmake``. Here is a
+brief summary.
 
-If you do not enable this, then you do not need to have tiff and
-ghostscript.
+You can usually just run
 
-For information on building the documentation, see :ref:`build-doc`.
+::
 
-.. _building:
+   cmake -S . -B build
+   cmake --build build
 
-Build Instructions
-------------------
+If you are using a multi-configuration generator such as MSVC, you
+should pass ``--config <Config>`` (where ``<Config>`` is ``Release``,
+``Debug``, ``RelWithDebInfo``, or ``MinSizeRel`` as discussed in the
+CMake documentation) to the *build* command. If you are running a
+single configuration generator such as the default Makefile generators
+in Linux or MSYS, you may want to pass ``-DCMAKE_BUILD_TYPE=<Config>``
+to the original ``cmake`` command.
 
-Building qpdf on UNIX is generally just a matter of running
+Run ``ctest`` to run the test suite. Since the real tests are
+implemented with `qtest <https://qtest.sourceforge.io/>`__, you will
+want to pass ``--verbose`` to ``cmake`` so you can see the individual
+test outputs. Otherwise, you will see a small number of ``ctest``
+commands that take a very long to run.
 
-::
+.. _installation:
 
-   ./configure
-   make
-
-You can also run :command:`make check` to run the test
-suite and :command:`make install` to install. Please run
-:command:`./configure --help` for options on what can be
-configured. You can also set the value of ``DESTDIR`` during
-installation to install to a temporary location, as is common with many
-open source packages. Please see also the
-:file:`README.md` and
-:file:`INSTALL` files in the source distribution.
-
-Building on Windows is a little bit more complicated. For details,
-please see :file:`README-windows.md` in the source
-distribution. You can also download a binary distribution for Windows.
-There is a port of qpdf to Visual C++ version 6 in the
-:file:`contrib` area generously contributed by Jian
-Ma. This is also discussed in more detail in
-:file:`README-windows.md`.
-
-While ``wchar_t`` is part of the C++ standard, qpdf uses it in only one
-place in the public API, and it's just in a helper function. It is
-possible to build qpdf on a system that doesn't have ``wchar_t``, and
-it's also possible to compile a program that uses qpdf on a system
-without ``wchar_t`` as long as you don't call that one method. This is a
-very unusual situation. For a detailed discussion, please see the
-top-level README.md file in qpdf's source distribution.
-
-There are some other things you can do with the build. Although qpdf
-uses :command:`autoconf`, it does not use
-:command:`automake` but instead uses a
-hand-crafted non-recursive Makefile that requires gnu make. If you're
-really interested, please read the comments in the top-level
-:file:`Makefile`.
-
-.. _build-doc:
-
-Building Documentation
-----------------------
+Installation and Packaging
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The qpdf manual is written in reStructured Text and built with `Sphinx
-<https://www.sphinx-doc.org>`__ using the `Read the Docs Sphinx Theme
-<https://sphinx-rtd-theme.readthedocs.io>`__. In order to build the
-HTML documentation from source, you need to install sphinx and the
-theme, which you can typically do with ``pip install sphinx
-sphinx_rtd_theme``. To build the PDF version of the documentation, you
-need ``pdflatex``, ``latexmk``, and a fairly complete LaTeX
-installation. Detailed requirements can be found in the Sphinx
-documentation. To see how the documentation is built for the qpdf
-distribution, refer to the :file:`build-scripts/build-doc` file in the
-qpdf source distribution.
+Installation can be performed using ``cmake --install`` or ``cpack``.
+For most normal use cases, ``cmake --install`` or ``cpack`` can be run
+in the normal way as described in CMake documentation. qpdf follows
+all normal installation conventions and uses CMake-defined variables
+for standard behavior.
+
+There are several components that can be installed separately:
+
+.. list-table:: Installation Components
+   :widths: 5 80
+   :header-rows: 0
+
+   - - cli
+     - Command-line tools
+
+   - - lib
+     - The runtime libraries; required if you built with shared
+       libraries
+
+   - - dev
+     - Static libraries, header files, and other files needed by
+       developers
+
+   - - doc
+     - Documentation and, if selected for installation, the manual
+
+   - - examples
+     - Example source files
+
+There are also separate options, discussed in :ref:`build-options`,
+that control how certain specific parts of the software are installed.
+
+.. _build-options:
+
+Build Options
+-------------
+
+.. last verified consistent with build: 2022-03-13. The top-level
+   CMakeLists.txt contains a comment that references this section.
+
+.. cSpell:ignore ccmake
+
+All available build options are defined in the the top-level
+:file:`CMakeLists.txt` file and have help text. You can see them using
+any standard cmake front-end (like ``cmake-gui`` or ``ccmake``). This
+section describes options that apply to most users. If you are trying
+to map autoconf options (from prior to qpdf 11) to cmake options,
+please see :ref:`autoconf-to-cmake`.
+
+If you are packaging qpdf for a distribution, you should also read
+:ref:`packaging`.
+
+Basic Build Options
+~~~~~~~~~~~~~~~~~~~
+
+BUILD_DOC
+  Whether to build documentation with sphinx. You must have the
+  required tools installed.
+
+BUILD_DOC_HTML
+  Visible when BUILD_DOC is selected. This option controls building
+  HTML documentation separately from PDF documentation since
+  the sphinx theme only needed for the HTML documentation.
+
+BUILD_DOC_PDF
+  Visible when BUILD_DOC is selected. This option controls building
+  PDF documentation separately from HTML documentation since
+  additional tools are required to build the PDF documentation.
+
+BUILD_SHARED_LIBS, BUILD_STATIC_LIBS
+  You can configure whether to build shared libraries, static
+  libraries, or both. You must select at least one of these options.
+  For rapid iteration, select only one as this cuts the build time in
+  half.
+
+  On Windows, if you build with shared libraries, you must have the
+  output directory for libqpdf (e.g. :file:`libqpdf/Release` or
+  :file:`libqpdf` within the build directory) in your path so that the
+  compiled executables can find the DLL. Updating your path is not
+  necessary if you build with static libraries only.
+
+QTEST_COLOR
+  Turn this on or off to control whether qtest uses color in its
+  output.
+
+Options for Working on qpdf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+GENERATE_AUTO_JOB
+  Some qpdf source files are automatically generated from
+  :file:`job.yml` and the CLI documentation. If you are adding new
+  command-line arguments to the qpdf CLI or updating
+  :file:`manual/cli.rst` in the qpdf sources, you should turn this on.
+  This option requires Python 3.
+
+WERROR
+  Make any compiler warnings into errors. We want qpdf to compile free
+  of warnings whenever possible, but there's always a chance that a
+  compiler upgrade or tool change may cause warnings to appear that
+  weren't there before. If you are testing qpdf with a new compiler,
+  you should turn this on.
+
+Environment-Specific Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SHOW_FAILED_TEST_OUTPUT
+  Ordinarily, qtest (which drives qpdf's test suite) writes detailed
+  information about its output to the file ``qtest.log`` in the build
+  output directory. If you are running a build in a continuous
+  integration or automated environment where you can't get to those
+  files, you should enable this option and also run ``ctest
+  --verbose`` or ``ctest --output-on-failure``. This will cause
+  detailed test failure output to be written into the build log.
+
+CI_MODE
+  Turning this on sets options used in qpdf's continuous integration
+  environment to ensure we catch as many problems as possible.
+  Specifically, this option enables ``SHOW_FAILED_TEST_OUTPUT`` and
+  ``WERROR`` and forces the native crypto provider to be built.
+
+MAINTAINER_MODE
+  Turning this option on sets options that should be on if you are
+  maintaining qpdf. In turns on the following:
+
+  - ``BUILD_DOC``
+
+  - ``GENERATE_AUTO_JOB``
+
+  - ``WERROR``
+
+  - ``REQUIRE_NATIVE_CRYPTO``
+
+  It is possible to turn ``BUILD_DOC`` off in maintainer mode so that
+  the extra requirements for building documentation don't have to be
+  available.
+
+.. _crypto.build:
+
+Build-time Crypto Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since version 9.1.0, qpdf can use external crypto providers in
+addition to its native provider. For a general discussion, see
+:ref:`crypto`. This section discusses how to configure which crypto
+providers are compiled into qpdf.
+
+In nearly all cases, external crypto providers should be preferred
+over the native one. However, if you are not concerned about working
+with encrypted files and want to reduce the number of dependencies,
+the native crypto provider is fully supported.
+
+By default, qpdf's build enables every external crypto providers whose
+dependencies are available and only enables the native crypto provider
+if no external providers are available. You can change this behavior
+with the options described here.
+
+USE_IMPLICIT_CRYPTO
+  This is on by default. If turned off, only explicitly selected
+  crypto providers will be built. You must use at least one of the
+  ``REQUIRE`` options below.
+
+ALLOW_CRYPTO_NATIVE
+  This option is only available when USE_IMPLICIT_CRYPTO is selected,
+  in which case it is on by default. Turning it off prevents qpdf from
+  falling back to the native crypto provider when no external provider
+  is available.
+
+REQUIRE_CRYPTO_NATIVE
+  Build the native crypto provider even if other options are
+  available.
+
+REQUIRE_CRYPTO_GNUTLS
+  Require the gnutls crypto provider. Turning this on makes in an
+  error if the gnutls library is not available.
+
+REQUIRE_CRYPTO_OPENSSL
+  Require the openssl crypto provider. Turning this on makes in an
+  error if the openssl library is not available.
+
+DEFAULT_CRYPTO
+  Explicitly select which crypto provider is used by default. See
+  :ref:`crypto.runtime` for information about run-time selection of
+  the crypto provider. If not specified, qpdf will pick gnutls if
+  available, otherwise openssl if available, and finally native as a
+  last priority.
+
+Example: if you wanted to build with only the gnutls crypto provider,
+you should run cmake with ``-DUSE_IMPLICIT_CRYPTO=0
+-DREQUIRE_CRYPTO_GNUTLS=1``.
+
+Advanced Build Options
+~~~~~~~~~~~~~~~~~~~~~~
+
+These options are used only for special purposes and are not relevant
+to most users.
+
+AVOID_WINDOWS_HANDLE
+  Disable use of the ``HANDLE`` type in Windows. This can be useful if
+  you are building for certain embedded Windows environments. Some
+  functionality won't work, but you can still process PDF files from
+  memory in this configuration.
+
+BUILD_DOC_DIST, INSTALL_MANUAL
+  By default, installing qpdf does not include a pre-built copy of the
+  manual. Instead, it installs a README file that tells people where
+  to find the manual online. If you want to install the manual, you
+  must enable the ``INSTALL_MANUAL`` option, and you must have a
+  ``doc-dist`` directory in the manual directory of the build. The
+  ``doc-dist`` directory is created if ``BUILD_DOC_DIST`` is selected
+  and ``BUILD_DOC_PDF`` and ``BUILD_DOC_HTML`` are both on.
+
+  The ``BUILD_DOC_DIST`` and ``INSTALL_MANUAL`` options are separate
+  and independent because of the additional tools required to build
+  documentation. In particular, for qpdf's official release
+  preparation, a ``doc-dist`` directory is built in Linux and then
+  extracted into the Windows builds so that it can be included in the
+  Windows installers. This prevents us from having to build the
+  documentation in a Windows environment. For additional discussion,
+  see :ref:`doc-packaging-rationale`.
+
+INSTALL_CMAKE_PACKAGE
+  Controls whether or not to install qpdf's cmake configuration file
+  (on by default).
+
+INSTALL_EXAMPLES
+  Controls whether or not to install qpdf's example source files with
+  documentation (on by default).
+
+INSTALL_PKGCONFIG
+  Controls whether or not to install qpdf's pkg-config configuration
+  file (on by default).
+
+OSS_FUZZ
+  Turning this option on changes the build of the fuzzers in a manner
+  specifically required by Google's oss-fuzz project. There is no
+  reason to turn this on for any other reason. It is enabled by the
+  build script that builds qpdf from that context.
+
+SKIP_OS_SECURE_RANDOM, USE_INSECURE_RANDOM
+  The native crypto implementation uses the operating systems's secure
+  random number source when available. It is not used when an external
+  crypto provider is in use. If you are building in a very specialized
+  environment where you are not using an external crypto provider but
+  can't use the OS-provided secure random number generator, you can
+  turn both of these options on. This will cause qpdf to fall back to
+  an insecure random number generator, which may generate guessable
+  random numbers. The resulting qpdf is still secure, but encrypted
+  files may be more subject to brute force attacks. Unless you know
+  you need these options for a specialized purpose, you don't need
+  them. These options were added to qpdf in response to a special
+  request from a user who needed to run a specialized PDF-related task
+  in an embedded environment that didn't have a secure random number
+  source.
+
+Building without wchar_t
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to build qpdf on a system that doesn't have
+``wchar_t``. The resulting build of qpdf is not API-compatible with a
+regular qpdf build, so this option cannot be selected from cmake. This
+option was added to qpdf to support installation on a very stripped
+down embedded environment that included only a partial implementation
+of the standard C++ library.
+
+You can disable use of ``wchar_t`` in qpdf's code by defining the
+``QPDF_NO_WCHAR_T`` preprocessor symbol in your build (e.g. by
+including ``-DQPDF_NO_WCHAR_T`` in ``CFLAGS`` and ``CXXFLAGS``).
+
+While ``wchar_t`` is part of the C++ standard library and should be
+present on virtually every system, there are some stripped down
+systems, such as those targeting certain embedded environments, that
+lack ``wchar_t``. Internally, qpdf uses UTF-8 encoding for everything,
+so there is nothing important in qpdf's API that uses ``wchar_t``.
+However, there are some helper methods for converting between
+``wchar_t*`` and ``char*``.
+
+If you are building in an environment that does not support
+``wchar_t``, you can define the preprocessor symbol
+``QPDF_NO_WCHAR_T`` in your build. This will work whether you are
+building qpdf and need to avoid compiling the code that uses wchar_t
+or whether you are building client code that uses qpdf.
+
+Note that, when you build code with libqpdf, it is *not necessary* to
+have the definition of ``QPDF_NO_WCHAR_T`` in your build match what
+was defined when the library was built as long as you are not calling
+any of the methods that use ``wchar_t``.
 
 .. _crypto:
 
@@ -134,93 +449,36 @@ to as "crypto providers." At the time of writing, a crypto
 implementation must provide MD5 and SHA2 (256, 384, and 512-bit) hashes
 and RC4 and AES256 with and without CBC encryption. In the future, if
 digital signature is added to qpdf, there may be additional requirements
-beyond this.
+beyond this. Some of these are weak cryptographic algorithms. For a
+discussion of why they're needed, see :ref:`weak-crypto`.
 
-Starting with qpdf version 9.1.0, the available implementations are
-``native`` and ``gnutls``. In qpdf 10.0.0, ``openssl`` was added.
-Additional implementations may be added if needed. It is also possible
-for a developer to provide their own implementation without modifying
-the qpdf library.
+The available crypto provider implementations are ``gnutls``,
+``openssl``, and ``native``. OpenSSL support was added in qpdf 10.0.0
+with support for OpenSSL added in 10.4.0. GnuTLS support was
+introduced in qpdf 9.1.0. Additional implementations can be added as
+needed. It is also possible for a developer to provide their own
+implementation without modifying the qpdf library.
 
-.. _crypto.build:
-
-Build Support For Crypto Providers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When building with qpdf's build system, crypto providers can be enabled
-at build time using various :command:`./configure`
-options. The default behavior is for
-:command:`./configure` to discover which crypto providers
-can be supported based on available external libraries, to build all
-available crypto providers, and to use an external provider as the
-default over the native one. This behavior can be changed with the
-following flags to :command:`./configure`:
-
-- :samp:`--enable-crypto-{x}`
-  (where :samp:`{x}` is a supported crypto
-  provider): enable the :samp:`{x}` crypto
-  provider, requiring any external dependencies it needs
-
-- :samp:`--disable-crypto-{x}`:
-  disable the :samp:`{x}` provider, and do not
-  link against its dependencies even if they are available
-
-- :samp:`--with-default-crypto={x}`:
-  make :samp:`{x}` the default provider even if
-  a higher priority one is available
-
-- :samp:`--disable-implicit-crypto`: only build crypto
-  providers that are explicitly requested with an
-  :samp:`--enable-crypto-{x}`
-  option
-
-For example, if you want to guarantee that the gnutls crypto provider is
-used and that the native provider is not built, you could run
-:command:`./configure --enable-crypto-gnutls
---disable-implicit-crypto`.
-
-If you build qpdf using your own build system, in order for qpdf to work
-at all, you need to enable at least one crypto provider. The file
-:file:`libqpdf/qpdf/qpdf-config.h.in` provides
-macros ``DEFAULT_CRYPTO``, whose value must be a string naming the
-default crypto provider, and various symbols starting with
-``USE_CRYPTO_``, at least one of which has to be enabled. Additionally,
-you must compile the source files that implement a crypto provider. To
-get a list of those files, look at
-:file:`libqpdf/build.mk`. If you want to omit a
-particular crypto provider, as long as its ``USE_CRYPTO_`` symbol is
-undefined, you can completely ignore the source files that belong to a
-particular crypto provider. Additionally, crypto providers may have
-their own external dependencies that can be omitted if the crypto
-provider is not used. For example, if you are building qpdf yourself and
-are using an environment that does not support gnutls or openssl, you
-can ensure that ``USE_CRYPTO_NATIVE`` is defined, ``USE_CRYPTO_GNUTLS``
-is not defined, and ``DEFAULT_CRYPTO`` is defined to ``"native"``. Then
-you must include the source files used in the native implementation,
-some of which were added or renamed from earlier versions, to your
-build, and you can ignore
-:file:`QPDFCrypto_gnutls.cc`. Always consult
-:file:`libqpdf/build.mk` to get the list of source
-files you need to build.
+For information about selecting which crypto providers are compiled
+into qpdf, see :ref:`crypto.build`.
 
 .. _crypto.runtime:
 
 Runtime Crypto Provider Selection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use the :qpdf:ref:`--show-crypto` option to
-:command:`qpdf` to get a list of available crypto
-providers. The default provider is always listed first, and the rest are
-listed in lexical order. Each crypto provider is listed on a line by
-itself with no other text, enabling the output of this command to be
-used easily in scripts.
+You can use the :qpdf:ref:`--show-crypto` option to :command:`qpdf` to
+get a list of available crypto providers. The default provider is
+always listed first, and the rest are listed in lexical order. Each
+crypto provider is listed on a line by itself with no other text,
+enabling the output of this command to be used easily in scripts.
 
 You can override which crypto provider is used by setting the
-``QPDF_CRYPTO_PROVIDER`` environment variable. There are few reasons to
-ever do this, but you might want to do it if you were explicitly trying
-to compare behavior of two different crypto providers while testing
-performance or reproducing a bug. It could also be useful for people who
-are implementing their own crypto providers.
+``QPDF_CRYPTO_PROVIDER`` environment variable. There are few reasons
+to ever do this, but you might want to do it if you were explicitly
+trying to compare behavior of two different crypto providers while
+testing performance or reproducing a bug. It could also be useful for
+people who are implementing their own crypto providers.
 
 .. _crypto.develop:
 
@@ -229,11 +487,11 @@ Crypto Provider Information for Developers
 
 If you are writing code that uses libqpdf and you want to force a
 certain crypto provider to be used, you can call the method
-``QPDFCryptoProvider::setDefaultProvider``. The argument is the name of
-a built-in or developer-supplied provider. To add your own crypto
-provider, you have to create a class derived from ``QPDFCryptoImpl`` and
-register it with ``QPDFCryptoProvider``. For additional information, see
-comments in :file:`include/qpdf/QPDFCryptoImpl.hh`.
+``QPDFCryptoProvider::setDefaultProvider``. The argument is the name
+of a built-in or developer-supplied provider. To add your own crypto
+provider, you have to create a class derived from ``QPDFCryptoImpl``
+and register it with ``QPDFCryptoProvider``. For additional
+information, see comments in :file:`include/qpdf/QPDFCryptoImpl.hh`.
 
 .. _crypto.design:
 
@@ -308,3 +566,126 @@ provide their own implementations for basic filters like
 Implementing the registration functions and internal storage of
 registered providers was also easier using C++-11's functional
 interfaces, which was another reason to require C++-11 at this time.
+
+.. _autoconf-to-cmake:
+
+Converting From autoconf to cmake
+---------------------------------
+
+Versions of qpdf before qpdf 11 were built with ``autoconf`` and a
+home-grown GNU Make-based build system. If you built qpdf with special
+``./configure`` options, this section can help you switch them over to
+``cmake``.
+
+In most cases, there is a one-to-one mapping between configure options
+and cmake options. There are a few exceptions:
+
+- The cmake build behaves differently with respect to whether or not
+  to include support for the native crypto provider. Specifically, it
+  is not implicitly enabled unless explicitly requested if there are
+  other options available. You can force it to be included by enabling
+  ``REQUIRE_CRYPTO_NATIVE``. For details, see :ref:`crypto.build`.
+
+- The ``--enable-external-libs`` option is no longer available. The
+  cmake build detects the presence of ``external-libs`` automatically.
+  See :file:`README-windows.md` in the source distribution for a more
+  in-depth discussion.
+
+- The sense of the option representing use of the OS-provided secure
+  random number generator has been reversed: the
+  ``--enable-os-secure-random``, which was on by default, has been
+  replaced by the ``SKIP_OS_SECURE_RANDOM`` option, which is off by
+  default. The option's new name and behavior match the preprocessor
+  symbol that it turns on.
+
+- Non-default test configuration is selected with environment
+  variables rather than cmake. The old ``./configure`` options just
+  set environment variables. Note that the sense of the variable for
+  image comparison tests has been reversed. It used to be that you had
+  to set ``QPDF_SKIP_TEST_COMPARE_IMAGES`` to ``1`` to *disable* image
+  comparison tests. This was done by default. Now you have to set
+  ``QPDF_TEST_COMPARE_IMAGES`` to ``1`` to *enable* image comparison
+  tests. Either way, they are off by default.
+
+- A handful of options that were specific to autoconf or the old build
+  system have been dropped.
+
+- ``cmake --install`` installs example source code in
+  ``doc/qpdf/examples`` in the ``examples`` installation component.
+  Packagers are encouraged to package this with development files if
+  there is no separate doc package. This can be turned off by
+  disabling the ``INSTALL_EXAMPLES`` build option.
+
+There are some new options available in the cmake build that were not
+available in the autoconf build. This table shows the old options and
+their equivalents in cmake.
+
+.. list-table:: configure flags to cmake options
+   :widths: 40 60
+   :header-rows: 0
+
+   - - enable-avoid-windows-handle
+     - AVOID_WINDOWS_HANDLE
+
+   - - enable-check-autofiles
+     - none -- not relevant to cmake
+
+   - - enable-crypto-gnutls
+     - REQUIRE_CRYPTO_GNUTLS
+
+   - - enable-crypto-native
+     - REQUIRE_CRYPTO_NATIVE (but see above)
+
+   - - enable-crypto-openssl
+     - REQUIRE_CRYPTO_OPENSSL
+
+   - - enable-doc-maintenance
+     - BUILD_DOC
+
+   - - enable-external-libs
+     - none -- detected automatically
+
+   - - enable-html-doc
+     - BUILD_DOC_HTML
+
+   - - enable-implicit-crypto
+     - USE_IMPLICIT_CRYPTO
+
+   - - enable-insecure-random
+     - USE_INSECURE_RANDOM
+
+   - - enable-ld-version-script
+     - none -- detected automatically
+
+   - - enable-maintainer-mode
+     - MAINTAINER_MODE (slight differences)
+
+   - - enable-os-secure-random (on by default)
+     - SKIP_OS_SECURE_RANDOM (off by default)
+
+   - - enable-oss-fuzz
+     - OSS_FUZZ
+
+   - - enable-pdf-doc
+     - BUILD_DOC_PDF
+
+   - - enable-rpath
+     - none -- cmake handles rpath correctly
+
+   - - enable-show-failed-test-output
+     - SHOW_FAILED_TEST_OUTPUT
+
+   - - enable-test-compare-images
+     - set the ``QPDF_TEST_COMPARE_IMAGES`` environment variable
+
+   - - enable-werror
+     - WERROR
+
+   - - with-buildrules
+     - none -- not relevant to cmake
+
+   - - with-default-crypto
+     - DEFAULT_CRYPTO
+
+   - - large-file-test-path
+     - set the ``QPDF_LARGE_FILE_TEST_PATH`` environment variable