Rework doc/arm/build.rst

- Revise the list of required libraries.
  - Apply miscellaneous tweaks to style, formatting, and ordering.

doc/arm/build.rst

@@ -16,14 +16,12 @@ To build on a Unix or Linux system, use:
 
 ::
 
-       $ autoreconf -fi (if you are building in the git repository)
+    $ autoreconf -fi ### (only if building from the git repository)
-       $ ./configure
+    $ ./configure
-       $ make
+    $ make
 
-If you’re using Emacs, you might find ``make tags`` helpful.
+Several environment variables affect compilation, and they can be set
-
+before running ``configure``. The most significant ones are:
-Several environment variables, which can be set before running
-``configure``, affect compilation. Significant ones are:
 
 +--------------------+-------------------------------------------------+
 | Variable           | Description                                     |
@@ -31,11 +29,11 @@ Several environment variables, which can be set before running
 | ``CC``             | The C compiler to use. ``configure`` tries to   |
 |                    | figure out the right one for supported systems. |
 +--------------------+-------------------------------------------------+
-| ``CFLAGS``         | C compiler flags. Defaults to include -g and/or |
+| ``CFLAGS``         | The C compiler flags. Defaults to include -g    |
-|                    | -O2 as supported by the compiler. Please        |
+|                    | and/or -O2 as supported by the compiler. Please |
-|                    | include ‘-g’ if you need to set ``CFLAGS``.     |
+|                    | include ``-g`` if ``CFLAGS`` needs to be set.   |
 +--------------------+-------------------------------------------------+
-| ``LDFLAGS``        | Linker flags. Defaults to empty string.         |
+| ``LDFLAGS``        | The linker flags. Defaults to an empty string.  |
 +--------------------+-------------------------------------------------+
 
 Additional environment variables affecting the build are listed at the
@@ -44,91 +42,93 @@ command:
 
 ::
 
-   $ ./configure --help
+    $ ./configure --help
 
-macOS
+If using Emacs, the ``make tags`` command may be helpful.
-~~~~~
-
-Building on macOS assumes that the “Command Tools for Xcode” are
-installed. These can be downloaded from
-https://developer.apple.com/download/more/ or, if you have Xcode already
-installed, you can run ``xcode-select --install``. (Note that an Apple
-ID may be required to access the download page.)
 
 .. _build_dependencies:
 
-Required libraries
+Required Libraries
 ~~~~~~~~~~~~~~~~~~
 
-To build BIND you need to have the following packages installed:
+To build BIND 9, the following packages must be installed:
 
-- ``libuv`` for asynchronous I/O operations and event loops
+- ``libcrypto``, ``libssl``
-- ``libssl`` and ``libcrypto`` from OpenSSL for cryptography
+- ``libuv``
-- ``pkg-config / pkgconfig / pkgconf`` for build system support
+- ``perl``
+- ``pkg-config`` / ``pkgconfig`` / ``pkgconf``
 
-BIND 9.19 requires a fairly recent version of ``libuv`` (at least 1.x).
+BIND 9.19 requires ``libuv`` 1.x or higher. On older systems, an updated
-For some older systems, you will have to install an updated ``libuv``
+``libuv`` package needs to be installed from sources such as EPEL, PPA,
-package from sources such as EPEL, PPA, or other native sources for updated
+or other native sources. The other option is to build and install
-packages. The other option is to build and install ``libuv`` from source.
+``libuv`` from source.
 
-OpenSSL 1.0.2e or newer is required.
+OpenSSL 1.0.2e or newer is required. If the OpenSSL library is installed
-If the OpenSSL library is installed in a nonstandard location,
+in a nonstandard location, specify the prefix using
-specify the prefix using ``--with-openssl=<PREFIX>`` on the
+``--with-openssl=<PREFIX>`` on the ``configure`` command line. To use a
-configure command line. To use a PKCS#11 hardware service module for
+PKCS#11 hardware service module for cryptographic operations,
-cryptographic operations, it will be necessary to compile and use
+``engine_pkcs11`` from the OpenSC project must be compiled and used.
-engine_pkcs11 from the OpenSC project.
 
-To build BIND from the git repository, you need the following tools
+To build BIND from the git repository, the following tools must also be
 installed:
 
-- ``autoconf`` (includes autoreconf)
+- ``autoconf`` (includes ``autoreconf``)
 - ``automake``
 - ``libtool``
 
-Optional features
+Optional Features
 ~~~~~~~~~~~~~~~~~
 
 To see a full list of configuration options, run ``configure --help``.
 
