path: root/win32utils/build.txt

<!--
Copyright (C) Internet Systems Consortium, Inc. ("ISC")

SPDX-License-Identifier: MPL-2.0

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0.  If a copy of the MPL was not distributed with this
file, you can obtain one at https://mozilla.org/MPL/2.0/.

See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
-->

Building BIND 9 on Windows has the following prerequisites:

1) You need to install Perl for Windows.  ActivePerl
(http://www.activestate.com/) and Strawberry Perl
(http://www.strawberryperl.com) have both been tested and found
to work.

2) libuv (https://libuv.org/) must be downloaded and built on the
system on which you are building BIND 9.

3) OpenSSL (https://www.openssl.org) must be downloaded and built on
the system on which you are building BIND 9.

4) If you wish to use the statistics channel, LibXML2
(ftp://xmlsoft.org/libxml2) must be downloaded and built on
the system on which you are building BIND 9.

5) Optional external packages (not used by default)

If you wish to use IP geolocation, GeoIP API and database must be
downloaded, patched and built on the system on which you are building
BIND 9.

If you wish to use zlib/deflate on the statistics channel, zlib
must be downloaded and built on the system on which you are building
BIND 9.

If you wish to use python tools, you need a python (version 2 or 3)
interpreter with its standard libraries.

If you wish to use readline, the readline library must be downloaded
and built on the system on which you are building BIND 9.

6) The BIND 9 Installer (BINDInstall) includes a copy of the
redistributable runtime object vcredist_x86.exe (or vcredist_x64.exe),
which is included with Visual Studio and can be downloaded from
Microsoft.  This file must be in place prior to running Configure.

Step 1: Download and build libuv

  Download and untar the libuv sources from https://libuv.org/ in the same
  directory in which you extracted the BIND 9 source: if BIND 9 is in
  \build\bind-9.16.9, for instance, libuv should be in \build\libuv-v1.40.0
  (subject to version number changes).

  As of this writing, a patch (win32utils/libuv.diff) needs to be applied
  to the libuv source code in order for it to work with BIND on Windows.  A
  pull request including the changes from this patch has been submitted to
  the libuv maintainers:

      https://github.com/libuv/libuv/pull/2653

  Applying the win32utils/libuv.diff patch will no longer be necessary
  for libuv versions released after this pull request has been merged.

  On Windows, libuv is built using CMake.  Here is a sample sequence of
  commands which builds a 64-bit shared libuv library:

      cd libuv-v1.40.0
      mkdir build
      cd build
      cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..
      cmake --build . --config Release

Step 2: Download and build OpenSSL

  Download and untar the OpenSSL sources from https://www.openssl.org/ in
  the same directory in which you extracted the BIND 9 source: if BIND 9 is
  in \build\bind-9.16.0, for instance, OpenSSL should be in
  \build\openssl-1.1.1d (subject to version number changes).

  Note: Building OpenSSL requires that you install Perl and NASM as it
  uses these during its build process. The following commands work as of
  openssl-1.1.1d, but you should check the OpenSSL distribution to see
  if the build instructions in the INSTALL file have changed:

      (In an x64 Visual Studio Command Prompt window)
      cd openssl-1.1.1d
      perl Configure VC-WIN64A
      nmake

Step 3: Download and build LibXML2

  LibXML2 is required to use the statistics channel. If you wish to
  build BIND 9 without support for this feature, skip to step 4.

  Download and untar the libxml2 sources from ftp://xmlsoft.org/libxml2 in
  the same directory in which you extracted the BIND 9 source: if BIND 9 is
  in \build\bind-9.16.0, for instance, libxml2 should be in
  \build\libxml2-2.9.2 (subject to version number changes).

  Now build libxml2:

    cd libxml2-2.9.2\win32
    cscript configure.js iconv=no
    nmake /f Makefile.msvc

Step 4: Download and build zlib

  The statistics channel (aka internal HTTP server) can support
  zlib "deflate" compression method. If you don't want to this
  feature, skip to step 5.

  Download and untar the zlib sources from https://www.zlib.net in the same
  directory in which you extracted the BIND 9 source: if BIND 9 is in
  \build\bind-9.16.0, for instance, zlib should be in \build\zlib-1.2.11
  (subject to version number changes).

  Read the win32\Makefile.msc for the Usage comment at the beginning of
  this file, then build the zlib1.dll DLL for the intended processor (i.e.,
  win32 aka x86, or x64), e.g.:

    cd zlib-1.2.11
    nmake /f win32\Makefile.msc

Step 5: Download and build GeoIP

  Geographic ("geoip") ACLs require libGeoIP. If you wish to build BIND 9
  without support for this feature, skip to step 6.

  The libGeoIP source code is available from:

    https://github.com/maxmind/geoip-api-c/releases.

  As of this writing, the current version of libGeoIP is 1.6.0.  There
  is a known bug in this and all prior versions which prevents it from
  building a suitable DLL with thread support on Windows.  You can apply
  the patch file bind9/win32utils/GeoIP.diff to address the problem.
  This patch has been submitted upstream, and will be included in
  future versions of libGeoIP.