-To improve performance, ``libjemalloc`` library is strongly recommended.
+To improve performance, use of the ``jemalloc`` library
+(http://jemalloc.net/) is strongly recommended.
 
-To support DNS over HTTPS, the server must be linked with
+To support :rfc:`DNS over HTTPS (DoH) <8484>`, the server must be linked
-``libnghttp2``.
+with ``libnghttp2`` (https://nghttp2.org/). If the library is
+unavailable, ``--disable-doh`` can be used to disable DoH support.
 
 To support the HTTP statistics channel, the server must be linked with
-at least one of the following libraries: ``libxml2`` http://xmlsoft.org
+at least one of the following libraries: ``libxml2``
-or ``json-c`` https://github.com/json-c/json-c. If these are installed
+(http://xmlsoft.org) or ``json-c`` (https://github.com/json-c/json-c).
-at a nonstandard location, then:
+If these are installed at a nonstandard location, then:
 
--  for ``libxml2``, specify the prefix using ``--with-libxml2=/prefix``.
+- for ``libxml2``, specify the prefix using ``--with-libxml2=/prefix``,
--  for ``json-c``, adjust ``PKG_CONFIG_PATH``.
+- for ``json-c``, adjust ``PKG_CONFIG_PATH``.
 
 To support compression on the HTTP statistics channel, the server must
-be linked against ``libzlib``. If this is installed in a nonstandard
+be linked against ``zlib`` (https://zlib.net/). If this is installed in
-location, specify the prefix using ``--with-zlib=/prefix``.
+a nonstandard location, specify the prefix using
+``--with-zlib=/prefix``.
 
 To support storing configuration data for runtime-added zones in an LMDB
-database, the server must be linked with ``liblmdb``. If this is
+database, the server must be linked with ``liblmdb``
-installed in a nonstandard location, specify the prefix using
+(https://github.com/LMDB/lmdb). If this is installed in a nonstandard
-``with-lmdb=/prefix``.
+location, specify the prefix using ``--with-lmdb=/prefix``.
 
 To support MaxMind GeoIP2 location-based ACLs, the server must be linked
-with ``libmaxminddb``. This is turned on by default if the library is
+with ``libmaxminddb`` (https://maxmind.github.io/libmaxminddb/). This is
-found; if the library is installed in a nonstandard location, specify
+turned on by default if the library is found; if the library is
-the prefix using ``--with-maxminddb=/prefix``. GeoIP2 support can be
+installed in a nonstandard location, specify the prefix using
-switched off with ``--disable-geoip``.
+``--with-maxminddb=/prefix``. GeoIP2 support can be switched off with
+``--disable-geoip``.
 
-For DNSTAP packet logging, you must have installed ``libfstrm``
+For DNSTAP packet logging, ``libfstrm``
-https://github.com/farsightsec/fstrm and ``libprotobuf-c``
+(https://github.com/farsightsec/fstrm) and ``libprotobuf-c``
-https://developers.google.com/protocol-buffers, and BIND must be
+(https://developers.google.com/protocol-buffers) must be installed, and
-configured with ``--enable-dnstap``.
+BIND must be configured with ``--enable-dnstap``.
 
-To support internationalized domain names in ``dig``, you must have installed
+To support internationalized domain names in ``dig``, ``libidn2``
-``libidn2``. If the library is installed in a nonstandard location, specify
+(https://www.gnu.org/software/libidn/#libidn2) must be installed. If the
-the prefix using ``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``.
+library is installed in a nonstandard location, specify the prefix using
+``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``.
 
-For line editing in ``nsupdate`` and ``nslookup``, you must have installed
+For line editing in ``nsupdate`` and ``nslookup``, either the
-``readline`` library.
+``readline`` (https://tiswww.case.edu/php/chet/readline/rltop.html) or
+the ``libedit`` library (https://www.thrysoee.dk/editline/) must be
+installed. If these are installed at a nonstandard location, adjust
+``PKG_CONFIG_PATH``. ``readline`` is used by default, and ``libedit``
+can be explicitly requested using ``--with-readline=libedit``.
 
 Certain compiled-in constants and default settings can be decreased to
 values better suited to small machines, e.g. OpenWRT boxes, by
@@ -137,32 +137,43 @@ This decreases memory usage by using smaller structures, but degrades
 performance.
 
 On Linux, process capabilities are managed in user space using the
-``libcap`` library, which can be installed on most Linux systems via the
+``libcap`` library
-``libcap-dev`` or ``libcap-devel`` package. Process capability support
+(https://git.kernel.org/pub/scm/libs/libcap/libcap.git/), which can be
-can also be disabled by configuring with ``--disable-linux-caps``.
+installed on most Linux systems via the ``libcap-dev`` or
+``libcap-devel`` package. Process capability support can also be
+disabled by configuring with ``--disable-linux-caps``.
 
 On some platforms it is necessary to explicitly request large file
 support to handle files bigger than 2GB. This can be done by using
 ``--enable-largefile`` on the ``configure`` command line.
 
-Support for the “fixed” rrset-order option can be enabled or disabled by
+Support for the “fixed” RRset-order option can be enabled or disabled by
 specifying ``--enable-fixed-rrset`` or ``--disable-fixed-rrset`` on the
-configure command line. By default, fixed rrset-order is disabled to
+``configure`` command line. By default, fixed RRset-order is disabled to
 reduce memory footprint.
 
-The ``--enable-querytrace`` option causes ``named`` to log every step of
+The ``--enable-querytrace`` option causes ``named`` to log every step
-processing every query. The ``--enable-singletrace`` option turns on the
+while processing every query. The ``--enable-singletrace`` option turns
-same verbose tracing, but allows an individual query to be separately
+on the same verbose tracing, but allows an individual query to be
-traced by setting its query ID to 0. These options should only be
+separately traced by setting its query ID to 0. These options should
-enabled when debugging, because they have a significant negative impact
+only be enabled when debugging, because they have a significant negative
-on query performance.
+impact on query performance.
 
 ``make install`` installs ``named`` and the various BIND 9 libraries. By
 default, installation is into /usr/local, but this can be changed with
 the ``--prefix`` option when running ``configure``.
 
-You may specify the option ``--sysconfdir`` to set the directory where
+The option ``--sysconfdir`` can be specified to set the directory where
-configuration files like ``named.conf`` go by default, and
+configuration files such as ``named.conf`` go by default;
-``--localstatedir`` to set the default parent directory of
+``--localstatedir`` can be used to set the default parent directory of
 ``run/named.pid``. ``--sysconfdir`` defaults to ``$prefix/etc`` and
 ``--localstatedir`` defaults to ``$prefix/var``.
+
+macOS
+~~~~~
+
+Building on macOS assumes that the “Command Tools for Xcode” are
+installed. These can be downloaded from
+https://developer.apple.com/download/more/ or, if Xcode is already
+installed, simply run ``xcode-select --install``. (Note that an Apple ID
+may be required to access the download page.)