Step 6: Enable python tools

  Some python packages are required: argparse, ply, win32con and win32api.
  Last CPython's (version 2 or 3) from https://www.python.org include
  the pip package manager which can install missing packages, for
  instance for the 2 last packages 'pip install pypiwin32' downloads and
  installs win32con and win32api.

  Note when the python interpreter is in the command path and
  the required packages available the Configure script will detect
  them and add python tools to the BIND 9 build.

  To be used a python tool must be invoked with python (e.g.,
  python dnssec-checkds.py <args>) as the shebang doesn't work
  on Windows. The isc package should be installed too, cf step 12.
  Unlike on Unix systems, this isc package uses the Registry to
  learn where BIND 9 was installed in step 11.

Step 7: Download and build Readline

  The readline library adds command-line editing in nslookup and nsupdate.
  If you wish to build BIND 9 without support for this feature, skip to
  step 8.

  Because the original GNU source for the readline library has no WIN32
  support, it will be necessary to download a version of the static
  readline library source that is ready to be built by Visual Studio.  One
  such version is available at:

    http://gpsim.sourceforge.net/gpsimWin32/gpsimWin32.html#readline_lib

  Note: Windows command (cmd.exe) provides an integrated line editing
  feature so it is not recommended to configure bind with readline.

Step 8: Make the redistributable runtime object available

  Check that the Microsoft redistributable object (vcredist_x86.exe or
  vcredist_x64.exe) is available to the build.  The file may be placed
  in the directory in which the BIND 9 source was extracted (for
  instance, if BIND 9 is in \build\bind-9.16.0, the redistributable
  may be placed in \build\vcredist_x86.exe).  Or, the path to the file
  can be specified via the VCREDIST_PATH environment variable, or via
  the "with-vcredist=PATH" option to the configuration script (see
  step 9). If none of these options is used, Configure will attempt to
  find the redistributable based on clues in the build environment.

Step 9: Configuring the BIND 9 build

  From the command prompt, cd to the win32utils directory under
  the BIND 9 root:

    cd bind-9.16.0\win32utils

  In this directory, you can prepare the Windows build by running:

    perl Configure <options> x64

  This will set up all the files needed for building BIND 9 according
  to the given options.  To see the available options, run:

    perl Configure help

  To remove all files generated by Configure, run:

    perl Configure clean

Step 10: Building BIND 9

  Building using 'nmake' or older versions of Visual Studio
  (e.g. VS 2005 or VS 2008) is no longer supported.

  Building with a version of Visual Studio newer than VS 2010
  requires the solution to first be upgraded by running:

    devenv bind9.sln /upgrade

  If the build host only has Visual Studio Build Tools available
  and not a full Visual Studio installation, devenv.exe will not
  be present.  In that case, the Configure invocation from step 9
  must be extended with the following parameters set to values
  matching the Visual Studio Build Tools version used:

    with-tools-version
    with-platform-version
    with-platform-toolset

  Example use for a 64-bit Visual Studio 2017 build:

    perl Configure ^
      with-tools-version=15.0 ^
      with-platform-toolset=v141 ^
      with-platform-version=10.0.17763.0 ^
      ...
      x64

  To build using the Visual Studio GUI in VS 2010 or newer:
  open the bind9.sln solution file; this will load the project
  files for all of the BIND 9 libraries and applications.  Select
  "Build->Batch Build", click "Select All", then click "Build".

  To build using MSBuild in VS 2010 or newer: call MSBuild on
  the bind9.sln solution file:

    msbuild /t:Build /p:Configuration=Release bind9.sln
    msbuild /t:Build /p:Configuration=Debug bind9.sln

  Note: This mode does not support building for Windows XP.

  After this step this documentation applies to external or remote
  builds, i.e., is common with installation.

Step 11: Install

  Installation is accomplished by running the BINDInstall program. All
  DLL's are copied to the Program Files area and all applications
  (including BINDInstall which may be necessary for uninstalling BIND
  9) to the bin directory.  If BIND 8 has previously been installed on
  the system it must be uninstalled first by running it's own
  BINDInstall program.  The BIND 9 installer does not yet do this.

  Note: BINDInstall.exe requires the MFC (Microsoft Foundation Class).
  This is only distributed with non-free (i.e., not "Express") versions of
  Visual Studio. The other BIND 9 libraries and applications do not have
  this dependency.

  The very last version of BINDInstall uses two files created by
  the Configure perl script:
   - InstallFlags: 32/64 bit build, and/or should the redistributable
    object be run.
   - InstallFiles: the list of files to install with for each files
    4 flags (destination, importance, check version and part of tools).
  The idea is to be able to use any BINDInstall.exe binary so
  a non-free version of Visual Studio is no longer required.

Step 12: Python package install

  When BIND 9 was built with python support, the isc python package
  must be installed locally by:

   cd <top-bind9-directory>
   cd bin/python
   python setup.py install

  (replace 'python' by the path of your python interpreter if needed.)

  BIND 9 python tools should work with version 2 or 3, 32 or 64 bits.

Please report bugs, whether in the process of building the application
or in BIND 9 itself, at https://gitlab.isc.org/isc-projects/bind9.